更新了说明文档和环境配置教程

README.md

@@ -18,7 +18,7 @@
 
 - 分层：
 
-  本框架主要代码分为**BSP、Module、APP**三层。三层的代码分别存放在同名的三个文件夹中，这三个文件夹存放在根目录下。开发过程中主要编写APP层代码，Module层与BSP层不建议修改。如需添加module（如oled屏幕、其他传感器和外设等），请按照规范编写并联系组长提交commit到dev分支，完善后合并至主分支。
+  本框架主要代码分为**BSP、Module、APP**三层。三层的代码分别存放在同名的三个文件夹中，这三个文件夹存放在根目录下。开发过程中主要编写APP层代码，Module层与BSP层不建议修改。如需添加module（如oled屏幕、其他传感器和外设等），请按照规范编写并联系组长提交commit到dev分支，完善后合并至主分支。在配置git的时候，将自己的`user.name`配置成英文缩写或易懂的nick name。
 
   BSP层构建与HAL之上。HAL库和实时系统、DSP支持等文件都在`HAL_N_Middlewares`文件夹下（包括Cube生成的外设初始化的Inc和Src文件夹）。
 
@@ -26,8 +26,13 @@
 
 - 代码格式：
 
-  在vscode-设置-扩展-C/C++-C_Cpp:style下修改。默认为`Visual Studio`。请手动修改为：
-  `{ BasedOnStyle: Google, IndentWidth: 4, TabWidth: 4, ColumnLimit: 0 }`。修改完成后可在代码中使用右键-格式化文档(注：请勿对cube生成的文件使用此操作)。此操作不会改变文档的内容，但会改变缩进、空行、符号位置等，使代码更加统一、整洁。
+  在vscode-设置-扩展-C/C++-C_Cpp:style下修改。默认为`Visual Studio`。编写完新的代码后，使用右键-格式化文档(注：请勿对cube生成的文件使用此操作)。此操作不会改变文档的内容，但会改变缩进、空行、符号位置等，使代码更加统一、整洁。
+
+  请保持良好的注释编写习惯，建议安装doxygen插件。务必统一在.h文件中为外部接口编写注释，并给类型定义编写必要的注释。对于私有函数（.c文件中static修饰），请在.c文件中进行注释。对于复杂的代码段，也请添加注释。
+
+  每个功能模块编写完之后，及时添加说明文档。内容参照已有的文档，要进行简短的**总体说明、代码结构、外部接口和类型定义、私有函数和变量，以及使用的说明和范例**。如果有特别需要注意的地方，也请说明。
+
+  ==**在编写代码的时候，注意添加安全检查，“treat your users as idiot！”**==
 
 - 面向对象设计：
 
@@ -59,12 +64,16 @@
   5. 增加舵机模块
   6. 增加单点激光模块
   
-- 主要功能：实现对设备的封装
+- 主要功能：实现对设备的封装，如将IMU、PC、电机等视为一个完整的功能模块，让应用层不需要关心其底层的具体实现，直接使用接口。
 
 - 子文件与子文件夹
 
-  - 注意，module层没有也不需要进行同意初始化。app层的应用会包含一些模块，因此由app来调用各个模块的init函数，只有当一个module被app实例化，这个模块才会存在。
+  - **注意，module层没有也不需要进行同意初始化**。app层的应用会包含一些模块，因此由app来调用各个模块的init或register函数，只有当一个module被app实例化，这个模块才会存在。
+
+    > 命名为init()的初始化一般来说是开发板的独占资源，即有且只有一个这样的模块，无法拥有多个实例，如板载陀螺仪、LED、按键等。命名为register()的模块则可以拥有多个，比如电机。
+
   - monitor文件夹:实现看门狗功能。提供回调函数和count可选（TODO）
+
   - algorithm:该层软件库存放位置，这些功能与硬件无关，而是提供通用的数据结构和“算子”以供该层的其他部分调用，主要是算法、控制器、底盘和位姿解算等。
 
 - module要点：
@@ -88,6 +97,12 @@
 
 Module层主要存放的是类型定义和实例指针数组，在该层没有进行实例化（定义或通过malloc分配空间），若在APP层没有实例化，则该模块的存在与否基本不会影响编译后的可执行文件，只会占用初始化和代码区所需的少量内存。module只会保存每个实例对象的指针，在没有初始化的时候仅仅占用一个指针数组的空间。因此，基于本框架的其他工程没有必要删除APP层未使用的module文件。
 
