Concepts
How a level-1 session moves, what an ECM-ID is, and why a missing live value is not 0.
Session lifecycle
connect(transport) is the only way to open a session. It runs wake, StartComm, liveness and StartDiag, then returns with state === 'ready'. You call identify(), live() and dtc.read() after that. close() drops the port.
App Cable / ECU
|-- connect() ------------------------------------------->|
| wake: line LOW 70 ms, release, idle 130 ms |
| StartComm FE 04 72 8C (reply not required) |
| liveness first non-empty reply means "up" |
| 72 05 00 F0 99 |
| 72 05 71 00 18 |
| 7E 06 01 01 00 7A |
|<------------------------ any reply --------------------|
| StartDiag 72 05 71 00 18 |
|<------------------------ 02 0F 71 00 <5-byte id> .. ----|
| |
| state is now "ready" |
|-- identify() ------------------------------------------>|
| 72 07 72 00 00 05 10 up to 3 tries, 300 ms apart |
|<------------------------ 02 0B 72 00 00 <5 bytes> ck ---|
|-- live() or dtc.read() (not at the same time) ------>|
|<------------------------ frames -----------------------|
|-- close() --------------------------------------------->|
| state is "closed" |
If no liveness probe answers, connect repeats wake + StartComm + liveness, up to 4 times, then throws ECU_SILENT. StartDiag is required: without it the live tables stay silent. connect sends it for you.
state is idle, then waking, then ready. live() moves it to live and back to ready when the loop ends. identify, detect, live and dtc.read all require ready. Stop the live loop before reading fault codes. identify() remembers its result; a second call does not touch the bus.
ECM-ID
The ECM-ID is 5 bytes, shown as 10 upper-case hex characters, for example 0104780D01. identify() prefers the dedicated ID frame. If that frame never arrives it uses the ID carried in the StartDiag reply (source is id_frame, start_diag, or null).
The ID is not a model name. The name, maker and part code come only from lookupModel (see Identify and API key). Live data and fault codes do not need it.
Live profiles
live() with no profile probes tables 0x17, then 0x13, then 0x11 (2 tries each) and picks a layout. Pass profile only when you already know the id.
| Profile | Maker | Fields |
|---|---|---|
t17.sub8 |
Keihin | rpm, tps_v, tps, ect, batt, inj_ms, ign, ltft, o2r |
t17.sub4 |
Shindengen | rpm, tps_v, tps, eot, batt, inj_ms, ign |
t13.type7 |
Keihin | rpm, tps, ect, batt, inj_ms, ign, o2r |
t11.type1 |
Keihin | rpm, tps, ect, batt, inj_ms, ign, o2r |
generic.t17 |
either | rpm, tps, inj_ms, ign |
generic.t17 is the fallback when table 0x17 answers but neither sub-layout matches. It only has the fields that match on both makers, so temperature and battery are absent on purpose.
Each value is raw × scale + add over big-endian bytes. Scales live in spec/live.json. The SDK does not emit o2_v. If you want a voltage for display, o2r × 0.0195 when o2r is ok. That conversion is provisional, and a narrowband sensor says rich or lean, not an air-fuel number.
detect() returns { profile, method, mismatch } or null. method is probed or generic. mismatch is true when a maker hint and the profile maker are both set and differ. The observed layout still wins.
Field status
Every field is reported on every frame, even when its table did not answer.
status |
Meaning | What to show |
|---|---|---|
ok |
value is a number |
the number |
absent |
not in this frame | — |
invalid |
out of range, or two sources disagree | —, not the raw number |
absent is the "missing" case. It is not 0. A sentinel (for example temperature byte 0xFF, or a battery byte 0) is absent. A table that has not been read yet is absent. A field that does not exist on this profile is absent. Substituting 0 paints a dead sensor as a real zero.
Rpm has no sentinel, so it is always status: 'ok' when its table answers, even with the engine off. With the key ON and the engine off, a box can report 0 or a meaningless number: a bench Keihin K03-H01 gave about 17,500 rpm and −30 °C engine temperature. Use frame.engine: 'off' (injector 0 ms and ignition 0°) means rpm and temperature are not real values. Hide them or show "engine off".
prov is separate from status. It is bench (measured on a real ECU), field (consistent in field logs, not meter-checked), reference (from the reference decoder only), or provisional (one sample or an inference). Show a provisional value, and do not let it make a decision on its own. Battery on the Shindengen layout is provisional. prov is not a status: do not test status === 'provisional'.
In Dart, reading.ok is status == 'ok'. In JavaScript, test reading.status === 'ok' before using value.
A frame with primaryOk: false failed the primary table read. Those fields are absent for this tick. The SDK does not reuse the previous number.
Makers
| Maker | Part code starts with | Fault codes in v0.1 |
|---|---|---|
keihin |
38770- |
decoded (beta) |
shindengen |
30400- |
same reads, but a non-zero payload is unreadable |
makerHint on connect, or model.maker / model.partCode after identify(), selects the decoder. Unknown maker plus a non-zero payload is unreadable with reason: 'maker_unknown'. All-zero payloads are clean for either maker. The SDK never guesses a code.
Timing
Defaults (DEFAULT_TIMING in JavaScript, new Timing() in Dart). Override a field only when you mean to.
| Default | |
|---|---|
| Wake LOW / idle after wake | 70 ms / 130 ms |
| Wake tries (wake + StartComm + liveness) | 4 |
| ECM-ID tries / gap | 3 / 300 ms |
| Command quiet / timeout | 120 ms / 2000 ms |
| Live-table quiet / timeout | 120 ms / 500 ms |
| Gap between fault-code reads | 60 ms |
| Live tick unit (how often a secondary table is due) | 300 ms |
| Target gap between live frames / minimum gap | 150 ms / 60 ms |
A read ends after quiet milliseconds of silence, or at timeout, whichever comes first. A timeout does not throw. You get an empty reply, and the field or the DTC outcome says so.
The primary live table is read every frame. At most one secondary table (o2r on t20, Shindengen battery on d0) is read per frame, so those fields are absent on the first frames. That is the poll schedule, not a failed sensor.
Next: Hardware