8.4 KiB
8.4 KiB
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 添加新功能的正确流程
-
在 CubeMX 中配置外设
- 打开
CloudPlant.ioc - 配置所需外设(I2C, UART, TIM 等)
- 生成代码
- 打开
-
在 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 */ -
在 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