{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://synacl.com/protocol/v1/schemas/bus-tap.json",
  "title": "Bus tap batch",
  "description": "A batch of RS485 frames seen on the bus, published on `<prefix>/bus/tap` while a tap is active: from `bus/tap/start` until `bus/tap/stop` or until the start's `durationMs` elapses — stop on your own, like the log tail, so a forgotten tap cannot run up bandwidth. The reference firmware flushes every 250 ms, at most 64 frames and about 3 KB per message, and rate-limits to about 40 frames/s: on a busy 115200-baud bus it is a SAMPLER, and `dropped` says how many frames were not sent since the previous batch. Each frame is the raw Modbus RTU ADU (address, function, data, CRC) as hex, with its direction and the gateway's own verdict; a frame longer than 64 bytes keeps its first 64 and sets `tr`. Timing is relative — `t0` is the batch's first frame on the gateway clock and each `t` is microseconds after it — so request/response pairing and turnaround times survive a gateway whose clock is not NTP-synced. Relayed live to the gateway's debug room as `gw:bus:tap`; never stored.",
  "type": "object",
  "required": [
    "ts",
    "seq",
    "t0",
    "frames"
  ],
  "properties": {
    "ts": {
      "description": "Epoch milliseconds when the batch was published (gateway clock). Before 2100.",
      "type": "integer",
      "minimum": 0,
      "maximum": 4102444800000
    },
    "seq": {
      "description": "Batch counter since the tap started, so a reader can spot a lost batch.",
      "type": "integer",
      "minimum": 0
    },
    "t0": {
      "description": "Epoch milliseconds of the batch's FIRST frame (gateway clock). Every frame's `t` is relative to it. Before 2100.",
      "type": "integer",
      "minimum": 0,
      "maximum": 4102444800000
    },
    "dropped": {
      "description": "Frames the tap saw but did not send since the previous batch (rate limit or ring overflow). Absent means none.",
      "type": "integer",
      "minimum": 0
    },
    "unitId": {
      "description": "The slave-address filter in force (from `bus/tap/start`): only frames to or from this unit are in `frames`. Absent = every frame.",
      "type": "integer",
      "minimum": 1,
      "maximum": 247
    },
    "frames": {
      "description": "Oldest first. At most 64 per batch.",
      "type": "array",
      "maxItems": 64,
      "items": {
        "type": "object",
        "required": [
          "t",
          "d",
          "h"
        ],
        "properties": {
          "t": {
            "description": "Microseconds after `t0` at which the frame completed (its last byte, or the timeout expiry for a synthetic `to` frame). At most one hour.",
            "type": "integer",
            "minimum": 0,
            "maximum": 3600000000
          },
          "d": {
            "description": "Direction as seen from the gateway: `tx` = the gateway sent it (a request), `rx` = received from the bus (a response, or another master's traffic in listen-only mode).",
            "type": "string",
            "enum": [
              "tx",
              "rx"
            ]
          },
          "h": {
            "description": "The frame bytes as hex, two characters per byte, no separators, INCLUDING the CRC (upper or lower case). Empty for a synthetic timeout frame (`st: \"to\"`) that marks a request which got no reply. At most 256 bytes.",
            "type": "string",
            "pattern": "^([0-9A-Fa-f]{2})*$",
            "maxLength": 512
          },
          "st": {
            "description": "The gateway's verdict: `to` = no reply within the response timeout (`h` is empty, `d` is `rx`), `crc` = the CRC did not match (bytes shown as received), `exc` = a Modbus exception response (function code with bit 7 set). Absent = a well-formed frame.",
            "type": "string",
            "enum": [
              "to",
              "crc",
              "exc"
            ]
          },
          "tr": {
            "description": "True when the frame was longer than 64 bytes and `h` holds only its first 64 — the CRC is then NOT in `h`.",
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}
