Files
motor-controller/AGENTS.md
T

8.4 KiB
Raw Blame History

AGENTS.md - CloudPlant 项目开发指南

项目概述

CloudPlant 是基于 STM32F407 的嵌入式项目,使用 STM32CubeMX + CMake + FreeRTOS 开发框架,集成 JY-901 姿态传感器。


1. 构建命令

编译项目

# 编译 Debug 版本(默认)
cmake --build build\Debug

# 编译 Release 版本
cmake --build build\Release

# 清理并重新编译
cmake --build build\Debug --clean-first

烧写固件

# 烧写默认路径 (build/Debug/CloudPlant.elf)
python flash.py

# 烧写指定文件
python flash.py build\Debug\CloudPlant.elf

# 仅擦除芯片
python flash.py --erase-only

构建后操作

# 生成 bin 文件
arm-none-eabi-objcopy -O binary build\Debug\CloudPlant.elf build\Debug\CloudPlant.bin

# 生成 hex 文件
arm-none-eabi-objcopy -O ihex build\Debug\CloudPlant.elf build\Debug\CloudPlant.hex

2. 项目结构

CloudPlant/
├── Core/                    # STM32CubeMX 生成的核心代码
│   ├── Src/                # 源文件 (main.c, freertos.c, i2c.c 等)
│   └── Inc/                # 头文件
├── Drivers/                # STM32 HAL 库和 CMSIS
├── Middlewares/            # FreeRTOS 等中间件
├── User/                   # 用户自定义代码(⭐ 主要修改区域)
│   └── Sensors/
│       ├── j901p.c/h/reg.h    # JY-901 官方 SDK
│       └── j901p_hal.c/h      # HAL 硬件 I2C 适配层
├── cmake/                  # CMake 配置文件
├── build/                  # 编译输出目录
├── docs/                   # 项目文档
├── CMakeLists.txt          # CMake 主配置(用户可修改)
├── CloudPlant.ioc          # STM32CubeMX 项目文件
├── flash.py                # 烧写脚本
└── AGENTS.md               # 本文件

3. 代码风格指南

3.1 命名约定

文件命名:

  • 源文件:小写字母 + 下划线 (如 j901p_hal.c)
  • 头文件:小写字母 + 下划线 (如 j901p_hal.h)

变量命名:

// 局部变量:小写字母 + 下划线
int32_t acc_scaled;
uint8_t data_buffer[256];

// 全局变量:加 s_ 前缀
static volatile uint8_t s_cDataUpdate;

// 静态变量:加 s_ 前缀
static int32_t s_sensorValue;

// 句柄变量:加 Handle 后缀
I2C_HandleTypeDef hi2c2;
UART_HandleTypeDef huart1;

函数命名:

// CubeMX 风格:MX_前缀 + 外设名
void MX_I2C2_Init(void);
void MX_USART1_UART_Init(void);

// HAL 库风格:HAL_前缀 + 功能
HAL_I2C_Mem_Write();
HAL_UART_Transmit();

// 用户函数:大驼峰命名
void StartControlTask(void *argument);
int32_t J901P_HAL_Init(uint8_t i2cAddr);

宏定义:

// 全大写 + 下划线
#define WIT_HAL_OK      (0)
#define WIT_DATA_BUFF_SIZE  256

3.2 代码格式

缩进:2 空格(不使用 Tab)

大括号:K&R 风格

void function(void)
{
    if (condition) {
        // code
    } else {
        // code
    }
}

行宽:最大 100 字符

指针和引用:

int *ptr;      // 正确:* 靠近类型
int* ptr;      // 避免

3.3 类型使用

优先使用固定宽度类型:

#include <stdint.h>

uint8_t data;      // 代替 unsigned char
int16_t value;     // 代替 short
uint32_t count;    // 代替 unsigned int
int32_t scaled;    // 代替 long

避免隐式类型转换:

// 正确:显式转换
int32_t acc_scaled = (int32_t)raw * 16 * 1000 / 32768;

// 避免:隐式转换可能导致溢出
int32_t acc_scaled = raw * 16 * 1000 / 32768;

3.4 错误处理

HAL 库错误处理:

if (HAL_I2C_Mem_Write(&hi2c2, addr, reg, size, data, timeout) != HAL_OK) {
    // 处理错误
    return WIT_HAL_ERROR;
}

返回值约定:

#define WIT_HAL_OK      (0)     // 成功
#define WIT_HAL_ERROR   (-3)    // 通用错误
#define WIT_HAL_TIMEOUT (-2)    // 超时
#define WIT_HAL_INVAL   (-6)    // 无效参数

3.5 注释规范

文件头注释:

/**
  * @file    j901p_hal.c
  * @brief   JY-901 HAL 硬件 I2C 适配层
  * @author  CloudPlant Team
  * @version v1.0
  */

函数注释:

/**
  * @brief  初始化 JY-901 传感器
  * @param  i2cAddr: I2C 设备地址(默认 0x50)
  * @retval 成功返回 WIT_HAL_OK,失败返回 WIT_HAL_ERROR
  */