+> **待优化：**
+>
+> 由于C语言没有对象的概念，对于需要使用通信的module，在其.c文件下都需要保存每个实例的指针，在收到消息时遍历所有实例指针，找到收到消息的实例。这种处理方式可能会导致实时性下降，CAN接收时要遍历所有注册了CAN的实例，进入module层还需要一次遍历。用C++则可以将对象的this指针和模块的回调函数进行绑定，生成一个可调用对象然后再进行CAN的注册，使得其不需要module层的遍历。
+>
+> 后续考虑在CAN instance中加入一个额外的`void*`域成员（成员变量），其内容为module层实例的地址。这样CAN收到消息时只需要遍历所有CAN instance，对于相同的模块，可以在其回调函数内部获取CAN instance的`void*`指针并通过强制类型转换cast成模块的实例结构体指针类型，从而访问特定的模块。
+
 ## APP层(application)
 
   - TODO：
@@ -97,9 +112,13 @@ Module层主要存放的是类型定义和实例指针数组，在该层没有
     4. 增加机器人整车控制应用
   - 主要功能：实现机器人的控制
 
-  在完成BSP层和Module层后，如果在APP层没有控制代码，则代码并无实际功能。换言之，BSP层与Module层的存在是为了APP层更简单、更合理、更易于扩展和移植。本框架的初始目标即是实现：在APP层仅需思考逻辑并用无关硬件的C语言代码实现即可完成整个机器人的控制。所有需要使用的模块和算法都在Module层提供。
+ 在完成BSP层和Module层后，如果在APP层没有控制代码，则代码并无实际功能。换言之，BSP层与Module层的存在是为了APP层更简单、更合理、更易于扩展和移植。本框架的初始目标即是实现：在APP层仅需思考逻辑并用无关硬件的C语言代码实现即可完成整个机器人的控制。所有需要使用的模块和算法都在Module层提供。
 
-  - APP层按照模块（如云台、发射、底盘）可以建立对应的子文件夹，在其中完成初始化和相关逻辑功能的编写。目前尚未对app层进行开发。
+  - APP层按照模块（如云台、发射、底盘）建立对应的子文件夹，在其中完成初始化和相关逻辑功能的编写。还有用于发布指令的云台指令应用和底盘指令应用，前者应该包含一个遥控器模块和一个视觉通信模块，后者包含裁判系统模块。它们包含的模块都会处理一些指令和控制信息，因此将这两个应用从云台和底盘应用中隔离出来。这样还可以方便兼容双板。
+
+  - 单双板切换在application的`robot_def.h`中进行，修改宏定义可以切换开发板的设定模式。当设定为单板的时候，在`robot.c`中会对gimbal，chassis，shoot，gimbal_cmd，chassis_cmd五个应用都进行初始化。对于双板的情况，需要将上板配置为gimbal board，下板配置为chassis board，它们会分别初始化gimbal/shoot/gimbal_cmd和chassis/chassis_cmd。
+
+  - 对于单板的情况，所有应用之间的信息交互通过message center完成。而使用双板时，需要通过板间通信传递控制信息（默认遥控器接收机和pc在云台板，裁判系统在底盘板，因此需要互发信息）。当前通过**条件编译**来控制信息的去向（发往message center/接收，还是通过can comm发送/接收），后续考虑将双板通信纳入message center的实现中，根据`robot_def.h`的开发板定义自动处理通信，降低应用层级的逻辑复杂度。
 
     
 
@@ -283,4 +302,8 @@ HAL库初始化 --> BSP初始化 --> Application初始化 --> app调用其拥有
 
 APP会调用其所有的模块的初始化函数（注册函数），这是因为本框架的设计思想是任何模块在被注册（构造/初始化）之前，都是不存在的，当且仅当定义了一个模块结构体（也称实例）的时候，才有一个实体的概念。
 
-> 代码参考了哈工深南宫小樱战队的框架设计，在此鸣谢。
+main函数唯一需要的函数是app层的`robot.c`中的`RobotInitia()`函数，它首先会调用BSP初始化，然后进行所有应用的初始化；每个应用会调用对应模块的初始化；一些依赖通信外设的模块会将通信支持相关的bsp进行初始化。初始化结束之后实时系统启动。
+
+
+
+> **代码参考了哈工深南宫小樱战队的框架设计，在此鸣谢。**

