# eferu/hoverboard-firmware-hack-foc architecture

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

- Interactive diagram: https://gitdiagram.com/eferu/hoverboard-firmware-hack-foc
- Repository: https://github.com/eferu/hoverboard-firmware-hack-foc

## Overview

##### Project Type and Purpose
- This is an embedded‐firmware project implementing Field-Oriented Control (FOC) for stock hoverboards on an STM32F103 (or GD32F103) MCU. Its goal is to replace standard commutation with FOC for smoother, more efficient BLDC motor control, with multiple control modes (voltage, speed, torque) and a variety of input variants (ADC pots, UART, PPM, PWM, iBUS, Nunchuk, pedals).

##### File‐Structure Analysis
- Top-level build & config files: Makefile, platformio.ini, MDK-ARM project files (.uvprojx, .uvoptx), linker and startup scripts.
- Drivers/: CMSIS (core + DSP library + device headers + RTOS template), STM32F1xx_HAL_Driver (HAL API for GPIO/ADC/DMA/TIM/UART/I2C, etc.).
- Inc/: Board-specific config headers (config.h, defines.h), peripheral abstractions (comms.h, eeprom.h, hd44780.h, pcf8574.h), RTOS/STM32 interrupts and system headers.
- Src/: Application code:
- BLDC_controller.c / _data.c – FOC algorithm implementation + calibrated parameters (fixed-point).
- control.c, bldc.c – high-level control loop orchestrator.
- comms.c – serial protocol handler.
- setup.c, util.c, eeprom.c, hd44780.c, pcf8574.c – initialization, utility, nonvolatile storage, display / I²C expander drivers.
- stm32f1xx_it.c, system_stm32f1xx.c – interrupt handlers, system clock setup.
- Arduino/: Example host sketch showing how to drive the firmware via serial.

##### README Insights
- Clearly describes hardware pinouts, supported sideboard cables, peripheral usage (USART2/3 for UART, PWM, ADC, I²C), FOC vs. commutation vs. sinusoidal modes, calibration data, build badges.
- Points to related FOC controller repo (bldc-motor-control-FOC) and webview for algorithm exploration.
- Enumerates firmware “variants” that map different input sources to the same control core.

a. Main Components
- Hardware Layer
- STM32F103 MCU – CPU core + peripherals (ADC, TIM/PWM, UART2/3, I²C, DMA, NVIC).
- Motor-power stage (MOSFET bridge), phase-current and voltage sensors.
- Sideboard connector cables carrying GND, 12/15V, UART2/3 lines, optional analog inputs (pots), I²C, PWM/PPM, iBUS.
- Optional host / Arduino / PC (serial console).
- Firmware Layer
1. CMSIS & DSP Lib – core startup, vector table, optimized math routines.
2. HAL Driver Layer – GPIO, ADC, TIM (PWM), UART, I²C, DMA, RCC.
3. Board‐Support Package – board init (setup.c), system clock (system_stm32f1xx.c), interrupt handlers.
4. Motor Control Core – BLDC_controller.c + BLDC_controller_data.c implementing FOC algorithm, state estimation, field-weakening.
5. Control Orchestrator – control.c / bldc.c scheduling the real-time loop:
- ADC interrupt → sample phase currents/voltages
- Run FOC math (coordinate transforms, PI controller)
- Update PWM duty via HAL TIM API
6. Communication & Input Variants – comms.c parsing UART commands; ADC-based variants; PWM/PPM input capture; iBUS (serial) decoding; Nunchuk I²C.
7. Utilities – eeprom.c (store/load calibration), hd44780.c (LCD display over GPIO), pcf8574.c (I²C I/O expander), util.c (math helpers).

b. Relationships & Data Flows
- HAL drivers feed Board‐Support init & Motor Control Core.
- Motor Control Core outputs duty cycles to TIM PWM registers → Motor power stage.
- Comms/UI modules ingest commands from USART2/3 → control parameters → Motor Control Core.
- Configuration (config.h, BLDC_controller_data) statically compiled or loaded from EEPROM.

c. Architectural Patterns
- Layered architecture: Hardware → HAL → Board-Support → Application (Control Core + Comms + Utilities).
- Real-time control loop implemented via interrupt driven sampling (ADC/DMA + TIM) and periodic algorithm execution.
- Modular “variant” plugins mapping physical inputs to the same controller core.

