From 90b4444677b621b9f6e444c45a0a31a0492277a7 Mon Sep 17 00:00:00 2001
From: TuxMonkey <nqx_2004@qq.com>
Date: Mon, 20 Oct 2025 17:40:42 +0800
Subject: [PATCH] changed userapp->usertask init some docs

---
 .idea/editor.xml                      |  1 +
 User_Code/app/app_doc.md              |  4 +-
 User_Code/app/write_app.md            |  2 -
 User_Code/bsp/bsp_doc.md              | 54 ++++-----------------------
 User_Code/bsp/write_bsp.md            |  5 +++
 User_Code/module/module_doc.md        |  4 ++
 User_Code/module/write_module.md      |  5 +++
 User_Code/user/userapp_doc.md         |  0
 User_Code/user/write_userapp.md       |  0
 User_Code/user_task/usertask_doc.md   |  5 +++
 User_Code/user_task/write_usertask.md |  5 +++
 readme.md                             | 24 +++++++++---
 12 files changed, 53 insertions(+), 56 deletions(-)
 delete mode 100644 User_Code/user/userapp_doc.md
 delete mode 100644 User_Code/user/write_userapp.md
 create mode 100644 User_Code/user_task/usertask_doc.md
 create mode 100644 User_Code/user_task/write_usertask.md

diff --git a/.idea/editor.xml b/.idea/editor.xml
index 633b554..510869e 100644
--- a/.idea/editor.xml
+++ b/.idea/editor.xml
@@ -121,6 +121,7 @@
     <option name="/Default/CodeInspection/Highlighting/InspectionSeverities/=CppMismatchedClassTags/@EntryIndexedValue" value="WARNING" type="string" />
     <option name="/Default/CodeInspection/Highlighting/InspectionSeverities/=CppMissingIncludeGuard/@EntryIndexedValue" value="WARNING" type="string" />
     <option name="/Default/CodeInspection/Highlighting/InspectionSeverities/=CppMissingKeywordThrow/@EntryIndexedValue" value="WARNING" type="string" />
+    <option name="/Default/CodeInspection/Highlighting/InspectionSeverities/=CppModulePartitionWithSeveralPartitionUnits/@EntryIndexedValue" value="WARNING" type="string" />
     <option name="/Default/CodeInspection/Highlighting/InspectionSeverities/=CppMsExtAddressOfClassRValue/@EntryIndexedValue" value="WARNING" type="string" />
     <option name="/Default/CodeInspection/Highlighting/InspectionSeverities/=CppMsExtBindingRValueToLvalueReference/@EntryIndexedValue" value="WARNING" type="string" />
     <option name="/Default/CodeInspection/Highlighting/InspectionSeverities/=CppMsExtCopyElisionInCopyInitDeclarator/@EntryIndexedValue" value="WARNING" type="string" />
diff --git a/User_Code/app/app_doc.md b/User_Code/app/app_doc.md
index 2e05391..4d06891 100644
--- a/User_Code/app/app_doc.md
+++ b/User_Code/app/app_doc.md
@@ -1,4 +1,4 @@
-# app
+# app_doc
 
 这是app(应用)层的说明。
 
@@ -8,7 +8,7 @@
 
 在main函数中包含`robot.h`头文件，这是对整车的抽象。将`INStask`，`motortask`，`ledtask`，`monitortask`这四个task加入`freertos.c`中，创建对应的任务，设置合适的任务运行间隔；然后将`robottask`放入freertos.c中，同样以一定的频率运行。 在初始化实时系统之前，在`main()`中调用`RobotInit()`进行整车的初始化。
 
