From a35bb3e37a57b00f6649ca9cd68940c1c9b8e8cd Mon Sep 17 00:00:00 2001
From: TuxMonkey <8196772+tuxmonkey@user.noreply.gitee.com>
Date: Sat, 18 Oct 2025 22:08:50 +0800
Subject: [PATCH] inited docs

---
 User_Code/app/app_doc.md         | 50 +++++++++++++++++++
 User_Code/app/write_app.md       | 68 ++++++++++++++++++++++++++
 User_Code/bsp/bsp_doc.md         | 52 ++++++++++++++++++++
 User_Code/bsp/write_bsp.md       |  0
 User_Code/module/module_doc.md   |  0
 User_Code/module/write_module.md |  0
 User_Code/user/userapp_doc.md    |  0
 User_Code/user/write_userapp.md  |  0
 readme.md                        | 83 ++++++++++++++++++++++++++++++++
 9 files changed, 253 insertions(+)
 create mode 100644 User_Code/app/app_doc.md
 create mode 100644 User_Code/app/write_app.md
 create mode 100644 User_Code/bsp/bsp_doc.md
 create mode 100644 User_Code/bsp/write_bsp.md
 create mode 100644 User_Code/module/module_doc.md
 create mode 100644 User_Code/module/write_module.md
 create mode 100644 User_Code/user/userapp_doc.md
 create mode 100644 User_Code/user/write_userapp.md
 create mode 100644 readme.md

