# cu-robotics/firmware architecture

> Architecture diagram of the GitHub repository cu-robotics/firmware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cu-robotics/firmware
- Repository: https://github.com/cu-robotics/firmware

## Overview

##### Project Type and Purpose
- This is an embedded‐firmware project targeting a PJRC Teensy 4.1 microcontroller.
- It implements layered robotics firmware that:
- Reads data from a variety of sensors (IMU, encoders, LiDAR, CAN devices, etc.)
- Applies filters and state estimation
- Runs control loops
- Exposes telemetry and command interfaces over Ethernet and HID to an external host running the `hive` software
- External Arduino-style libraries and a custom Teensy HAL provide low-level hardware support.

##### Directory and Component Analysis
- Top-level build & tooling
- Makefile & githooks: local build, upload, linting, documentation
- .github/workflows: CI for PR checks and docs deploy
- docs/: Doxygen and markdown guidelines
- tools/: helper scripts (installer, monitor, a Rust “waggle-interceptor” tool)
- External Libraries (libraries/ and teensy4/)
- Arduino-style hardware abstraction (“teensy4/”)
- Standard sensor, bus, networking, filesystem libraries (FastLED, QNEthernet with lwIP, SdFat, etc.)
- Application Source (src/)
- src/sensors: sensor drivers & SensorManager (I²C, SPI, CAN, TOF, encoders…)
- src/filters: basic signal filters (lowpass, PID)
- src/controls: state estimation, control loops, ControllerManager
- src/comms: packet definitions, HID & Ethernet comms layers, SD logging
- src/utils: timing, vector math, profiling, watchdog

- Hardware Abstraction Layer (HAL): teensy4/ sources
- External Libraries: grouped library blocks (I2C, SPI, Ethernet, FileSystem, CAN)
- Sensor Layer: SensorManager + individual drivers
- Filtering & Estimation Layer
- Control Layer: ControllerManager, state machine
- Communication Layer:
- EthernetComms (QNEthernet/lwIP)
- HIDComms
- SDManager for on-board logging
- External Host (`hive`): running on PC, communicates via Ethernet/HID
- Build & Docs: Makefile, CI pipelines, Doxygen (ancillary)

- HAL → Sensor drivers → SensorManager → filters → estimator → controller → comms
- Controller outputs → actuator interfaces (PWM, GPIO via HAL)
- Comms layers ↔ External Host (`hive`)
- SDManager logs data from SensorManager and Controller
- Build tools & CI: interacts with code base but outside of runtime flow

c. Architectural Patterns & Principles
- Layered architecture: clear separation of HAL, drivers, application logic, and communication
- Manager/Adapter pattern for sensors, filters, and controllers
- Data flow pipeline: sensor → filter → estimate → control → output/telemetry
- Modularity: each subsystem in its own directory, all using consistent C++ interfaces
- Use of external open-source libraries for reusable functionality (networking, filesystems)

