# gyrocopterllc/ebike-g4 architecture

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

- Interactive diagram: https://gitdiagram.com/gyrocopterllc/ebike-g4
- Repository: https://github.com/gyrocopterllc/ebike-g4

## Overview

1. This repository is an embedded firmware project for an STM32G4-based brushless DC motor controller for e-bikes. The core product is the `ebike-g4` firmware; everything else supports that firmware at build time or for host-side tooling.

2. The firmware is organized around a classic bare-metal MCU architecture: startup/system code under `system/`, application logic under `ebike-g4/src`, and public interfaces under `ebike-g4/include`. The project uses CMSIS and STM32G473 device headers, plus linker scripts in `ldscripts/` to define memory layout and section placement.

3. The main runtime entry point is `src/main.c`, with low-level initialization handled by system startup/reset code and interrupt plumbing in `src/interrupts.c`. The control flow is likely interrupt-driven: hardware peripherals wake the controller, while the main loop coordinates motor control, telemetry, and safety tasks.

4. Motor control is split into a dedicated control subsystem: `motor_loop.c`, `foc_lib.c`, `cordic_sin_cos.c`, and `power_calcs.c`. This is the functional core of the controller, responsible for field-oriented control math, torque/speed-related calculations, and the periodic commutation/control loop.

5. Hardware actuation is abstracted through peripheral drivers for PWM, GPIO, ADC, timers, and the DRV8353 gate driver. Files such as `pwm.c`, `adc.c`, `gpio.c`, and `drv8353.c` form the hardware boundary between the control algorithm and the inverter power stage.

6. Sensor and input acquisition is handled by `hall_sensor.c` and `throttle.c`, with ADC-based measurements feeding the control loop. These modules provide the physical feedback signals the controller needs for rotor position, rider input, and likely current/voltage sensing.

7. Communications are a separate subsystem with both wired and USB paths. `uart.c`, `usb.c`, `usb_cdc.c`, `usb_data_comm.c`, `hbd_data_comm.c`, `data_packet.c`, `data_commands.c`, and `ram_commands.c` suggest a packetized command/telemetry protocol with multiple transports and command namespaces.

8. Telemetry and observability are first-class concerns. `live_data.c` plus `scripts/live_data_ids.py` and generated headers in `scripts/project_live_data_ids.h` indicate a structured live-data channel used to stream internal state out of the controller for monitoring and tuning.

9. Configuration is split between persistent and runtime domains. `project_parameters.h`, `periphconfig.h`, and `pinconfig.h` define compile-time wiring and tuning constants, while `eeprom_emulation.c` provides nonvolatile storage behavior on top of MCU flash rather than a discrete EEPROM.

10. Safety and robustness are handled by watchdog and bounded initialization support. `wdt.c` enforces liveness, `delay.c` provides timing primitives, and the startup/reset sources in `system/src/cortexm` ensure hardware comes up in a controlled state before application code runs.

11. The `scripts/` directory is a host-side code generation and analysis boundary, not part of the firmware image. `datavars.xml`, `comm_commands.xml`, `datavar_codegen.py`, and `config_vars.py` generate C headers such as `project_configuration_variables.h` and `project_live_data_ids.h`, keeping protocol IDs and configuration constants synchronized between firmware and tools.

12. The plotting utility under `scripts/plotMotorData/` is a separate desktop analysis tool that consumes controller packets. Its Python/UI files indicate the repo also includes an offline visualization workflow for motor data, likely used during tuning and debugging.

13. Build and tooling are centered on GNU MCU Eclipse / Eclipse CDT, with a standard embedded C toolchain and newlib support. The `system/src/newlib` files provide minimal C runtime/syscall glue, while the `system/src/diag` and `_write.c` pieces support semihosting or trace-style debugging on the target.

14. For an architecture diagram, the key boundaries are: host-side code generation and plotting; MCU startup/runtime infrastructure; peripheral drivers; the motor control core; and communication/telemetry channels. The firmware’s central data flow is sensor inputs and command packets in, control math in the middle, and PWM/gate-driver outputs plus telemetry packets out.

