Speeduino - Open Source ECU Firmware

Q: What target should I build first?

For a basic source check, build megaatmega2560, because it is the default PlatformIO environment. For real hardware, build the target matching your actual ECU board.

Q: Does the firmware build locally?

Yes. On this machine, platformio run -e megaatmega2560 completed successfully and produced firmware.hex.

Q: Did all tests pass?

No. platformio test -e native_code_coverage reported 2102 succeeded, 11 skipped, and 1 failed test case. The failing group was test_fuel_controller, which hit a segmentation fault.

Some open source projects can break your dashboard.

Speeduino can change how an engine runs.

That puts it in a different category from the usual self-hosted app. Speeduino is open source ECU firmware: fuel, spark, trigger decoding, idle, boost, fan, nitrous, VVT, launch, programmable IO, serial communication, and tuning software definitions all living in one embedded firmware tree.

This is not a Docker guide. There is no web UI to expose on localhost. The useful test is whether the firmware builds, which targets it supports, how its tuning contract is represented, and where the safety boundaries are.

What is Speeduino?

Speeduino is a low cost, DIY friendly engine management system based on the Arduino framework.

The repository contains the firmware source, board definitions, TunerStudio reference files, tests, CI workflows, MISRA scanning config, and Doxygen config. It is written primarily in C++ for PlatformIO, with the Arduino Mega 2560 as the default target and additional environments for Teensy and STM32 boards.

The upstream README describes the project as a flexible engine management system for hobbyist and enthusiast use, with hardware, firmware, and software components provided under open licenses.

Repository Tour

The repo has a clean embedded layout:

boards/
misra/
reference/
speeduino/
test/
platformio.ini

speeduino/ contains the firmware. The main entry point is:

speeduino/speeduino.ino

That file wires together the main loop, communications, sensor reads, crank/cam decoding, fuel calculation, ignition calculation, scheduled outputs, idle control, engine protection, secondary tables, CAN, SD logging, launch control, fan control, boost, air conditioning, nitrous, and VVT modules.

reference/ matters more than it might first appear. reference/speeduino.ini is a TunerStudio project definition, and in the clone I inspected it was 6062 lines long. It defines the firmware signature, settings groups, PC variables, pin layouts, trigger IDs, dashboards, dialogs, tables, curves, and logging fields.

That INI is part of the system contract. If firmware pages or protocol behavior change, the tuning software needs to understand the same shape.

PlatformIO Targets

Speeduino uses platformio.ini as its build matrix.

The environments include:

megaatmega2560
megaatmega2560-6-3
megaatmega2560-8-1
megaatmega2560_sim_unittest
teensy35
teensy36
teensy41
black_F407VE
FCR_Micro_F4
BlackPill_F401CC
BlackPill_F411CE_UART
BlackPill_F411CE_USB
native_code_coverage

The default target is megaatmega2560. That build uses Atmel AVR, Arduino, C++14 flags, optimized math/division libraries, FastCRC, EEPROM, Time, and AVR-specific helper packages.

The Teensy and STM32 environments show the project has moved beyond one board family. Teensy targets use FlexCAN_T4 and related libraries. STM32 targets include DFU/ST-Link settings, USB CDC flags, CAN flags, RTC dependencies, and a project-local FCR Micro F4 board definition for STM32F429VIT6 hardware.

What the Firmware Does

Speeduino is built around timing and state.

The decoder layer handles crank and cam patterns. The code comments describe a consistent interface for each decoder: setup, primary trigger, secondary trigger, RPM, crank angle, and cam angle functions. The reference INI lists trigger families such as missing tooth, basic distributor, dual wheel, GM7X, 4G63, 24X, Jeep 2000, Audi 135, Honda D17, Miata 99-05, Mazda AU, Nissan 360, Subaru 6/7, Daihatsu, Harley, Ford ST170, DRZ400, NGC, VMAX, Renix, Rover MEMS, Suzuki K6A, Honda J32, and Ford TFI.

The fuel layer calculates required fuel, applies load and AFR logic, corrections, injector open time, acceleration enrichment, nitrous enrichment, pulse width limits, and staged injection behavior.

The scheduler layer turns those calculations into timed events. It has schedule states for off, pending, running, and queued-next behavior. Atomic sections protect updates where an interrupt could fire while the firmware is changing timing state.

The serial layer speaks to tuning software. comms.cpp handles command parsing, CRCs, timeouts, EEPROM write deferral, page access, tooth logs, composite logs, and firmware identity responses.

