| name | firmware-architecture |
| description | Design firmware architecture — HAL abstraction, driver layers, application logic, and cross-platform portability |
| allowed-tools | ["Read","Write","Grep"] |
| effort | high |
When to activate
- Designing firmware architecture for a new embedded product
- Creating hardware abstraction layers (HAL)
- Structuring driver and application layers
- Porting firmware across microcontroller families
- Planning memory layout and linker scripts
When NOT to use
- For application-level software architecture
- For hardware PCB design
- For cloud backend architecture
Instructions
- Define layers. Hardware → HAL → Driver → Service → Application. Each layer only calls the layer below.
- HAL design. Abstract MCU-specific registers behind portable interfaces.
hal_gpio_set(pin, value) not GPIOB->BSRR = ....
- Driver pattern. Init → Configure → Read/Write → Deinit. Non-blocking with callbacks or DMA where possible.
- Memory layout. Flash: bootloader + app + OTA slot + config. RAM: stack, heap, static, DMA buffers. Use linker script explicitly.
- Build system. CMake for cross-compilation. Separate HAL per target (STM32, ESP32, nRF52). Common application code.
- Error handling. Return codes (not exceptions). Assert in debug, graceful degrade in release. Watchdog for hard faults.
- Documentation. Pin assignments, peripheral mapping, memory map, interrupt priority table.
Example
Firmware Architecture: Environmental Sensor Node
Layers:
Application: DataLogger, AlertManager, ConfigManager
Service: SensorService, NetworkService, StorageService
Driver: BME280, nRF24L01, SPIFlash, UART
HAL: GPIO, SPI, I2C, UART, Timer, ADC (MCU-specific)
Hardware: STM32L4 + BME280 + nRF24L01
Memory Map:
0x08000000: Bootloader (16KB)
0x08004000: Application (240KB)
0x08040000: OTA Slot (240KB)
0x0807C000: Config/NVS (16KB)
