# lyallulric/stacked-smolslime architecture

> Architecture diagram of the GitHub repository lyallulric/stacked-smolslime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lyallulric/stacked-smolslime
- Repository: https://github.com/lyallulric/stacked-smolslime

## Overview

##### Project type and purpose
- This is an embedded firmware project built on the Zephyr RTOS.
- It targets various Nordic nRF boards (nRF52840, nRF52833, etc.) and implements sensor reading, sensor-fusion algorithms (Motionsense, VQF, XioFusion), and a connection layer (ESB radio or RTT console) to forward data.

##### High-level layers / top-level components
A. Hardware (Board & Sensors)
B. Zephyr RTOS (Kernel + HAL)
C. Firmware Application
1. System Services
2. Sensor Subsystem
3. Fusion Engine
4. Connection / Communication
5. Utilities

##### Detailed breakdown of components
A. Hardware layer
- Microcontroller (nRF52840, nRF5340, etc.)
- On-board peripherals (I²C, SPI, GPIO)
- External sensors:
– IMUs (LSM6DSM, ICM42688, BMI270, etc.)
– Magnetometers (BMM150, AK09940, MMC5983MA, etc.)
- LEDs, battery monitor, power management

B. Zephyr RTOS
- Kernel scheduler, device driver framework
- HAL/drivers auto-generated via DTS and board overlays
- Kconfig-based configuration (prj.conf + board_defconfig)

C. Application layer
1. System Services (src/system)
– power.c / battery.c / led.c / status.c
– Manages power states, LED indications, status logs
2. Sensor Subsystem (src/sensor)
– interface.c / scan.c / scan_spi.c
– Sensor “drivers” organized by category: imu/, mag/, magneto/
– Exposes uniform API to read raw sensor data
3. Fusion Engine (src/sensor/fusion)
- motionsense/
- vqf/
- xiofusion/
– Each folder implements one fusion algorithm, consuming raw accel/gyro/mag and producing orientation estimates
4. Connection / Communication (src/connection)
– esb.c / esb.h: Nordic ESB radio protocol to send packets wirelessly
– timer.c: scheduling radio transmissions
– console.c / rtt_console.h: SWO or RTT logging to host
5. Utilities (src/util.c)
– common helper routines, macros, data conversions

##### Data-flow and interactions
- Raw data path:
Hardware Sensors → Zephyr device drivers (I²C/SPI) → Sensor Subsystem → Fusion Engine → Connection layer → Host
- Control/config path:
Kconfig & DTS → Zephyr build system → Generated firmware image → Flash to board
- System monitoring:
System Services ↔ Hardware (battery, LEDs)
System Services → Console

