# hoverboard-firmware-hack-FOC and the control loop behind a hoverboard

> This firmware replaces the commutation control on a stock hoverboard mainboard with Field Oriented Control, giving three selectable control types and, inside FOC, voltage, speed and torque modes with current and speed protection. It targets the STM32F103 family, is built with arm-none-eabi-gcc, PlatformIO or the Keil project, and its most useful feature is a comparison table that admits where the other methods win.

**EFeru/hoverboard-firmware-hack-FOC** — With Field Oriented Control (FOC)

- Repository: https://github.com/EFeru/hoverboard-firmware-hack-FOC
- Stars: 1,837 · Forks: 1,451
- Language: C
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/eferu-hoverboard-firmware-hack-foc

## Firmware for the brain of a stock hoverboard

This repository implements Field Oriented Control for stock hoverboards, and the framing matters. It is not a controller board design and not a general BLDC library. It is replacement firmware for the mainboard of a hoverboard, the part with the two sideboards and the two motors, and the companion project bldc-motor-control-FOC holds the controller design itself.

The reason to replace the stock firmware is stated as a comparison with the commutation method, which is what a stock hoverboard uses. The claimed advantages are reduced noise and vibrations, smooth torque output and improved motor efficiency, which the README turns into lower energy consumption, and field weakening to increase the maximum speed range.

The audience is therefore specific: people with a hoverboard they want to ride better, or turn into something else. The videos linked in the README make that concrete, with a hovercar, cruise control functionality, hovercar pedals, and two side by side comparison plots of commutation against FOC at constant and at variable speed. A project that is mostly firmware for a consumer product is also a project where the hardware list matters, because a lot of people reading it will not know whether their board is supported.

The repository is a real embedded project rather than a script. The top level holds a Makefile, a PlatformIO configuration, a Keil project directory, an Arduino directory, the linker script STM32F103RCTx_FLASH.ld, the startup assembly file, a Drivers/ directory with the STM32 HAL, Inc/, Src/ and docs/ with the reverse engineered schematics and the datasheets for both supported microcontrollers.

## The sideboard cables define the interface, and one USART is not 5V tolerant

The hardware section is where most readers will find the answer to whether this applies to them, and it is shorter than expected.

Hoverboards with a mainboard also come with two sideboards, and the mainboard supports two 4-pin cables that were originally connected to those sideboards. Those cables break out ground, 12 and 15 volts, and USART2 and USART3. Both USARTs support UART, PWM, PPM and iBUS input, USART2 can also be used as a 12-bit ADC, and USART3 can be used for I2C.

The electrical warning is explicit. USART3, the right sideboard cable, is 5V tolerant. USART2, the left sideboard cable, is not. That asymmetry is the kind of detail that damages hardware if it is missed, so it belongs in any summary of the project.

The processor is typically an STM32F103RCT6, and some mainboards feature a GD32F103RCT6, which this firmware also supports. The reverse engineered schematics of the mainboard are published in the repository as a PDF, along with the datasheets for both microcontrollers in the docs/literature directory.

One exclusion is stated up front, in a note near the top of the README: split boards are not supported, and the wiki has a page describing the sideboards for this firmware. Anything built on the split board topology, where the two motor controllers live on separate boards, is out of scope for this project and the wiki entry is the place to confirm it.

## Three control types, and three ways to run FOC

The firmware offers three control types, selected through the CTRL_TYP_SEL parameter in config.h. Commutation, abbreviated COM_CTRL, is the stock method. Sinusoidal, SIN_CTRL, drives the phases with a sine wave. Field Oriented Control, FOC_CTRL, is the point of the project.

FOC itself has three control modes, chosen with the CTRL_MOD_REQ parameter, and each is described in terms of what it regulates and what it is recommended for.

Voltage mode, VLT_MODE, applies a constant voltage to the motors and is recommended for robotics applications or cases where a fast motor response is required. Speed mode, SPD_MODE, runs a closed loop controller that realises the input speed in RPM target by rejecting any disturbance such as a resistive load applied to the motor, and is recommended for robotics or constant speed applications. Torque mode, TRQ_MODE, realises the input torque target and enables motor freewheeling when the torque target is zero, which is the mode recommended for most applications with a sitting human driver.

That last detail is the one that matters for anyone converting a hoverboard into a vehicle, because freewheeling is what a rider expects when they stop asking for torque, and standstill hold is what keeps the board from rolling away. The selection is done in a configuration header, not at runtime, so the choice is compiled into the firmware:

