How eferu/hoverboard-firmware-hack-foc works
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.