# 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