{
  "$schema": "./schema/live.schema.json",
  "spec": "smongrot.live",
  "spec_version": "1.0.0-phase1",
  "level": 1,
  "status": "stable",
  "summary": "Honda K-Line live data (engine sensors). Poll one or more 0x72 table reads, cut the data bytes out of each reply, and decode every field from a declarative rule. Requires an open diagnostic session (spec/kline.json session).",
  "authority": "Reference implementation (live decoder, detector and profile set). If this file and the reference implementation ever disagree, the reference wins and this file is a bug.",
  "derived_from": {"file": "reference implementation: live profile set", "schema_v": 1, "profile_set_version": 2},
  "reply_extraction": {
    "summary": "How the data bytes of one table read are taken from the echo-stripped reply (reference table read).",
    "steps": [
      "Strip the TX echo (spec/kline.json echo_strip). Call the rest R.",
      "Scan start index i from len(R)-4 down to 0 (the LAST matching frame wins).",
      "Skip i unless R[i] == 0x02 and R[i+2] == request[2] (service byte, 0x72) and R[i+3] == request[3] (table byte).",
      "L = R[i+1] (total frame length incl. the checksum). Skip i unless L >= reply_header_len + 1 and i + L <= len(R).",
      "Skip i unless the bytes R[i .. i+L-1] sum to 0 mod 256 (spec/kline.json checksum.verify).",
      "data = R[i+reply_header_len .. i+L-2] (after the header, before the checksum).",
      "If len(data) >= data_len return data, else return NO DATA. Stop at this first checksum-valid match either way (do not keep scanning).",
      "No match: NO DATA."
    ],
    "header_layout": "Reply = 02 L 72 <table> <offset> <data...> <checksum>; reply_header_len 5 for every profile table.",
    "no_data_means": "The table is absent for this tick: every field read from it is 'absent'."
  },
  "value_rule": {
    "summary": "Per source: raw = unsigned big-endian integer over `width` bytes at data[offset]. If raw is in null_if → absent. value = raw * scale + add (IEEE-754 double, in that order). If range is given and value < range[0] or value > range[1] → invalid. Then, if clamp is given, value = min(max(value, clamp[0]), clamp[1]). Otherwise ok.",
    "absent_when": ["the source's table has no data yet", "offset + width > len(data)", "raw is listed in null_if"],
    "invalid_when": ["value outside range (inclusive bounds)"],
    "chain": [
      "A field has 1..n sources tried in order. A source with `ecm` is skipped (not read at all) unless the session's ECM-ID, normalised (whitespace removed, upper case), is in that list; an unknown ECM-ID skips it too.",
      "absent → try the next source.",
      "invalid → the FIELD is invalid; stop. An out-of-range value is never masked by a later source.",
      "ok and the field has no `agree` → the field is this value; stop.",
      "ok and the field has `agree` → keep the first ok value, keep reading later sources: if a later source is invalid → field invalid; if a later source is ok and |later - first| > agree → field invalid; else continue. At the end the field is the FIRST ok value.",
      "No ok source → absent. Never 0."
    ],
    "result": "Each field yields {status: ok|absent|invalid, value (only when ok), prov, source (table id of the winning source, only when ok)}.",
    "prov_rule": "ok → the winning source's prov. absent/invalid → the first source's prov. Exception: v2_provisional (see detection.match_v2) forces prov = provisional for the listed fields in every status.",
    "prov_values": {
      "bench": "proven on a real ECU on the bench",
      "field": "consistent across real field logs, not meter-checked",
      "reference": "from the reference live-data tool source only",
      "provisional": "single sample / inferred; show it, but ask the rider to confirm before any decision"
    },
    "every_field_reported": "Decode returns an entry for every field of the profile, even when its table never answered."
  },
  "units": {
    "rpm": "engine speed, rev/min",
    "tps_v": "throttle sensor volts",
    "tps": "throttle opening, % of the box's full-open angle (0..100). The raw byte is the angle in 0.5 degree steps.",
    "ect": "engine temperature, degC (coolant or oil, depending on the bike; display label only)",
    "eot": "engine temperature, degC (Shindengen layout)",
    "batt": "battery volts as the ECU measures it",
    "inj_ms": "injector pulse width, ms",
    "ign": "ignition advance, degrees",
    "ltft": "long-term fuel trim, %",
    "o2r": "narrowband O2 sensor raw byte (1..255); see derived_values"
  },
  "derived_values": [
    {
      "key": "o2_v",
      "from": "o2r",
      "formula": "o2r * 0.0195",
      "unit": "V",
      "prov": "provisional",
      "source": "Reference implementation (8-bit ADC over 5 V). The reference live-data tool uses o2r / 753.75 * 14.7 (= o2r * 0.019502), equal within 0.0005 V for every raw byte.",
      "note": "Display only. Narrowband O2 says rich/lean side, not an AFR number."
    }
  ],
  "polling": {
    "tick_unit_ms": 300,
    "summary": "A table's poll_every_ticks counts ticks of tick_unit_ms wall time (the board firmware's POLL_MS). The primary table is read every tick; at most ONE secondary table per tick, round-robin. A secondary with give_up_after_misses = N is not asked again this session after N misses in a row while the primary answered.",
    "usb_target_tick_ms": 150,
    "min_gap_between_frames_ms": 60,
    "read_timeout_ms": 500,
    "read_quiet_ms": 120,
    "source": "Reference implementation (USB live pacing, table read)."
  },
  "detection": {
    "summary": "Pick a profile once per connect (reference detector, probe branch).",
    "probe_table_order": [23, 19, 17],
    "probe_table_order_hex": ["0x17", "0x13", "0x11"],
    "probe_request_source": "For each table byte, the request of the first profile (in file order) whose primary table has that table byte.",
    "tries_per_table": 2,
    "steps": [
      "For each probe table in order: send its request up to tries_per_table times until reply_extraction gives data. No data → next table.",
      "On data: candidates = non-generic profiles whose primary table has this table byte and whose match rules ALL hold on {primary: data}.",
      "match_v2 off (default): use `match`. match_v2 on: a profile with `match_v2` uses those rules instead; a profile that matched ONLY by match_v2 (its `match` rules fail) is dropped when a maker hint is given and differs from the profile maker.",
      "Sort candidates by specificity (number of rules in the active rule list) descending, then range_score descending. Take the first → method 'probed'.",
      "No candidate → the first generic profile on this table → method 'generic'. No generic → next table.",
      "No table answered → no profile (connected, live data not supported)."
    ],
    "rule_test": "A rule reads raw = unsigned big-endian over width bytes at data[offset] of its table (false when the table is missing or too short). eq: raw must equal eq. ne: raw must not equal ne. A profile with no rules always matches.",
    "range_score": "Decode the frame with NO ECM-ID; among fields whose status is not absent, the fraction that are ok (0 when none). Used only as a tie-break.",
    "maker_hint": "From the part code: '38770-' → keihin, '30400-' → shindengen, else none. The observed layout always wins; mismatch = hint and profile maker both set and different (never on a generic profile).",
    "match_v2": {
      "flag": "live_temp_v2",
      "default": false,
      "summary": "App build flag (internal-test builds only, not server-controlled). When on, profiles that have match_v2 use it in place of match, and fields in v2_provisional get prov = provisional on a frame that matches only by match_v2.",
      "why": "The reference live-data tool picks Type-4 sub 4 only when data[4..5] == FF FF; build 196's rule (data[4] != FF) sent some Keihin frames to generic.t17 (no temperature)."
    },
    "cache": "Optional, app-specific: remember profile id per ECM-ID; on reconnect validate with one primary read + match, else drop the cache and probe. A cached generic profile is always dropped and re-probed.",
    "tie_note": "On the shipped profiles no two candidates on one table can both match, so the tie-break order never decides a real frame."
  },
  "profiles": [
    {
      "id": "t17.sub8",
      "maker": "keihin",
      "generic": false,
      "notes": [
        "Keihin Type-4 layout (bench: Wave 110i 38770-K03-H01, 2026-10-02). Request 72 07 72 17 00 0F EF is the reference tool's 'Table 20' read for ECM Type 4.",
        "tps: data[3] is the throttle angle in 0.5 degree steps; shown as % of the box's full-open angle (scale = 50 / full-open degrees, rounded up). Full-open per ECM-ID from real ride plateaus (not meter-checked): 01040F0D01 78, 0105550D01 79, 01033E0D01 74, 0103FA0D01 73, everything else 80.",
        "t20 = narrowband O2 table 0x20 (reference tool _cmdO2, read every few cycles). o2r = data[0]; 0 = no reading. Not captured on a running bike yet.",
        "v2_provisional batt: a frame that matches only by match_v2 (data[4] = FF) is on a layout no bench confirmed for that box, so its battery is provisional."
      ],
      "primary": "t17",
      "tables": {
        "t17": {"request": "72 07 72 17 00 0F EF", "reply_header_len": 5, "data_len": 15, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null},
        "t20": {"request": "72 07 72 20 00 0B EA", "reply_header_len": 5, "data_len": 1, "poll_every_ticks": 5, "optional": true, "give_up_after_misses": 3}
      },
      "match": [
        {"table": "t17", "offset": 4, "width": 1, "ne": 255}
      ],
      "match_v2": [
        {"table": "t17", "offset": 4, "width": 2, "ne": 65535}
      ],
      "v2_provisional": ["batt"],
      "fields": [
        {
          "key": "rpm",
          "unit": "rpm",
          "sources": [
            {"table": "t17", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "bench", "range": [0, 20000]}
          ]
        },
        {
          "key": "tps_v",
          "unit": "V",
          "sources": [
            {"table": "t17", "offset": 2, "width": 1, "scale": 0.0195, "add": 0, "null_if": [], "prov": "reference", "range": [0, 5.1]}
          ]
        },
        {
          "key": "tps",
          "unit": "%",
          "sources": [
            {"table": "t17", "offset": 3, "width": 1, "scale": 0.641026, "add": 0, "null_if": [], "prov": "field", "range": [0, 120], "clamp": [0, 100], "ecm": ["01040F0D01"]},
            {"table": "t17", "offset": 3, "width": 1, "scale": 0.632912, "add": 0, "null_if": [], "prov": "field", "range": [0, 120], "clamp": [0, 100], "ecm": ["0105550D01"]},
            {"table": "t17", "offset": 3, "width": 1, "scale": 0.675676, "add": 0, "null_if": [], "prov": "field", "range": [0, 120], "clamp": [0, 100], "ecm": ["01033E0D01"]},
            {"table": "t17", "offset": 3, "width": 1, "scale": 0.684932, "add": 0, "null_if": [], "prov": "field", "range": [0, 120], "clamp": [0, 100], "ecm": ["0103FA0D01"]},
            {"table": "t17", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "field", "range": [0, 120], "clamp": [0, 100]}
          ]
        },
        {
          "key": "ect",
          "unit": "degC",
          "sources": [
            {"table": "t17", "offset": 5, "width": 1, "scale": 1, "add": -40, "null_if": [255], "prov": "bench", "range": [-40, 160]}
          ]
        },
        {
          "key": "batt",
          "unit": "V",
          "sources": [
            {"table": "t17", "offset": 10, "width": 1, "scale": 0.1, "add": 0, "null_if": [0], "prov": "bench", "range": [6, 18]}
          ]
        },
        {
          "key": "inj_ms",
          "unit": "ms",
          "sources": [
            {"table": "t17", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "bench", "range": [0, 100]}
          ]
        },
        {
          "key": "ign",
          "unit": "deg",
          "sources": [
            {"table": "t17", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "bench", "range": [-64, 64]}
          ]
        },
        {
          "key": "ltft",
          "unit": "%",
          "sources": [
            {"table": "t17", "offset": 14, "width": 1, "scale": 0.78, "add": -100, "null_if": [], "prov": "reference", "range": [-100, 100]}
          ]
        },
        {
          "key": "o2r",
          "unit": "raw",
          "sources": [
            {"table": "t20", "offset": 0, "width": 1, "scale": 1, "add": 0, "null_if": [0], "prov": "reference", "range": [1, 255]}
          ]
        }
      ]
    },
    {
      "id": "t17.sub4",
      "maker": "shindengen",
      "generic": false,
      "notes": [
        "Shindengen Type-4 layout (bench: Lead 30400-K2TA-T02, 2026-10-02 and 2026-10-08). EOT proven by a bench knob sweep.",
        "batt chain: t17 data[10] x 0.1 V, read ONLY on ECM-ID 0105950D01 (Lead 125 K2TG; inferred from field logs, the reference tool has no Shindengen case), then D0 data[0] on every sub4 box. Both provisional until a multimeter check. 0 = absent; out of range or the two more than 0.5 V apart = invalid.",
        "tps full-open 85 degrees from one Shindengen ride (provisional until more rides)."
      ],
      "primary": "t17",
      "tables": {
        "t17": {"request": "72 07 72 17 00 0F EF", "reply_header_len": 5, "data_len": 15, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null},
        "d0": {"request": "72 07 72 D0 00 10 35", "reply_header_len": 5, "data_len": 16, "poll_every_ticks": 10, "optional": true, "give_up_after_misses": null}
      },
      "match": [
        {"table": "t17", "offset": 4, "width": 1, "eq": 255},
        {"table": "t17", "offset": 5, "width": 1, "eq": 255}
      ],
      "fields": [
        {
          "key": "rpm",
          "unit": "rpm",
          "sources": [
            {"table": "t17", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "bench", "range": [0, 20000]}
          ]
        },
        {
          "key": "tps_v",
          "unit": "V",
          "sources": [
            {"table": "t17", "offset": 2, "width": 1, "scale": 0.0195, "add": 0, "null_if": [], "prov": "reference", "range": [0, 5.1]}
          ]
        },
        {
          "key": "tps",
          "unit": "%",
          "sources": [
            {"table": "t17", "offset": 3, "width": 1, "scale": 0.588236, "add": 0, "null_if": [], "prov": "field", "range": [0, 120], "clamp": [0, 100]}
          ]
        },
        {
          "key": "eot",
          "unit": "degC",
          "sources": [
            {"table": "t17", "offset": 9, "width": 1, "scale": 1, "add": -40, "null_if": [255], "prov": "bench", "range": [-40, 160]}
          ]
        },
        {
          "key": "batt",
          "unit": "V",
          "agree": 0.5,
          "sources": [
            {"table": "t17", "offset": 10, "width": 1, "scale": 0.1, "add": 0, "null_if": [0], "prov": "provisional", "range": [6, 18], "ecm": ["0105950D01"]},
            {"table": "d0", "offset": 0, "width": 1, "scale": 0.1, "add": 0, "null_if": [0], "prov": "provisional", "range": [6, 18]}
          ]
        },
        {
          "key": "inj_ms",
          "unit": "ms",
          "sources": [
            {"table": "t17", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "bench", "range": [0, 100]}
          ]
        },
        {
          "key": "ign",
          "unit": "deg",
          "sources": [
            {"table": "t17", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "bench", "range": [-64, 64]}
          ]
        }
      ]
    },
    {
      "id": "t13.type7",
      "maker": "keihin",
      "generic": false,
      "notes": ["Keihin Type-7 per the reference tool ParseType7 (table 0x13, 14 bytes). Not bench-proven."],
      "primary": "t13",
      "tables": {
        "t13": {"request": "72 07 72 13 00 0E F4", "reply_header_len": 5, "data_len": 14, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null},
        "t20": {"request": "72 07 72 20 00 0B EA", "reply_header_len": 5, "data_len": 1, "poll_every_ticks": 5, "optional": true, "give_up_after_misses": 3}
      },
      "match": [],
      "fields": [
        {
          "key": "rpm",
          "unit": "rpm",
          "sources": [
            {"table": "t13", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "reference", "range": [0, 20000]}
          ]
        },
        {
          "key": "tps",
          "unit": "%",
          "sources": [
            {"table": "t13", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "reference", "range": [0, 120], "clamp": [0, 100]}
          ]
        },
        {
          "key": "ect",
          "unit": "degC",
          "sources": [
            {"table": "t13", "offset": 5, "width": 1, "scale": 1, "add": -40, "null_if": [255], "prov": "reference", "range": [-40, 160]}
          ]
        },
        {
          "key": "batt",
          "unit": "V",
          "sources": [
            {"table": "t13", "offset": 10, "width": 1, "scale": 0.1, "add": 0, "null_if": [0], "prov": "reference", "range": [6, 18]}
          ]
        },
        {
          "key": "inj_ms",
          "unit": "ms",
          "sources": [
            {"table": "t13", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "reference", "range": [0, 100]}
          ]
        },
        {
          "key": "ign",
          "unit": "deg",
          "sources": [
            {"table": "t13", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "reference", "range": [-64, 64]}
          ]
        },
        {
          "key": "o2r",
          "unit": "raw",
          "sources": [
            {"table": "t20", "offset": 0, "width": 1, "scale": 1, "add": 0, "null_if": [0], "prov": "reference", "range": [1, 255]}
          ]
        }
      ]
    },
    {
      "id": "t11.type1",
      "maker": "keihin",
      "generic": false,
      "notes": ["Keihin Type-1 per the reference tool ParseType1 (table 0x11, 20 bytes). LTFT omitted: its reference offset is past the table. Not bench-proven."],
      "primary": "t11",
      "tables": {
        "t11": {"request": "72 07 72 11 00 14 F0", "reply_header_len": 5, "data_len": 20, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null},
        "t20": {"request": "72 07 72 20 00 0B EA", "reply_header_len": 5, "data_len": 1, "poll_every_ticks": 5, "optional": true, "give_up_after_misses": 3}
      },
      "match": [],
      "fields": [
        {
          "key": "rpm",
          "unit": "rpm",
          "sources": [
            {"table": "t11", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "reference", "range": [0, 20000]}
          ]
        },
        {
          "key": "tps",
          "unit": "%",
          "sources": [
            {"table": "t11", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "reference", "range": [0, 120], "clamp": [0, 100]}
          ]
        },
        {
          "key": "ect",
          "unit": "degC",
          "sources": [
            {"table": "t11", "offset": 5, "width": 1, "scale": 1, "add": -40, "null_if": [255], "prov": "reference", "range": [-40, 160]}
          ]
        },
        {
          "key": "batt",
          "unit": "V",
          "sources": [
            {"table": "t11", "offset": 12, "width": 1, "scale": 0.1, "add": 0, "null_if": [0], "prov": "reference", "range": [6, 18]}
          ]
        },
        {
          "key": "inj_ms",
          "unit": "ms",
          "sources": [
            {"table": "t11", "offset": 14, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "reference", "range": [0, 100]}
          ]
        },
        {
          "key": "ign",
          "unit": "deg",
          "sources": [
            {"table": "t11", "offset": 16, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "reference", "range": [-64, 64]}
          ]
        },
        {
          "key": "o2r",
          "unit": "raw",
          "sources": [
            {"table": "t20", "offset": 0, "width": 1, "scale": 1, "add": 0, "null_if": [0], "prov": "reference", "range": [1, 255]}
          ]
        }
      ]
    },
    {
      "id": "generic.t17",
      "maker": null,
      "generic": true,
      "notes": ["Fallback when table 0x17 answers but no sub-layout matches: only fields proven identical on Keihin AND Shindengen."],
      "primary": "t17",
      "tables": {
        "t17": {"request": "72 07 72 17 00 0F EF", "reply_header_len": 5, "data_len": 15, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null}
      },
      "match": [],
      "fields": [
        {
          "key": "rpm",
          "unit": "rpm",
          "sources": [
            {"table": "t17", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "bench", "range": [0, 20000]}
          ]
        },
        {
          "key": "tps",
          "unit": "%",
          "sources": [
            {"table": "t17", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "field", "range": [0, 120], "clamp": [0, 100]}
          ]
        },
        {
          "key": "inj_ms",
          "unit": "ms",
          "sources": [
            {"table": "t17", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "bench", "range": [0, 100]}
          ]
        },
        {
          "key": "ign",
          "unit": "deg",
          "sources": [
            {"table": "t17", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "bench", "range": [-64, 64]}
          ]
        }
      ]
    }
  ]
}
