How gyrocopterllc/ebike-g4 works
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: motor_loop.c Motor loop · data_packet.c Packet core · main.c Main loop · _reset_hardware.c Reset boot
Components 22
Host tools
Desktop-side code generation, protocol sync, and offline analysis.
Firmware app
Main STM32G4 motor-controller firmware.
- Main loop · Top-level firmware entry point and control orchestration.
ebike-g4/src/main.c - Interrupts · Interrupt handlers and event dispatch into the runtime.
ebike-g4/src/interrupts.c - Motor loop · Periodic control-loop coordination for motor regulation and safety.
ebike-g4/src/motor_loop.c - FOC math · Field-oriented control calculations and transforms used by the controller.
ebike-g4/src/foc_lib.c - Power calc · Derived torque, current, voltage, and power calculations.
ebike-g4/src/power_calcs.c - PWM · PWM generation for inverter phase drive and timing output.
ebike-g4/src/pwm.c - ADC · Analog sampling path for current, voltage, and other sensed inputs.
ebike-g4/src/adc.c - Gate driver · DRV8353 interface for inverter gate-drive control and fault handling.
ebike-g4/src/drv8353.c - Hall sensor · Rotor position sensing for commutation and startup.
ebike-g4/src/hall_sensor.c - Throttle · Rider command input acquisition and conditioning.
ebike-g4/src/throttle.c - Config store · Persistent parameter storage backed by flash EEPROM emulation.
ebike-g4/src/eeprom_emulation.c - Watchdog · 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 · Hardware reset and initialization sequence before application code runs.
ebike-g4/system/src/cortexm/_reset_hardware.c - CMSIS · ARM CMSIS and STM32G4 device headers, vector tables, and system setup.
ebike-g4/system/src/cmsis/system_stm32g4xx.c - Linker scripts · 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 · Shared packet framing and command dispatch core.
ebike-g4/src/data_packet.c - Commands · Command namespace and request handling for control and configuration.
ebike-g4/src/data_commands.c - USB data · USB-side packet transport and application data exchange.
ebike-g4/src/usb_data_comm.c - UART data · Wired serial packet transport for controller data and commands.
ebike-g4/src/hbd_data_comm.c - Live data · Structured observability channel for internal state and tuning data.
ebike-g4/src/live_data.c
Connections 22
- 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.