{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://synacl.com/protocol/v1/schemas/bus-scan.json",
  "title": "Bus scan progress / result",
  "description": "Progress and the result of a `bus/scan` gateway command, on `<prefix>/bus/scan`: a sweep of Modbus RTU slave addresses over the requested bauds and parities, with normal polling paused. Echo the command's `correlationId` on every message. Send `phase: progress` about every 2 s with `done`/`total` (addresses probed / to probe across the whole sweep) and the slaves found SO FAR — `found` is cumulative, so a reader replaces its list on each message — then exactly one `phase: done` with the full list and `durationMs`, or one `phase: error` with `error` when the sweep could not run or was aborted by `bus/scan/stop`. A slave counts as found when it answers the probe (FC03 or FC04, register 0, quantity 1) with a normal response OR a Modbus exception: an exception still proves something listens at that id. A reply whose CRC fails (`status: crc`) usually means the wrong baud or parity for that slave. `ident` is the FC43/14 Read Device Identification (basic objects) answer when the command asked for it and the slave implements it. The platform keeps only the LAST message per gateway for 10 minutes (GET /gateway/:id/bus/discovered) and relays each one live as `gw:bus:scan`. Never scan a bus that has another master — your probes collide with its traffic; use listen-only mode instead.",
  "type": "object",
  "required": [
    "correlationId",
    "phase"
  ],
  "properties": {
    "correlationId": {
      "description": "Copied from the `bus/scan` command.",
      "type": "string",
      "maxLength": 64
    },
    "phase": {
      "description": "`progress` while sweeping, then one `done` or one `error`.",
      "type": "string",
      "enum": [
        "progress",
        "done",
        "error"
      ]
    },
    "done": {
      "description": "Addresses probed so far, across the whole sweep.",
      "type": "integer",
      "minimum": 0
    },
    "total": {
      "description": "Addresses the sweep will probe in total: (number of ids) × bauds × parities.",
      "type": "integer",
      "minimum": 0
    },
    "found": {
      "description": "Slaves that answered, cumulative, one entry per (id, baud, parity) that replied. Report what you saw: the same id answering at two settings is two entries.",
      "type": "array",
      "maxItems": 247,
      "items": {
        "type": "object",
        "required": [
          "id",
          "baud",
          "parity",
          "replyMs",
          "status"
        ],
        "properties": {
          "id": {
            "description": "The slave address that answered.",
            "type": "integer",
            "minimum": 1,
            "maximum": 247
          },
          "baud": {
            "description": "The baud rate the probe was sent at.",
            "type": "integer",
            "minimum": 1
          },
          "parity": {
            "description": "The parity the probe was sent with: `N` none, `E` even, `O` odd (8 data bits, 1 stop bit).",
            "type": "string",
            "enum": [
              "N",
              "E",
              "O"
            ]
          },
          "replyMs": {
            "description": "Milliseconds from the end of the probe to the end of the reply.",
            "type": "integer",
            "minimum": 0
          },
          "status": {
            "description": "`ok` = a normal response. `exc` = a Modbus exception (`exc` holds the code): the slave is alive but does not serve that register. `crc` = a reply whose CRC failed: garbled, usually the wrong baud/parity for this slave or a noisy bus.",
            "type": "string",
            "enum": [
              "ok",
              "exc",
              "crc"
            ]
          },
          "exc": {
            "description": "The Modbus exception code when `status` is `exc`: 1 illegal function, 2 illegal data address, 3 illegal data value, 4 slave device failure, ….",
            "type": "integer",
            "minimum": 1,
            "maximum": 255
          },
          "ident": {
            "description": "FC43/14 basic device identification, when requested and answered. Each string as received, trimmed; omit an object the slave did not return.",
            "type": "object",
            "properties": {
              "vendor": {
                "description": "Object 0x00, VendorName.",
                "type": "string",
                "maxLength": 64
              },
              "product": {
                "description": "Object 0x01, ProductCode.",
                "type": "string",
                "maxLength": 64
              },
              "rev": {
                "description": "Object 0x02, MajorMinorRevision.",
                "type": "string",
                "maxLength": 64
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    },
    "durationMs": {
      "description": "`done`: how long the sweep ran.",
      "type": "integer",
      "minimum": 0
    },
    "error": {
      "description": "`error`: why the sweep stopped — `aborted` after a `bus/scan/stop`, `BUS_BUSY` when a tap or capture holds the bus, or a short firmware reason.",
      "type": "string",
      "maxLength": 512
    },
    "ts": {
      "description": "Epoch milliseconds (gateway clock).",
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false
}