d. Key Technologies & Frameworks
- CMSIS-DSP for fixed-point math.
- STM32 HAL for peripheral abstraction.
- Makefile / PlatformIO / MDK-ARM for multi-toolchain builds.
- FixedPointViewer tool for calibrating BLDC parameters.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        Sideboard["Sideboard Connector"]:::external
        ArduinoHost["Arduino Host / PC"]:::external
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        MCU["STM32F103<br/>ADC/TIM/PWM/UART/I²C/DMA"]:::hardware
        PhaseSensors["Phase Currents/Voltages Sensors"]:::hardware
        MotorPS["Motor Power Stage<br/>(MOSFET Bridge)"]:::hardware
    end

    %% HAL & CMSIS
    subgraph "HAL & CMSIS Layer"
        direction TB
        CMSIS["CMSIS & DSP Library"]:::hal
        HALDrv["STM32 HAL Driver"]:::hal
    end

    %% Board-Support Package
    subgraph "Board-Support Package"
        direction TB
        Setup["Board Init (setup.c)"]:::hal
        System["System Clock & Startup"]:::hal
        IRQ["Interrupt Handlers"]:::hal
        Config["Config Headers"]:::hal
        Defines["Defines Headers"]:::hal
    end

    %% Application Modules
    subgraph "Application Layer"
        direction TB
        subgraph "Motor Control Core"
            ControlCore["FOC Algorithm<br/>(BLDC_controller.c)"]:::app
            Data["Controller Data<br/>(BLDC_controller_data.c)"]:::app
        end
        Orchestrator["Control Orchestrator<br/>(control.c,bldc.c)"]:::app
        MainLoop["Main (main.c)"]:::app
        Comms["Comm & Input Variants<br/>(comms.c)"]:::app

        subgraph Utilities
            EEPROM["EEPROM Storage"]:::app
            LCD["LCD Display"]:::app
            Expander["I²C Expander"]:::app
            Util["Math Helpers"]:::app
        end
    end

    %% Build & Documentation
    subgraph "Build & Documentation"
        direction TB
        Build["Makefile"]:::external
        PlatformIO["platformio.ini"]:::external
        MDK["MDK-ARM Projects"]:::external
        Docs["Documentation & Schematics"]:::external
    end

    %% Connections
    Sideboard --> MCU
    ArduinoHost --> Comms

    PhaseSensors --> MCU
    MCU --> CMSIS
    MCU --> HALDrv

    CMSIS --> Setup
    HALDrv --> Setup
    HALDrv --> System
    HALDrv --> IRQ

    Setup --> MainLoop
    System --> MainLoop
    IRQ --> Orchestrator

    Config --> ControlCore
    Defines --> ControlCore

    MainLoop --> Orchestrator
    Orchestrator --> ControlCore
    Orchestrator -->|"ADC Interrupt"| ControlCore
    ControlCore --> MCU
    MCU --> MotorPS

    Sideboard --> Comms
    Comms --> Orchestrator

    EEPROM --> ControlCore
    LCD --> MainLoop
    Expander --> MainLoop
    Util --> ControlCore

    Build -.-> MainLoop
    PlatformIO -.-> MainLoop
    MDK -.-> MainLoop
    Docs -.-> MainLoop

    %% Click Events
    click CMSIS "https://github.com/eferu/hoverboard-firmware-hack-foc/tree/main/Drivers/CMSIS"
    click HALDrv "https://github.com/eferu/hoverboard-firmware-hack-foc/tree/main/Drivers/STM32F1xx_HAL_Driver"
    click Setup "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/setup.c"
    click System "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/system_stm32f1xx.c"
    click IRQ "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/stm32f1xx_it.c"
    click ControlCore "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/BLDC_controller.c"
    click Data "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/BLDC_controller_data.c"
    click Orchestrator "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/control.c"
    click MainLoop "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/main.c"
    click Comms "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/comms.c"
    click EEPROM "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/eeprom.c"
    click LCD "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/hd44780.c"
    click Expander "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/pcf8574.c"
    click Util "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Src/util.c"
    click Config "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Inc/config.h"
    click Defines "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Inc/defines.h"
    click Build "https://github.com/eferu/hoverboard-firmware-hack-foc/tree/main/Makefile"
    click PlatformIO "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/platformio.ini"
    click MDK "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/MDK-ARM/mainboard-hack.uvprojx"
    click Docs "https://github.com/eferu/hoverboard-firmware-hack-foc/tree/main/docs/"
    click ArduinoHost "https://github.com/eferu/hoverboard-firmware-hack-foc/blob/main/Arduino/hoverserial/hoverserial.ino"

    %% Styles
    classDef hardware fill:#AED6F1,stroke:#1F618D,color:#1B2631
    classDef hal fill:#D5DBDB,stroke:#566573,color:#1B2631
    classDef app fill:#ABEBC6,stroke:#1D8348,color:#1B2631
    classDef external fill:#F9E79F,stroke:#B7950B,color:#1B2631
```
