octoturge
1b1df9c438
camera_snapshot_request (cloud to gateway) and camera_snapshot (gateway to cloud) carry one JPEG frame at a time; telemetry gains camera_snapshot and the app view gains cameraSnapshot.
226 lines
8.8 KiB
JSON
226 lines
8.8 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://git.octoturge.com/Continuum/continuum-schemas/raw/branch/main/schemas/continuum/v1/edge/client_message.schema.json",
|
|
"title": "EdgeClientMessage",
|
|
"description": "What a continuum-proxy gateway sends up to continuum-backend's /ws/edge/v1 route. Discriminated on 'type'. Field names are snake_case, matching every other schema in this repository - note that this differs from the camelCase the backend's HTTP routes use, because this wire format is shared with a Rust consumer whose serde structs derive these names directly.",
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"title": "Hello",
|
|
"description": "First message on every connection, before anything else is accepted. Carries NO credential: the edge JWT minted by POST /auth/edge-token goes in an Authorization: Bearer header on the WebSocket upgrade request, and is verified before the socket exists, so an unauthenticated peer gets an HTTP 401 and no socket at all. This message used to carry a 'token' field; it was removed, because a token in the first frame means a live socket and a parsed message for a peer that has proved nothing. farm_id here is redundant with the token's own claim and is checked against it rather than trusted - a gateway naming a farm its token was not minted for is refused.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "hello"
|
|
},
|
|
"gateway_id": {
|
|
"type": "string"
|
|
},
|
|
"farm_id": {
|
|
"type": "string"
|
|
},
|
|
"stream_base_url": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "Where this gateway serves camera restreams, e.g. http://gateway.local:1984 - the base of a go2rtc instance the gateway supervises. Optional: a gateway with no cameras configured, or with go2rtc not installed, omits it. Reported by the gateway rather than configured in the cloud because only the gateway knows the address it is actually reachable at. NOTE the consequence, which is a real limit and not a bug: this is a LAN address. A browser on the same network as the gateway can play the stream directly; one outside it cannot, and making that work needs a relay that does not exist yet. Anything surfacing this to a user has to cope with it being unreachable."
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"gateway_id",
|
|
"farm_id"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "Heartbeat",
|
|
"properties": {
|
|
"type": {
|
|
"const": "heartbeat"
|
|
},
|
|
"seq": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Monotonic per connection, restarting at 1 on reconnect. Echoed back in heartbeat_ack so the gateway can tell a stalled connection from a slow one."
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"seq"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "Telemetry",
|
|
"description": "One snapshot per printer that has something to report, on a timer. Sent as a batch rather than a message per printer: a farm has one uplink and many printers, and the backend wants a coherent picture of the farm at an instant more than it wants the lowest possible latency per machine.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "telemetry"
|
|
},
|
|
"printers": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "./printer_telemetry.schema.json"
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"printers"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "CommandResult",
|
|
"description": "The reply to a server 'command'. Correlated by command_id, which the backend generates - unlike Bambu's sequence_id, Continuum owns both ends of this protocol, so the side that needs the correlation gets to choose it.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "command_result"
|
|
},
|
|
"command_id": {
|
|
"type": "string"
|
|
},
|
|
"ok": {
|
|
"type": "boolean"
|
|
},
|
|
"error": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Present only when ok is false. A human-readable message, not a code: its only destination is an operator looking at why a command did not take. Readers must accept an explicit null here as equivalent to the key being absent: a gateway omits what it has no value for, but a serde-derived Rust producer emits null unless every field is annotated, and rejecting a whole batch over that is not worth it."
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"command_id",
|
|
"ok"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "FrameBatch",
|
|
"description": "Camera stills already uploaded to object storage, handed over for the AI worker to score. Not yet sent by any gateway - continuum-proxy restreams cameras through go2rtc and has no frame-capture path yet - but the backend consumes it, so it is part of the contract.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "frame_batch"
|
|
},
|
|
"printer_id": {
|
|
"type": "string"
|
|
},
|
|
"print_job_id": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"format": "uuid",
|
|
"description": "Readers must accept an explicit null here as equivalent to the key being absent: a gateway omits what it has no value for, but a serde-derived Rust producer emits null unless every field is annotated, and rejecting a whole batch over that is not worth it."
|
|
},
|
|
"frames": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"object_key": {
|
|
"type": "string"
|
|
},
|
|
"captured_at": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
"required": [
|
|
"object_key",
|
|
"captured_at"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"printer_id",
|
|
"frames"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "WebrtcAnswer",
|
|
"description": "go2rtc's answer SDP for a WebrtcOffer, passed through verbatim.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "webrtc_answer"
|
|
},
|
|
"session_id": {
|
|
"type": "string"
|
|
},
|
|
"sdp": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"session_id",
|
|
"sdp"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "WebrtcError",
|
|
"description": "The gateway could not get an answer: no such camera, go2rtc not running, or it refused the offer. A variant of its own rather than an empty answer, so the viewer is told something instead of watching a video element that never loads.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "webrtc_error"
|
|
},
|
|
"session_id": {
|
|
"type": "string"
|
|
},
|
|
"message": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"session_id",
|
|
"message"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "CameraSnapshot",
|
|
"description": "The answer to a CameraSnapshotRequest: one JPEG frame (base64), or the reason there is none.",
|
|
"properties": {
|
|
"type": { "const": "camera_snapshot" },
|
|
"request_id": { "type": "string" },
|
|
"jpeg_base64": { "type": "string" },
|
|
"error": { "type": "string", "description": "Set instead of jpeg_base64 when no frame could be read." }
|
|
},
|
|
"required": ["type", "request_id"]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "DiscoveredPrinters",
|
|
"description": "Printers the gateway found on its own network or USB ports that are not in its fleet file, so an operator can add one in the web app without first reading an IP address or a serial off a machine. Sent as a whole batch and treated as a replacement for what this gateway previously reported, not as additions: a printer that has gone is reported by its absence, and a gateway that can see nothing sends an empty list. Only sent when discovery is enabled in the gateway's own config, which it is NOT by default - probing a customer's network is something they have to ask for.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "discovered_printers"
|
|
},
|
|
"printers": {
|
|
"type": "array",
|
|
"maxItems": 256,
|
|
"items": {
|
|
"$ref": "./discovered_printer.schema.json"
|
|
}
|
|
},
|
|
"scanned_at": {
|
|
"description": "When the gateway finished the scan these results came from, so the cloud can show the age of the list rather than implying it is live.",
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"printers"
|
|
]
|
|
}
|
|
]
|
|
}
|