## Repo overview (quick)

- This is an STM32H7 firmware project for a lawnmower MCU. Key folders:
  - `Core/` — HAL/RTOS entry (Cube-generated code; see `Core/Src/main.c`).
  - `Drivers/` — STM32 HAL driver sources.
  - `APL/` — high-level application config and app entry (`APL/app.c`, `APL/AppConfig.h`).
  - `FML/` — feature modules (GPS, Internet, Bluetooth, UDPClient, etc.). Example: `FML/GPS.c` parses NMEA and uploads via `UDPClient`.
  - `HIDOLibrary/Include` — shared utility types and helpers (HIDO_* API and types used everywhere).
  - `MDK-ARM/` — Keil project files (`STM32H743.uvprojx`, `.uvoptx`) and build artifacts.

## What matters for edits

- Entry flow: `Core/Src/main.c` initializes HAL, registers UARTs and starts the RTOS. It calls `app_main()` (implemented in `APL/app.c`) before `osKernelStart()`.
- Main app loop runs in `APL/app_task` which polls subsystems after being awakened by a binary semaphore. ISR-to-main wake uses `app_trigger_from_isr()` (gives the same semaphore).
- Use existing registration patterns: `Uart_Register(...)` for UART endpoints, `GPS_PinRegister(...)` for GPIO pins, and module init functions e.g. `GPS_Init()`, `Internet_Init()`, `UDPClient_Init()`.
- Preserve Cube-generated sections: keep code inside/near `/* USER CODE BEGIN */` / `/* USER CODE END */` unchanged when modifying generated files.

## Build & debug notes (concrete)

- Two supported project entry points are present: STM32Cube `.ioc` (STM32H743/STM32H743.ioc) and Keil MDK `.uvprojx` (MDK-ARM/STM32H743.uvprojx). Developers typically:
  - Open the `.ioc` in STM32CubeIDE and generate code, or
  - Open the `.uvprojx` in Keil uVision (MDK) to build and flash.
- Debug/log serial: `USART1` is used as debug (`huart1`) at 921600 (see `MX_USART1_UART_Init` in `main.c`). GPS is on `USART2` (115200 default).
- UARTs use DMA for RX/TX in many places — be careful when changing buffer sizes or switching to interrupt-based I/O.

## Project-specific conventions & patterns

- Types and helpers use the `HIDO_` prefix (e.g. `HIDO_UINT32`, `HIDO_Util*`, `HIDO_Debug`). Search `HIDOLibrary/Include` for helper APIs.
- Polling model: many subsystems expose `*_Init()` and `*_Poll()` (e.g. `GPS_Poll()`, `Internet_Poll()`). Work is driven by the `app_task` loop.
- ISR -> application wake uses the global semaphore from `app_trigger_from_isr()` — prefer this pattern rather than direct task notifications in new code for consistency.
- Generated HAL code pattern: keep peripheral init in `MX_*_Init()` functions within `main.c` and put higher-level logic in `APL/` or `FML/`.

## Examples for common changes

- Add a new UART-based sensor: call `Uart_Register(UART_ID_X, &huartX)` in `main.c` after the corresponding `MX_USARTX_UART_Init()`, then create `Sensor_Init()`/`Sensor_Poll()` in `FML/` and call from `app_task`.
- Change debug log speed: edit `MX_USART1_UART_Init` in `Core/Src/main.c` and adjust callers that assume 921600.
- Add a periodic job: use the existing `HIDO_Timer` utilities and the app semaphore wake flow; follow `app_task`'s pattern to poll on wake.

## Where to look (quick file list)

- Entry & init: `Core/Src/main.c`
- App startup & scheduler task: `APL/app.c`, `Core/Src/freertos.c`
- Feature modules: `FML/GPS.c`, `FML/Internet/*.c`, `FML/UDPClient.c`
- Utilities and shared types: `HIDOLibrary/Include/*` (HIDO_* APIs)
- Project files: `STM32H743/STM32H743.ioc`, `MDK-ARM/STM32H743.uvprojx`

## Short guidelines for AI agents

- Only change generated files inside USER CODE blocks unless you also regenerate the Cube project (.ioc); prefer adding new modules under `FML/` or `APL/`.
- Follow existing naming and type conventions: use `HIDO_` helpers and typedefs for cross-module compatibility.
- When modifying peripheral config, update `MX_*_Init()` in `main.c` and check related registration calls (`Uart_Register`, `GPIO` pin registers).
- Use the semaphore-based `app_trigger_from_isr()` to wake the main loop from ISRs.

If you'd like, I can convert this into a shorter or longer version, or merge any existing instructions you have. Any areas you want me to expand or examples to add?