VSCode+Ozone使用方法.md

@@ -6,9 +6,9 @@
 
 > TODO：
 >
-> 1. 添加一键编译+启用ozone调试/一键编译+下载的脚本，使得整个进一步流程自动化
+> 1. 添加一键编译+启用ozone调试d 脚本，使得整个进一步流程自动化
 > 2. 增加更多的背景知识介绍
-> 3. 增加VSCode下RTT viewer的支持和一键下载(不调试)的支持
+> 3. 增加VSCode下RTT viewer的支持
 
 
 
@@ -162,16 +162,18 @@ ITM是instrument trace macrocell指令追踪宏单元的缩写，它用于提供
 > 支持一键配置Arm GNU工具链、MinGW64（make工具）和OpenOCD！可以尝试使用这个插件替代下面的配置流程。并且，此插件还提供了一键下载、一键调试的支持，只需要选择合适的下载器配置即可，全部都是图形化界面的操作！
 >
 > 你可以尝试使用这个插件进行环境的配置。当然，环境变量仍然需要手动添加。
+>
+> ==**另外，如果你不想配置太多东西也不想了解底层的信息，可以尝试Embedded IDE插件。它支持直接在VSCode中编辑KEIL MDK的项目，相关信息请自行查阅，或直接查看EIDE的项目网站：**==[https://em-ide.com](https://em-ide.com/)
 
 - 安装STM32CubeMX，并安装F4支持包和DSP库支持包
 
 - 安装VSCode，并安装以下插件：
 
-  - C/C++：提供C/C++的调试和代码高亮支持
-  - Better C++ Syntax：提供更丰富的代码高亮和智能提示
-  - C/C++ Snippets：提供代码块（关键字）补全
-  - Cortex-Debug，Cortex-Debug: Device Support Pack - STM32F4：提供调试支持
-  - IntelliCode，Makfile Tools：提供代码高亮支持
+  - **C/C++**：提供C/C++的调试和代码高亮支持
+  - **Better C++ Syntax**：提供更丰富的代码高亮和智能提示
+  - **C/C++ Snippets**：提供代码块（关键字）补全
+  - **Cortex-Debug**，**Cortex-Debug: Device Support Pack - STM32F4**：提供调试支持
+  - **IntelliCode**，**Makfile Tools**：提供代码高亮支持
 
   ![image-20221112172157533](assets\image-20221112172157533.png)
 
@@ -445,6 +447,16 @@ VSCode `ctrl+,`进入设置，通过`搜索`找到cortex-debug插件的设置。
 
 
 
+### 更好的编辑体验
+
+建议安装以下插件：
+
+1. Hex Hover Converter，鼠标悬停在数值上的时候会自动显示其对应的16、2、10进制值和编码
+2. Hex Editor，在查看汇编代码和机器代码的时候，提供2、10、16进制转换，并且可以以16进制或2进制的格式编辑文件。
+3. GitLens，提供强大的可视化Git支持
+
+
+
 ---
 
 ---

modules/led_light/led_task.c

@@ -5,15 +5,17 @@
  * @brief 流水灯效
  * @version 0.1
  * @date 2022-11-30
- * 
+ *
  * @copyright Copyright (c) 2022
- * 
+ *
  */
 
 #include "led_task.h"
+
+#include <stdint-gcc.h>
+
 #include "bsp_led.h"
 #include "main.h"
-#include <stdint-gcc.h>
 
 #define RGB_FLOW_COLOR_CHANGE_TIME 1000
 #define RGB_FLOW_COLOR_LENGHT 6
@@ -21,7 +23,6 @@
 // 蓝 -> 绿(灭) -> 红 -> 蓝(灭) -> 绿 -> 红(灭) -> 蓝
 uint32_t RGB_flow_color[RGB_FLOW_COLOR_LENGHT + 1] = {0xFF0000FF, 0x0000FF00, 0xFFFF0000, 0x000000FF, 0xFF00FF00, 0x00FF0000, 0xFF0000FF};
 
-
 void led_RGB_flow_task()
 {
 	static float delta_alpha, delta_red, delta_green, delta_blue;
@@ -55,5 +56,4 @@ void led_RGB_flow_task()
 			aRGB_led_show(aRGB);
 		}
 	}
-
 }