##### Architectural patterns & design principles
- Layered architecture (hardware abstraction via Zephyr)
- Modular C code: separation into connection, sensor, fusion, system subfolders
- Plugin-style fusion engines: interchangeable modules selected at compile-time via Kconfig
- Board-agnostic code: board definitions, overlays, and DTS files isolate hardware specifics

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Hardware (Board & Sensors)"
        direction TB
        MCU["Microcontroller\n(nRF52840, nRF52833, etc.)"]:::hardware
        Peripherals["Peripherals\n(I²C, SPI, GPIO)"]:::hardware
        SensorsIMU["IMUs\n(LSM6DSM, ICM42688, BMI270)"]:::hardware
        SensorsMag["Magnetometers\n(BMM150, AK09940, MMC5983MA)"]:::hardware
        LEDs["LEDs, Battery Monitor,\nPower Management"]:::hardware
    end

    subgraph "Zephyr RTOS"
        direction TB
        Kernel["Kernel Scheduler\nDevice Driver Framework"]:::zephyr
        HAL["HAL/Drivers\n(DTS & Overlays)"]:::zephyr
        Conf["Kconfig & DTS\n(prj.conf, board_defconfig)"]:::zephyr
    end

    subgraph "Application Layer"
        direction TB
        subgraph "System Services"
            SysPower["power.c / power.h"]:::sys
            SysBatt["battery.c / battery.h"]:::sys
            SysLED["led.c / led.h"]:::sys
            SysStatus["status.c / status.h"]:::sys
            SysSystem["system.c / system.h"]:::sys
            SysRTT["rtt_console.h"]:::sys
        end
        subgraph "Sensor Subsystem"
            SensorIF["interface.c / interface.h"]:::sensor
            Scan["scan.c / scan.h"]:::sensor
            ScanSPI["scan_spi.c / scan_spi.h"]:::sensor
            SensorCore["sensor.c / sensor.h"]:::sensor
            SensorExt["sensor_ext.c / sensor_ext.h"]:::sensor
            SensorNone["sensor_none.c / sensor_none.h"]:::sensor
            SensorsEnum["sensors.h\nsensors_enum.h"]:::sensor
            subgraph "IMU Drivers"
                BMI["BMI270.c / BMI270.h"]:::sensor
                ICM["ICM42688.c / ICM42688.h"]:::sensor
                LSM["LSM6DSM.c / LSM6DSM.h"]:::sensor
            end
            subgraph "Mag Drivers"
                BMM["BMM150.c / BMM150.h"]:::sensor
                AK["AK09940.c / AK09940.h"]:::sensor
                MMC["MMC5983MA.c / MMC5983MA.h"]:::sensor
            end
            subgraph "Magneto"
                MAG1["magneto1_4.c / magneto1_4.h"]:::sensor
                MATH["mymathlib_matrix.c / mymathlib_matrix.h"]:::sensor
            end
        end
        subgraph "Fusion Engine"
            Fusions["fusions.h"]:::fusion
            Motion["motionsense.c / motionsense.h"]:::fusion
            VQF["vqf.c / vqf.h"]:::fusion
            XIO["xiofusion.c / xiofusion.h"]:::fusion
            XIOOff["xioFusionOffset2.c / xioFusionOffset2.h"]:::fusion
        end
        subgraph "Connection / Communication"
            ConnCore["connection.c / connection.h"]:::conn
            ESB["esb.c / esb.h"]:::conn
            Timer["timer.c / timer.h"]:::conn
            Console["console.c"]:::conn
        end
        Utilities["util.c / util.h\nglobals.h\nbuild_defines.h\nretained.c / retained.h"]:::util
        Main["main.c"]:::main
    end

    %% Data flow
    SensorsIMU -->|I²C/SPI| HAL
    SensorsMag -->|I²C/SPI| HAL
    HAL -->|device API| SensorIF
    Kernel -->|scheduler| SensorIF
    SensorCore -->|raw data| Fusions
    SensorExt -->|raw data| Fusions
    SensorNone -->|raw data| Fusions
    Fusions -->|orientation data| ESB
    Fusions -->|orientation data| Console

    %% Control / config
    Conf -.->|build-time config| HAL
    Conf -.->|build-time config| Kernel

    %% System monitoring
    SysPower -->|power states| LEDs
    SysBatt -->|battery status| LEDs
    SysSystem -->|status logs| Console

    %% Build tool
    West["West Build & Flash"]:::tool
    West -->|uses| CMake["CMakeLists.txt"]:::tool
    West -->|uses| Conf

    %% External host
    Host["Host GUI / Console"]:::external
    ESB -->|wireless packets| Host
    Console -->|RTT / SWO logs| Host

    %% Click events
    click boards/nordic/ "https://github.com/lyallulric/stacked-smolslime/tree/master/boards/nordic/"
    click socs/ "https://github.com/lyallulric/stacked-smolslime/tree/master/socs/"
    click Kconfig "https://github.com/lyallulric/stacked-smolslime/tree/master/Kconfig"
    click prj.conf "https://github.com/lyallulric/stacked-smolslime/blob/master/prj.conf"
    click CMakeLists.txt "https://github.com/lyallulric/stacked-smolslime/blob/master/CMakeLists.txt"
    click west.yml "https://github.com/lyallulric/stacked-smolslime/blob/master/west.yml"
    click src/system/power.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/system/power.c"
    click src/system/battery.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/system/battery.c"
    click src/system/led.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/system/led.c"
    click src/system/status.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/system/status.c"
    click src/system/system.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/system/system.c"
    click src/system/rtt_console.h "https://github.com/lyallulric/stacked-smolslime/blob/master/src/system/rtt_console.h"
    click src/sensor/interface.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/interface.c"
    click src/sensor/scan.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/scan.c"
    click src/sensor/scan_spi.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/scan_spi.c"
    click src/sensor/sensor.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/sensor.c"
    click src/sensor/sensor_ext.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/sensor_ext.c"
    click src/sensor/sensor_none.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/sensor_none.c"
    click src/sensor/imu/BMI270.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/imu/BMI270.c"
    click src/sensor/imu/ICM42688.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/imu/ICM42688.c"
    click src/sensor/imu/LSM6DSM.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/imu/LSM6DSM.c"
    click src/sensor/mag/BMM150.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/mag/BMM150.c"
    click src/sensor/mag/AK09940.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/mag/AK09940.c"
    click src/sensor/mag/MMC5983MA.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/mag/MMC5983MA.c"
    click src/sensor/magneto/magneto1_4.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/magneto/magneto1_4.c"
    click src/sensor/magneto/mymathlib_matrix.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/magneto/mymathlib_matrix.c"
    click src/sensor/fusion/motionsense/motionsense.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/fusion/motionsense/motionsense.c"
    click src/sensor/fusion/vqf/vqf.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/fusion/vqf/vqf.c"
    click src/sensor/fusion/xiofusion/xiofusion.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/fusion/xiofusion/xiofusion.c"
    click src/sensor/fusion/xiofusion/xioFusionOffset2.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/sensor/fusion/xiofusion/xioFusionOffset2.c"
    click src/connection/connection.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/connection/connection.c"
    click src/connection/esb.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/connection/esb.c"
    click src/connection/timer.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/connection/timer.c"
    click src/console.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/console.c"
    click src/util.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/util.c"
    click src/globals.h "https://github.com/lyallulric/stacked-smolslime/blob/master/src/globals.h"
    click src/build_defines.h "https://github.com/lyallulric/stacked-smolslime/blob/master/src/build_defines.h"
    click src/retained.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/retained.c"
    click src/main.c "https://github.com/lyallulric/stacked-smolslime/blob/master/src/main.c"

    %% Styles
    classDef hardware fill:#f9d5b5,stroke:#e07a5f,color:#000
    classDef zephyr fill:#a8dadc,stroke:#457b9d,color:#000
    classDef sys fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef sensor fill:#d8f3dc,stroke:#2d6a4f,color:#000
    classDef fusion fill:#cdb4db,stroke:#9d4edd,color:#000
    classDef conn fill:#e0fbfc,stroke:#3a86ff,color:#000
    classDef util fill:#ffccd5,stroke:#d00000,color:#000
    classDef main fill:#fff3b0,stroke:#f4d35e,color:#000
    classDef tool fill:#e9ecef,stroke:#adb5bd,color:#000
    classDef external fill:#f1faee,stroke:#1d3557,color:#000
```