diff --git a/User_Code/app/app_doc.md b/User_Code/app/app_doc.md
new file mode 100644
index 0000000..2e05391
--- /dev/null
+++ b/User_Code/app/app_doc.md
@@ -0,0 +1,50 @@
+# app
+
+这是app(应用)层的说明。
+
+> todo: 是否有必要将所有电机等模块的初始化参数放到一个头文件？
+
+## 使用说明
+
+在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`以发布-订阅的方式进行消息交换，不要出现包含关系，这可以大大减小耦合度并提高合作开发的效率。
diff --git a/User_Code/app/write_app.md b/User_Code/app/write_app.md
new file mode 100644
index 0000000..00a9345
--- /dev/null
+++ b/User_Code/app/write_app.md
@@ -0,0 +1,68 @@
+# APP层应用编写指引
+
+## 通信机制
+
+**应用之间不应该有任何包含关系，它们必须是平行工作的。**而这通过pub-sub的机制实现。module层提供了`message_center`模块，支持发布订阅者的消息订阅机制。以传统的框架为例，负责整车控制的应用和其他应用（或任务）是从属的树状结构，或不同的任务和应用之间通过全局变量传递消息（**请不要使用全局变量！**），而此框架下的不同应用是并行的关系。
+
+如果一个应用希望获取另一个应用的数据，那么他应该**订阅**由此此应用发布的话题。一个应用要把自己希望共享的数据，注册到消息中心，即**发布**。为了区别不同的消息来源（你希望订阅谁的消息？哪一个消息？），可以通过**话题名**进行订阅。也就是说，消息中心作为第三方，管理所有的消息发布者和订阅者，它像报刊亭一样对消息进行中转，使得不同的应用之间不需要包含彼此，更不用全局变量也能共享消息。
+
+> 更多关于发布-订阅的实现，请参考`modules/message_center`下的文档。
+
+
+## robot_def.h
+
+这是机器人的参数配置文件，必须要针对每个机器人进行修改。包括机器人的尺寸参数和性能参数等。你还需要在这里设定软硬件配置：云台板/底盘板/单板等。这里定义的宏会作为条件编译的决断。
+
+app层共用的状态变量和结构体等也应该定义在这里（例如用于应用之间通信的数据）。记得用于通信的变量要用:
+```c
+#pragma pack(1) 
+typedef struct
+{
+    // your struct 
+
+} your_struct;
+#pragma pack()
+```
+包裹起来，取消字节对齐以防止出现访问8-bit地址而出现错误。
+
+如果你需要其他的通信数据类型或修改模块间通信数据的格式，直接在此处更改即可。
+
+## robot_cmd
+
+机器人命令模块是对整个机器人的抽象，对于单板控制整车的情况，该应用应该包含接收控制指令的模块，例如遥控器、视觉通信模块。该模块会处理接收到的控制数据，并将其转化为**具体的、定量的**控制信息，发送给其他模块。同时，cmd应用会处理模块和应用离线的情况，出现紧急状况时停止所有执行机构的运行。
+
+如从遥控器获知当前右侧摇杆拨向上方，则将遥控器发来的数值转化为底盘前进的速度值，然后发送给其他应用。同时，robot_cmd还要从其他应用获取反馈信息，做出其他决策。可以将其视为整个机器人的**大脑**。
+
+robot_cmd工作起来就像一个遥控数据的兼容层，不论数据的来源是视觉上位机/遥控器/键鼠/图传通信链路/ps手柄，最后都会被转化成真实参考输入提供给其他的app。它的任务是将其他来源的数据映射到控制输入上。
+
+
+
+## gimbal
+
+以步兵为例，云台应用应当包含两个电机，分别用于驱动yaw和pitch轴（除非你是一个三轴的云台），还有一个imu（开发板一般放在云台上）。gimbal模块会接收robot_cmd发来的控制信息（云台的角度、转速等），并通过电机提供的接口完成电机的参考值设定。gimbal还要把imu的数据反馈给cmd，用于和视觉的通信以及云台状态的判断。
+
+
+
+## shoot
+
+还是以步兵为例，发射应用应当包括摩擦轮电机、拨盘电机和弹舱盖。根据cmd应用发来的控制信息，决定当前的发射模式（单发、双发、连发），弹舱盖的开合，以及射速（15？18？30？）等。
+
+
+
+##  chassis
+
+以步兵为例，底盘应该包括4个电机。根据cmd应用发来的控制信息，进行麦克纳姆轮的运动学解算，从而获知四个电机需要的设定值，然后调用电机提供的接口进行设定。chassis还要根据电机的反馈数据以及imu信息（如果有imu的话，即双板的情况，云台一个底盘一个），计算底盘的实际运动状态，反馈给robot_cmd应用。
+
+
+
+## lift
+
+以工程机器人为例，抬升机构应该包含用于抬升的执行单元（可能是气缸、电磁阀、电机、点推杆等），根据cmd发来的数据控制执行单元运行到特定的高度，并进行必要的反馈。
+
+
+
+## 双板兼容
+
+此框架对单开发板/双开发板/多开发板的情况都提供了支持（多板一般只在工程机器人上出现，需要自己在robot_cmd和robot_def增加相应的条件编译选项，robot.c中也不要忘记增加初始化和任务运行函数），目前通过条件编译实现了对单双板的切换。使用双板时，主控板在云台上，连接遥控器和上位机；副板在底盘上，负责底盘的运动控制和与裁判系统的通信。
+
+当然，你可以为每台不同的机器人进行特化，因为本框架是针对步兵/英雄定制的。
diff --git a/User_Code/bsp/bsp_doc.md b/User_Code/bsp/bsp_doc.md
new file mode 100644
index 0000000..9e9636b
--- /dev/null
+++ b/User_Code/bsp/bsp_doc.md
@@ -0,0 +1,52 @@
+# application
+
+<p align='right'>neozng1@hnu.edu.cn</p>
+
+这是application层的说明。
+
+> todo: 是否有必要将所有电机等模块的初始化参数放到一个头文件？
+
+## 使用说明
+
+在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`以发布-订阅的方式进行消息交换，不要出现包含关系，这可以大大减小耦合度并提高合作开发的效率。
diff --git a/User_Code/bsp/write_bsp.md b/User_Code/bsp/write_bsp.md
new file mode 100644
index 0000000..e69de29
diff --git a/User_Code/module/module_doc.md b/User_Code/module/module_doc.md
new file mode 100644
index 0000000..e69de29
diff --git a/User_Code/module/write_module.md b/User_Code/module/write_module.md
new file mode 100644
index 0000000..e69de29
diff --git a/User_Code/user/userapp_doc.md b/User_Code/user/userapp_doc.md
new file mode 100644
index 0000000..e69de29
diff --git a/User_Code/user/write_userapp.md b/User_Code/user/write_userapp.md
new file mode 100644
index 0000000..e69de29
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..c8b0cae
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,83 @@
+# TronOneH7_Scaffold
+# 创一达妙开发板脚手架
+
+介绍
+
+创一工作室达妙H7开发板cpp框架，使用CLion+gcc编译，Ozone/Clion+OpenOCD进行调试,可以下载STM32CubeCLT进行环境配置，一键编译。
+
+## 功能介绍和展示
+
+### 起源
+
+### 优势
+
+- 轻量级框架，易于上手
+> 用软件开发的思想设计嵌入式系统是一种降维打击
+>
+> <p align=right>—— 沃兹基·烁德</p>
+
+---
+### 效果展示
+
+实战展示：
+
+### 可用功能
+
+#### bsp封装
+
+#### 模块封装
+
+#### 应用封装
+
+---
+## 架构
+
+总览。
+
+### 软件栈
+
+### 设计思想
+
+## 执行顺序与数据流
+
+### 初始化
+
+### 数据流
+
+---
+
+
+
+## 开发工具
+
+介绍完整的工作流。
+
+### 工具链
+
+### IDE?
+
+### 调试和性能分析
+
+---
+
+## 如何使用本框架
+
+仓库中有各种各样的说明文档和使用帮助。
+
+### 编译烧录
+
+### 基本文档
+
+### 阅读代码
+
+### 运行单个bsp/module测试
+
+### VSCode集成工具
+
+---
+## 后续计划
+
+
+---
+
+## 致谢
\ No newline at end of file