This is the kind of embedded project where a “simple” change can touch firmware timing, calibration data, tuning software assumptions, and hardware output behavior.

Local Field Test: Building Speeduino

I cloned the repository into /tmp/foss-post-speeduino/speeduino and installed PlatformIO into a temporary Python virtualenv:

python3 -m venv /tmp/foss-post-speeduino/pio-venv
/tmp/foss-post-speeduino/pio-venv/bin/python -m pip install --upgrade pip platformio

Then I built the default Mega 2560 target:

/tmp/foss-post-speeduino/pio-venv/bin/platformio run -e megaatmega2560

That passed:

Environment     Status    Duration
megaatmega2560  SUCCESS   00:00:32.315

PlatformIO reported:

RAM:   77.5% (used 6347 bytes from 8192 bytes)
Flash: 74.0% (used 187880 bytes from 253952 bytes)

The generated artifacts included:

firmware.elf 248428 bytes
firmware.hex 528479 bytes

For a first-pass firmware article, that is the important practical result: the default target builds cleanly from a fresh isolated PlatformIO setup.

Local Field Test: Native Tests

I also ran:

/tmp/foss-post-speeduino/pio-venv/bin/platformio test -e native_code_coverage

The native run collected 31 test groups and produced this final summary:

2115 test cases: 1 failed, 11 skipped, 2102 succeeded in 00:01:59.033

The one errored group was:

native_code_coverage  test_fuel_controller  ERRORED
Program received signal SIGSEGV (Segmentation fault)

Most of the suite did pass, including schedules, PID, engine protection, VVT, idle, air conditioning, init, storage, pages, tachometer, tables, ignition, sensors, water/methanol injection, fuel, decoder API coverage, nitrous, fan, timers, boost, secondary tables, general tests, decoders, loggers, programmable IO, launch control, schedule calculations, command control, and math.

I would treat the test run as useful local evidence, but not as a completely green verification.

Build It Yourself

A minimal local build looks like this:

git clone https://github.com/speeduino/speeduino
cd speeduino
python3 -m venv .venv
. .venv/bin/activate
pip install platformio
platformio run -e megaatmega2560

To build another target:

platformio run -e teensy41
platformio run -e black_F407VE
platformio run -e FCR_Micro_F4

To run native tests:

platformio test -e native_code_coverage

To flash hardware, use the upload path for your exact board. That is intentionally not a copy-paste line here. ECU firmware should not be flashed casually.

Safety Notes

Speeduino controls fuel and spark. Treat it as real engine-control firmware:

Match the firmware target to the exact ECU board.
Use the matching speeduino.ini with TunerStudio-compatible tooling.
Bench test before connecting outputs to an engine.
Disable fuel and ignition outputs during early checks.
Confirm trigger pattern, timing, and sync before running.
Use a timing light and logs, not guesses.
Keep backups of known-good tunes.
Never test unknown firmware behavior on a running engine.

The project is open and hackable, but the outputs are physical.

Project Links

Conclusion

Speeduino is a serious open source ECU firmware project with enough engineering structure to be worth studying even if you are not building an engine controller tomorrow.

The repository has multi-board PlatformIO targets, extensive firmware modules, a large TunerStudio INI contract, native tests, simulator tests, CI builds, memory-delta reporting, MISRA scanning, and Doxygen generation.

The default Mega 2560 firmware built cleanly on this machine. The native test suite mostly passed but reported one segmentation fault in test_fuel_controller, so I would use the build result confidently and treat the native test result as a follow-up investigation item.

FAQ

Is Speeduino self-hosted?

No. It is firmware for ECU hardware, not a web service. The local validation path is PlatformIO build/test, not Docker.

Can I run it in Docker?

You can wrap PlatformIO in a container if you want repeatable builds, but the upstream repo does not need Docker for the normal firmware build path.

What target should I build first?

For a basic source check, build megaatmega2560, because it is the default PlatformIO environment. For real hardware, build the target matching your actual ECU board.

Does the firmware build locally?

Yes. On this machine, platformio run -e megaatmega2560 completed successfully and produced firmware.hex.

Did all tests pass?

No. platformio test -e native_code_coverage reported 2102 succeeded, 11 skipped, and 1 failed test case. The failing group was test_fuel_controller, which hit a segmentation fault.

Can I flash the generated hex to any Speeduino board?

No. Match the firmware target, board hardware, pinout, and tuning INI before flashing anything.