```bash
# control selection, set in config.h
CTRL_TYP_SEL
FOC_CTRL
CTRL_MOD_REQ
TRQ_MODE
```

The Arduino directory at the root of the repository suggests the project can also be built and flashed through the Arduino tooling, which is a convenience for people who do not normally work with embedded C toolchains.

## The comparison table admits where the other methods win

The most valuable thing in the README is the table comparing control methods across six properties: complexity, efficiency, smoothness, field weakening, freewheeling and standstill hold.

Read across the rows and the picture is not a clean win for FOC, which is unusual and useful. Commutation has the lowest complexity and the lowest efficiency, high smoothness, no field weakening, no freewheeling and only a basic standstill hold. Sinusoidal adds complexity, high efficiency, high smoothness and strong field weakening. FOC voltage mode has high complexity, high efficiency, good smoothness, field weakening and a standstill hold that can be forced. FOC speed mode raises the complexity further, keeps high efficiency, drops smoothness to a single plus, and has the best standstill hold of the three. FOC torque mode has the highest complexity, the highest smoothness, field weakening and freewheeling, but the standstill hold is marked as not applicable.

The footnotes explain the two asterisks. Freewheeling in torque mode can be tuned by enabling ELECTRIC_BRAKE_ENABLE in config.h and adjusting the ELECTRIC_BRAKE_MAX parameter, and the standstill hold can be forced by enabling STANDSTILL_HOLD_ENABLE in config.h. So the table is a summary of default behaviour with a pointer to the configuration that changes it.

Across all FOC modes the controller features maximum motor speed and maximum motor current protection, and the README frames that as the point that makes the mode worth choosing for robotic applications while keeping the operation safe.

## Field weakening is off by default, and recalibrating it is genuinely dangerous

Field weakening, also called phase advance, is the mechanism behind the extended speed range. It is disabled by default and is enabled in config.h by setting FIELD_WEAK_ENA to 1. The weakening is a linear interpolation from zero to either FIELD_WEAK_MAX or PHASE_ADV_MAX, depending on whether FOC or sinusoidal control is selected, and it starts engaging at FIELD_WEAK_LO and reaches its maximum at FIELD_WEAK_HI. A figure in the repository shows several possible calibrations.

The warning that follows that figure is the most important sentence in the README for anybody planning to experiment. If you recalibrate the field weakening, take all the safety measures, because the motors can spin very fast. Power consumption increases sharply, and you can trigger the overvoltage protection of your battery management system.

That is a physical warning, not a legal one. Weakening raises the motor speed beyond the point where back EMF limits it, which means more current for the same torque, which means heat in the battery and the motor, and which means a BMS that cuts out under a load you did not expect. A board that is ridden by a person is a different proposition from a bench test.

The motor parameters themselves live in BLDC_controller_data.c, and the README says an already calibrated controller is provided, with an invitation to fine tune. The parameters are represented in a fixed point data type for more efficient code execution, and a separate FixedPointViewer tool is provided for calibrating them, with the full parameter table hosted in the bldc-motor-control-FOC repository.

## Three build systems for one firmware image

The repository supports building the same firmware through three toolchains, and the top level of the tree shows each of them: a Makefile, platformio.ini and an MDK-ARM directory for the Keil IDE, plus an Arduino directory.

The Makefile is the most explicit. It sets the target to hover, enables debugging with DEBUG = 1, uses the -Og optimisation level, and builds into a build directory. The compiler is prefixed with arm-none-eabi-, with the variables CC and AS pointing at the cross compiler and the assembler. The source list is explicit as well, compiling the STM32 HAL driver sources, the system file and the project's own sources, which include control.c, bldc.c, comms.c, setup.c, eeprom.c, hd44780.c, pcf8574.c, main.c and util.c, plus the two files that hold the controller logic and its parameters, BLDC_controller.c and BLDC_controller_data.c. The startup code is the assembly file startup_stm32f103xe.s:

```bash
Src/control.c
Src/bldc.c
Src/comms.c
Src/BLDC_controller.c
Src/BLDC_controller_data.c
```

The presence of hd44780.c and pcf8574.c is a good clue about the hardware in use, since those are a character LCD and an I2C GPIO expander, which are common additions on hoverboards fitted with displays.

The serial communication between the two sides of the board is a documented concern, since one of the linked videos is about reliable serial communication, and the comms.c source is the place to look. The wiki carries a Getting Started page and a Troubleshooting page, and the firmware compatibility page is where a specific board should be checked before flashing.

