# nhorro/rover-firmware-ng architecture

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

- Interactive diagram: https://gitdiagram.com/nhorro/rover-firmware-ng
- Repository: https://github.com/nhorro/rover-firmware-ng

## Overview

##### Project type and purpose
- This is an embedded-firmware plus ground-station client system. On the device side it’s STM32CubeIDE / HAL + FreeRTOS–based firmware running on an STM32F767ZITX microcontroller to drive a 4WD rover (read sensors, compute control, drive motors, send/receive messages). On the host side it’s a set of Python clients and Jupyter notebooks (serial, UDP, ZMQ endpoints, PS4 controller interface, video pipeline) to teleoperate and monitor the rover.

##### File structure
- Top level
- Core: CMSIS + startup + generated HAL + FreeRTOS glue (C files, startup assembler, hal config, interrupt handlers)
- Drivers: CMSIS device headers, STM32F7xx HAL driver sources
- Middlewares: FreeRTOS sources (kernel, portable layer, heap)
- Application: C++ application logic (Inc/Src) organized into Actuators, Controllers (PID), Filters, Protocol (encoder/decoder), Sensors (LM393 tach, MPU9250), Services (CommandReceiver, MainControlLoop, TelemetrySender)
- Python: host-side code – “rover” package (endpoints, protocol definitions, tctm: telecommands/telemetry), “rovervision2” video-processing pipeline, notebooks, PS4 controller script
- Scripts: shell scripts to publish/receive video
- Documentation, configuration (STM32CubeMx .ioc), linker scripts, launch files

##### README for additional insights
- Firmware uses HAL for peripherals, FreeRTOS for task scheduling, and C++ for separation of application logic from HAL-generated code.
- Python notebooks and scripts talk to firmware over serial, UDP, or ZMQ and also consume video streams for live monitoring.
- Hardware pins and peripherals are defined in HardwareSetup.md; software design in SoftwareDesign.md.

