增加了大量注释

bsp/adc/bsp_adc.md

@@ -0,0 +1,3 @@
+待添加adc的bsp支持,应该提供阻塞/IT/DMA的量测接口
+
+是否需要bsp_adc?由于功能非常简单,似乎可以直接使用HAL的接口,没有必要多此一举进行封装?

bsp/bsp_init.c

@@ -10,6 +10,8 @@ void BSPInit()
 {
     DWT_Init(168);
     BSPLogInit();
+
+    // 下面都是待删除的,将在实现了module之后移动到app层
     LEDInit();
     IMUTempInit();
     BuzzerInit();

bsp/bsp_init.h

@@ -3,7 +3,7 @@
 
 
 /**
- * @brief bsp层初始化统一入口
+ * @brief bsp层初始化统一入口,这里仅初始化必须的bsp组件,其他组件的初始化在各自的模块中进行
  * 
  */
 void BSPInit();

bsp/bsp_legacy_support/legacy.md

@@ -0,0 +1,3 @@
+# legacy bsp
+
+这些bsp实现将在v0.1删除,因为他们实际上都是用pwm实现的,应当放在module层,以彻底隔离bsp和CubeMX的初始化代码.之后在修改CubeMX的初始化配置之后就不再需要修改bsp的内容了,所有的修改都会通过app层的初始化配置`xxx_Init_Config_s`来实现.

bsp/can/bsp_can.c

@@ -5,23 +5,21 @@
 
 /* can instance ptrs storage, used for recv callback */
 // 在CAN产生接收中断会遍历数组,选出hcan和rxid与发生中断的实例相同的那个,调用其回调函数
-static CANInstance *can_instance[MX_REGISTER_DEVICE_CNT] = {NULL};
+static CANInstance *can_instance[CAN_MX_REGISTER_CNT] = {NULL};
 static uint8_t idx; // 全局CAN实例索引,每次有新的模块注册会自增
 
 /* ----------------two static function called by CANRegister()-------------------- */
 
 /**
- * @brief add filter to receive mesg with specific ID,called by CANRegister()
+ * @brief 添加过滤器以实现对特定id的报文的接收,会被CANRegister()调用
  *        给CAN添加过滤器后,BxCAN会根据接收到的报文的id进行消息过滤,符合规则的id会被填入FIFO触发中断
  *
- * @note there are total 28 filter and 2 FIFO in bxCAN of STM32F4 series product.
- *       here, we assign the former 14 to CAN1 and the rest for CAN2
- *       when initializing, module with odd ID will be assigned to FIFO0 while even one to FIFO1
- *       those modules which registered in CAN1 would use Filter0-13, while CAN2 use Filter14-27
+ * @note f407的bxCAN有28个过滤器,这里将其配置为前14个过滤器给CAN1使用,后14个被CAN2使用
+ *       初始化时,奇数id的模块会被分配到FIFO0,偶数id的模块会被分配到FIFO1
+ *       注册到CAN1的模块使用过滤器0-13,CAN2使用过滤器14-27
  *
- * @attention you don't have to fully understand what this function done, cause it is basically
- *            for initialization.Enjoy developing without caring about the infrastructure!
- *            if you really want to know what is happeng, contact author.
+ * @attention 你不需要完全理解这个函数的作用,因为它主要是用于初始化,在开发过程中不需要关心底层的实现
+ *            享受开发的乐趣吧!如果你真的想知道这个函数在干什么,请联系作者或自己查阅资料(请直接查阅官方的reference manual)
  *
  * @param _instance can instance owned by specific module
  */
@@ -42,11 +40,9 @@ static void CANAddFilter(CANInstance *_instance)
 }
 
 /**
- * @brief called by CANRegister before the first module being registered
- *        在第一个CAN实例初始化的时候会自动调用此函数,启动CAN服务
+ * @brief 在第一个CAN实例初始化的时候会自动调用此函数,启动CAN服务
  *
- * @note this func will handle all these thing automatically
- *       there is no need to worry about hardware initialization, we do these for you!
+ * @note 此函数会启动CAN1和CAN2,开启CAN1和CAN2的FIFO0 & FIFO1溢出通知
  *
  */
 static void CANServiceInit()
@@ -67,13 +63,16 @@ CANInstance *CANRegister(CAN_Init_Config_s *config)
     {
         CANServiceInit(); // 第一次注册,先进行硬件初始化
     }