-**关于运行的任务**，INStask的运行频率必须为1kHz，motortask推荐的运行频率为200Hz\~1000Hz（详情见module/motor/motor_task.c），在MotorTask内部，对于高实时性要求的电机可以提升到1kHz，不过要注意CAN总线的负载。monitortask的运行频率为100Hz；robottask的运行频率推荐为150Hz以上，应当高于视觉发送的频率，若后续使用插帧，同样应该保证不低过motortask太多。
+**关于运行的任务**，INStask的运行频率必须为1kHz+，motortask推荐的运行频率为200Hz\~1000Hz（详情见module/motor/motor_task.c），在MotorTask内部，对于高实时性要求的电机可以提升到1kHz，不过要注意CAN总线的负载。monitortask的运行频率为100Hz；robottask的运行频率推荐为150Hz以上，应当高于视觉发送的频率，若后续使用插帧，同样应该保证不低过motortask太多。
 
 若使用双板，则在`robot_def.h`中给对应的开发板设定宏定义，如底盘板使用`#define CHASSIS_BOARD`，云台板使用`#define GIMBAL_BOARD`；单个开发板控制整车，则定义`#define ONE_BOARD`。在每个应用中，都已经使用编译预处理指令完成条件编译，会自动根据设定的宏切换功能。使用双板的时候，目前板间通信通过CAN完成，因此两个开发板会挂载在一条总线上，在两个开发板对这条总线的其他使用CAN的设备进行配置时注意**不要发生ID冲突**，还要注意**防止负载过大**。
 
diff --git a/User_Code/app/write_app.md b/User_Code/app/write_app.md
index 00a9345..2279f89 100644
--- a/User_Code/app/write_app.md
+++ b/User_Code/app/write_app.md
@@ -64,5 +64,3 @@ robot_cmd工作起来就像一个遥控数据的兼容层，不论数据的来
 ## 双板兼容
 
 此框架对单开发板/双开发板/多开发板的情况都提供了支持（多板一般只在工程机器人上出现，需要自己在robot_cmd和robot_def增加相应的条件编译选项，robot.c中也不要忘记增加初始化和任务运行函数），目前通过条件编译实现了对单双板的切换。使用双板时，主控板在云台上，连接遥控器和上位机；副板在底盘上，负责底盘的运动控制和与裁判系统的通信。
-
-当然，你可以为每台不同的机器人进行特化，因为本框架是针对步兵/英雄定制的。
diff --git a/User_Code/bsp/bsp_doc.md b/User_Code/bsp/bsp_doc.md
index 9e9636b..de00d6e 100644
--- a/User_Code/bsp/bsp_doc.md
+++ b/User_Code/bsp/bsp_doc.md
@@ -1,52 +1,12 @@
-# application
+# bsp_doc
 
-<p align='right'>neozng1@hnu.edu.cn</p>
+这是BSP(芯片支持包)层的说明文档。
 
-这是application层的说明。
+> TODO:
+> 1. 增加硬件和软件CRC支持,统一不同crc顺序和计算码的调用方式
 
-> todo: 是否有必要将所有电机等模块的初始化参数放到一个头文件？
+bsp的功能是提供对片上（MCU中）外设的封装，即单片机芯片内部拥有的功能的封装。**在开发板pcb上集成的模块(蜂鸣器，加热电阻，wifi等)应该放在module层而不是这里**。
 
-## 使用说明
+bsp应该提供几种接口。包括初始化接口，一般命名为`XXXRegister()`(对于只有一个instance的可以叫`XXXInit()`,但建议统一风格都叫register)；调用此模块实现的必要功能，如通信型外设（CubeMX下的connectivity）提供接收和发送的接口，以及接收完成、发送完成（若有必要，或有发送队列需求）的数据回调函数。
 
