# evvgc/firmware architecture

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

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

## Overview

##### Project Type & Purpose
- Full-stack embedded system:
- Host-side GUI application (Processing/Java)
- Target-side firmware for STM32F10x microcontroller
- Bootloader for USB/DFU flashing
- Purpose: configure and control a 3-axis brushless gimbal in real time.

##### Top-Level Components
1. Host PC
– EvvGC_GUI (v0.4) Processing/Java application
– DFU-Util / Bootloader interface
2. Physical Hardware (STM32F10x board)
– Bootloader (maple_boot.bin)
– Firmware v0.4 (compiled ELF/HEX via Eclipse+GCC)
– External peripherals:
- IMU/Gyro (I²C)
- RC Rx (PWM / digital input)
- Motors (PWM outputs)
- EEPROM (internal MCU)
- UART1/UART4 (serial for bootloader and GUI)
- USB-CDC VCP (virtual COM)
3. Software Libraries & BSP
– CMSIS core + DSP libs
– STM32 Standard Peripheral Driver
– USB-FS Device Driver

##### Internal Firmware Modules (logical layers)
A. Hardware Abstraction Layer
- startup_stm32f10x_hd.S, system_stm32f10x.c
- stm32f10x_conf.h + CMSIS + StdPeriph
B. Peripheral Drivers
- src/VCP (USB CDC)
- src/usb.c/.h (USB stack)
- src/usart.c/.h (UART)
- src/i2c.c/.h (I²C for gyro)
- src/adc.c/.h (ADC, if used)
- src/pwm.c/.h (PWM output)
C. Middleware & Utilities
- sys/printf, sys/itoa (retargeted I/O)
- newlib_stubs.c (malloc, etc.)
- ringbuffer.c (buffering comms)
D. Application Layer
- commhandler.c/.h (parse commands from GUI)
- config.c/.h (store/load parameters in EEPROM)
- engine.c/.h (main control loop, PID)
- gyro.c/.h (sensor read + filtering)
- rc.c/.h (process RC input)
- reboot.c/.h (soft reboot to bootloader)
- fasttrig.c/.h (fast math approximations)
- utils.c/.h (support functions)

##### Relationships & Data Flows
- Host PC ↔ USB-CDC ↔ VCP driver ↔ commhandler
(bi-directional: configuration & telemetry)
- commhandler → config → EEPROM (store/retrieve settings)
- commhandler → engine → PWM (motor commands)
- engine ↔ gyro over I²C (sensor data feed)
- engine ↔ rc (user stick input)
- engine uses fasttrig & DSP functions (via CMSIS)
- Any reboot command → reboot module → bootloader

##### Architectural Patterns & Principles
- Layered architecture (HAL → drivers → middleware → app)
- Modular design: each peripheral and function is isolated by C module
- Real-time control loop: deterministic cycle in main.c
- Interrupt-driven comms and timing (SysTick, USB IRQ, USART IRQ)