## GPL-3.0, no releases, and a last push in July 2026

The licence is GPL-3.0, and the README carries a matching licence badge. For a firmware project, that is the licence most makers expect for this kind of work, since it keeps derived firmware open and it suits a hobbyist and robotics community rather than a commercial product.

The maintenance record is thin but not stale. The repository is not archived, the last push was on 2026-07-04, and there are no GitHub releases at all, so there is no tagged version to flash and no changelog of published builds. For a firmware project that is a real limitation, because there is no way to say which build you are running other than by commit, and the README does not point to a release archive.

The build badge in the README shows a GitHub Actions workflow named build_on_commit, so the project does have continuous integration that builds on every commit, even though it does not publish release artefacts.

What the project offers instead of releases is documentation: a wiki with Getting Started, Troubleshooting, Firmware Compatibility and Sideboards pages, a docs/ directory with the reverse engineered mainboard schematic and the component datasheets, a set of comparison videos that show the behavioural difference between commutation and FOC, and a separate repository for the controller design itself. The audience it serves is a person comfortable with embedded toolchains who wants to understand and tune the control loop, and for that person the documentation is the deliverable and the absence of tagged releases is an inconvenience rather than a blocker.

## Conclusion

Adopt this firmware if you own a stock hoverboard with a serviceable mainboard, you want smoother torque, less noise and field weakening rather than the stock commutation behaviour, and you are prepared to flash and tune embedded firmware. Do not adopt it if your hoverboard has a split board layout, which the wiki lists as unsupported, or if you need a standstill hold in torque mode and are not willing to enable STANDSTILL_HOLD_ENABLE. Verify three things first: that your mainboard is an STM32F103RCT6 or a GD32F103RCT6, that you read the wiring constraints for the sideboard cables, because USART2 is not 5V tolerant while USART3 is, and that your battery management system can absorb the power draw that field weakening causes. The last push was on 2026-07-04, the repository has no GitHub releases, and the licence is GPL-3.0.

## FAQ

### What hardware does hoverboard-firmware-hack-FOC support?

Hoverboards with a mainboard, typically an STM32F103RCT6, and some mainboards with a GD32F103RCT6, which the firmware also supports. Split boards are not supported, and the wiki has a page on sideboards describing what this firmware expects.

### Which control modes does the hoverboard FOC firmware offer?

Three control types are set with CTRL_TYP_SEL in config.h: Commutation, Sinusoidal and FOC. FOC itself has three modes set with CTRL_MOD_REQ: voltage mode, speed mode and torque mode, the last of which enables freewheeling when the torque target is zero.

### How do I enable field weakening in hoverboard-firmware-hack-FOC?

Set FIELD_WEAK_ENA to 1 in config.h. The weakening interpolates linearly to FIELD_WEAK_MAX or PHASE_ADV_MAX, starting at FIELD_WEAK_LO and reaching the maximum at FIELD_WEAK_HI. The README warns that recalibrating it can make the motors spin very fast, raises power consumption sharply and can trip your battery management system's overvoltage protection.

### Where are the motor parameters stored?

In BLDC_controller_data.c, represented in a fixed point data type for more efficient code execution. A calibrated controller is provided, and the FixedPointViewer tool is published for working with those values.

### What do the sideboard cables provide, and what is the wiring warning?

The two 4-pin cables break out ground, 12 and 15 volts, and USART2 and USART3. USART3, the right sideboard cable, is 5V tolerant; USART2, the left one, is not. USART2 can also act as a 12-bit ADC and USART3 as I2C.

### How do I build the hoverboard FOC firmware?

The repository offers three routes: a Makefile that cross compiles with an arm-none-eabi- prefixed compiler, a platformio.ini configuration, and an MDK-ARM project for the Keil IDE. The Makefile builds the target hover with the HAL sources, the project sources and the startup_stm32f103xe.s assembly file.

## Sources

- [EFeru/hoverboard-firmware-hack-FOC on GitHub](https://github.com/EFeru/hoverboard-firmware-hack-FOC)
- [Issues](https://github.com/EFeru/hoverboard-firmware-hack-FOC/issues)
- [License: GPL-3.0](https://github.com/EFeru/hoverboard-firmware-hack-FOC/blob/main/LICENSE)
- [README](https://github.com/EFeru/hoverboard-firmware-hack-FOC/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/eferu-hoverboard-firmware-hack-foc