# waterloo-rocketry/cansw_processor_canards architecture

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

- Interactive diagram: https://gitdiagram.com/waterloo-rocketry/cansw_processor_canards
- Repository: https://github.com/waterloo-rocketry/cansw_processor_canards

## Overview

##### Project Type & Purpose
- This is an embedded firmware project built for the 2024-2025 processor board. Its purpose is to perform state estimation and control of the “canards” system.
- The project integrates real-time operations (via FreeRTOS), hardware peripheral access (using STM32 HAL, CMSIS, and custom drivers), and high-level application logic (under src/application) that coordinates components such as the controller, estimator, sensor handlers, and logging.

##### Analyzing the File Structure – Identifying Components
- Core/Startup, Core/Inc, and Core/Src: These represent the core initialization, system configuration, and low-level hardware abstraction. They also include FreeRTOS configurations.
- Drivers and Middlewares:
- The Drivers directory contains both CMSIS and HAL drivers which abstract the STM32H7 hardware.
- The Middlewares folder wraps third-party libraries such as FatFs and FreeRTOS and handles additional functionality.
- src/ Directory Submodules:
- src/drivers/: Custom peripheral driver implementations (e.g., ADC, I2C, UART, GPIO, timer) that interface with the hardware.
- src/application/: Contains high-level logic modules such as the can_handler, controller (and its associated algorithm and gain table), estimator, imu_handler, flight_phase, init, and logger.
- src/common/: Shared resources and math libraries to support application computations.
- src/third_party/: Third-party libraries (like CMSIS-DSP, rocketlib, printf) required for additional processing.
- tests/ Directory:
- Contains unit testing infrastructure, including GoogleTest-based unit tests and mocks for HAL, FreeRTOS, and other functions. This shows separation of concerns for testing versus production code.

a. Main Components to Represent:
- Core Firmware Layer: Startup code, system initialization, FreeRTOS integration (Core directory content).
- Hardware Abstraction & Drivers: Libraries (CMSIS, HAL) and custom drivers that interact directly with peripheral hardware.
- Middleware: FatFs for file system support, FreeRTOS for scheduling/RTOS functions, plus any additional third-party libraries.
- Application Logic: Divided into modules such as:
- CAN Handler – managing CAN bus communications.
- Controller and its algorithm – performing control operations.
- Estimator – reading sensor inputs and handling state estimation.
- IMU Handler, Flight Phase – managing sensor processing/flight mode.
- Logger – managing data logging and message formatting.
- Unit Testing Framework: GoogleTest and Fake Function Framework (fff) used for testing components.

b. Relationships and Interactions:
- That several application components (controller, estimator, logger) interact with each other and read/write from hardware peripherals via the drivers.
- A separate section (or overlay) for Unit Testing that “mocks” underlying HAL/RTOS calls to isolate logic from hardware, illustrating dependency inversion.

c. Architectural Patterns and Design Principles:
- Modular Design: Indicate grouping of similar modules (e.g., all sensor drivers in one grouping; all application features in another).
- Use of a RTOS pattern where tasks or threads are scheduled for different modules (if applicable).
- Integration of third-party libraries via dedicated modules (e.g., FreeRTOS, FatFs, CMSIS libraries).