d. Key Technologies & Frameworks
- C++17 (Arduino-style) on ARM Cortex-M7 (Teensy 4.1)
- QNEthernet + lwIP for TCP/UDP/Ethernet
- USB HID for alternative comms
- SdFat for SD-card logging
- Doxygen for API docs, GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% HAL & External Libraries
    subgraph "HAL & External Libraries"
        HAL["Hardware Abstraction Layer\n(teensy4/)"]:::hal
        LIB["External Libraries\n(libraries/)"]:::hal
    end

    %% Sensor Layer
    subgraph "Sensor Layer"
        SDV["Sensor Drivers\n(src/sensors/)"]:::pipeline
        SM["SensorManager"]:::pipeline
    end

    %% Filtering & Estimation
    subgraph "Filtering & Estimation"
        FIL["Signal Filters\n(src/filters/)"]:::pipeline
        EM["EstimatorManager"]:::pipeline
        EST["Estimator"]:::pipeline
    end

    %% Control Layer
    subgraph "Control Layer"
        CI["Controller Interface"]:::pipeline
        CM["ControllerManager"]:::pipeline
        ST["Global State"]:::pipeline
    end

    %% Communication Layer
    subgraph "Communication Layer"
        CL["Comms Layer"]:::comm
        EC["EthernetComms"]:::comm
        HC["HIDComms"]:::comm
        SDM["SDManager"]:::comm
        CFG["Config Layer"]:::comm
        DD["Data Definitions"]:::comm
    end

    %% Utilities & Entry
    UTIL["Utilities\n(src/utils/)"]:::util
    MAIN["main.cpp"]:::util

    %% External Host & Storage
    HOST(("Host PC\n(hive)")):::external
    SD_CARD[(SD Card)]:::storage

    %% Tooling & Docs
    subgraph "Build & Docs"
        MK["Makefiles"]:::util
        CIWF["CI Workflows"]:::util
        DOCS["Documentation\ndocs/"]:::util
    end
    TOOLS["Tools & Scripts\ntools/"]:::util

    %% Data Flow
    HAL --> SDV
    LIB --> SDV
    SDV --> SM
    SM --> FIL
    FIL --> EM
    EM --> EST
    EST --> CM
    CM --> HAL
    SM --> SDM
    CM --> SDM
    CM --> CL
    SM --> CL
    CL --> EC
    CL --> HC
    EC <--> HOST
    HC <--> HOST
    SDM --> SD_CARD
    CL --> CFG
    CL --> DD
    UTIL --> SM
    UTIL --> FIL
    UTIL --> CM
    MAIN --> SM
    MAIN --> CM
    MAIN --> CL

    %% Tooling connections
    MK -->|builds| MAIN
    CIWF -->|tests| MAIN
    DOCS -->|docs| MAIN
    TOOLS -->|scripts| MAIN

    %% Click Events
    click HAL "https://github.com/cu-robotics/firmware/tree/main/teensy4/"
    click LIB "https://github.com/cu-robotics/firmware/tree/main/libraries/"
    click SDV "https://github.com/cu-robotics/firmware/tree/main/src/sensors/"
    click SM "https://github.com/cu-robotics/firmware/blob/main/src/sensors/SensorManager.hpp"
    click FIL "https://github.com/cu-robotics/firmware/tree/main/src/filters/"
    click EM "https://github.com/cu-robotics/firmware/blob/main/src/controls/estimator_manager.hpp"
    click EST "https://github.com/cu-robotics/firmware/blob/main/src/controls/estimator.hpp"
    click CI "https://github.com/cu-robotics/firmware/blob/main/src/controls/controller.hpp"
    click CM "https://github.com/cu-robotics/firmware/blob/main/src/controls/controller_manager.hpp"
    click ST "https://github.com/cu-robotics/firmware/blob/main/src/controls/state.hpp"
    click EC "https://github.com/cu-robotics/firmware/blob/main/src/comms/ethernet_comms.hpp"
    click HC "https://github.com/cu-robotics/firmware/blob/main/src/comms/hid_comms.hpp"
    click SDM "https://github.com/cu-robotics/firmware/blob/main/src/comms/SDManager.hpp"
    click CL "https://github.com/cu-robotics/firmware/blob/main/src/comms/comms_layer.hpp"
    click CFG "https://github.com/cu-robotics/firmware/blob/main/src/comms/config_layer.hpp"
    click DD "https://github.com/cu-robotics/firmware/tree/main/src/comms/data/"
    click UTIL "https://github.com/cu-robotics/firmware/tree/main/src/utils/"
    click MAIN "https://github.com/cu-robotics/firmware/blob/main/src/main.cpp"
    click MK "https://github.com/cu-robotics/firmware/tree/main/Makefile"
    click CIWF "https://github.com/cu-robotics/firmware/tree/main/.github/workflows/"
    click DOCS "https://github.com/cu-robotics/firmware/tree/main/docs/"
    click TOOLS "https://github.com/cu-robotics/firmware/tree/main/tools/"

    %% Styles
    classDef hal fill:#ADD8E6,stroke:#000;
    classDef pipeline fill:#90EE90,stroke:#000;
    classDef comm fill:#FFA500,stroke:#000;
    classDef util fill:#D3D3D3,stroke:#000;
    classDef external fill:#F0F8FF,stroke:#000;
    classDef storage fill:#FFE4B5,stroke:#000;
```