-在main函数中包含`robot.h`头文件，这是对整车的抽象。将`INStask`，`motortask`，`ledtask`，`monitortask`这四个task加入`freertos.c`中，创建对应的任务，设置合适的任务运行间隔；然后将`robottask`放入freertos.c中，同样以一定的频率运行。 在初始化实时系统之前，在`main()`中调用`RobotInit()`进行整车的初始化。
-
-**关于运行的任务**，INStask的运行频率必须为1kHz，motortask推荐的运行频率为200Hz\~1000Hz（详情见module/motor/motor_task.c），在MotorTask内部，对于高实时性要求的电机可以提升到1kHz，不过要注意CAN总线的负载。monitortask的运行频率为100Hz；robottask的运行频率推荐为150Hz以上，应当高于视觉发送的频率，若后续使用插帧，同样应该保证不低过motortask太多。
-
-若使用双板，则在`robot_def.h`中给对应的开发板设定宏定义，如底盘板使用`#define CHASSIS_BOARD`，云台板使用`#define GIMBAL_BOARD`；单个开发板控制整车，则定义`#define ONE_BOARD`。在每个应用中，都已经使用编译预处理指令完成条件编译，会自动根据设定的宏切换功能。使用双板的时候，目前板间通信通过CAN完成，因此两个开发板会挂载在一条总线上，在两个开发板对这条总线的其他使用CAN的设备进行配置时注意**不要发生ID冲突**，还要注意**防止负载过大**。
-
-**同样，在该文件中你需要修改一些关于机器人的参数**。比如底盘和云台对齐时yaw电机编码器的值，拨盘的单圈载弹量、底盘的轴距等等。
-
-
-
-## 封装总览
-
-Robot.c是整个机器人的抽象，其下有4个应用：robot_cmd，gimbal，chassis，shoot。此框架当前是针对步兵/英雄/哨兵设计的，其他机器人只需要根据各自的特殊机构进行修改即可。robot_cmd是整个机器人的核心应用，其负责接受遥控器/上位机发来的指令，并将指令转化为实际的运动控制目标，发送给其他三个应用。后者会根据robot_cmd发来的命令，设定电机和其他执行单元的参考值等。
-
-为了进一步解耦应用之间的关系，app层并没有module和bsp之间的那种层级结构（或设计模式中所谓的**结构类型模式**，即robot_cmd包含其他三个模块），而采用了应用并列的**发布-订阅**机制，四个应用之间没有任何相互包含关系，他们之间的通信通过module层提供的`message_center`实现。每个应用会通过该模块向一些话题（事件）发布一些消息，同时从一些话题订阅消息。如robot_cmd应用会发布其他三个模块的控制信息，同时订阅其他三个模块的反馈信息。其他三个模块会订阅robot_cmd发布的控制信息，同时发布反馈给robot_cmd的信息，他们不需要知道彼此的存在，只是从`message_center`处获取其他应用发布的消息或向自己发布的话题推送消息。
-
-application在初始化module的时候，初始化参数会包含部分bsp的内容，但仅仅是外设和引脚的选择以及id设置（用于通信的外设需要id设置）。实际上当前框架的app层和cubemx初始化部分耦合，在配置的时候就必须确定每个外设的作用和归属权，一旦cubemx完成设置app层必须按照对应参数设置引脚和并分配module的外设。后续考虑将cubemx和bsp耦合，去除顶层代码和底层的关系
-
-
-
-## 整车程序流程
-
-```mermaid
-graph TD
-main调用RobotInit进行初始化 --> RobotInit调用基础bsp初始化以及各个app的初始化 --> 各个app进行消息订阅初始化和自有模块的初始化 --> 启动实时系统 --> 各任务开始运行
-
-```
-
-任务开始之后，每个app之间的交互关系如下：
-
-```mermaid
-graph TD
-robot_cmd获取遥控器/上位机指令以及各个应用发布的回传信息 --> 将指令转化为具体的控制信息 --> 发布指令到对应话题
-```
-
-gimbal/chassis/shoot则根据订阅的robot_cmd发布的消息，将具体的控制信息根据当前模式转化为执行单元的目标值，通过自己拥有的模块完成这些指令，然后把回传的信息发布到对应话题。
-
-每个应用的具体流程和实现，参见它们各自的说明文档。
-
-## 开发要点
-
-各个应用之间务必通过`message_center`以发布-订阅的方式进行消息交换，不要出现包含关系，这可以大大减小耦合度并提高合作开发的效率。
+- bsp_tools.h中提供了将bsp数据接收回调函数设置为任务的接口，通过这种方式，可以进一步提高整个系统的实时性，同时保证高优先级的任务一定按时执行。
\ No newline at end of file
diff --git a/User_Code/bsp/write_bsp.md b/User_Code/bsp/write_bsp.md
index e69de29..04866ca 100644
--- a/User_Code/bsp/write_bsp.md
+++ b/User_Code/bsp/write_bsp.md
@@ -0,0 +1,5 @@
+# write_bsp
+
+这是如何编写BSP层下程序的说明文档
+
+TBD
\ No newline at end of file
diff --git a/User_Code/module/module_doc.md b/User_Code/module/module_doc.md
index e69de29..1bba86d 100644
--- a/User_Code/module/module_doc.md
+++ b/User_Code/module/module_doc.md
@@ -0,0 +1,4 @@
+# module_doc
+
+这是module层的说明文档(TBD)
+
diff --git a/User_Code/module/write_module.md b/User_Code/module/write_module.md
index e69de29..3ae8f12 100644
--- a/User_Code/module/write_module.md
+++ b/User_Code/module/write_module.md
@@ -0,0 +1,5 @@
+# write_module
+
+这是如何编写module层下程序的说明文档
+
+TBD
\ No newline at end of file
diff --git a/User_Code/user/userapp_doc.md b/User_Code/user/userapp_doc.md
deleted file mode 100644
index e69de29..0000000
diff --git a/User_Code/user/write_userapp.md b/User_Code/user/write_userapp.md
deleted file mode 100644
index e69de29..0000000
diff --git a/User_Code/user_task/usertask_doc.md b/User_Code/user_task/usertask_doc.md
new file mode 100644
index 0000000..db4bc81
--- /dev/null
+++ b/User_Code/user_task/usertask_doc.md
@@ -0,0 +1,5 @@
+# userapp_doc
+
+这是user_task层的说明。
+
+TBD
\ No newline at end of file
diff --git a/User_Code/user_task/write_usertask.md b/User_Code/user_task/write_usertask.md
new file mode 100644
index 0000000..660444d
--- /dev/null
+++ b/User_Code/user_task/write_usertask.md
@@ -0,0 +1,5 @@
+# write_usertask
+
+这是如何编写usertask层下程序的说明文档
+
+TBD
\ No newline at end of file
diff --git a/readme.md b/readme.md
index c8b0cae..b54cd9b 100644
--- a/readme.md
+++ b/readme.md
@@ -3,7 +3,7 @@
 
 介绍
 
-创一工作室达妙H7开发板cpp框架，使用CLion+gcc编译，Ozone/Clion+OpenOCD进行调试,可以下载STM32CubeCLT进行环境配置，一键编译。
+创一工作室基于达妙H7(MC02)开发板编写的c/cpp框架，使用Clion作为IDE，CMake构建，GCC编译，Ozone/Clion+OpenOCD/MDK进行调试,可以下载STM32CubeCLT进行环境配置，一键编译。
 
 ## 功能介绍和展示
 
@@ -52,7 +52,7 @@
 
 介绍完整的工作流。
 
-### 工具链
+### 工具链及环境配置
 
 ### IDE?
 
@@ -72,12 +72,26 @@
 
 ### 运行单个bsp/module测试
 
-### VSCode集成工具
+### Clion集成工具
 
 ---
+
 ## 后续计划
 
-
 ---
 
-## 致谢
\ No newline at end of file
+
+
+## 致谢
+
+本项目高度参考以下开源项目，它们是：
+
+Basic_framework
+
+One_framework
+
+XRobot
+
+LingRoboMX(暂未开源)
+
+Helios_powerful_framework(暂未开源)
\ No newline at end of file