d. Relevant Technologies/Frameworks:
- STM32 HAL/CMSIS for hardware access.
- FreeRTOS (and its integration via Middlewares and Core) for real-time operations.
- CMake as the build system (configured in the project with CMakeLists.txt files).
- GoogleTest and fff for unit testing.
- Custom-developed drivers and application modules for handling CAN communications, state estimation, control logic, and data logging.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Platform
    subgraph "Hardware Platform"
        HW["STM32H7 Microcontroller"]:::hardware
    end

    %% Core Firmware Layer
    subgraph "Core Firmware Layer"
        CORE_INC["Core/Inc"]:::core
        CORE_SRC["Core/Src"]:::core
        CORE_STARTUP["Core/Startup"]:::core
    end

    %% RTOS & Middleware
    subgraph "RTOS & Middleware"
        FREE_RTOS["FreeRTOS Integration"]:::middleware
        FATFS["FatFs Middleware"]:::middleware
    end

    %% Hardware Abstraction
    subgraph "Hardware Abstraction"
        HAL_CMSIS["STM32 HAL & CMSIS"]:::drivers
        CUSTOM_DRIVERS["Custom Peripheral Drivers"]:::drivers
    end

    %% Application Logic
    subgraph "Application Logic"
        CAN_HANDLER["CAN Handler"]:::application
        CONTROLLER["Controller & Algorithm"]:::application
        ESTIMATOR["Estimator"]:::application
        IMU_HANDLER["IMU Handler"]:::application
        FLIGHT_PHASE["Flight Phase"]:::application
        LOGGER["Logger"]:::application
    end

    %% Shared Resources
    subgraph "Shared Resources"
        MATH_LIB["Math Libraries"]:::shared
    end

    %% Unit Testing
    subgraph "Unit Testing"
        UNIT_TESTS["Unit Testing Framework"]:::testing
    end

    %% Connections
    HW -->|"initializes"| CORE_STARTUP
    CORE_STARTUP -->|"configures"| FREE_RTOS
    CORE_STARTUP -->|"initializes"| HAL_CMSIS
    FREE_RTOS -->|"schedules"| CUSTOM_DRIVERS
    HAL_CMSIS -->|"supports"| CUSTOM_DRIVERS
    CUSTOM_DRIVERS -->|"provides data to"| CAN_HANDLER
    CUSTOM_DRIVERS -->|"provides data to"| ESTIMATOR
    CUSTOM_DRIVERS -->|"receives commands from"| CONTROLLER
    CAN_HANDLER -->|"communicates with"| CONTROLLER
    IMU_HANDLER -->|"sends sensor data to"| ESTIMATOR
    ESTIMATOR -->|"logs output via"| LOGGER
    CONTROLLER -->|"logs output via"| LOGGER
    MATH_LIB -->|"supports"| ESTIMATOR
    MATH_LIB -->|"supports"| CONTROLLER
    FATFS -->|"logs data through"| LOGGER
    UNIT_TESTS ---|"mocks"| CORE_STARTUP
    UNIT_TESTS ---|"mocks"| CUSTOM_DRIVERS
    UNIT_TESTS ---|"tests"| CAN_HANDLER
    UNIT_TESTS ---|"tests"| CONTROLLER
    UNIT_TESTS ---|"tests"| ESTIMATOR

    %% Click Events
    click CORE_INC "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/Core/Inc"
    click CORE_SRC "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/Core/Src"
    click CORE_STARTUP "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/Core/Startup"
    click FREE_RTOS "https://github.com/waterloo-rocketry/cansw_processor_canards/blob/main/Core/Inc/FreeRTOSConfig.h"
    click FREE_RTOS "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/Middlewares/Third_Party/FreeRTOS"
    click HAL_CMSIS "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/Drivers/STM32H7xx_HAL_Driver"
    click HAL_CMSIS "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/Drivers/CMSIS"
    click CUSTOM_DRIVERS "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/drivers"
    click CAN_HANDLER "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/application/can_handler"
    click CONTROLLER "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/application/controller"
    click ESTIMATOR "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/application/estimator"
    click IMU_HANDLER "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/application/imu_handler"
    click FLIGHT_PHASE "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/application/flight_phase"
    click LOGGER "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/application/logger"
    click MATH_LIB "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/src/common/math"
    click FATFS "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/Middlewares/Third_Party/FatFs"
    click UNIT_TESTS "https://github.com/waterloo-rocketry/cansw_processor_canards/tree/main/tests"

    %% Styles
    classDef hardware fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef core fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef middleware fill:#cfc,stroke:#333,stroke-width:2px;
    classDef drivers fill:#ffd700,stroke:#333,stroke-width:2px;
    classDef application fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef shared fill:#e0bbff,stroke:#333,stroke-width:2px;
    classDef testing fill:#cccccc,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
