{
  "$schema": "./schema/board-ble.schema.json",
  "spec": "smongrot.board-ble",
  "spec_version": "1.0.0-phase1",
  "level": 1,
  "status": "stable",
  "summary": "Minimal BLE GATT needed for level 1 over a smongrot board. There are TWO firmwares with different GATT: `klineble` (what shipped SMR boards run: the board talks K-Line itself and sends decoded JSON) and `raw_tunnel` (dev firmware: the phone sends raw K-Line frames and times nothing but the wake). Pick by the service UUID the board exposes.",
  "authority": "SMR board firmware (KLineBLE, klineble-1.0.11) and the reference app BLE client; dev firmware raw tunnel. Level-1 commands only.",
  "out_of_scope": [
    "image / OTA characteristics (ff13, ff15, EC24, EC27) and every write, flash, recovery, ROM-read or OTA command",
    "access or programming procedures of any kind"
  ],
  "klineble": {
    "status": "production (SMR boards)",
    "advertising": {
      "name": "SMR-<6 upper-case hex from the BT MAC>, e.g. SMR-A526F17C",
      "scan_by": "service 0000ff10-... OR the name prefix SMR- (iOS/macOS often put the service UUID only in the scan response, and may cache an old name)."
    },
    "service": "0000ff10-0000-1000-8000-00805f9b34fb",
    "characteristics": {
      "cmd": {"uuid": "0000ff11-0000-1000-8000-00805f9b34fb", "props": ["write", "write_without_response"], "payload": "ASCII text command, no terminator"},
      "data": {"uuid": "0000ff12-0000-1000-8000-00805f9b34fb", "props": ["notify"], "payload": "UTF-8: one JSON object or one text line per message"},
      "ver": {"uuid": "0000ff14-0000-1000-8000-00805f9b34fb", "props": ["read"], "payload": "JSON {\"fw\": \"klineble-x.y.z\", \"hw\": ..., \"sn\": \"<6 hex>\", ...}; absent on legacy boards"}
    },
    "mtu": {"board_sets": 512, "note": "A notify carries at most MTU-3 bytes; iOS may negotiate 185 (182 B) while a live JSON can be ~210 B."},
    "reassembly": "Join ff12 notifies while a JSON object's braces are unbalanced (drop pieces older than 1 s or longer than 2048 B); a cut-off object never parses and must yield no value. Text lines pass through unchanged.",
    "wake_and_session": "Done by the board: HIGH 100 ms, LOW 70 ms, UART 10400 8N1, idle 150 ms, then FE 04 72 8C and 72 05 00 F0 99 (session up when that answers); up to 5 wakes; re-opened every 1.5 s while down. The realtime loop does not send StartDiag before polling.",
    "commands": [
      {
        "cmd": "R",
        "does": "Start realtime. Board answers the line `STAT realtime on`, then one JSON object per successful poll (every 300 ms).",
        "board_poll_request": "72 05 71 17 01",
        "note": "The board polls 72 05 71 17 01, not the 72 07 72 17 00 0F EF read in spec/live.json. Its reply has 4 header bytes; the board decodes it itself (see realtime_json)."
      },
      {"cmd": "S", "does": "Stop realtime. Answer `STAT realtime off`."},
      {
        "cmd": "ECMID",
        "does": "Read the ECM-ID (72 07 72 00 00 05 10 on the wire).",
        "answer": "`ECMID <10 hex>` or `ECMID FAIL`",
        "parse": "split on whitespace; parts[0] == 'ECMID' and parts[1] matches ^[0-9A-Fa-f]{10}$ → upper-case it; anything else = no ID.",
        "note": "Send one at a time per link: two ECMIDs on one K-Line session collide. App timeout 12 s."
      },
      {
        "cmd": "DTCPROBE",
        "status": "beta",
        "does": "Board opens a session, sends StartDiag, then a sweep of read candidates including 72 05 74 01/02/03 (labels RD_74_01..RD_74_03) and reports one line per candidate, 60 ms apart. Realtime stops; re-send R afterwards if wanted.",
        "line": "STAT dtcprobe <label> n=<reply bytes> r=<echo-stripped reply hex|(silent)> f=<request hex> cls=<DATA|NAK|ACK|SILENT>",
        "line_regex": "^STAT dtcprobe (\\S+) n=(\\d+) r=(\\S+?)(?:\\s+f=(\\S+))?(?:\\s+cls=(\\S+))?$",
        "bookends": ["STAT dtcprobe start n_candidates=<n>", "STAT dtcprobe summary data=<n> nak=<n> ack=<n> silent=<n>", "DTCPROBEDONE"],
        "no_session": "STAT dtcprobe no-session (check key ON + DLC) then DTCPROBEDONE",
        "cls": "SILENT = no bytes; NAK = any byte 0x7F; DATA = any non-zero byte from index 4 to len-2; else ACK.",
        "decode": "Take the hits whose label is RD_74_0<sub> (or whose f= request is 72 .. 74 <sub>), feed r= as the reply into spec/dtc.json read_decode with those subs. App timeout 25 s."
      }
    ],
    "realtime_json": {
      "example": "{\"session\":true,\"valid\":true,\"running\":false,\"rpm\":0,\"tps\":0.0,\"ect\":-30,\"batt\":12.5,\"inj\":0.0,\"ign\":0.0,\"iat\":0,\"map\":0,\"speed\":0}",
      "fields": {
        "session": "bool, K-Line session up",
        "valid": "bool, last poll decoded",
        "running": "bool, inj > 0 and ign != 0",
        "rpm": "int",
        "tps": "float, throttle ANGLE in degrees (raw * 0.5), NOT the % of spec/live.json",
        "ect": "int degC (raw - 40)",
        "batt": "float V (raw / 10)",
        "inj": "float, raw * 3.92. Injector ms = inj / 980 (the reference implementation).",
        "ign": "float deg (raw * 0.5 - 64)",
        "iat": "int, 0 when not reported",
        "map": "int, 0 when not reported",
        "speed": "int",
        "o2r": "optional int 1..255 (newer firmware, only while fresh); anything else = no reading",
        "o2v": "optional float volts in (0, 1.3]; anything else = no reading"
      },
      "parse_rule": "Accept an object only if it has key rpm. Missing iat/map/speed = 0.",
      "status": "Board-side decode, Keihin-only formula for every box (e.g. Shindengen batt reads 0.0 here). Not covered by the live vectors."
    }
  },
  "raw_tunnel": {
    "status": "dev-only (dev firmware, not on shipped SMR boards)",
    "service": "0000EC20-0000-1000-8000-00805F9B34FB",
    "characteristics": {
      "control": {"uuid": "0000EC21-0000-1000-8000-00805F9B34FB", "props": ["write"], "payload": "1-byte opcode + little-endian args; write WITH response so steps stay ordered"},
      "kline_tx": {"uuid": "0000EC22-0000-1000-8000-00805F9B34FB", "props": ["write", "write_without_response"], "payload": "raw K-Line bytes, chunked to MTU-3 (phone requests MTU 247); the board joins chunks by K-Line timing"},
      "kline_rx": {"uuid": "0000EC23-0000-1000-8000-00805F9B34FB", "props": ["notify"], "payload": "raw bytes read back from the bus INCLUDING the TX echo; strip it per spec/kline.json echo_strip"},
      "info": {"uuid": "0000EC26-0000-1000-8000-00805F9B34FB", "props": ["read"], "payload": "JSON caps (optional)"}
    },
    "opcodes": [
      {"op": 1, "hex": "0x01", "name": "ENTER", "firmware_name": "FOP_ENTER_FLASH", "args": [], "does": "Open the K-Line UART tunnel (suspends board telemetry). Must come first. Sends nothing to the ECU."},
      {"op": 2, "hex": "0x02", "name": "EXIT", "firmware_name": "FOP_EXIT", "args": [], "does": "Leave tunnel mode."},
      {"op": 16, "hex": "0x10", "name": "KLINE_OPEN", "args": [], "does": "(Re)init the UART at the current baud and flush."},
      {"op": 18, "hex": "0x12", "name": "KLINE_PURGE", "args": [], "does": "Flush RX."},
      {"op": 19, "hex": "0x13", "name": "SET_BAUD", "args": ["u32 LE baud"], "example": "13 A0 28 00 00 (10400)"},
      {"op": 22, "hex": "0x16", "name": "WAKE_PULSE", "args": ["u16 LE low_ms"], "example": "16 46 00 (70 ms)", "does": "Atomic ISO 9141 wake on the board: TX LOW, delay(low_ms), HIGH, re-open the UART. Phone then waits 130 ms before StartComm."}
    ],
    "legacy_opcodes": "0x14 SET_MODE / 0x15 GPIO built the wake from separate writes; do not use (jittery wake).",
    "session": "Phone runs spec/kline.json session itself: 12 (purge) → 13 A0 28 00 00 → 16 46 00 → wait 130 ms → FE 04 72 8C on kline_tx → liveness → StartDiag → ECM-ID → live tables."
  }
}
