# trovad/bldc_d architecture

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

- Interactive diagram: https://gitdiagram.com/trovad/bldc_d
- Repository: https://github.com/trovad/bldc_d

## Overview

##### Project type and purpose
- This is an embedded firmware project (“VESC firmware”) for DC/BLDC/FOC motor control. It’s neither a web app nor desktop tool, but a real-time, bare-metal/microcontroller application built on ChibiOS RTOS.

##### Top-level architectural components
a. Build system
- Makefiles & scripts (Makefile, make/*.mk, package_firmware.py, Qt Creator project)
- Configuration generator (confgenerator.c, conf_general.h, hwconf/)
- External tools (ARM SDK installer, Python scripts, Qt Creator integration)
b. Bootloader & debugger support
- Blackmagic SWD interface (blackmagic/)
- OpenOCD config files (stm32-bv_openocd.cfg, Project/Qt Creator)
c. RTOS & HAL
- ChibiOS kernel (ChibiOS_3.0.5/os/rt/)
- Hardware abstraction (ChibiOS_3.0.5/os/hal/)
- BSP & LLD drivers (ChibiOS_3.0.5/ext, ports for STM32 families)
d. Board configuration
- Hardware configurations (hwconf/…) for dozens of VESC variants
- MCU configuration (mcuconf.h, chconf.h, halconf.h)
e. Low-level drivers
- GPIO, ADC, DAC, timers, PWM, SPI, I²C, CAN, USB, etc.
- Utility libraries (util/, motor/, encoder/, imu/)
f. Communication stack
- USB serial & CDC (comm/comm_usb.c, terminal.c)
- CAN bus driver & packet layer (comm_can.c, packet.c)
- UAVCAN library (libcanard/)
g. Motor-control algorithms
- FOC & PWM (motor/mcpwm_foc.c, motor/foc_math.c)
- Speed/position sensing (encoder/, imu/)
h. Middleware & utilities
- Logging, CRC, digital filters (util/, comm/log.c)
- Shell & CLI (os/various/shell.c)
i. Application layer
- Pre-written apps (applications/*.c) for Nunchuk, PPM, UART-comm, custom templates
- Application selection via build target
j. Host-side UI & scripting
- Qt/QML UI templates (qmlui/)
- Python packaging scripts (package_firmware.py)
- LispBM interpreter integration (lispBM/) for dynamic expansion (optional)

##### Relationships and data flows
- Build system assembles configuration + HAL + ChibiOS + drivers + applications → firmware binary
- Debug tools (Blackmagic, OpenOCD) flash the binary to the MCU
- On-chip at reset: bootloader → jump to main firmware
- main.c initializes ChibiOS kernel and HAL → spawns threads
- High-priority control loop thread reads ADC/encoder/IMU → runs FOC math → updates PWM
- Comm thread handles USB & CAN interrupts → packet framing → invokes command handlers
- Utility threads (logging, shell) process background tasks via queues/semaphores
- Middleware (libcanard) sits between CAN driver and application for UAVCAN messages
- Application code registers callbacks into command/middleware layers

##### Architectural patterns & principles
- Layered design:
1. HAL & board support
2. Drivers & utilities
3. RTOS kernel
4. Middleware & comm stacks
5. Application
- Event-driven concurrency: ChibiOS threads + ISRs + message queues
- Hardware-abstraction: single HAL API + board-specific low-level drivers
- Build-time configuration: code-generation from conf files to tailor firmware to each board

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Host Tools
    subgraph "Build & Toolchain" 
        direction TB
        MF["Makefiles & Scripts"]:::build
        CG["Configuration Generator"]:::build
        QTC["Qt Creator Project"]:::build
        PP["Python Packaging"]:::build
    end

    subgraph "Host UI & Scripting"
        direction TB
        QML["Qt/QML UI"]:::build
        LISP["LispBM Interpreter"]:::build
    end

    MF -->|generates config| CG
    MF -->|build target| PP
    QTC -->|invokes make| MF
    QML -->|upload .bin| PP

    %% Firmware and Debug
    FW["Firmware Binary"]:::build
    MF -->|outputs| FW
    PP -->|packages| FW

    DBG["Blackmagic SWD & OpenOCD"]:::build
    FW -->|flash| DBG
    DBG -->|program via SWD| MCU["MCU Runtime"]

    %% MCU Runtime
    subgraph "MCU Runtime" 
        direction TB
        BOOT["Bootloader"]:::build
        BOOT -->|jump to| MAIN["main.c"]:::rtos

        subgraph "ChibiOS Kernel & HAL" 
            direction TB
            KERNEL["ChibiOS Kernel"]:::rtos
            HAL["HAL Core"]:::rtos
            KERNEL --> HAL
        end

        %% Drivers Layer
        subgraph "Low-Level Drivers" 
            direction TB
            DR_ADC["ADC, Timers, PWM, GPIO, CAN, USB"]:::drivers
            DR_SPI["SPI, I2C"]:::drivers
            DR_FLASH["Flash Helper"]:::drivers
            HAL --> DR_ADC
            HAL --> DR_SPI
            HAL --> DR_FLASH
        end

        %% Middleware & Comm
        subgraph "Middleware & Comm Stack"
            direction TB
            LIBCAN["libcanard (UAVCAN)"]:::middleware
            COMM_USB["USB/CDC & Packet"]:::middleware
            COMM_CAN["CAN Driver & Packet"]:::middleware
            DR_ADC --> COMM_USB
            DR_ADC --> COMM_CAN
            COMM_CAN --> LIBCAN
        end

        %% Application Layer
        subgraph "Application Layer"
            direction TB
            APPS["Pre-written Apps"]:::app
            APPS -->|callbacks| COMM_USB
            APPS -->|callbacks| LIBCAN
            LIBCAN --> APPS
        end

        %% Threads
        subgraph "RTOS Threads"
            direction TB
            T_CTRL["Control Loop Thread"]:::rtos
            T_COMM["Comm Thread"]:::rtos
            T_UTIL["Logging & Shell"]:::rtos
            KERNEL --> T_CTRL
            KERNEL --> T_COMM
            KERNEL --> T_UTIL
            T_CTRL --> DR_ADC
            T_CTRL --> DR_SPI
            T_COMM --> COMM_USB
            T_COMM --> COMM_CAN
            T_UTIL --> DR_FLASH
        end
    end

    %% Click Events
    click MF "https://github.com/trovad/bldc_d/tree/release_6_05//Makefile"
    click CG "https://github.com/trovad/bldc_d/blob/release_6_05//confgenerator.c"
    click QTC "https://github.com/trovad/bldc_d/blob/release_6_05//Project/Qt Creator/vesc.pro"
    click PP "https://github.com/trovad/bldc_d/blob/release_6_05//package_firmware.py"
    click DBG "https://github.com/trovad/bldc_d/tree/release_6_05//blackmagic/"
    click KERNEL "https://github.com/trovad/bldc_d/tree/release_6_05//ChibiOS_3.0.5/os/rt/"
    click HAL "https://github.com/trovad/bldc_d/tree/release_6_05//ChibiOS_3.0.5/os/hal/"
    click COMM_USB "https://github.com/trovad/bldc_d/blob/release_6_05//comm/comm_usb.c"
    click COMM_CAN "https://github.com/trovad/bldc_d/blob/release_6_05//comm/comm_can.c"
    click LIBCAN "https://github.com/trovad/bldc_d/tree/release_6_05//libcanard/"
    click DR_FLASH "https://github.com/trovad/bldc_d/blob/release_6_05//flash_helper.c"
    click APPS "https://github.com/trovad/bldc_d/blob/release_6_05//applications/applications.mk"

    %% Styles
    classDef build fill:#c2f0c2,stroke:#2f882f
    classDef rtos fill:#c2e0ff,stroke:#0047b3
    classDef drivers fill:#ffe0b3,stroke:#b36b00
    classDef middleware fill:#e6ccff,stroke:#660099
    classDef app fill:#ffd6d6,stroke:#b30000
```