+    if (idx >= CAN_MX_REGISTER_CNT) // 超过最大实例数
+        while (1)
+            ;
     CANInstance *instance = (CANInstance *)malloc(sizeof(CANInstance)); // 分配空间
-    memset(instance, 0, sizeof(CANInstance));
+    memset(instance, 0, sizeof(CANInstance));                           // 分配的空间未必是0,所以要先清空
     // 进行发送报文的配置
-    instance->txconf.StdId = config->tx_id;
-    instance->txconf.IDE = CAN_ID_STD;
-    instance->txconf.RTR = CAN_RTR_DATA;
-    instance->txconf.DLC = 0x08; // 默认发送长度为8
+    instance->txconf.StdId = config->tx_id; // 发送id
+    instance->txconf.IDE = CAN_ID_STD;      // 使用标准id,扩展id则使用CAN_ID_EXT(目前没有需求)
+    instance->txconf.RTR = CAN_RTR_DATA;    // 发送数据帧
+    instance->txconf.DLC = 0x08;            // 默认发送长度为8
     // 设置回调函数和接收发送id
     instance->can_handle = config->can_handle;
     instance->tx_id = config->tx_id; // 好像没用,可以删掉
@@ -87,10 +86,11 @@ CANInstance *CANRegister(CAN_Init_Config_s *config)
     return instance; // 返回can实例指针
 }
 
