From c87c855ca98bfcf23e7426c438f62aaa3f850d47 Mon Sep 17 00:00:00 2001
From: LokLiang <LokLiang@163.com>
Date: Tue, 25 Feb 2025 11:52:37 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E7=AE=80=E8=A6=81=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fb63039
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# 项目说明
+
+## 项目结构
+
+```bash
+.
+├── app                 # 应用层代码。仅有一个入口 app_main.c/void work_app_main(void *arg)
+│   ├── button          # 完整独立的按键检测模块代码（少量依赖底层抽象），上层使用接口文件： button.h
+│   ├── config          # 配置文件
+│   │   ├── app_config      # 应用层的配置，与具体硬件无关，只存放头文件，用以定义出厂默认配置，被上层 app_config.c 所包含，通过 idf.py menuconfig 配置
+│   │   └── board_config    # 板载硬件的配置，仅与具体硬件相关，只存放头文件，用以适应不同的 PCB 布局，被上层 board_config.c 所包含，通过 idf.py menuconfig 配置
+│   ├── drivers         # 拥有具体硬件的驱动代码，包括 MCU 外设
+│   │   ├── data_port       # 数据端口，用于连接上层应用。由 sb_data_port.h 统一应用层的通讯接口，接口对象由具体硬件的驱动获得
+│   │   └── ws2812_spi      # 使用 SPI 接口驱动 WS2812 灯珠的代码
+│   ├── led_strip       # 灯带驱动，这里只提供一个 Kconfig 的示例
+│   └── utils           # 工具函数，纯软件，与具体硬件无关
+├── components          # 自定义组件。重点关注 system/include 目录，统一抽象实时内核和驱动接口
+├── main                # 主函数。执行仅与具体平台相关的初始化，并调用 app_main.c/void work_app_main(void *arg) 开始运行应用
+├── partitions.csv      # ESP32 的分区表。如无特殊需求不必修改
+├── README.md           # 项目说明
+├── release             # 发布文件。使用顶层目录的脚本自动生成，如 ./.release-sbdemo_s3.sh
+├── sal                 # components 目录下抽象层的实现代码，实现实时内核和驱动接口的抽象
+└── sdkconfig_defaults  # 默认配置文件，通过 idf.py menuconfig 配置
+```
+
+## 编译命令
+
+```bash
+$ get_idf  # 设置当前终端的编译环境变量，当打开一个新的终端时需要重新执行
+$ ./.release-sbdemo_s3.sh # 仅需要切换项目时执行一次，需要新增项目时参考此文件添加一个配置
+$ idf.py build size flash monitor # 编译、查看大小、烧录、打开串口
+```
+
+## 新增一个默认的配置
+- 当新增一个项目时，为方便设置不同项目间的配置差异，可以参考 sdkconfig_defaults 目录下的文件，生成一个默认的配置文件。具体操作方法：
+1. 使用 idf.py menuconfig 配置好一个项目。
+2. 使用 idf.py save-defconfig 保存配置。这将输出一个 sdkconfig.defaults 文件。
+3. 在 sdkconfig_defaults 目录下新增一个文件，文件名格式为： "sdkconfig.release_${FW_NAME}_${CHIP_NAME}${ADDITIONAL}.defaults" 。注意：文件名中的变量在第 6 步中定义。
+4. 把 sdkconfig.defaults 文件的内容复制到 "sdkconfig.release_${FW_NAME}_${CHIP_NAME}${ADDITIONAL}.defaults" 文件中。
+5. 以 .release-sbdemo_s3.sh 为例，复制一个新文件，命名规范为 .release-PRODUCT_ID_name.sh 。其中 PRODUCT_ID 在 app/config/version.h 中应与宏 PRODUCT_ID 所定义的值一致。注意 PRODUCT_ID 必须是6个字符。
+6. 根据实际项目修改 .release-PRODUCT_ID_name.sh 文件中变量的值。
+7. 使用 .release-PRODUCT_ID_name.sh 脚本生成固件。
+
+## 其他功能概要
+
+### 对设备调用的设计建议：
+```text
+应用 <---> 设备抽象接口 <---> 设备驱动 <---> 硬件抽象接口 <---> 硬件驱动
+```
+
+### 实时内核： #include "os/os.h"
+- 请把所有与实时内核相关的代码通过此文件的接口调用。
+
+### 命令行工具： #include "shell/sh.h"
+- 请参考 app/drivers/ws2812_spi/ws2812_spi_shell.c
+
+### 调试日志： #include "sys_log.h"
+- 使用范例：
+```C
+#define CONFIG_SYS_LOG_LEVEL SYS_LOG_LEVEL_DBG
+#define SYS_LOG_DOMAIN "MAIN"
+#include "sys_log.h"
+
+int main(void)
+{
+    SYS_LOG_INF("Hello, World!");
+    return 0;
+}
+```
+