int32_t J901P_HAL_Init(uint8_t i2cAddr);

行内注释:

// 计算加速度:raw / 32768 * 16g
int32_t acc_scaled = (raw * 16 * 1000) / 32768;

4. STM32CubeMX 使用规范

4.1 文件修改原则

⚠️ 不要直接修改的文件(会被 CubeMX 覆盖):

  • Core/Src/main.c 的 USER CODE 区域之外
  • Core/Src/freertos.c 的 USER CODE 区域之外
  • Core/Src/i2c.c, usart.c, gpio.c 等外设驱动
  • Core/Inc/*.h 头文件

✅ 应该修改的位置:

  • 所有 /* USER CODE BEGIN xxx */ 和 /* USER CODE END xxx */ 之间
  • User/ 目录下的文件(完全由用户控制)
  • CMakeLists.txt(用户可自由修改)

4.2 添加新功能的正确流程

  1. 在 CubeMX 中配置外设

    • 打开 CloudPlant.ioc
    • 配置所需外设(I2C, UART, TIM 等)
    • 生成代码
  2. 在 USER CODE 区域添加代码

    /* USER CODE BEGIN Includes */
    #include "my_sensor.h"
    /* USER CODE END Includes */
    
    /* USER CODE BEGIN PV */
    static int32_t sensorData;
    /* USER CODE END PV */
    
    /* USER CODE BEGIN 0 */
    void SensorInit(void) {
        // 初始化代码
    }
    /* USER CODE END 0 */
    
  3. 在 CMakeLists.txt 添加源文件

    target_sources(${CMAKE_PROJECT_NAME} PRIVATE
        User/Sensors/my_sensor.c
    )
    
    target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
        User/Sensors
    )
    

5. FreeRTOS 开发指南

5.1 任务创建

在 freertos.c 中:

/* USER CODE BEGIN Header_StartMyTask */
/**
* @brief Function implementing the myTask thread.
* @param argument: Not used
* @retval None
*/
/* USER CODE END Header_StartMyTask */

void StartMyTask(void *argument)
{
  /* USER CODE BEGIN StartMyTask */
  for(;;)
  {
    // 任务代码
    osDelay(100);
  }
  /* USER CODE END StartMyTask */
}

5.2 任务优先级

osPriorityIdle     = 0,   // 空闲任务
osPriorityLow      = 1,   // 低优先级
osPriorityNormal   = 2,   // 正常优先级(默认)
osPriorityHigh     = 3,   // 高优先级
osPriorityRealtime = 4,   // 实时优先级

5.3 常用 API

// 延时
osDelay(100);              // 延时 100ms
osDelayUntil(&ticks, 100); // 精确周期延时

// 信号量
osSemaphoreId_t sem;
sem = osSemaphoreNew(10, 10, NULL);
osSemaphoreAcquire(sem, osWaitForever);
osSemaphoreRelease(sem);

// 消息队列
osMessageQueueId_t queue;
queue = osMessageQueueNew(10, sizeof(uint32_t), NULL);
osMessageQueuePut(queue, &data, 0, 0);
osMessageQueueGet(queue, &data, NULL, 0);

6. 调试技巧

6.1 串口打印

// 基本打印
const uint8_t msg[] = "Hello\r\n";
HAL_UART_Transmit(&huart1, msg, sizeof(msg)-1, 100);

// 格式化打印(定点数,避免浮点)
int32_t value = 1234;
char buf[20];
int len = snprintf(buf, sizeof(buf), "Value: %ld\r\n", value);
HAL_UART_Transmit(&huart1, (uint8_t*)buf, len, 100);

// 定点数小数打印
int32_t scaled = 12345;  // 实际值 12.345
int int_part = scaled / 1000;
int frac_part = scaled % 1000;
snprintf(buf, sizeof(buf), "Value: %d.%03d\r\n", int_part, frac_part);

6.2 I2C 调试

// 扫描 I2C 设备
for (uint8_t addr = 0; addr < 128; addr++) {
    if (HAL_I2C_IsDeviceReady(&hi2c2, addr << 1, 1, 10) == HAL_OK) {
        // 找到设备
        printf("Found device at 0x%02X\r\n", addr);
    }
}

6.3 常见问题

Q: 浮点数 printf 不输出?

  • ARM GCC 默认不支持浮点 printf
  • 使用定点数格式(推荐)
  • 或添加链接选项:-u _printf_float

Q: HardFault 错误?

  • 检查数组越界
  • 检查栈溢出(增加任务栈大小)
  • 检查空指针解引用

Q: I2C 通信失败?

  • 检查上拉电阻(4.7kΩ)
  • 检查时钟速度(不超过 400kHz)
  • 检查地址是否正确(7 位地址需要左移 1 位)

7. 现有 Cursor/Copilot 规则

当前项目没有 Cursor 或 Copilot 规则文件。


8. 文档资源

  • docs/JY901_Sensor_Guide.md - JY-901 姿态传感器使用指南
  • docs/2Axis_Gimbal_Guide.md - 二轴云台开发指南(待创建)

最后更新: 2026-03-30
维护者: CloudPlant Team