# Repository Guidelines

## Project Structure & Module Organization

`apps/chrg/` is the primary STM32F405 RT-Thread application: product code lives in `applications/`, board setup and linker scripts in `board/`, and build configuration beside them. Keep device-facing code in `applications/bsp/`, protocol and control helpers in `applications/utils/`, and long-running tasks in `applications/thread/`. `apps/boot/` is the standalone bootloader. Shared CMSIS and STM32 HAL sources are under `libs/`; `rt-thread/` is vendored upstream code. Hardware specifications and protocol references belong in `docs/`. Treat `build/`, Keil `Objects/`, maps, and firmware binaries as generated output.

## Build, Test, and Development Commands

Run charger commands from `apps/chrg/`:

- `scons -j4` builds `chrg.elf` and `rtthread.bin` using the toolchain selected by `RTT_CC`/`RTT_EXEC_PATH` (GCC is the default in `rtconfig.py`).
- `scons --target=mdk5` regenerates the Keil MDK project when SCons configuration or source lists change.
- `C:\Keil_v5\UV4\UV4.exe -b chrg.uvprojx` performs a command-line Keil build. Build `apps/boot/boot.uvprojx` similarly for the bootloader.
- `keilkill.bat` removes Keil intermediates; review untracked files before running cleanup scripts.

SCons and an ARM compiler are prerequisites and are not bundled on `PATH`.

## Coding Style & Naming Conventions

Use C99 and follow the surrounding file's indentation; new blocks should use four spaces. Place braces on the next line for functions and keep paired declarations/definitions in `.h`/`.c` files. Product symbols use lower snake case with the `chrg_` prefix, structs end in `_t`, and constants/macros use uppercase snake case. Use RT-Thread types and APIs (`rt_uint16_t`, `rt_thread_mdelay`) in application code and HAL APIs at the board boundary. Preserve existing file encodings when editing Chinese comments or documentation.

## Testing Guidelines

There is no product-level automated test suite or coverage threshold. Every firmware change must compile both affected targets and be exercised on STM32F405 hardware. Record checks for boot/upgrade flow, serial console, Modbus north/south communication, relay behavior, and LCD output as applicable. Tests in `rt-thread/tools/testcases/` cover vendored build tooling only; run them when modifying that tooling with `python -m unittest discover rt-thread/tools/testcases -p "test_*.py"`.

## Commit & Pull Request Guidelines

History uses short, lowercase, imperative summaries such as `fix south ch` and `add roll thread`; keep each commit focused and avoid generated artifacts. Pull requests should describe the affected target and behavior, link the issue, list build and hardware results, and include serial logs or LCD captures for user-visible or protocol changes. Call out changes to register maps, flash layout, linker scripts, or upgrade compatibility explicitly.