-/* TODO:目前似乎封装过度,应该添加一个指向tx_buff的指针,tx_buff不应该由CAN instance保存 */
+/* @todo 目前似乎封装过度,应该添加一个指向tx_buff的指针,tx_buff不应该由CAN instance保存 */
+/* 如果让CANinstance保存txbuff,会增加一次复制的开销 */
 void CANTransmit(CANInstance *_instance)
 {
-    while (HAL_CAN_GetTxMailboxesFreeLevel(_instance->can_handle) == 0)
+    while (HAL_CAN_GetTxMailboxesFreeLevel(_instance->can_handle) == 0) // 等待邮箱空闲
         ;
     // tx_mailbox会保存实际填入了这一帧消息的邮箱,但是知道是哪个邮箱发的似乎也没啥用
     HAL_CAN_AddTxMessage(_instance->can_handle, &_instance->txconf, _instance->tx_buff, &_instance->tx_mailbox);
@@ -107,22 +107,23 @@ void CANSetDLC(CANInstance *_instance, uint8_t length)
 /* -----------------------belows are callback definitions--------------------------*/
 
 /**
- * @brief this func will recv data from @param:fifox to a tmp can_rx_buff
- *        then, all the instances will be polling to check which should recv this pack of data
+ * @brief 此函数会被下面两个函数调用,用于处理FIFO0和FIFO1溢出中断(说明收到了新的数据)
+ *        所有的实例都会被遍历,找到can_handle和rx_id相等的实例时,调用该实例的回调函数
  *
  * @param _hcan
  * @param fifox passed to HAL_CAN_GetRxMessage() to get mesg from a specific fifo
  */
 static void CANFIFOxCallback(CAN_HandleTypeDef *_hcan, uint32_t fifox)
 {
-    static uint8_t can_rx_buff[8];
-    static CAN_RxHeaderTypeDef rxconf;
-    HAL_CAN_GetRxMessage(_hcan, fifox, &rxconf, can_rx_buff);
+    static uint8_t can_rx_buff[8];     // 用于保存接收到的数据,static是为了减少栈空间占用,避免重复分配
+    static CAN_RxHeaderTypeDef rxconf; // 同上
+
+    HAL_CAN_GetRxMessage(_hcan, fifox, &rxconf, can_rx_buff); // 从FIFO中获取数据
     for (size_t i = 0; i < idx; ++i)
     { // 两者相等说明这是要找的实例
         if (_hcan == can_instance[i]->can_handle && rxconf.StdId == can_instance[i]->rx_id)
         {
-            if (can_instance[i]->can_module_callback != NULL)
+            if (can_instance[i]->can_module_callback != NULL) // 回调函数不为空就调用
             {
                 can_instance[i]->rx_len = rxconf.DLC;                      // 保存接收到的数据长度
                 memcpy(can_instance[i]->rx_buff, can_rx_buff, rxconf.DLC); // 消息拷贝到对应实例
@@ -133,8 +134,13 @@ static void CANFIFOxCallback(CAN_HandleTypeDef *_hcan, uint32_t fifox)
     }
 }
 
-/* ATTENTION: two CAN devices in STM32 share two FIFOs */
-/* functions below will call CANFIFOxCallback() to further process message from a specific CAN device */
+/**
+ * @brief 注意,STM32的两个CAN设备共享两个FIFO
+ * 下面两个函数是HAL库中的回调函数,他们声明为__weak,这里对他们进行重载(重写)
+ * 当FIFO0或FIFO1溢出时会调用这两个函数
+ */
+// 下面的函数会调用CANFIFOxCallback()来进一步处理来自特定CAN设备的消息
+
 /**
  * @brief rx fifo callback. Once FIFO_0 is full,this func would be called
  *
@@ -142,7 +148,7 @@ static void CANFIFOxCallback(CAN_HandleTypeDef *_hcan, uint32_t fifox)
  */
 void HAL_CAN_RxFifo0MsgPendingCallback(CAN_HandleTypeDef *hcan)
 {
-    CANFIFOxCallback(hcan, CAN_RX_FIFO0);
+    CANFIFOxCallback(hcan, CAN_RX_FIFO0); // 调用我们自己写的函数来处理消息
 }
 
 /**
@@ -152,5 +158,5 @@ void HAL_CAN_RxFifo0MsgPendingCallback(CAN_HandleTypeDef *hcan)
  */
 void HAL_CAN_RxFifo1MsgPendingCallback(CAN_HandleTypeDef *hcan)
 {
-    CANFIFOxCallback(hcan, CAN_RX_FIFO1);
+    CANFIFOxCallback(hcan, CAN_RX_FIFO1); // 调用我们自己写的函数来处理消息
 }

bsp/can/bsp_can.h

@@ -4,10 +4,10 @@
 #include <stdint.h>
 #include "can.h"
 
-#define MX_REGISTER_DEVICE_CNT 12  // maximum number of device can be registered to CAN service
-                                   // this number depends on the load of CAN bus.
-#define MX_CAN_FILTER_CNT (2 * 14) // temporarily useless
-#define DEVICE_CAN_CNT 2           // CAN1,CAN2
+// 最多能够支持的CAN设备数
+#define CAN_MX_REGISTER_CNT 16     // 这个数量取决于CAN总线的负载
+#define MX_CAN_FILTER_CNT (2 * 14) // 最多可以使用的CAN过滤器数量,目前远不会用到这么多
+#define DEVICE_CAN_CNT 2           // 根据板子设定,F407IG有CAN1,CAN2,因此为2;F334只有一个,则设为1
 
 /* can instance typedef, every module registered to CAN should have this variable */
 #pragma pack(1)
@@ -23,20 +23,28 @@ typedef struct _
     uint8_t rx_len;                // 接收长度,可能为0-8
     // 接收的回调函数,用于解析接收到的数据
     void (*can_module_callback)(struct _ *); // callback needs an instance to tell among registered ones
-    void* id; // 使用can外设的
+    void *id;                                // 使用can外设的
 } CANInstance;
 #pragma pack()
 
-/* this structure is used for initialization */
+/* CAN实例初始化结构体,将此结构体指针传入注册函数 */
 typedef struct
 {
-    CAN_HandleTypeDef *can_handle;
-    uint32_t tx_id;
-    uint32_t rx_id;
-    void (*can_module_callback)(CANInstance *);
-    void* id;
+    CAN_HandleTypeDef *can_handle;              // can句柄
+    uint32_t tx_id;                             // 发送id
+    uint32_t rx_id;                             // 接收id
+    void (*can_module_callback)(CANInstance *); // 处理接收数据的回调函数
+    void *id;                                   // 拥有can实例的模块地址,用于区分不同的模块(如果有需要的话),如果不需要可以不传入
 } CAN_Init_Config_s;
 
+/**
+ * @brief Register a module to CAN service,remember to call this before using a CAN device
+ *        注册(初始化)一个can实例,需要传入初始化配置的指针.
+ * @param config init config
+ * @return CANInstance* can instance owned by module
+ */
+CANInstance *CANRegister(CAN_Init_Config_s *config);
+
 /**
  * @brief 修改CAN发送报文的数据帧长度;注意最大长度为8,在没有进行修改的时候,默认长度为8
  *
@@ -53,12 +61,4 @@ void CANSetDLC(CANInstance *_instance, uint8_t length);
  */
 void CANTransmit(CANInstance *_instance);
 
-/**
- * @brief Register a module to CAN service,remember to call this before using a CAN device
- *        注册(初始化)一个can实例,需要传入初始化配置的指针.
- * @param config init config
- * @return CANInstance* can instance owned by module
- */
-CANInstance *CANRegister(CAN_Init_Config_s *config);
-
 #endif

bsp/can/bsp_can.md

@@ -34,6 +34,7 @@ typedef struct _
     uint8_t rx_buff[8];
     uint32_t rx_id;
     void (*can_module_callback)(struct _*);
+    void* id;
 } can_instance;
 
 typedef struct 
@@ -42,6 +43,7 @@ typedef struct
     uint32_t tx_id;
     uint32_t rx_id;
     void (*can_module_callback)(can_instance*);
+    void* id;
 } can_instance_config;
 
 typedef void (*can_callback)(can_instance*);

