# Quick instructions for AI coding agents

Overview
- STM32H743 (FreeRTOS) firmware for an autonomous lawnmower. Mix of CubeMX HAL, platform glue (HIDO_*), FML functional modules, and APL tasks.

What to read first
- Entry: `STM32H743/Core/Src/main.c` (MX_* init, `app_main()`, osKernelStart)
- App: `STM32H743/APL/app.c` (`app_task()` initializes modules and polls with a binary semaphore)
- Modules: `STM32H743/FML/*` (GPS, SBUS, Motion, Internet, UDP/TCP)
- Utilities: `STM32H743/HIDOLibrary/Include/` (HIDO_* helpers)

Core rules and patterns
- Do not change CubeMX generated code outside `/* USER CODE BEGIN/END */` blocks. If you must regenerate, move logic to `FML/`/`APL/`.
- Init & Poll pattern: implement `Module_Init()` and `Module_Poll()`; call Init in `app_task()` and Poll during app loop.
- UARTs: register HAL handles with `Uart_Register(UART_ID_*, &huartX)` after `MX_USARTX_UART_Init()`; `Uart_Init()` config may require DMA buffers.
- ISR wake: signal `app_task` using `app_trigger_from_isr()`; avoid direct task notification unless you match existing pattern.
- Naming & API: follow `HIDO_*` typedefs and `HIDO_OK/HIDO_ERR` return conventions; use `HIDO_*` timers, queues, and helpers.

Build & debug
- Two build modes: CubeMX + STM32CubeIDE (edit `.ioc`) or Keil MDK-uVision (`MDK-ARM/STM32H743.uvprojx`).
- Use J-Link to flash; default debug UART: `USART1` (921600). Python telemetry/telemetry tool uses `UART5` (921600).
- DMA/coherency: avoid enabling D-cache while using DMA unless buffer cache maintenance is implemented.

Safe changes and examples
- Add a new UART-based sensor:
  1) Configure UART in CubeMX / MX_USARTX_UART_Init() in `main.c` (USER CODE blocks)
  2) `Uart_Register(UART_ID_NEW, &huartX)` in `main.c` after init
  3) Add `FML/NewModule_Init()` and `FML/NewModule_Poll()` and call from `app_task()`
- Tuning: adjust motion PID and constants in `STM32H743/FML/motion_config.h` and `APL/global_param.h`. Persist via `save_com_map_to_flash()`.

Notes for AI agents
- Only change generated code inside USER blocks. Prefer to add files in `FML/`/`APL/` and follow `HIDO_` conventions.
- Minimize blocking work in `MotionControl_Task` and `app_task()`; keep real-time paths deterministic.
- For deeper module rules and examples, consult `STM32H743/.github/copilot-instructions.md` and `docs/`.

If any section should include deeper examples (UART template, module skeletons, or unit test patterns), tell me which piece to expand.