433_STM32/AGENTS.md

AGENTS.md - Development Guidelines for E32-433TBH-SC

Project Overview

This is an STM32F103C8T6 embedded C project using STM32CubeMX code generation. The project implements a LoRa module (E32-TTL-433) control system with USB CDC communication, OLED display (u8g2), and a menu system.

Build System

• IDE: Keil MDK-ARM V5.32
• Linker: GCC
• Project File: project.ioc (STM32CubeMX configuration)
• No standard build system (Makefile/CMake) - build via Keil uVision or re-generate with CubeMX

To rebuild:

1. Open project.ioc in STM32CubeMX
2. Click "Generate Code"
3. Open the generated project in Keil uVision
4. Build using Keil's build system

There is no test framework - this is a bare-metal embedded project without unit tests.

Code Style Guidelines

Naming Conventions

• Functions: snake_case (e.g., e32_hal_uart_tx, Menu_Init)
• Variables: snake_case (e.g., usb_rx_data, my_usb_rx_num)
• Constants/Defines: UPPER_SNAKE_CASE (e.g., GPIO_PIN_RESET, E32_USE_GPIO_AUX)
• Types/Enums: snake_case_t suffix for types (e.g., key_name_t, work_mode_t)
• Pin Defines: Follow CubeMX pattern (e.g., RESET_Pin, AUX_GPIO_Port)

File Organization

Core/Src/          - Main application source (main.c, gpio.c, usart.c, etc.)
Core/Inc/          - Main application headers
Middlewares/       - Third-party libraries (u8g2, MultMenu, USB)
USB_DEVICE/       - USB CDC implementation
docs/             - Documentation

Code Structure

• Use HAL library for peripheral access (e.g., HAL_UART_Transmit, HAL_GPIO_ReadPin)
• Follow CubeMX USER CODE blocks - place custom code between /* USER CODE BEGIN ... */ and /* USER CODE END ... */
• Keep hardware-specific code in Core/Src/ (e.g., e32_hal.c, u8g2_hal.c)
• Keep application logic separate from HAL

Formatting

• Use tabs for indentation (consistent with generated CubeMX code)
• Opening brace on same line as function declaration
• Maximum line width: ~120 characters (follow existing style)
• No enforced code formatter - maintain consistency with surrounding code

Comments

• Use Doxygen-style function comments:

  /**
   * @brief  Brief description
   * @param  param_name Description
   * @retval Return value description
   */
  

• Chinese comments are acceptable (project uses mixed EN/ZH)
• Comment complex logic, not trivial code

Error Handling

• Use Error_Handler() (defined in main.c) for fatal errors
• Check HAL return values for UART, I2C, USB operations
• Implement timeout mechanisms for blocking operations
• Use HAL_Delay() for timing-critical operations

Includes

• Group includes: standard library, HAL, application-specific
• Use include guards in headers (#ifndef __FILE_H, #define __FILE_H)
• Use extern "C" guards when mixing C/C++ headers

Types and Constants

• Use stdint types (uint8_t, uint16_t, uint32_t) for portability
• Prefer bool over uint8_t for boolean values (include <stdbool.h>)
• Define magic numbers as constants or enums

Important Notes

1. Never modify auto-generated code outside USER CODE sections - it will be overwritten by CubeMX
2. Preserve the project.ioc - this is the single source of truth for hardware configuration
3. USB CDC uses usbd_cdc_if.c for custom implementation
4. Menu system uses MultMenu middleware in Middlewares/MultMenu/
5. Display driver uses u8g2 in Middlewares/u8g2Lib/

Key Files

• Core/Src/main.c - Application entry point
• Core/Src/e32_hal.c - E32 LoRa module HAL
• Core/Src/u8g2_hal.c - OLED display HAL
• Core/Src/key.c - Key input handling
• Middlewares/MultMenu/menu/menu.c - Menu system
• USB_DEVICE/App/usbd_cdc_if.c - USB CDC interface
• project.ioc - STM32CubeMX project configuration

Working with this Repository

1. Edit source files in Core/Src/ or Core/Inc/
2. For hardware changes, edit project.ioc in STM32CubeMX and regenerate
3. Build with Keil uVision (project.uvprojx)
4. Flash using ST-Link or compatible programmer