##### Essential architectural elements
- Sensors and actuators as distinct components
- Protocol encoder/decoder as a separate block mediating between tasks and comm link
- Don’t shy away from showing multiple host-side interfaces (serial, UDP, ZMQ) and video path

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware" 
        style Hardware fill:#dddddd,stroke:#888888
        MCU["STM32F767ZITX MCU"]:::hardware
        subgraph "Sensors & Actuators"
            Tach["LM393 Tachometers (4)"]:::hardware
            IMU["MPU9250 IMU"]:::hardware
            GPS["GPS Neo6M"]:::hardware
            Motor["L298N Motor Controller"]:::hardware
        end
        MCU --> Tach
        MCU --> IMU
        MCU --> GPS
        MCU --> Motor
    end

    %% Firmware Layer
    subgraph "Firmware" 
        style Firmware fill:#bbdefb,stroke:#1e88e5
        subgraph "HAL & Startup"
            Startup["startup_stm32f767zitx.s"]:::firmware
            HALconf["stm32f7xx_hal_conf.h"]:::firmware
            HALdriver["stm32f7xx_hal*.c"]:::firmware
            Peripheral["gpio/usart/i2c/tim/usb_otg"]:::firmware
        end
        subgraph "FreeRTOS Kernel"
            Kernel["FreeRTOS Kernel"]:::firmware
        end
        subgraph "Application Layer"
            CmdRecv["CommandReceiver Task"]:::firmware
            MainLoop["MainControlLoop Task"]:::firmware
            Telemetry["TelemetrySender Task"]:::firmware
            PID["PID Controller"]:::firmware
            Filters["Filters (Median, MovingAvg)"]:::firmware
            Protocol["Protocol Encoder/Decoder"]:::firmware
            ActDrv["Motor Controller"]:::firmware
            SensorDrv["Sensor Drivers"]:::firmware
        end
        MCU --> Startup
        Startup --> HALconf
        HALconf --> HALdriver
        HALdriver --> Peripheral
        HALdriver --> Kernel
        Kernel --> CmdRecv
        Kernel --> MainLoop
        Kernel --> Telemetry
        CmdRecv --> Protocol
        MainLoop --> PID
        MainLoop --> Filters
        MainLoop --> SensorDrv
        MainLoop --> ActDrv
        Telemetry --> Protocol
    end

    %% Communication Interfaces
    subgraph "Communication" 
        style Communication fill:#ffe0b2,stroke:#fb8c00
        Serial["Serial (USB)"]:::comm
        UDP["UDP/Ethernet"]:::comm
        ZMQ["ZMQ Proxy"]:::comm
        Serial --> CmdRecv
        UDP --> CmdRecv
        ZMQ --> CmdRecv
        Telemetry --> Serial
        Telemetry --> UDP
        Telemetry --> ZMQ
    end

    %% Host Ground Station
    subgraph "Host Ground Station" 
        style Host fill:#c8e6c9,stroke:#388e3c
        SerClient["serialif.py"]:::host
        UDPclient["udpproxyif.py"]:::host
        ZMQclient["zmqproxyif.py"]:::host
        TCDefs["telecommands.py / telemetry.py"]:::host
        PS4["ps4_control.py"]:::host
        Notebooks["Jupyter Notebooks"]:::host
        VideoPipe["rovervision2 Pipeline"]:::host
        PubVid["publish_video.sh"]:::host
        RecVid["receive_video.sh"]:::host
        Serial --> SerClient
        UDP --> UDPclient
        ZMQ --> ZMQclient
        SerClient --> TCDefs
        UDPclient --> TCDefs
        ZMQclient --> TCDefs
        PS4 --> SerClient
        TCDefs --> Notebooks
        VideoSrc["Camera"]:::hardware
        VideoSrc --> PubVid
        PubVid --> RecVid
        RecVid --> VideoPipe
        VideoPipe --> Notebooks
    end

    %% Click Events
    click Startup "https://github.com/nhorro/rover-firmware-ng/blob/main/Core/Startup/startup_stm32f767zitx.s"
    click HALconf "https://github.com/nhorro/rover-firmware-ng/blob/main/Core/Inc/stm32f7xx_hal_conf.h"
    click HALdriver "https://github.com/nhorro/rover-firmware-ng/tree/main/Drivers/STM32F7xx_HAL_Driver/Inc"
    click HALdriver "https://github.com/nhorro/rover-firmware-ng/tree/main/Drivers/STM32F7xx_HAL_Driver/Src"
    click Peripheral "https://github.com/nhorro/rover-firmware-ng/blob/main/Core/Inc/gpio.h"
    click Kernel "https://github.com/nhorro/rover-firmware-ng/tree/main/Middlewares/Third_Party/FreeRTOS/Source"
    click Kernel "https://github.com/nhorro/rover-firmware-ng/blob/main/Middlewares/Third_Party/FreeRTOS/Source/portable/GCC/ARM_CM7/r0p1/port.c"
    click CmdRecv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Services/CommandReceiver.h"
    click CmdRecv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Services/CommandReceiver/CommandReceiver.cpp"
    click MainLoop "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Services/MainControlLoop.h"
    click MainLoop "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Services/MainControlLoop/MainControlLoop.cpp"
    click Telemetry "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Services/TelemetrySender.h"
    click Telemetry "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Services/TelemetrySender/TelemetrySender.cpp"
    click PID "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Controllers/PID.h"
    click PID "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Controllers/PID.cpp"
    click Filters "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Filters/Median.hpp"
    click Filters "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Filters/MovingAverage.hpp"
    click Protocol "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Protocol/encoder.hpp"
    click Protocol "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Protocol/decoder.hpp"
    click Protocol "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Protocol/protocol.hpp"
    click Protocol "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Protocol/protocol.cpp"
    click SensorDrv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Sensors/LM393Tachometer.h"
    click SensorDrv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Sensors/LM393Tachometer/LM393Tachometer.cpp"
    click SensorDrv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Sensors/MPU9250/MPU9250.h"
    click SensorDrv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Sensors/MPU9250/MPU9250.cpp"
    click ActDrv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Inc/Actuators/L298NMotorController.h"
    click ActDrv "https://github.com/nhorro/rover-firmware-ng/blob/main/Application/Src/Actuators/L298NMotorController.cpp"
    click SerClient "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rover/endpoint/serialif.py"
    click UDPclient "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rover/endpoint/udpproxyif.py"
    click ZMQclient "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rover/endpoint/zmqproxyif.py"
    click TCDefs "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rover/tctm/telecommands.py"
    click TCDefs "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rover/tctm/telemetry.py"
    click PS4 "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/ps4_control.py"
    click Notebooks "https://github.com/nhorro/rover-firmware-ng/tree/main/Python/notebooks/"
    click VideoPipe "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rovervision2/__main__.py"
    click VideoPipe "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rovervision2/pipeline/videoprocessinglayers/display.py"
    click VideoPipe "https://github.com/nhorro/rover-firmware-ng/blob/main/Python/rovervision2/pipeline/videoprocessinglayers/roverhud.py"
    click PubVid "https://github.com/nhorro/rover-firmware-ng/blob/main/Scripts/publish_video.sh"
    click RecVid "https://github.com/nhorro/rover-firmware-ng/blob/main/Scripts/receive_video.sh"

    %% Styles
    classDef hardware fill:#eeeeee,stroke:#666666
    classDef firmware fill:#bbdefb,stroke:#1e88e5
    classDef comm fill:#ffe0b2,stroke:#fb8c00
    classDef host fill:#c8e6c9,stroke:#388e3c
```