##### Final Checklist
- Callouts for build tools (GCC/Eclipse) & config files (Makefile, .ld)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Layer
    subgraph "Host PC" 
        style HostGUI fill:#cce5ff,stroke:#333,stroke-width:1px
        HostGUI["EvvGC_GUI v0.4<br/>(Processing/Java)"]:::host
        DFUUtil["dfu-util / Bootloader Interface"]:::host
    end

    %% Bootloader and Firmware Artifacts
    BootloaderBin["Bootloader (maple_boot.bin)"]:::firmware
    FirmwareArtifact["Firmware v0.4<br/>(ELF/HEX)"]:::firmware
    Linker1["stm32_flash.ld"]:::firmware
    Linker2["stm32_flash_usb.ld"]:::firmware

    %% MCU Firmware Layer
    subgraph "MCU Firmware" 
        style HAL fill:#d4edda,stroke:#333,stroke-width:1px
        subgraph "HAL & BSP"
            startup["startup_stm32f10x_hd.S"]:::firmware
            systeminit["system_stm32f10x.c"]:::firmware
            conf["stm32f10x_conf.h"]:::firmware
        end
        subgraph "Peripheral Drivers"
            VCP["src/VCP<br/>(USB CDC)"]:::firmware
            usbDrv["usb.c/.h"]:::firmware
            usartDrv["usart.c/.h"]:::firmware
            i2cDrv["i2c.c/.h"]:::firmware
            adcDrv["adc.c/.h"]:::firmware
            pwmDrv["pwm.c/.h"]:::firmware
        end
        subgraph "Middleware & Utilities"
            newlib["newlib_stubs.c"]:::firmware
            ringbuf["ringbuffer.c/.h"]:::firmware
            printfIo["sys/printf.c/.h"]:::firmware
            itoaIo["sys/itoa.c/.h"]:::firmware
        end
        subgraph "Application Layer"
            comm["commhandler.c/.h"]:::firmware
            configMod["config.c/.h"]:::firmware
            eepromMod["eeprom.c/.h"]:::firmware
            engine["engine.c/.h"]:::firmware
            gyro["gyro.c/.h"]:::firmware
            rcmod["rc.c/.h"]:::firmware
            rebootMod["reboot.c/.h"]:::firmware
            fasttrig["fasttrig.c/.h"]:::firmware
            utils["utils.c/.h"]:::firmware
        end
        subgraph "Core & IRQ"
            mainLoop["main.c/.h"]:::firmware
            sysTick["systick.c/.h"]:::firmware
            irqHandlers["stm32_it.c/.h"]:::firmware
        end
        subgraph "Definitions & Pins"
            definitions["definitions.h"]:::firmware
            pins["pins.c/.h"]:::firmware
        end
    end

    %% Hardware Peripherals
    subgraph "Hardware Peripherals"
        style Periph fill:#ffe5b4,stroke:#333,stroke-width:1px
        STM32["STM32F10x MCU"]:::hardware
        IMU["IMU/Gyro<br/>(I²C)"]:::hardware
        RC_RX["RC Rx<br/>(PWM/digital)"]:::hardware
        Motors["Motors<br/>(PWM outputs)"]:::hardware
        EEPROM_HW["EEPROM<br/>(internal)"]:::hardware
        UART1["UART1 / UART4"]:::hardware
        USBCDC["USB-CDC VCP"]:::hardware
    end

    %% Libraries & BSP
    subgraph "Libraries & BSP"
        style Lib fill:#e2e3e5,stroke:#333,stroke-width:1px
        CMSIS["CMSIS Core & DSP Libs"]:::libs
        StdPeriph["STM32 StdPeriph Driver"]:::libs
        USBFS["USB-FS Device Driver"]:::libs
    end

    %% Connections
    HostGUI -->|"USB-CDC VCP"| USBCDC
    DFUUtil -->|"DFU Serial"| BootloaderBin
    USBCDC -->|"VCP Driver"| VCP
    VCP -->|"calls"| comm
    comm -->|"config/telemetry"| configMod
    configMod -->|"store/retrieve"| EEPROM_HW
    comm -->|"commands"| engine
    engine -->|"PWM commands"| pwmDrv
    pwmDrv -->|"PWM signals"| Motors
    engine -->|"I²C data"| IMU
    engine -->|"stick input"| rcmod
    rcmod -->|"digital input"| RC_RX
    engine -->|"uses"| fasttrig
    engine -->|"uses DSP"| CMSIS
    mainLoop -->|"SysTick interrupt"| engine
    rebootMod -->|"soft reboot"| BootloaderBin

    %% Click Events
    click HostGUI "https://github.com/evvgc/firmware/tree/master/GUI/EvvGC_GUI_v0_4"
    click BootloaderBin "https://github.com/evvgc/firmware/blob/master/bootloader/maple_boot.bin"
    click FirmwareArtifact "https://github.com/evvgc/firmware/blob/master/built-versions/0.4/STM32Gimbal.hex"
    click Linker1 "https://github.com/evvgc/firmware/blob/master/stm32_flash.ld"
    click Linker2 "https://github.com/evvgc/firmware/blob/master/stm32_flash_usb.ld"
    click startup "https://github.com/evvgc/firmware/blob/master/src/startup/startup_stm32f10x_hd.S"
    click systeminit "https://github.com/evvgc/firmware/blob/master/src/system_stm32f10x.c"
    click conf "https://github.com/evvgc/firmware/blob/master/src/stm32f10x_conf.h"
    click VCP "https://github.com/evvgc/firmware/tree/master/src/VCP"
    click usbDrv "https://github.com/evvgc/firmware/blob/master/src/usb.c"
    click usbDrv "https://github.com/evvgc/firmware/blob/master/src/usb.h"
    click usartDrv "https://github.com/evvgc/firmware/blob/master/src/usart.c"
    click usartDrv "https://github.com/evvgc/firmware/blob/master/src/usart.h"
    click i2cDrv "https://github.com/evvgc/firmware/blob/master/src/i2c.c"
    click i2cDrv "https://github.com/evvgc/firmware/blob/master/src/i2c.h"
    click adcDrv "https://github.com/evvgc/firmware/blob/master/src/adc.c"
    click adcDrv "https://github.com/evvgc/firmware/blob/master/src/adc.h"
    click pwmDrv "https://github.com/evvgc/firmware/blob/master/src/pwm.c"
    click pwmDrv "https://github.com/evvgc/firmware/blob/master/src/pwm.h"
    click newlib "https://github.com/evvgc/firmware/blob/master/src/newlib_stubs.c"
    click ringbuf "https://github.com/evvgc/firmware/blob/master/src/ringbuffer.c"
    click ringbuf "https://github.com/evvgc/firmware/blob/master/src/ringbuffer.h"
    click printfIo "https://github.com/evvgc/firmware/blob/master/src/sys/printf.c"
    click printfIo "https://github.com/evvgc/firmware/blob/master/src/sys/printf.h"
    click itoaIo "https://github.com/evvgc/firmware/blob/master/src/sys/itoa.c"
    click itoaIo "https://github.com/evvgc/firmware/blob/master/src/sys/itoa.h"
    click comm "https://github.com/evvgc/firmware/blob/master/src/commhandler.c"
    click comm "https://github.com/evvgc/firmware/blob/master/src/commhandler.h"
    click configMod "https://github.com/evvgc/firmware/blob/master/src/config.c"
    click configMod "https://github.com/evvgc/firmware/blob/master/src/config.h"
    click eepromMod "https://github.com/evvgc/firmware/blob/master/src/eeprom.c"
    click eepromMod "https://github.com/evvgc/firmware/blob/master/src/eeprom.h"
    click engine "https://github.com/evvgc/firmware/blob/master/src/engine.c"
    click engine "https://github.com/evvgc/firmware/blob/master/src/engine.h"
    click gyro "https://github.com/evvgc/firmware/blob/master/src/gyro.c"
    click gyro "https://github.com/evvgc/firmware/blob/master/src/gyro.h"
    click rcmod "https://github.com/evvgc/firmware/blob/master/src/rc.c"
    click rcmod "https://github.com/evvgc/firmware/blob/master/src/rc.h"
    click rebootMod "https://github.com/evvgc/firmware/blob/master/src/reboot.c"
    click rebootMod "https://github.com/evvgc/firmware/blob/master/src/reboot.h"
    click fasttrig "https://github.com/evvgc/firmware/blob/master/src/fasttrig.c"
    click fasttrig "https://github.com/evvgc/firmware/blob/master/src/fasttrig.h"
    click utils "https://github.com/evvgc/firmware/blob/master/src/utils.c"
    click utils "https://github.com/evvgc/firmware/blob/master/src/utils.h"
    click mainLoop "https://github.com/evvgc/firmware/blob/master/src/main.c"
    click mainLoop "https://github.com/evvgc/firmware/blob/master/src/main.h"
    click sysTick "https://github.com/evvgc/firmware/blob/master/src/systick.c"
    click sysTick "https://github.com/evvgc/firmware/blob/master/src/systick.h"
    click irqHandlers "https://github.com/evvgc/firmware/blob/master/src/stm32_it.c"
    click irqHandlers "https://github.com/evvgc/firmware/blob/master/src/stm32_it.h"
    click definitions "https://github.com/evvgc/firmware/blob/master/src/definitions.h"
    click pins "https://github.com/evvgc/firmware/blob/master/src/pins.c"
    click pins "https://github.com/evvgc/firmware/blob/master/src/pins.h"
    click CMSIS "https://github.com/evvgc/firmware/tree/master/Libraries/CMSIS"
    click StdPeriph "https://github.com/evvgc/firmware/tree/master/Libraries/STM32F10x_StdPeriph_Driver"
    click USBFS "https://github.com/evvgc/firmware/tree/master/Libraries/STM32_USB-FS-Device_Driver"

    %% Styles
    classDef host fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef firmware fill:#d4edda,stroke:#333,stroke-width:1px
    classDef hardware fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef libs fill:#e2e3e5,stroke:#333,stroke-width:1px
```
