105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
# 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:
|
|
```c
|
|
/**
|
|
* @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 |