STM32F103/AGENTS.md

STM32F103C8T6 项目

项目类型

STM32CubeMX 生成的项目，使用 Keil MDK-ARM V5.32 工具链。

关键文件

• STM32F103C8T6/STM32F103C8T6.ioc — CubeMX 配置（引脚、时钟、外设）
• STM32F103C8T6/Core/Src/main.c — 应用入口
• STM32F103C8T6/MDK-ARM/STM32F103C8T6.uvprojx — Keil 工程文件
• STM32F103C8T6/Drivers/BSP/MultiButton/ — MultiButton 按键驱动库
• STM32F103C8T6/Drivers/BSP/LCD/ — ST7735S LCD 驱动
  • st7735s.c/h — 底层驱动（SPI通信、初始化、填充、画点）
  • lcd.c/h — 绘图模块（字符/字符串、线条、矩形、圆形）
  • lcd_data.c/h — ASCII 8×16 字库
  • hz16_data.c/h — CJK 16×16 字库

硬件配置

• MCU: STM32F103C8T6 (LQFP48, 72MHz, 64KB Flash, 20KB RAM)
• 时钟: HSE 8MHz → PLL ×9 = 72MHz SYSCLK
• 外设:
  • USART1: PA9 (TX), PA10 (RX) — 异步模式
  • SPI2: PB13 (SCK), PB15 (MOSI) — 18MHz, DMA1_Channel5
  • LED: PC13 (低电平有效，上拉)
  • 按键: PB3 (KEY1), PB4 (KEY2), PB5 (KEY3), PC14 (KEY4), PC15 (KEY5) — 下拉
  • LCD: PB10 (DC), PB11 (CS), PB12 (RST), PB13 (SCK), PB15 (SDA) — ST7735S 128x160
  • TIM4: PB6~9 四路 1kHz PWM
  • TIM3: CH4 内部触发 ADC1 注入组
  • ADC1: IN0IN3 (PA0PA3), 注入组, TIM3_CH4 触发

初始化顺序（main.c）

HAL_Init → SystemClock_Config → MX_GPIO → MX_DMA → MX_USART1 → MX_SPI2
→ MX_TIM4 → MX_ADC1 → MX_TIM3
→ button_driver_init() → st7735s_init() → lcd_* draw → PWM start → ADC start

ADC 采坑记录（不可从 CubeMX 重新生成时光靠设置）

• ADC 时钟: SystemClock_Config 初始为 PCLK2/2=36MHz（超 14MHz 规格），必须在 USER CODE SysInit 中手动改为 /6：

  RCC->CFGR = (RCC->CFGR & ~RCC_CFGR_ADCPRE) | RCC_CFGR_ADCPRE_DIV6;
  

• TIM3_CH4 触发 ADC: CubeMX 默认生成 TIM_OCMODE_TIMING，这不会产生 OC4REF 上升沿 → ADC 收不到触发。必须在 tim.c 中手动改为 TIM_OCMODE_PWM1 + Pulse = 500。CubeMX 需选 CH4 为 "PWM Generation4 No Output" 并设 Pulse=500。

printf 无 MicroLIB

在 usart.c 中通过 #pragma import(__use_no_semihosting) + 提供 _sys_exit() + struct __FILE + FILE __stdout 实现。Keil 取消勾选 Use MicroLIB 即可。

SPI 注意事项

• LCD (ST7735S) 使用硬件SPI2（PB13 SCK, PB15 MOSI），18MHz，Mode 3（CPOL=HIGH, CPHA=2EDGE）
• 若通过 CubeMX 重新生成 spi.c，务必在 SPI2 配置中设置 Clock Polarity=High, Clock Phase=2 Edge
• CS(PB11)、DC(PB10)、RST(PB12) 为 GPIO 控制

LCD 字库生成（tools/font_gen.py）

• Python + Pillow 渲染，使用 C:\ProgramData\anaconda3\python.exe
• ASCII 8×16（默认）：python font_gen.py
• CJK 16×16（按需）：python font_gen.py --cjk --string "你的汉字" --output STM32F103C8T6/Drivers/BSP/LCD/hz16_data
• ASCII 默认参数：--font simsun --size 56 --threshold 64 --scale 4
• CJK 默认参数：--font simsun --size 48 --threshold 50 --scale 3
• ASCII _ 下划线手动设为 0x7F（GDI 无法可靠提取）
• 输出目录 MDK-ARM\STM32F103C8T6\ 已 gitignore

代码规范

• 遵循: 嵌入式C语言代码规范（V1.0）.md
• 缩进: 4个空格，禁止Tab
• 命名: 小写+下划线；全局加 g_，静态加 s_，指针加 p_；宏大写+下划线；类型 _t 后缀
• 注释: 所有文档、注释、提交信息使用中文
• 禁止: goto、递归、可变参数函数、注释掉的代码提交
• CubeMX 代码: 自定义代码必须在 /* USER CODE BEGIN */ 和 /* USER CODE END */ 之间；Drivers/ 下 HAL 源码禁止直接修改