Main entry points: [`ebike-g4/src/motor_loop.c`](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/motor_loop.c) (Motor loop), [`ebike-g4/src/data_packet.c`](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/data_packet.c) (Packet core), [`ebike-g4/src/main.c`](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/main.c) (Main loop), [`ebike-g4/system/src/cortexm/_reset_hardware.c`](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/system/src/cortexm/_reset_hardware.c) (Reset boot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host_tools["Host tools"]
  node_scripts_codegen["Codegen<br/>python/xml generators<br/>[datavar_codegen.py]"]
  node_scripts_plotter["Plotter<br/>desktop analysis<br/>[plotMotorData.py]"]
end

subgraph group_firmware_app["Firmware app"]
  node_main(("Main loop<br/>application entry<br/>[main.c]"))
  node_interrupts["Interrupts<br/>ISR plumbing<br/>[interrupts.c]"]
  node_motor_loop["Motor loop<br/>control scheduler<br/>[motor_loop.c]"]
  node_foc_lib["FOC math<br/>motor control math<br/>[foc_lib.c]"]
  node_power_calcs["Power calc<br/>electrical math<br/>[power_calcs.c]"]
  node_pwm["PWM<br/>actuation driver<br/>[pwm.c]"]
  node_adc["ADC<br/>measurement driver<br/>[adc.c]"]
  node_drv8353["Gate driver<br/>power-stage driver<br/>[drv8353.c]"]
  node_hall_sensor["Hall sensor<br/>rotor sensor<br/>[hall_sensor.c]"]
  node_throttle["Throttle<br/>user input<br/>[throttle.c]"]
  node_eeprom_emulation[("Config store<br/>nonvolatile storage<br/>[eeprom_emulation.c]")]
  node_wdt["Watchdog<br/>safety service<br/>[wdt.c]"]
end

subgraph group_mcu_support["MCU support"]
  node_startup["Reset boot<br/>boot/runtime support<br/>[_reset_hardware.c]"]
  node_cmsis["CMSIS<br/>device support<br/>[system_stm32g4xx.c]"]
  node_linker["Linker scripts<br/>memory layout<br/>[sections.ld]"]
end

subgraph group_protocols["Protocol layer"]
  node_data_packet["Packet core<br/>packet protocol<br/>[data_packet.c]"]
  node_data_commands["Commands<br/>command handlers<br/>[data_commands.c]"]
  node_usb_data_comm["USB data<br/>usb transport<br/>[usb_data_comm.c]"]
  node_hbd_data_comm["UART data<br/>serial transport<br/>[hbd_data_comm.c]"]
  node_live_data["Live data<br/>telemetry stream<br/>[live_data.c]"]
end

node_scripts_codegen -.->|"generates IDs"| node_data_commands
node_scripts_codegen -.->|"generates IDs"| node_live_data
node_scripts_plotter -.->|"consumes packets"| node_live_data
node_startup -->|"boots"| node_main
node_cmsis -->|"provides"| node_startup
node_linker -->|"lays out"| node_startup
node_main -->|"coordinates"| node_motor_loop
node_interrupts -->|"triggers"| node_motor_loop
node_motor_loop -->|"uses"| node_foc_lib
node_motor_loop -->|"uses"| node_power_calcs
node_motor_loop -->|"reads"| node_hall_sensor
node_motor_loop -->|"reads"| node_throttle
node_motor_loop -->|"samples"| node_adc
node_motor_loop -->|"drives"| node_pwm
node_motor_loop -->|"controls"| node_drv8353
node_adc -->|"feeds"| node_power_calcs
node_data_packet -->|"runs over"| node_usb_data_comm
node_data_packet -->|"runs over"| node_hbd_data_comm
node_data_commands -->|"dispatches"| node_data_packet
node_live_data -->|"publishes"| node_data_packet
node_eeprom_emulation -->|"stores"| node_data_commands
node_wdt -->|"guards"| node_main

click node_scripts_codegen "https://github.com/gyrocopterllc/ebike-g4/blob/master/scripts/datavar_codegen.py"
click node_scripts_plotter "https://github.com/gyrocopterllc/ebike-g4/blob/master/scripts/plotMotorData/plotMotorData.py"
click node_main "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/main.c"
click node_interrupts "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/interrupts.c"
click node_motor_loop "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/motor_loop.c"
click node_foc_lib "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/foc_lib.c"
click node_power_calcs "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/power_calcs.c"
click node_pwm "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/pwm.c"
click node_adc "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/adc.c"
click node_drv8353 "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/drv8353.c"
click node_hall_sensor "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/hall_sensor.c"
click node_throttle "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/throttle.c"
click node_data_packet "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/data_packet.c"
click node_data_commands "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/data_commands.c"
click node_usb_data_comm "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/usb_data_comm.c"
click node_hbd_data_comm "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/hbd_data_comm.c"
click node_live_data "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/live_data.c"
click node_eeprom_emulation "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/eeprom_emulation.c"
click node_wdt "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/wdt.c"
click node_startup "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/system/src/cortexm/_reset_hardware.c"
click node_cmsis "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/system/src/cmsis/system_stm32g4xx.c"
click node_linker "https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/ldscripts/sections.ld"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scripts_codegen,node_scripts_plotter toneBlue
class node_main,node_interrupts,node_motor_loop,node_foc_lib,node_power_calcs,node_pwm,node_adc,node_drv8353,node_hall_sensor,node_throttle,node_eeprom_emulation,node_wdt toneAmber
class node_startup,node_cmsis,node_linker toneMint
class node_data_packet,node_data_commands,node_usb_data_comm,node_hbd_data_comm,node_live_data toneRose
```

## Components

### Host tools

Desktop-side code generation, protocol sync, and offline analysis.

- [Codegen](https://github.com/gyrocopterllc/ebike-g4/blob/master/scripts/datavar_codegen.py): python/xml generators · Synchronizes command IDs, configuration variables, and live-data metadata for firmware and tools. · `scripts/datavar_codegen.py`
- [Plotter](https://github.com/gyrocopterllc/ebike-g4/blob/master/scripts/plotMotorData/plotMotorData.py): desktop analysis · Offline visualization tool for controller packets and motor data. · `scripts/plotMotorData/plotMotorData.py`

### Firmware app

Main STM32G4 motor-controller firmware.

- [Main loop](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/main.c): application entry · Top-level firmware entry point and control orchestration. · `ebike-g4/src/main.c`
- [Interrupts](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/interrupts.c): ISR plumbing · Interrupt handlers and event dispatch into the runtime. · `ebike-g4/src/interrupts.c`
- [Motor loop](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/motor_loop.c): control scheduler · Periodic control-loop coordination for motor regulation and safety. · `ebike-g4/src/motor_loop.c`
- [FOC math](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/foc_lib.c): motor control math · Field-oriented control calculations and transforms used by the controller. · `ebike-g4/src/foc_lib.c`
- [Power calc](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/power_calcs.c): electrical math · Derived torque, current, voltage, and power calculations. · `ebike-g4/src/power_calcs.c`
- [PWM](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/pwm.c): actuation driver · PWM generation for inverter phase drive and timing output. · `ebike-g4/src/pwm.c`
- [ADC](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/adc.c): measurement driver · Analog sampling path for current, voltage, and other sensed inputs. · `ebike-g4/src/adc.c`
- [Gate driver](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/drv8353.c): power-stage driver · DRV8353 interface for inverter gate-drive control and fault handling. · `ebike-g4/src/drv8353.c`
- [Hall sensor](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/hall_sensor.c): rotor sensor · Rotor position sensing for commutation and startup. · `ebike-g4/src/hall_sensor.c`
- [Throttle](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/throttle.c): user input · Rider command input acquisition and conditioning. · `ebike-g4/src/throttle.c`
- [Config store](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/eeprom_emulation.c): nonvolatile storage · Persistent parameter storage backed by flash EEPROM emulation. · `ebike-g4/src/eeprom_emulation.c`
- [Watchdog](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/wdt.c): safety service · Liveness enforcement and recovery support for the firmware runtime. · `ebike-g4/src/wdt.c`

### MCU support

Startup, CMSIS, runtime glue, and memory layout.

- [Reset boot](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/system/src/cortexm/_reset_hardware.c): boot/runtime support · Hardware reset and initialization sequence before application code runs. · `ebike-g4/system/src/cortexm/_reset_hardware.c`
- [CMSIS](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/system/src/cmsis/system_stm32g4xx.c): device support · ARM CMSIS and STM32G4 device headers, vector tables, and system setup. · `ebike-g4/system/src/cmsis/system_stm32g4xx.c`
- [Linker scripts](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/ldscripts/sections.ld): memory layout · Target memory map and section placement for the embedded image. · `ebike-g4/ldscripts/sections.ld`

### Protocol layer

Shared packet, command, and telemetry boundaries inside firmware.

- [Packet core](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/data_packet.c): packet protocol · Shared packet framing and command dispatch core. · `ebike-g4/src/data_packet.c`
- [Commands](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/data_commands.c): command handlers · Command namespace and request handling for control and configuration. · `ebike-g4/src/data_commands.c`
- [USB data](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/usb_data_comm.c): usb transport · USB-side packet transport and application data exchange. · `ebike-g4/src/usb_data_comm.c`
- [UART data](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/hbd_data_comm.c): serial transport · Wired serial packet transport for controller data and commands. · `ebike-g4/src/hbd_data_comm.c`
- [Live data](https://github.com/gyrocopterllc/ebike-g4/blob/master/ebike-g4/src/live_data.c): telemetry stream · Structured observability channel for internal state and tuning data. · `ebike-g4/src/live_data.c`

## Connections

- Codegen → Commands: generates IDs · Keeps command definitions synchronized with firmware protocol code.
- Codegen → Live data: generates IDs · Produces live-data identifiers used by firmware and tooling.
- Plotter → Live data: consumes packets · Reads controller telemetry for offline visualization.
- Reset boot → Main loop: boots · Transfers control into the application entry point after reset.
- CMSIS → Reset boot: provides · Supplies device headers, vector tables, and core runtime support.
- Linker scripts → Reset boot: lays out · Defines memory regions and section placement for the target image.
- Main loop → Motor loop: coordinates · Main application orchestrates the control subsystem.
- Interrupts → Motor loop: triggers · Interrupts wake or schedule periodic control work.
- Motor loop → FOC math: uses · Core loop relies on FOC transforms and control math.
- Motor loop → Power calc: uses · Derives electrical and mechanical state for control decisions.
- Motor loop → Hall sensor: reads · Uses rotor position feedback for commutation and alignment.
- Motor loop → Throttle: reads · Consumes rider command input.
- Motor loop → ADC: samples · Pulls sensed electrical measurements into the control loop.
- Motor loop → PWM: drives · Produces inverter PWM outputs from control decisions.
- Motor loop → Gate driver: controls · Manages gate-driver enable and fault state around the power stage.
- ADC → Power calc: feeds · Measurement data supports electrical calculations.
- Packet core → USB data: runs over · Packet framing is transported over USB.
- Packet core → UART data: runs over · Packet framing is transported over UART.
- Commands → Packet core: dispatches · Command handlers are invoked through the packet layer.
- Live data → Packet core: publishes · Telemetry is exposed through the shared packet system.
- Config store → Commands: stores · Commands can read or update persistent settings.
- Watchdog → Main loop: guards · Watchdog constrains firmware liveness and recovery.