bsp/dwt/bsp_dwt.md

@@ -0,0 +1,3 @@
+# bsp_dwt
+
+DWT是stm32内部的一个"隐藏资源",他的用途是给下载器提供准确的定时,从而为调试信息加上时间戳.

bsp/gpio/bsp_gpio.h

@@ -0,0 +1,2 @@
+#include "gpio.h"
+

bsp/iic/bsp_iic.c

@@ -5,37 +5,11 @@
 static uint8_t idx = 0; // 配合中断以及初始化
 static IICInstance *iic_instance[IIC_DEVICE_CNT] = {NULL};
 
-/**
- * @brief 接收完成回调函数
- *
- * @param hi2c handle
- */
-void HAL_I2C_MasterRxCpltCallback(I2C_HandleTypeDef *hi2c)
-{
-    // 如果是当前i2c硬件发出的complete,且dev_address和之前发起接收的地址相同,同时回到函数不为空, 则调用回调函数
-    for (uint8_t i = 0; i < idx; i++)
-    {
-        if (iic_instance[i]->handle == hi2c && hi2c->Devaddress == iic_instance[i]->dev_address)
-        {
-            if (iic_instance[i]->callback != NULL)
-                iic_instance[i]->callback(iic_instance[i]);
-            return;
-        }
-    }
-}
-
-/**
- * @brief 仅做形式上的封装,仍然使用HAL_I2C_MasterRxCpltCallback
- *
- * @param hi2c handle
- */
-void HAL_I2C_MemRxCpltCallback(I2C_HandleTypeDef *hi2c)
-{
-    HAL_I2C_MasterRxCpltCallback(hi2c);
-}
-
 IICInstance *IICRegister(IIC_Init_Config_s *conf)
 {
+    if (idx >= MX_IIC_SLAVE_CNT) // 超过最大实例数
+        while (1)                // 酌情增加允许的实例上限,也有可能是内存泄漏
+            ;
     // 申请到的空间未必是0, 所以需要手动初始化
     IICInstance *instance = (IICInstance *)malloc(sizeof(IICInstance));
     instance = (IICInstance *)malloc(sizeof(IICInstance));
@@ -53,9 +27,9 @@ IICInstance *IICRegister(IIC_Init_Config_s *conf)
 
 void IICSetMode(IICInstance *iic, IIC_Work_Mode_e mode)
 { // HAL自带重入保护,不需要手动终止或等待传输完成
-    if (iic->work_mode != mode) // 如果不同才需要修改
+    if (iic->work_mode != mode)
     {
-        iic->work_mode = mode;
+        iic->work_mode = mode; // 如果不同才需要修改
     }
 }
 
@@ -65,13 +39,14 @@ void IICTransmit(IICInstance *iic, uint8_t *data, uint16_t size, IIC_Seq_Mode_e
         while (1)
             ; // 未知传输模式, 程序停止
 
+    // 根据不同的工作模式进行不同的传输
     switch (iic->work_mode)
     {
     case IIC_BLOCK_MODE:
         if (seq_mode != IIC_RELEASE)
             while (1)
-                ; // 阻塞模式下不支持HOLD ON模式!!!
-        HAL_I2C_Master_Transmit(iic->handle, iic->dev_address, data, size, 100);
+                ;                                                                // 阻塞模式下不支持HOLD ON模式!!!只能传输完成后立刻释放总线
+        HAL_I2C_Master_Transmit(iic->handle, iic->dev_address, data, size, 100); // 默认超时时间100ms
         break;
     case IIC_IT_MODE:
         if (seq_mode == IIC_RELEASE)
@@ -88,7 +63,6 @@ void IICTransmit(IICInstance *iic, uint8_t *data, uint16_t size, IIC_Seq_Mode_e
     default:
         while (1)
             ; // 未知传输模式, 程序停止
-        break;
     }
 }
 
@@ -108,7 +82,7 @@ void IICReceive(IICInstance *iic, uint8_t *data, uint16_t size, IIC_Seq_Mode_e s
         if (seq_mode != IIC_RELEASE)
             while (1)
                 ; // 阻塞模式下不支持HOLD ON模式!!!
-        HAL_I2C_Master_Receive(iic->handle, iic->dev_address, data, size, 100);
+        HAL_I2C_Master_Receive(iic->handle, iic->dev_address, data, size, 100); // 默认超时时间100ms
         break;
     case IIC_IT_MODE:
         if (seq_mode == IIC_RELEASE)
@@ -133,11 +107,11 @@ void IICAcessMem(IICInstance *iic, uint8_t mem_addr, uint8_t *data, uint16_t siz
 {
     if (mem_mode == IIC_WRITE_MEM)
     {
-        HAL_I2C_Mem_Write(iic->handle, iic->dev_address, mem_addr, I2C_MEMADD_SIZE_8BIT, data, size, 1000);
+        HAL_I2C_Mem_Write(iic->handle, iic->dev_address, mem_addr, I2C_MEMADD_SIZE_8BIT, data, size, 100);
     }
     else if (mem_mode == IIC_READ_MEM)
     {
-        HAL_I2C_Mem_Read(iic->handle, iic->dev_address, mem_addr, I2C_MEMADD_SIZE_8BIT, data, size, 1000);
+        HAL_I2C_Mem_Read(iic->handle, iic->dev_address, mem_addr, I2C_MEMADD_SIZE_8BIT, data, size, 100);
     }
     else
     {
@@ -145,3 +119,32 @@ void IICAcessMem(IICInstance *iic, uint8_t mem_addr, uint8_t *data, uint16_t siz
             ; // 未知模式, 程序停止
     }
 }
+
+/**
+ * @brief IIC接收完成回调函数
+ *
+ * @param hi2c handle
+ */
+void HAL_I2C_MasterRxCpltCallback(I2C_HandleTypeDef *hi2c)
+{
+    // 如果是当前i2c硬件发出的complete,且dev_address和之前发起接收的地址相同,同时回到函数不为空, 则调用回调函数
+    for (uint8_t i = 0; i < idx; i++)
+    {   
+        if (iic_instance[i]->handle == hi2c && hi2c->Devaddress == iic_instance[i]->dev_address)
+        {
+            if (iic_instance[i]->callback != NULL) // 回调函数不为空
+                iic_instance[i]->callback(iic_instance[i]);
+            return;
+        }
+    }
+}
+
+/**
+ * @brief 仅做形式上的封装,仍然使用HAL_I2C_MasterRxCpltCallback
+ *
+ * @param hi2c handle
+ */
+void HAL_I2C_MemRxCpltCallback(I2C_HandleTypeDef *hi2c)
+{
+    HAL_I2C_MasterRxCpltCallback(hi2c);
+}

bsp/iic/bsp_iic.md

@@ -0,0 +1,7 @@
+# bsp iic
+
+关于I2C的序列传输,Restart condition和总线仲裁,请看:
+
+https://blog.csdn.net/NeoZng/article/details/128496694
+
+https://blog.csdn.net/NeoZng/article/details/128486366

bsp/log/bsp_log.h

@@ -1,10 +1,27 @@
 #ifndef _BSP_LOG_H
 #define _BSP_LOG_H
 
+/**
+ * @brief 初始化日志功能,在操作系统启动之前调用
+ * 
+ */
 void BSPLogInit();
 
+/**
+ * @brief 通过segger RTT打印日志,支持格式化输出,格式化输出的实现参考printf
+ * 
+ * @param fmt 
+ * @param ... 
+ * @return int 
+ */
 int PrintLog(const char *fmt, ...);
 
+/**
+ * @brief 利用sprintf(),将float转换为字符串进行打印
+ * 
+ * @param str 转换后的字符串
+ * @param va 待转换的float
+ */
 void Float2Str(char *str, float va);
 
 #endif

bsp/pwm/bsp_pwm.c

@@ -13,9 +13,8 @@ void HAL_TIM_PWM_PulseFinishedCallback(TIM_HandleTypeDef *htim)
         if (pwm_instance[i]->htim == htim && htim->Channel == pwm_instance[i]->channel)
         {
             if (pwm_instance[i]->callback) // 如果有回调函数
-            {
                 pwm_instance[i]->callback(pwm_instance[i]);
-            }
+
             return; // 一次只能有一个通道的中断,所以直接返回
         }
     }
@@ -23,6 +22,9 @@ void HAL_TIM_PWM_PulseFinishedCallback(TIM_HandleTypeDef *htim)
 
 PWMInstance *PWMRegister(PWM_Init_Config_s *config)
 {
+    if (idx >= PWM_DEVICE_CNT) // 超过最大实例数,考虑增加或查看是否有内存泄漏
+        while (1)
+            ;
     PWMInstance *pwm = (PWMInstance *)malloc(sizeof(PWMInstance));
     memset(pwm, 0, sizeof(PWMInstance));
 
@@ -33,8 +35,8 @@ PWMInstance *PWMRegister(PWM_Init_Config_s *config)
     pwm->callback = config->callback;
     pwm->id = config->id;
 
-    HAL_TIM_PWM_Start(pwm->htim, pwm->channel);
-    __HAL_TIM_SetCompare(pwm->htim, pwm->channel, pwm->pulse);
+    HAL_TIM_PWM_Start(pwm->htim, pwm->channel); // 启动PWM
+    __HAL_TIM_SetCompare(pwm->htim, pwm->channel, pwm->pulse); // 设置占空比,初始为0
 
     pwm_instance[idx++] = pwm;
     return pwm;

bsp/pwm/bsp_pwm.h

@@ -4,7 +4,7 @@
 #include "tim.h"
 #include "stdint.h"
 
-#define PWM_DEVICE_CNT 16 // PWM实例数量
+#define PWM_DEVICE_CNT 16 // 最大支持的PWM实例数量
 
 /* pwm实例结构体 */
 typedef struct pwm_ins_temp
@@ -15,6 +15,9 @@ typedef struct pwm_ins_temp
     uint32_t pulse;                          // 脉宽
     void (*callback)(struct pwm_ins_temp *); // DMA传输完成回调函数
     void *id;                                // 实例ID
+
+    // 后续还要添加更多的参数,以提供更直观的封装,比如直接按照百分比设置占空比,直接设置频率等
+    // ...
 } PWMInstance;
 
 typedef struct
@@ -49,6 +52,7 @@ void PWMStart(PWMInstance *pwm);
  */
 void PWMStop(PWMInstance *pwm);
 
+// @todo 这三个函数还需要进一步封装,协调好三者之间的关系
 /**
  * @brief 设置pwm脉宽
  *
@@ -56,6 +60,8 @@ void PWMStop(PWMInstance *pwm);
  * @param pulse 脉宽
  */
 void PWMSetPulse(PWMInstance *pwm, uint32_t pulse);
+void PWMSetPeriod(PWMInstance *pwm, uint32_t period);       // 未实现
+void PWMSetPrescaler(PWMInstance *pwm, uint32_t prescaler); // 未实现
 
 /**
  * @brief 启动pwm dma传输

bsp/spi/bsp_spi.c

@@ -6,44 +6,14 @@
 static SPIInstance *spi_instance[SPI_DEVICE_CNT] = {NULL};
 static uint8_t idx = 0; // 配合中断以及初始化
 
-/**
- * @brief 当SPI接收完成,将会调用此回调函数,可以进行协议解析或其他必须的数据处理等
- *
- * @param hspi spi handle
- */
-void HAL_SPI_RxCpltCallback(SPI_HandleTypeDef *hspi)
-{
-    for (size_t i = 0; i < idx; i++)
-    {
-        // 如果是当前spi硬件发出的complete,且cs_pin为低电平(说明正在传输),则尝试调用回调函数
-        if (spi_instance[i]->spi_handle == hspi &&
-            HAL_GPIO_ReadPin(spi_instance[i]->GPIO_cs, spi_instance[i]->cs_pin) == GPIO_PIN_RESET)
-        {
-            if (spi_instance[i]->callback) // 回调函数不为空, 则调用回调函数
-            {
-                // 先拉高片选,结束传输
-                HAL_GPIO_WritePin(spi_instance[i]->GPIO_cs, spi_instance[i]->cs_pin, GPIO_PIN_SET);
-                spi_instance[i]->callback(spi_instance[i]);
-            }
-            return;
-        }
-    }
-}
-
-/**
- * @brief 和RxCpltCallback共用解析即可,这里只是形式上封装一下,不用重复写
- *
- * @param hspi spi handle
- */
-void HAL_SPI_TxRxCpltCallback(SPI_HandleTypeDef *hspi)
-{
-    HAL_SPI_RxCpltCallback(hspi);
-}
-
 SPIInstance *SPIRegister(SPI_Init_Config_s *conf)
 {
+    if (idx >= MX_SPI_BUS_SLAVE_CNT) // 超过最大实例数
+        while (1)
+            ;
     SPIInstance *instance = (SPIInstance *)malloc(sizeof(SPIInstance));
     memset(instance, 0, sizeof(SPIInstance));
+
     instance->spi_handle = conf->spi_handle;
     instance->GPIO_cs = conf->GPIO_cs;
     instance->cs_pin = conf->cs_pin;
@@ -57,7 +27,7 @@ SPIInstance *SPIRegister(SPI_Init_Config_s *conf)
 
 void SPITransmit(SPIInstance *spi_ins, uint8_t *ptr_data, uint8_t len)
 {
-    // 拉低片选,开始传输
+    // 拉低片选,开始传输(选中从机)
     HAL_GPIO_WritePin(spi_ins->GPIO_cs, spi_ins->cs_pin, GPIO_PIN_RESET);
     switch (spi_ins->spi_work_mode)
     {
@@ -68,7 +38,7 @@ void SPITransmit(SPIInstance *spi_ins, uint8_t *ptr_data, uint8_t len)
         HAL_SPI_Transmit_IT(spi_ins->spi_handle, ptr_data, len);
         break;
     case SPI_BLOCK_MODE:
-        HAL_SPI_Transmit(spi_ins->spi_handle, ptr_data, len, 10);
+        HAL_SPI_Transmit(spi_ins->spi_handle, ptr_data, len, 50); // 默认50ms超时
         // 阻塞模式不会调用回调函数,传输完成后直接拉高片选结束
         HAL_GPIO_WritePin(spi_ins->GPIO_cs, spi_ins->cs_pin, GPIO_PIN_SET);
         break;
@@ -122,7 +92,7 @@ void SPITransRecv(SPIInstance *spi_ins, uint8_t *ptr_data_rx, uint8_t *ptr_data_
         HAL_SPI_TransmitReceive_IT(spi_ins->spi_handle, ptr_data_tx, ptr_data_rx, len);
         break;
     case SPI_BLOCK_MODE:
-        HAL_SPI_TransmitReceive(spi_ins->spi_handle, ptr_data_tx, ptr_data_rx, len, 10);
+        HAL_SPI_TransmitReceive(spi_ins->spi_handle, ptr_data_tx, ptr_data_rx, len, 50); // 默认50ms超时
         // 阻塞模式不会调用回调函数,传输完成后直接拉高片选结束
         HAL_GPIO_WritePin(spi_ins->GPIO_cs, spi_ins->cs_pin, GPIO_PIN_SET);
         break;
@@ -144,3 +114,37 @@ void SPISetMode(SPIInstance *spi_ins, SPI_TXRX_MODE_e spi_mode)
         spi_ins->spi_work_mode = spi_mode;
     }
 }
+
+/**
+ * @brief 当SPI接收完成,将会调用此回调函数,可以进行协议解析或其他必须的数据处理等
+ *
+ * @param hspi spi handle
+ */
+void HAL_SPI_RxCpltCallback(SPI_HandleTypeDef *hspi)
+{
+    for (size_t i = 0; i < idx; i++)
+    {
+        // 如果是当前spi硬件发出的complete,且cs_pin为低电平(说明正在传输),则尝试调用回调函数
+        if (spi_instance[i]->spi_handle == hspi && // 显然同一时间一条总线只能有一个从机在接收数据
+            HAL_GPIO_ReadPin(spi_instance[i]->GPIO_cs, spi_instance[i]->cs_pin) == GPIO_PIN_RESET)
+        {
+            if (spi_instance[i]->callback != NULL) // 回调函数不为空, 则调用回调函数
+            {
+                // 先拉高片选,结束传输
+                HAL_GPIO_WritePin(spi_instance[i]->GPIO_cs, spi_instance[i]->cs_pin, GPIO_PIN_SET);
+                spi_instance[i]->callback(spi_instance[i]);
+            }
+            return;
+        }
+    }
+}
+
+/**
+ * @brief 和RxCpltCallback共用解析即可,这里只是形式上封装一下,不用重复写
+ *        这是对HAL库的__weak函数的重写,传输使用IT或DMA模式,在传输完成时会调用此函数
+ * @param hspi spi handle
+ */
+void HAL_SPI_TxRxCpltCallback(SPI_HandleTypeDef *hspi)
+{
+    HAL_SPI_RxCpltCallback(hspi); // 直接调用接收完成的回调函数
+}

bsp/spi/bsp_spi.h

@@ -21,15 +21,15 @@ typedef struct spi_ins_temp
     GPIO_TypeDef *GPIO_cs;         // 片选信号对应的GPIO,如GPIOA,GPIOB等等
     uint16_t cs_pin;               // 片选信号对应的引脚号,GPIO_PIN_1,GPIO_PIN_2等等
 
-    SPI_TXRX_MODE_e spi_work_mode;           // 传输工作模式
-    uint8_t rx_size;                         // 本次接收的数据长度
-    uint8_t *rx_buffer;                      // 本次接收的数据缓冲区
-    void (*callback)(struct spi_ins_temp *); // 接收回调函数
+    SPI_TXRX_MODE_e spi_work_mode; // 传输工作模式
+    uint8_t rx_size;               // 本次接收的数据长度
+    uint8_t *rx_buffer;            // 本次接收的数据缓冲区
 
-    void *id; // 模块指针
+    void (*callback)(struct spi_ins_temp *); // 接收回调函数
+    void *id;                                // 模块指针
 } SPIInstance;
 
-/* rx data resolve callback*/
+/* 接收回调函数定义,包含SPI的module按照此格式构建回调函数 */
 typedef void (*spi_rx_callback)(SPIInstance *);
 
 /* SPI初始化配置,其实基本和SPIIstance一模一样,为了代码风格统一因此再次定义 */

bsp/usart/bsp_usart.c

@@ -34,6 +34,9 @@ static void USARTServiceInit(USARTInstance *_instance)
 
 USARTInstance *USARTRegister(USART_Init_Config_s *init_config)
 {
+    if (idx >= DEVICE_USART_CNT) // 超过最大实例数
+        while (1)
+            ;
     USARTInstance *instance = (USARTInstance *)malloc(sizeof(USARTInstance));
     memset(instance, 0, sizeof(USARTInstance));
 

bsp/usart/bsp_usart.h

@@ -5,15 +5,14 @@
 #include "main.h"
 
 #define DEVICE_USART_CNT 3     // C板至多分配3个串口
-#define USART_RXBUFF_LIMIT 256 // if your protocol needs bigger buff, modify here
+#define USART_RXBUFF_LIMIT 256 // 如果协议需要更大的buff,请修改这里
 
-/* application callback,which resolves specific protocol,解析协议的回调函数 */
+// 模块回调函数,用于解析协议
 typedef void (*usart_module_callback)();
 
-/* USARTInstance struct,each app would have one instance */
+// 串口实例结构体,每个module都要包含一个实例
 typedef struct
 {
-    // 更新:弃用malloc方案,使用了固定大小的数组方便debug时查看
     uint8_t recv_buff[USART_RXBUFF_LIMIT]; // 预先定义的最大buff大小,如果太小请修改USART_RXBUFF_LIMIT
     uint8_t recv_buff_size;                // 模块接收一包数据的大小
     UART_HandleTypeDef *usart_handle;      // 实例对应的usart_handle
@@ -36,13 +35,10 @@ typedef struct
 USARTInstance *USARTRegister(USART_Init_Config_s *init_config);
 
 /**
- * @todo 是否需要进一步封装发送buff和size,并创建一个串口任务以一定频率自动发送?
- *       若采用此方法,则串口实例的拥有者仅需要在自己的任务中设置发送值,不需要关心发送buffer大小以及何时发送.
+ * @brief 通过调用该函数可以发送一帧数据,需要传入一个usart实例,发送buff以及这一帧的长度
  *
- * @brief api for sending data through a specific serial port,indicated by the first parameter:id
- *        通过调用该函数可以发送一帧数据,需要传入一个usart实例,发送buff以及这一帧的长度
- *
- * @param id specify which usart would be used
+ * @param _instance 串口实例
+ * @param send_buf 待发送数据的buffer
  * @param send_size how many bytes to send
  */
 void USARTSend(USARTInstance *_instance, uint8_t *send_buf, uint16_t send_size);