DNiev/ecu-lab
DNiev/ecu-lab has 70 GitHub stars and 10 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-17 21:27 UTC. Last push 2026-11-09.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
ECU Lab — an engine management and tuning simulator created by CaribouTuning. Design an engine, edit the calibration tables a real tuner edits, run a dyno pull, and read a log explaining what went right or wrong. Repo and tooling by Turtle.GTI.
Web & AppsREADME.md
OriginalECU Lab
An engine management and tuning simulator.
CaribouTuning and Turtle.GTI build ECU Lab together.
CaribouTuning created it. The concept, the engine model, the calibration tables, the pull log and the teaching material started with him, the domain knowledge behind them is his, and he still works on the physics.
Turtle.GTI develops and maintains it: the physics added since, the test suite and its behavioural fingerprint gate, the tooling and CI, and the current rework of the app.
Design an engine, edit the same three calibration tables a real tuner edits, run a dyno pull, read a log that explains what went right or wrong, then put the engine in a car and run a quarter mile with it.
It is a teaching tool, not a game with a horsepower slider.
Three ways in: SANDBOX is free play; TUTORIAL is five minutes on the basics, with the full Tuning Course under HOME › Learn; CAREER is a tuning shop of your own. Customers bring cars with real faults and describe what the car does, never what is wrong with it: a cast of named customers, and new walk-ins every day without end, generated from faults the simulator genuinely produces and harder as the shop's name grows. Every job is graded on the same simulator as everything else: the car you hand back is pulled and idled, and power bought with knock or a lean top end is not a finished job. Money buys a dyno, lifts and tools and pays the running costs; training opens more of the ECU, and eventually engine building, where customers bring a wish list instead of a fault. Its save is separate from SANDBOX's, and switching between them loses nothing.
The design rule
Nothing adds horsepower. Every part changes airflow, pressure, temperature or fuel delivery, and power is whatever falls out of the physics. If you contribute a feature, add it as a physical mechanism — never as a bonus multiplier.
That rule is why the numbers mean something. A stock 3.5 L V6 on 91 octane makes about 250 whp here because the ideal gas law, an integrated pressure trace and the friction model say so, not because someone typed 250.
What it actually models
- Air charge from the ideal gas law —
ρ = MAP / (R·T),airCharge = VE × V_cyl × ρ - Fuel mass from lambda and each fuel's real stoichiometric ratio, density and lower heating value — which is why E85 needs ~1.5× the fuel mass (about 1.43× the volume) for the same lambda
- Injector pulse width against the real time available per engine cycle, so duty cycle is a physical wall rather than a capacity index
- The closed cycle, integrated two crank degrees at a time from intake valve close
to exhaust valve open — Wiebe heat release, slider-crank volume, and indicated work as
∮ p dV. Peak cylinder pressure, the angle it occurs at, and MBT all come off that trace rather than from a correlation - Knock as an autoignition integral over the unburned end gas, so octane, compression, charge temperature, residual dilution and mixture all reach it through the pressure history instead of through separate corrections. Each fuel carries its RON and MON, and the integral reads Kalghatgi's octane index for the engine's own conditions, so a stock 10.3:1 engine on 91 is knock-limited through the midrange, as a real one is
- Port or direct injection per engine, as the real ones have it: port-injected fuel boils off the intake valve, direct-injected fuel cools the cylinder's own air, filling it better and holding off knock
- Torque as
IMEP − friction − PMEP → BMEP → T = BMEP × Vd / 4π. Pumping work is exhaust manifold pressure minus intake, with its real sign, so a turbine's backpressure is a cost and a well-matched one can hand work back - Superchargers from their makers' figures — Roots, twin-screw and centrifugal. A
positive-displacement blower pumps a fixed volume per turn and boost settles where the
engine swallows it; a centrifugal's comes from impeller tip speed. The adiabatic
efficiency sets both the charge heat and the drive power,
W = ṁ·cp·T·(PR^0.286 − 1)/η, charged to the crank - Nitrous oxide as chemistry: 36% oxygen by mass, heat from its own breakdown (−82 kJ/mol), charge cooling as it boils, bottle pressure from its vapour-pressure curve, wet and dry kits, and the controller's window, retard, ramp and lean cut
- A live engine integrating real crankshaft dynamics at 20 Hz: it idles, revs, stalls, hits a rev limiter with hysteresis, and cuts fuel on overrun
- Cam and valvetrain — duration shifts the VE peak, overlap costs idle vacuum, and springs set the speed at which the valves stop following the lobe
- A quarter mile — the measured torque curve goes into a car and runs the strip:
F = μNgrip,ΔN = m·a·h/Lweight transfer,F_aero = ½ρCdAv²drag, gearing that multiplies torque and divides speed by the same factor, and rotating inertia that behaves as extra mass in proportion to the square of the ratio
Units are real throughout: kPa, K, grams, ms, J, Nm, Pa, g/s, W.
Quick start
npm install
npm run dev # http://localhost:5173
npm test # physics test suite
npm run build # production build into dist/
Requires Node 20 or 22 — not newer; CONTRIBUTING.md explains why (the behavioural fingerprint is float-sensitive).
How the code is laid out
src/
sim/ the physics — pure functions, zero React, fully testable in Node
constants.js real measured values (gas constant, LHV, ...)
coefficients.js every empirical/tuned number, in one place
tables.js the editable calibration data and its axes
hardware.js the parts catalogue
math.js clamp, interpolation, run grouping
thermo.js charge temperature
friction.js rubbing, pumping and total parasitic losses
engine.js short-block design -> derived properties
manifold.js manifold pressure, best-power mixture
airflow.js hardware -> VE table
cycle.js the closed cycle: heat release, two-zone gas, knock integral, EGT
knock.js charge index and autoignition helpers
turbo.js the turbo spool-up solve (and the induction solve for a supercharger)
compressorMap.js efficiency, surge and choke on a compressor map (turbo and centrifugal)
blower.js superchargers: Roots, twin-screw and centrifugal, and what they cost the crank
blowerPreview.js what a supercharger and pulley will do on this engine, before a pull
nitrous.js nitrous oxide: the bottle, the jets, and its oxygen and heat in the cylinder
point.js evaluatePoint — the heart of it
sweep.js a full dyno pull + the event log
live.js real-time crank dynamics + ECU control loop
drivetrain.js the car: gearing, grip, weight transfer, the quarter mile
advisors.js what the hardware wants vs. what your tables say
scoring.js tuning / engineer / pull scores
presets.js the factory engines and their generated calibrations
acoustics.js the engine sound, built from the same cycle
ecu/ engine management: calibration, sensors, controllers, protections,
the live ECU and its pull-log events
ui/ presentation only — no physics below this line
career/ CAREER: the shop, its customers and jobs, and the grading, which
runs the real simulator on the car handed back
storage.js persistence adapter (artifact host / localStorage / memory)
tests/ physics intent tests + the behavioural fingerprint
Where to start reading: src/sim/point.js. Everything else either feeds it or
displays its output, and it is commented step by step in the order an ECU works.
To change how the engine behaves: adjust src/sim/coefficients.js, not the
formulas. Every empirical number lives there with a note on why it has the value it
has.
Testing
Two layers, doing different jobs:
tests/physics.test.jsandtests/drivetrain.test.jsassert on direction and relationship — "a longer cam gives away bottom end and gains top end", "a traction-limited launch is independent of mass". Readable failures that say what broke.tests/fingerprint.test.jshashes the entire simulation across 9,720 operating points, 756 full sweeps, 252 VE tables and 72 drag runs. It catches the coupled changes you did not think to check.- Accuracy —
tests/benchmark.test.jsholds the factory engines to real-engine ranges,tests/physics-invariants.test.jschecks physical laws on thousands of random builds,tests/consistency-fuzz.test.jschecks that the advisor, the dyno and LIVE agree, andtests/accuracy-claims.test.jsholds what the docs say about the model to what it does. docs/accuracy.md reports the results and what the model simplifies.
If the fingerprint fails, that is not automatically a bug — it means the numbers moved.
Work out whether you meant it. If you did, review the diff and run
npm run test:fingerprint:update, then explain the change in your PR. Never update the
fixture just to make CI green.
Contributing
See CONTRIBUTING.md. Physics corrections from people who tune real cars are especially welcome — if a model here is wrong, we want to know, ideally with a source.
Status
Working and playable. Known gaps and planned work are tracked in CONTRIBUTING.md; the short version is that the UI is still one large component pending decomposition, and accessibility needs work.
Credits
ECU Lab is built by CaribouTuning and Turtle.GTI, as partners.
It began as CaribouTuning's. The engine model, the calibration tables, the knock envelope, the pull log, the scoring, the tutorial and the original design all originated with him, and so did the domain knowledge behind them. Anything this app teaches at its core, it teaches because he knew it first — and he is still working on the physics.
Turtle.GTI develops and maintains it: the physics added since, the behavioural fingerprint that pins the model against drift, the intent test suite, CI, the release pipeline, and the current rebuild of the interface.
Decisions that touch the physics or the teaching material are made between them.
| CaribouTuning | Created it. Engine model, calibration design, pull log, scoring, teaching material, ongoing physics. |
| Turtle.GTI | Develops and maintains it. Physics, test suite and fingerprint gate, tooling, CI, and the UI rework. |
Contributions from anyone else are very welcome — see CONTRIBUTING.md.
Licence
MIT — copyright Caribou Tuning and Turtle.GTI.
A note on real engines
This is a simulator. The physics is real enough to teach the shape of the problem and the reasoning behind it, but it is not a substitute for a wideband, a knock ear, and someone who has done it before. Do not take a calibration from here to a real car.