Prototype

Genset ECU

Replacement engine control unit for a 25 kVA Kirloskar diesel genset — engine 3GK550ETA 4SR1, application code GK3.8703, 26.5 kW at 1500 rpm, 12 V system. Panel controller is a Deep Sea Electronics DSE4522 MKII AMF.

Start here

docs/pdf/ECU-Bible.pdf — everything, in reading order, in one 328-page file. Cover, handoff, field handbook, sensor reference, circuit reference, the specification, the decisions log, all twelve research memos, the plan. Bookmarked, so the PDF reader's outline pane is the table of contents.

Resuming work, or moving to another machine? docs/HANDOFF.md — setup, what is verified, what is open, and the traps that already cost a session each. docs/decisions-log.md — every design fork put to the owner, with the options and the reasoning.

Prefer the browser? Three of those are live HTML: the handbook, the circuit reference and the sensor reference.

What's in here

Rebuilding the PDFs

.venv/bin/python docs/build_pdf.py

Markdown documents are converted and printed; the handbook pages are printed as they stand, from a temporary copy with the print rules injected — the source HTML is never edited, so a PDF cannot drift from the page it came from.

Needs Chrome or Chromium on PATH (it is the renderer — the only engine here that handles the handbook's inline SVG schematics and CSS custom properties), plus markdown and pypdf:

.venv/bin/pip install markdown pypdf

Page rules live in docs/print.css.

Running the circuit simulations

.venv/bin/python sim/run_sim.py              # every block
.venv/bin/python sim/run_sim.py injector     # blocks matching "injector"

Each check is a claim about the circuit, so a red line means the design is wrong, not the simulator. All 26 blocks currently pass (on ngspice 42 — see docs/HANDOFF.md §2).

The netlists are plain SPICE — they also open directly in KiCad's built-in simulator (Tools → Simulator), LTspice, or standalone ngspice. See sim/README.md.

If .venv is missing, rebuild it:

python3 -m venv .venv && .venv/bin/pip install PySpice numpy schemdraw markdown pypdf

Running the firmware on the PC

make -C firmware/sim test                    # unit tests of the C core and the bootloader
.venv/bin/python firmware/sim/run_sil.py     # the 16 engine scenarios
.venv/bin/python firmware/sim/run_sil.py runaway   # scenarios matching "runaway"
.venv/bin/python firmware/sim/test_service.py      # the service tool end to end

The service tool reads and writes the end-of-line record and flashes the application, over USB, CAN channel 2 or the simulator (firmware guide §16). key.bin holds the 16 bytes of SEC_SECRET:

T=firmware/tools/ecu_service.py
.venv/bin/python $T --link sim --secret key.bin info
.venv/bin/python $T --link usb:/dev/tty.usbmodem1 --secret key.bin eol-read
.venv/bin/python $T --link can:socketcan:can0 --secret key.bin flash app.bin \
    --sw-ver 0x00010002 --hw-min 0x0100 --hw-max 0x01FF

The simulator runs the same firmware live or from scripts, traced in a browser, on Windows, macOS or Linux with nothing to install (guide simulator/README.md):

cd simulator && cargo run --release -p ecusim                 # the browser UI
cd simulator && cargo run --release -p ecusim -- run 'scenarios/sil/*.seq'

The C core in firmware/core/ touches no hardware. The simulator drives it with a model of the engine, generator and fuel rail. See decisions log §11, and §12 for the fault memory, event log, counters and trip recorder.

Preparing the PCB

The board is generated, then routed by hand in KiCad 10 (guide: docs/layout-guide.md). KP is KiCad's own Python:

KP=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/bin/python3
.venv/bin/python hw/test_schlib.py       # schematic regeneration keeps its UUIDs
.venv/bin/python hw/test_pcb_rules.py   # rules: widths, classes, regions, every power net classed
$KP hw/gen_pcb.py --selftest            # the generator's own checks, on a temp copy
$KP hw/gen_pcb.py                       # build hw/ecu25kva.kicad_pcb; on a routed board, rules only
.venv/bin/python hw/check_pcb.py        # footprints, nets, classes, widths, DRC

The outline, holes and J1001 are placeholders until the old ECU is measured: HOUSING and REGIONS in hw/pcb_rules.py.

The prototype board

A bench board that can be built now: the full production circuit with an STM32G474, screw terminals instead of the Bosch connector, 300 × 200 mm. Everything is in prototype/ (decisions log §15; bring-up guide prototype/docs/bring-up.md). Routing needs Java and Freerouting 2.4.1:

export PATH=/Applications/KiCad/KiCad.app/Contents/MacOS:$PATH
export KICAD_SYMBOL_DIR=~/opt/kicad7-libs/kicad-symbols-7.0.11   # the symbols hw/ was drawn with
.venv/bin/python prototype/gen_prototype.py     # schematic: production sheets + mcu_stm32 + lab_io
.venv/bin/python prototype/check_prototype.py   # netlist gate, no open items
$KP prototype/gen_board.py setup                # fetch Freerouting, check its SHA-256
$KP prototype/gen_board.py route                # place, power pours, Freerouting (about 2 h)
$KP prototype/gen_board.py finish               # route what Freerouting left, rip-up, tidy
$KP prototype/gen_board.py sync                 # after a schematic change: rename, add new parts
$KP prototype/gen_board.py rip_thin             # tracks too thin for TRACK_AMPS out; then finish
$KP prototype/gen_board.py widen                # tracks up to 0.2 mm, TRACK_AMPS nets to their IPC width
$KP prototype/gen_board.py fab                  # prototype/fab/: Gerbers, drill, positions, BOM
.venv/bin/python prototype/test_prototype.py    # every prototype check

Where the project stands

Phase 1 is complete: twelve research memos, 25 verified circuit blocks covering the whole power chain, both sensor front-end topologies, the speed input, the injector boost rail and its reservoir, both actuator drivers and the CAN termination — and a specification carrying the corrections that simulation forced, including one front-end that could not have worked as originally specified.

Simulation has now caught a design error in roughly a third of the blocks written. The ones worth knowing about: the discrete input was impossible as a divider rather than merely mis-valued; the battery divider would have destroyed an ADC pin; the MCU decoupling peaked thirty times over target against the regulator's own output inductance; and the EMI filter handed back 12 dB at the exact frequency it most needed to hold.

Four unknowns closed on 18 September, from photographs of the machine and one manufacturer's manual — and three of the four closed against an inference this project had made. The engine is 3GK550ETA 4SR1, not the model memo 01 derived. The panel controller is a DSE4522, not the KG640C the OEM diagram shows. The connector is Bosch 1 928 405 192 / 194, code C. And the controller has no speed pickup, which memo 02 got right about the wrong device.

That cost the project its safety argument. The DSE4522 takes engine speed from our ECU over CAN, so its overspeed trip is not independent of the thing it protects against. Spec §3 is rewritten and the standalone overspeed trip module reverts from recommended to mandatory.

U12 now stands alone as the load-bearing unknown. Every protective action the controller can take ends by de-energising one fuel relay; whether its contacts remove supply from the ECU and fuel system, or merely signal a hung ECU, decides whether any independent protection exists. Memo 08 is the printed checklist for that measurement.

Three things deserve reading before anything gets built. Memo 06 on the CPCB IV+ position — and the machine's type approval is now a specific certificate, ARAI/MoEF/DGTA/IGES4/KOEL-P25/2825/24. The single-source flag on the MC33816 injector driver in Memo 07. And §3's closing note: no air-intake shutoff exists anywhere in this design, which means nothing here can stop a diesel running away on its own lubricating oil.