{
  "openapi": "3.1.0",
  "info": {
    "title": "RoboBaton Neo HTTP API",
    "version": "1.0.0",
    "description": "31个方法/路径操作、7路实时流，HTTP/1.1 共用80端口。新增 GET /vio 查询真实进程/定位状态，POST 仍异步202受理。错误对象仅有code，不返回message；与本版网页配套更新。实机验收范围见专项报告。 设备业务由独立设备服务持有；Web重启保留命令去重、录制及预检状态。设备服务重启时内存去重和预检缓存清空。 更新流程为上传校验、安装、显式重启。"
  },
  "servers": [
    {
      "url": "/api"
    }
  ],
  "paths": {
    "/vio": {
      "post": {
        "operationId": "acceptVioCommand",
        "description": "异步受理；同key/action设备服务进程内10分钟去重，最多32项；并行新命令409。通过GET /vio查询，不以202推断运行成功。正文1~128字节，唯一Content-Length，不支持chunked。 预检期间或停止/重启会中断当前里程计录制时拒绝409；网页与物理按键共用此规则。",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 96,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VioAction"
              },
              "example": {
                "action": "start"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "已受理，尚不确认执行结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Accepted"
                },
                "example": {
                  "action": "start",
                  "accepted": true
                }
              }
            }
          },
          "400": {
            "description": "非法动作/请求或不完整正文",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "正文超时",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "长度超限",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "执行中或key冲突；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "命令服务/去重容量不可用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "查询 VIO 实际状态",
        "operationId": "getVioStatus",
        "description": "只读，不启动算法。未开放实时状态流，建议约1秒查询一次。",
        "responses": {
          "200": {
            "description": "当前状态；执行失败仍通过error.code表达",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VioStatus"
                }
              }
            }
          },
          "503": {
            "description": "进程状态/观察服务不可用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stream": {
      "get": {
        "operationId": "observeStream",
        "description": "每连接单选preview/odometry/imu/color/gray/gray_jpeg/depth；gray_jpeg最多3连接，其余最多4连接。chunked解码后按RBH1重组。color首条ColorMetadata，随后format7完整JPEG/AnnexB访问单元；配置或源变化断开重连。订阅不会启动VIO。 gray为未压缩mono8，固定544×640、stride544、5fps；首次订阅启动共享采集，不启动VIO，VIO停止不结束gray。 gray_jpeg为544×640 JPEG Q90，跟随源帧率，最多3个外部连接；独立有界队列优先服务TF。 depth: 固定384x384 float32相对深度，最多4订阅共享推理，最后退出3秒宽限。",
        "parameters": [
          {
            "name": "channels",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "preview",
                "odometry",
                "imu",
                "color",
                "gray",
                "gray_jpeg",
                "depth"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "持续RBH1数据；channel0控制JSON，1预览RBF2 image，2里程计JSON；错误可能结束连接。 IMU channel3/format1，每条消息恰好一个样本；无数据3秒结束连接，不补历史。 color channel4/format7，首条配置后才有图像，格式见x-rbh1.color。 gray channel5/format8；首条GrayMetadata，逐帧GrayFrame JSON前缀与348160字节像素；非JPEG，不改变TF录制。 gray_jpeg: channel6/format7，GrayJpegMetadata先行，ColorFrame前缀（pts_us=null,random_access=true）随后JPEG，最大1048576+512字节。 depth channel7/format9，DepthMetadata先行，DepthFrame JSON前缀+589824字节原始float32。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/vnd.robobaton.stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "x-rbh1": {
              "header_bytes": 40,
              "byte_order": "little",
              "version": 1,
              "max_fragment_bytes": 65536,
              "control_schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Metadata"
                  },
                  {
                    "$ref": "#/components/schemas/ColorMetadata"
                  },
                  {
                    "$ref": "#/components/schemas/GrayMetadata"
                  },
                  {
                    "$ref": "#/components/schemas/GrayJpegMetadata"
                  },
                  {
                    "$ref": "#/components/schemas/DepthMetadata"
                  }
                ]
              },
              "heartbeat_schema": {
                "$ref": "#/components/schemas/Heartbeat"
              },
              "odometry": {
                "channel": 2,
                "format": 1,
                "schema": {
                  "$ref": "#/components/schemas/Odometry"
                }
              },
              "preview": {
                "channel": 1,
                "format": 6,
                "payload": "RBF2 image schema2; context/descriptor precede frame",
                "reference": "HTTP-API.md#5-线上封装"
              },
              "imu": {
                "channel": 3,
                "format": 1,
                "schema": {
                  "$ref": "#/components/schemas/ImuSample"
                }
              },
              "color": {
                "channel": 4,
                "format": 7,
                "metadata_schema": {
                  "$ref": "#/components/schemas/ColorMetadata"
                },
                "frame_schema": {
                  "$ref": "#/components/schemas/ColorFrame"
                },
                "byte_order": "little",
                "layout": [
                  {
                    "offset": 0,
                    "bytes": 4,
                    "type": "uint32",
                    "meaning": "UTF-8 JSON字节数N，1..508"
                  },
                  {
                    "offset": 4,
                    "bytes": "N",
                    "meaning": "ColorFrame JSON"
                  },
                  {
                    "offset": "4+N",
                    "bytes": "RBH1.total-4-N",
                    "meaning": "JPEG或H26x AnnexB访问单元"
                  }
                ],
                "max_binary_bytes": 2097152,
                "max_message_bytes": 2097664,
                "frame_schema_by_codec": {
                  "mjpeg": {
                    "$ref": "#/components/schemas/ColorJpegFrame"
                  },
                  "h264": {
                    "$ref": "#/components/schemas/ColorVideoFrame"
                  },
                  "h265": {
                    "$ref": "#/components/schemas/ColorVideoFrame"
                  }
                }
              },
              "gray": {
                "channel": 5,
                "format": 8,
                "metadata_schema": {
                  "$ref": "#/components/schemas/GrayMetadata"
                },
                "frame_schema": {
                  "$ref": "#/components/schemas/GrayFrame"
                },
                "layout": [
                  {
                    "offset": 0,
                    "type": "uint32_le",
                    "meaning": "UTF-8 JSON byte length N, 1..252"
                  },
                  {
                    "offset": 4,
                    "length": "N",
                    "meaning": "GrayFrame JSON"
                  },
                  {
                    "offset": "4+N",
                    "length": 348160,
                    "meaning": "mono8 pixels, top-to-bottom rows, left-to-right columns; no padding"
                  }
                ],
                "max_message_bytes": 348416,
                "timestamp": "CLOCK_MONOTONIC_RAW exposure midpoint; null if not associated; do not add calibration time offset",
                "sequence": "source capture sequence as decimal uint64 string, not 5Hz output counter; intentional sampling gaps; scoped to connection",
                "lifecycle": "source epoch/session change closes stream; new GET starts with metadata. At most 4 viewers; latest-only mailbox, 1s whole-frame send deadline, source wait 8s initially/3s after delivery; no catch-up."
              },
              "gray_jpeg": {
                "channel": 6,
                "format": 7,
                "metadata_schema": {
                  "$ref": "#/components/schemas/GrayJpegMetadata"
                },
                "frame_schema": {
                  "$ref": "#/components/schemas/ColorJpegFrame"
                },
                "max_message_bytes": 1049088,
                "payload": "uint32 LE JSON size, JSON, one complete JPEG Q90; no base64; epoch/gap/stale terminates connection"
              },
              "depth": {
                "channel": 7,
                "format": 9,
                "max_message_bytes": 590080,
                "json_length_prefix_bytes": 4,
                "max_json_bytes": 252,
                "frame_schema": {
                  "$ref": "#/components/schemas/DepthFrame"
                },
                "binary_bytes": 589824,
                "binary": "384x384 row-major float32 little-endian; nonfinite preserved",
                "reference": "HTTP-API-深度.md",
                "metadata_schema": {
                  "$ref": "#/components/schemas/DepthMetadata"
                }
              }
            }
          },
          "400": {
            "description": "无效/混合通道",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "流连接上限",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "预览/IMU源、发送优先级或资源不可用；color配置/源未就绪或10秒内未取得参数集和IDR。 gray服务、资源、发送线程优先级不可用或8秒未取得新鲜图像；已开始HTTP200的流通过断开表示故障。 depth: DEPTH_CONFIG_UNAVAILABLE / DEPTH_UNAVAILABLE / DEPTH_NOT_READY；首帧最多等待20秒，随后3秒无新数据关闭连接。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "深度订阅与录制预检或应用更新互斥：CHECK_ACTIVE / UPDATE_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/color/config": {
      "get": {
        "operationId": "getColorConfig",
        "description": "获取全局输出配置，仅一次JSON响应，不订阅图像。",
        "responses": {
          "200": {
            "description": "返回实际配置。GET不订阅、不启动彩色编码；POST相同配置不断流。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ColorConfig"
                }
              }
            }
          },
          "400": {
            "description": "非法JSON、字段、类型或范围",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "编码器重配置失败，尝试回退；重新查询配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "配置服务不可用或回复不完整，重新查询确认",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "setColorConfig",
        "description": "完整替换配置（非PATCH）；必须codec/fps及质量或码率。正文1~256字节，application/json，唯一Content-Length，不接受chunked、未知/重复字段。允许运行时修改；改变结束所有旧color连接，新连接先配置再IDR/JPEG。不重启VIO/预览/IMU。不持久化到重启后。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ColorConfigRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "返回实际配置。GET不订阅、不启动彩色编码；POST相同配置不断流。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ColorConfig"
                }
              }
            }
          },
          "400": {
            "description": "非法JSON、字段、类型或范围",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "请求体接收超时",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "VIO帧率限制、录制锁或并发配置冲突；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "编码器重配置失败，尝试回退；重新查询配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "配置服务不可用或回复不完整，重新查询确认",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/recording": {
      "get": {
        "operationId": "getRecording",
        "description": "只查询当前任务；无当前任务时严格返回 {state:idle}。saving 时 duration_s 固定，计数可增长。此接口不返回最近一次结果。 counts/bytes_written在fflush成功后更新，不等于已落盘；约100ms刷新，约1秒或新增完整写入达到1MiB时请求合并的后台fsync，实际同步耗时取决于存储。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordingState"
                }
              }
            }
          },
          "400": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "acceptRecording",
        "description": "默认 gray+imu；start 冻结 mono.conf，异步连接板内源；odometry 需要 VIO 已运行。stop 必须指定当前 recording_id。202 只代表受理，最终按 ID 查询 datasets；同一进程内幂等键保留10分钟，最多32项。正文1..512字节，仅 application/json + Content-Length。 VIO命令执行中不接受开始录制，返回409 COMMAND_BUSY。 支持KEEP_SIZE时每段预分配256MiB；仅识别为exFAT且不支持该能力（EOPNOTSUPP）时使用空文件顺序增长，不承诺已预留空间，ENOSPC/EIO不降级。8MiB队列与8MiB未确认预算保持不变。",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 96,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecordingRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordingAccepted"
                }
              }
            }
          },
          "400": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "408": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "507": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/monitor": {
      "get": {
        "operationId": "getMonitor",
        "description": "只返回 TF 卡监控；capacity 为真实挂载 TF 文件系统容量。available 不减512 MiB预留。未识别设备不可直接等同没插卡。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Monitor"
                }
              }
            }
          },
          "400": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/datasets": {
      "get": {
        "operationId": "listDatasets",
        "description": "仅本版 recordings 根目录；不迁移旧 euroc。按 ID 升序分页（非时间排序），无卡503，空目录200空数组。查询字符串若存在必须 limit=N&offset=N。并发变化可能改变页偏移。",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetPage"
                }
              }
            }
          },
          "400": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{id}": {
      "get": {
        "operationId": "getDataset",
        "description": "录制配置和最终结果。录制中 result=null；恢复中 current.state=recovering。无卡503，不存在404。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetDetail"
                }
              }
            }
          },
          "400": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteDataset",
        "description": "单个明确 ID；实际删除完成才204。录制/保存/恢复/下载期间409。拒绝递归删除未知文件或链接；失败可能已删除部分文件，须重新查询。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{32}$"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "已删除"
          },
          "400": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{id}/archive": {
      "get": {
        "operationId": "downloadDataset",
        "description": "流式 tar，无二次压缩，无Range。所有录制/保存期间409；下载锁阻止新的录制和删除。保留异常 .part 原文，读者按有效CRC前缀解释。首版最多4096段，单文件上限8GiB-1。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "包含 manifest.json、mono.conf、result.json、segments",
            "content": {
              "application/x-tar": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "416": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "请求无效、资源冲突或存储/数据不可用。error.code 为稳定错误码；说明见错误码文档，不返回 message。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/recording/check": {
      "get": {
        "operationId": "getRecordingPreflight",
        "description": "查询当前实际配置对应的本次开机内存记录，同时返回全局活动预检。配置不匹配则untested。服务重启、卡连接或挂载代次变化后失效。最多保留128组，不淘汰已有记录；超限拒绝新配置预检。",
        "parameters": [
          {
            "name": "channels",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "以逗号分隔 gray,imu,color,odometry；每个最多一次；与勾选顺序无关。"
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckStatus"
                }
              }
            }
          },
          "400": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "acceptRecordingPreflight",
        "description": "真实采集30秒，再等待排空及同步；start默认gray+imu。与正式录制、数据下载/删除互斥；预检期间修改彩图配置或VIO动作409。停止以check_id取消。断线不取消。临时RBR1数据不进入datasets，结束清理，结果仅在内存。202仅表示受理。 与正式录制共用有效写缓冲、合并同步和exFAT预分配能力处理；仍使用原风险阈值，连续录制成功不等于预检passed。",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 96,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckAccepted"
                }
              }
            }
          },
          "400": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "JSON response；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "507": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/mount/config": {
      "get": {
        "operationId": "getMountConfig",
        "description": "返回磁盘已保存配置，非当前VIO内存副本；无需query、body或Content-Length（含0）。主配置不存在时读旧文件，两者都缺失才返回car/FLU默认正装；坏文件报错。旧IMU配置用mono.conf外参换算。GET不创建文件、不启动VIO。详见HTTP-API-安装补偿.md。",
        "responses": {
          "200": {
            "description": "完整已保存配置或默认配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MountConfig"
                },
                "examples": {
                  "default": {
                    "summary": "没有已保存文件时的默认安装",
                    "value": {
                      "configured": false,
                      "robot_type": "car",
                      "convention": "FLU",
                      "camera_in_robot": {
                        "position": {
                          "x": 0,
                          "y": 0,
                          "z": 0
                        },
                        "orientation": {
                          "x": 0,
                          "y": 0.7071067811865476,
                          "z": 0,
                          "w": 0.7071067811865476
                        }
                      }
                    }
                  },
                  "saved": {
                    "summary": "已保存配置，不代表当前VIO已采用",
                    "value": {
                      "robot_type": "car",
                      "convention": "FLU",
                      "camera_in_robot": {
                        "position": {
                          "x": 0.12,
                          "y": 0,
                          "z": 0
                        },
                        "orientation": {
                          "x": 0,
                          "y": 0.7071067811865476,
                          "z": 0,
                          "w": 0.7071067811865476
                        }
                      },
                      "configured": true
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_REQUEST：GET携带禁止的Content-Length/传输升级头或通用HTTP请求非法。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "CONFIG_LOAD_FAILED 或 CALIBRATION_LOAD_FAILED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND：路径、方法或查询参数不受支持。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "DEVICE_UNAVAILABLE / DEVICE_REQUEST_UNCONFIRMED / DEVICE_PROTOCOL_MISMATCH；POST结果未确认时先GET核对。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "saveMountConfig",
        "description": "完整替换；拒绝缺少、未知、重复字段及configured。精确Content-Type application/json、唯一Content-Length、正文1~1023字节；无Transfer-Encoding/Upgrade/Expect。临时文件写入、文件fsync、原子rename、目录fsync及回读完成后200；下次VIO启动加载。允许VIO运行和启停期间保存；当前实例保持启动快照，下次启动或重启加载。并发启动按实际读取与原子替换先后确定。写入及回读由设备服务串行处理，更新期间仍409 UPDATE_BUSY；相机/IMU标定运行保护不变。无需Idempotency-Key，无CAS、多客户端按保存先后覆盖；结果不确定先GET。默认持久化路径/home/VIO/parameters/mount.json。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MountConfigWrite"
              },
              "example": {
                "robot_type": "car",
                "convention": "FLU",
                "camera_in_robot": {
                  "position": {
                    "x": 0.12,
                    "y": 0,
                    "z": 0
                  },
                  "orientation": {
                    "x": 0,
                    "y": 0.7071067811865476,
                    "z": 0,
                    "w": 0.7071067811865476
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已持久化并回读，configured=true",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MountConfig"
                },
                "example": {
                  "robot_type": "car",
                  "convention": "FLU",
                  "camera_in_robot": {
                    "position": {
                      "x": 0.12,
                      "y": 0,
                      "z": 0
                    },
                    "orientation": {
                      "x": 0,
                      "y": 0.7071067811865476,
                      "z": 0,
                      "w": 0.7071067811865476
                    }
                  },
                  "configured": true
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_CONFIG",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "REQUEST_TIMEOUT",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "UPDATE_BUSY：应用更新期间拒绝写入，未执行本次保存。VIO运行或启停不再导致409。；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UPDATE_BUSY": {
                    "value": {
                      "error": {
                        "code": "UPDATE_BUSY"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "CONFIG_SAVE_FAILED：写入/同步/替换/回读失败；CONFIG_LOAD_FAILED：回读对象不可序列化。结果可能已落盘，先GET确认。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND：路径、方法或查询参数不受支持。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "DEVICE_UNAVAILABLE / DEVICE_REQUEST_UNCONFIRMED / DEVICE_PROTOCOL_MISMATCH；POST结果未确认时先GET核对。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/calibration/parameters": {
      "get": {
        "operationId": "getCalibrationParameters",
        "description": "读取本次有效参数。合法 mono.conf 优先，仅文件不存在时使用完整代码默认值；文件损坏或不可读返回500，不混用缺失字段，不写文件。",
        "responses": {
          "200": {
            "description": "有效 DS 参数及只读 source；POST 成功为 saved，GET 可为 default。保存或默认启动均不代表定位精度验收。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EffectiveCalibrationParameters"
                }
              }
            }
          },
          "400": {
            "description": "非法参数、未知或重复字段、不支持的模型/尺寸；旧配置不变",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "文件读取失败或保存结果未确认；GET回读后处理",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "saveCalibrationParameters",
        "description": "完整替换，仅DS 544x640与200Hz IMU。Content-Type application/json及唯一Content-Length，正文1~4095字节，不支持chunked。运行互斥、实际算法加载校验、fsync后原子替换；下次启动加载。无隐式stop/restart，无自动写入重试。 source 为只读响应字段，请求携带时400；GET返回对象用于保存前需删除source。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalibrationParameters"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "有效 DS 参数及只读 source；POST 成功为 saved，GET 可为 default。保存或默认启动均不代表定位精度验收。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EffectiveCalibrationParameters"
                }
              }
            }
          },
          "400": {
            "description": "非法参数、未知或重复字段、不支持的模型/尺寸；旧配置不变",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "408": {
            "description": "请求正文接收超时",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "VIO启停/运行、录制/预检或其他依赖任务占用；不自动停止；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文超过4095字节",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "文件读取失败或保存结果未确认；GET回读后处理",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/buttons/config": {
      "get": {
        "operationId": "getButtonsConfig",
        "description": "无正文和query。缺公开配置时只读兼容内部旧配置，录制内容默认为gray+imu；均不存在时短按none/长按record_toggle/2000ms。损坏配置禁用动作并503，不静默回退。",
        "responses": {
          "200": {
            "description": "完整配置；POST确认持久化并生效，未触发任何任务。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ButtonsConfig"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_CONFIG；完整四字段，拒绝未知、重复、缺失字段或非法值。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "CONFIG_LOAD_FAILED / CONFIG_SAVE_FAILED / BUTTON_UNAVAILABLE；保存未确认时重新读取。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "saveButtonsConfig",
        "description": "完整替换并持久化，正文1~511字节；Content-Type=application/json及唯一Content-Length，不接受chunked/Expect。无需Idempotency-Key；同配置可重试，多客户端按保存先后覆盖。保存使准备中及排队未执行手势失效，正在执行的任务保持原设置。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ButtonsConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "完整配置；POST确认持久化并生效，未触发任何任务。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ButtonsConfig"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_CONFIG；完整四字段，拒绝未知、重复、缺失字段或非法值。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "CONFIG_LOAD_FAILED / CONFIG_SAVE_FAILED / BUTTON_UNAVAILABLE；保存未确认时重新读取。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "REQUEST_TIMEOUT",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "业务冲突；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/serial/status": {
      "get": {
        "operationId": "getSerialStatus",
        "description": "Actual active UART baud; null on UART fault.",
        "responses": {
          "200": {
            "description": "Snapshot / parameter results",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SerialStatus"
                }
              }
            }
          },
          "400": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "404": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "409": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "503": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "504": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          }
        }
      }
    },
    "/mavlink/status": {
      "get": {
        "operationId": "getMavlinkStatus",
        "description": "Offline after 3000ms without target heartbeat. armed and flight_mode become null. Select at most one operation_id/request_key. Retains 32 completed records plus active; restart clears RAM.",
        "responses": {
          "200": {
            "description": "Snapshot / parameter results",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkStatus"
                }
              }
            }
          },
          "400": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "404": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "409": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "503": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "504": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "operation_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "request_key",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/mavlink/parameters": {
      "get": {
        "operationId": "getMavlinkParameters",
        "description": "Fresh case-sensitive named read, at most 32 unique names, 5s total. Partial results HTTP200; no all-parameter dump.",
        "responses": {
          "200": {
            "description": "Snapshot / parameter results",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkParameters"
                }
              }
            }
          },
          "400": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "404": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "409": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "503": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "504": {
            "description": "No parameter replies before the total deadline; replied-but-unsupported types are HTTP200 with per-item errors",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkParameters"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "names",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_]{1,16}(,[A-Za-z0-9_]{1,16})*$"
            }
          }
        ]
      },
      "post": {
        "operationId": "setMavlinkParameters",
        "description": "10s total pre-read/validate entire batch, write sequentially and verify. Never resend uncertain writes. First failure stops remainder. Types from controller. No rollback or auto reboot.",
        "responses": {
          "202": {
            "description": "Accepted; query operation result",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "404": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "409": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "503": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "504": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MavlinkWriteRequest"
              }
            }
          }
        }
      }
    },
    "/mavlink": {
      "post": {
        "operationId": "manageMavlink",
        "description": "One management operation, no queue. Same UUID and normalized arguments reuse original operation; conflicts409. Scan/cancel restore pre-scan local config. Reboot continuation aliases waiting operation. No persistent unfinished summaries. See HTTP-API-MAVLink.md for deadlines and reboot evidence.",
        "responses": {
          "202": {
            "description": "Accepted; query operation result",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "404": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "409": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "503": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          },
          "504": {
            "description": "Explicit request / operation / transport error; parameter read 504 returns MavlinkParameters",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MavlinkError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MavlinkAction"
              }
            }
          }
        }
      }
    },
    "/update": {
      "get": {
        "operationId": "getUpdate",
        "description": "查询独立设备服务管理的更新状态。running 是当前设备服务，gateway_running 是当前网关的编译身份；未知为 null。installed 是磁盘安装回执，不代表当前所有组件已生效。operation 为最近一项持久操作。",
        "responses": {
          "200": {
            "description": "当前状态",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateStatus"
                }
              }
            }
          },
          "503": {
            "description": "设备服务不可用、响应未确认或操作记录已满",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "acceptUpdate",
        "description": "仅安装（install）；reboot 动作已删除，统一 POST /system/reboot {}。安装受理前持久化操作及 key，同 key/内容返回原 ID，异内容409，最多128个持久 key。要求空闲；不自动停止业务，不重放未确认安装。",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 96,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCommand"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "仅受理，不表示安装完成",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateAccepted"
                }
              }
            }
          },
          "400": {
            "description": "请求无效",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "上传或正文超时",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "设备忙、维护中、活动采集/下载、幂等键冲突",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "超过最大包大小",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "更新包校验失败，候选包不替换",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "更新状态或存储写入失败",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "设备服务不可用、响应未确认或操作记录已满",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "507": {
            "description": "暂存/安装空间不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/update/package": {
      "post": {
        "operationId": "uploadUpdatePackage",
        "description": "固定 Content-Length 二进制上传，禁止 chunked/Expect。最大512MiB，还需实际可用空间。单上传、单候选；空闲时接受，正文15秒无进展或总600秒超时。设备完成校验和保存后返回200，随后才可安装。上传100%不代表校验通过。失败或残缺上传不可安装，已有候选保留；不提供续传。",
        "parameters": [
          {
            "name": "Content-Length",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 536870912
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已校验并保存候选包",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdatePackage"
                }
              }
            }
          },
          "400": {
            "description": "请求无效",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "上传或正文超时",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "设备忙、维护中、活动采集/下载、幂等键冲突",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "超过最大包大小",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "更新包校验失败，候选包不替换",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "更新状态或存储写入失败",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "设备服务不可用、响应未确认或操作记录已满",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "507": {
            "description": "暂存/安装空间不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/boot/config": {
      "get": {
        "summary": "查询已保存的开机策略",
        "responses": {
          "200": {
            "description": "已保存的下次开机策略；POST 200 表示保存成功，不表示 VIO 已启动。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BootConfig"
                }
              }
            }
          },
          "503": {
            "description": "配置无效或设备服务不可用，error 仅含 code。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "保存下次开机的 VIO 自动启动策略",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BootConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已保存的下次开机策略；POST 200 表示保存成功，不表示 VIO 已启动。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BootConfig"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_CONFIG / INVALID_REQUEST",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "UPDATE_BUSY；系统重启执行中或持久状态异常：REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "CONFIG_SAVE_FAILED 或设备服务不可用；重新 GET 核对保存结果。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/depth/config": {
      "get": {
        "operationId": "getDepthConfig",
        "description": "只读当前/运行冻结配置，不启动采集或推理、不续租；流内metadata才是该连接依据。",
        "responses": {
          "200": {
            "description": "深度输出配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepthConfig"
                }
              }
            }
          },
          "503": {
            "description": "配置服务不可用或回复不完整，重新查询确认",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/system/status": {
      "get": {
        "operationId": "getSystemStatus",
        "description": "当前 boot_id 与最近持久重启请求。受理时 boot_id 保存在 reboot 内；跨 boot 的未完成请求判 succeeded，同 boot 服务重启判 REBOOT_INTERRUPTED，不自动重放。此成功不代表 OTA 激活成功。初始化恢复失败 available=false，boot_id/reboot 为 null。",
        "responses": {
          "200": {
            "description": "系统状态",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemStatus"
                },
                "example": {
                  "boot_id": "00000000-0000-4000-8000-000000000001",
                  "available": true,
                  "reboot": null
                }
              }
            }
          },
          "400": {
            "description": "请求头或正文非法",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "设备服务不可用/IPC 未确认或不匹配",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/system/reboot": {
      "post": {
        "operationId": "acceptSystemReboot",
        "description": "空正文对象 {}，无 force。空闲或 OTA reboot_required 时受理，业务/采集/下载/上传/安装/待核查阻止重启；不强停。持久保存至 /home/.robobaton-update/reboot，相同 key 跨 boot 返回原回执不重复执行；最多128个 key，无自动淘汰。结果不确定先 GET，再用原 key 找回回执；明确失败后才用新 key。OTA 与重启结果分别查询。详见 HTTP-API-系统.md。",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 96,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SystemRebootCommand"
              },
              "example": {}
            }
          }
        },
        "responses": {
          "202": {
            "description": "仅受理；重复 key 返回原始回执",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemRebootAccepted"
                },
                "example": {
                  "request_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                  "state": "accepted",
                  "boot_id": "00000000-0000-4000-8000-000000000001"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_REQUEST / INCOMPLETE_BODY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "REQUEST_TIMEOUT",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "DEVICE_BUSY / CAPTURE_ACTIVE / UPDATE_BUSY / REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "BODY_TOO_LARGE（正文最多128字节）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "REBOOT_STORAGE_FAILED / REBOOT_HISTORY_FULL / REBOOT_FAILED / UPDATE_STORAGE_FAILED / DEVICE_UNAVAILABLE / DEVICE_REQUEST_UNCONFIRMED / DEVICE_PROTOCOL_MISMATCH",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/network/config": {
      "get": {
        "operationId": "readNetworkConfig",
        "summary": "读取当前生效的 USB 网络配置",
        "responses": {
          "200": {
            "description": "当前内核 usb0 地址；不是保存草稿",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkConfig"
                }
              }
            }
          },
          "409": {
            "description": "NETWORK_CHANGING；切换和落盘完成前不报告成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "NETWORK_UNAVAILABLE 或设备服务不可用",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "changeNetworkConfig",
        "summary": "修改 USB 网络网段",
        "description": "正文最多64字节，必须是唯一subnet整数字段。不需要Idempotency-Key。相同生效网段200，无切网；新网段202受理，网关发送响应后才授权执行。切换中409，不排队。不得在丢响应后自动重发；从新地址GET核对。网卡短暂重连，不重启VIO；本地失败尝试恢复旧地址。保存后开机沿用。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NetworkConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "无需变更，返回当前配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkConfig"
                }
              }
            }
          },
          "202": {
            "description": "受理不表示切换成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "accepted"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "accepted": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "INVALID_CONFIG 或 INVALID_REQUEST",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "NETWORK_CHANGING、UPDATE_BUSY 或 REBOOT_BUSY",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "NETWORK_UNAVAILABLE、CONFIG_SAVE_FAILED 或设备服务不可用",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Vector3": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "x",
          "y",
          "z"
        ],
        "properties": {
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          },
          "z": {
            "type": "number"
          }
        }
      },
      "Quaternion": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "x",
          "y",
          "z",
          "w"
        ],
        "properties": {
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          },
          "z": {
            "type": "number"
          },
          "w": {
            "type": "number"
          }
        },
        "description": "单位四元数 world_from_imu，具名 xyzw"
      },
      "Stamp": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sec",
          "nanosec"
        ],
        "properties": {
          "sec": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9223372036
          },
          "nanosec": {
            "type": "integer",
            "minimum": 0,
            "maximum": 999999999
          }
        },
        "description": "CLOCK_MONOTONIC_RAW，sec*1e9+nanosec<=9223372036854775807；不是UTC"
      },
      "Odometry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "header",
          "pose",
          "twist",
          "confidence",
          "trip_distance_m"
        ],
        "properties": {
          "header": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "seq",
              "stamp"
            ],
            "properties": {
              "seq": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "真实输出uint64，最大18446744073709551615，网络重连不重置"
              },
              "stamp": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Stamp"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "pose": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "position",
                  "orientation"
                ],
                "properties": {
                  "position": {
                    "$ref": "#/components/schemas/Vector3"
                  },
                  "orientation": {
                    "$ref": "#/components/schemas/Quaternion"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "twist": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "linear",
                  "angular"
                ],
                "properties": {
                  "linear": {
                    "$ref": "#/components/schemas/Vector3"
                  },
                  "angular": {
                    "$ref": "#/components/schemas/Vector3"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1,
            "description": "单一odometry置信度，现算法未实现，本版始终null"
          },
          "trip_distance_m": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "本次 VIO 进程内 IMU 原点的三维行进距离（米）。进程启动清零；无订阅者仍统计。失效、坐标重置或时间异常分段，不跨断点累加，保留总数。网页重连或清空轨迹不清零；不可用为 null。"
          }
        },
        "description": "固定IMU原点/传感器轴；position世界系m；twist同一IMU原点、IMU系m/s和rad/s，无协方差或轨迹段ID"
      },
      "VioAction": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "start",
              "stop",
              "restart"
            ]
          }
        }
      },
      "Accepted": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action",
          "accepted"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "start",
              "stop",
              "restart"
            ]
          },
          "accepted": {
            "const": true
          }
        },
        "description": "202仅代表接收执行请求，不代表操作执行成功/算法状态"
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string"
              }
            }
          }
        }
      },
      "Metadata": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "connection_id",
          "stream"
        ],
        "properties": {
          "type": {
            "const": "metadata"
          },
          "connection_id": {
            "type": "string"
          },
          "stream": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "source",
              "channels"
            ],
            "properties": {
              "source": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "const": "live"
                  }
                }
              },
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 1,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "name",
                    "format"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "enum": [
                        1,
                        2,
                        3
                      ]
                    },
                    "name": {
                      "type": "string",
                      "enum": [
                        "preview",
                        "odometry",
                        "imu"
                      ]
                    },
                    "format": {
                      "type": "integer",
                      "enum": [
                        1,
                        6
                      ]
                    }
                  },
                  "oneOf": [
                    {
                      "properties": {
                        "id": {
                          "const": 1
                        },
                        "name": {
                          "const": "preview"
                        },
                        "format": {
                          "const": 6
                        }
                      }
                    },
                    {
                      "properties": {
                        "id": {
                          "const": 2
                        },
                        "name": {
                          "const": "odometry"
                        },
                        "format": {
                          "const": 1
                        }
                      }
                    },
                    {
                      "properties": {
                        "id": {
                          "const": 3
                        },
                        "name": {
                          "const": "imu"
                        },
                        "format": {
                          "const": 1
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "Heartbeat": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "const": "heartbeat"
          }
        }
      },
      "ImuSample": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "header",
          "linear_acceleration",
          "angular_velocity"
        ],
        "properties": {
          "header": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "seq",
              "stamp"
            ],
            "properties": {
              "seq": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,19})$",
                "description": "驱动真实200Hz输出序号，0至18446744073709551615；不是RBH1传输序号。源重启结束旧HTTP连接。"
              },
              "stamp": {
                "$ref": "#/components/schemas/Stamp"
              }
            }
          },
          "linear_acceleration": {
            "$ref": "#/components/schemas/Vector3",
            "description": "固定IMU原点/传感器轴，m/s²，含重力响应，未减偏置"
          },
          "angular_velocity": {
            "$ref": "#/components/schemas/Vector3",
            "description": "固定IMU传感器轴，rad/s，未减偏置"
          }
        },
        "description": "每个RBH1消息只有一个样本，无samples数组/姿态/温度/置信度。时间为平均窗口采样时间，非发送时间。"
      },
      "ColorConfigRequest": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "quality"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "mjpeg"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "quality": {
                "type": "integer",
                "minimum": 1,
                "maximum": 99
              }
            }
          },
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "bitrate_kbps"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "h264"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "bitrate_kbps": {
                "type": "integer",
                "minimum": 64,
                "maximum": 20000
              }
            }
          },
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "bitrate_kbps"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "h265"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "bitrate_kbps": {
                "type": "integer",
                "minimum": 64,
                "maximum": 20000
              }
            }
          }
        ]
      },
      "ColorConfig": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "quality",
              "width",
              "height",
              "fps_max"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "mjpeg"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "quality": {
                "type": "integer",
                "minimum": 1,
                "maximum": 99
              },
              "width": {
                "const": 1080
              },
              "height": {
                "const": 1280
              },
              "fps_max": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              }
            }
          },
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "bitrate_kbps",
              "width",
              "height",
              "fps_max"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "h264"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "bitrate_kbps": {
                "type": "integer",
                "minimum": 64,
                "maximum": 20000
              },
              "width": {
                "const": 1080
              },
              "height": {
                "const": 1280
              },
              "fps_max": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              }
            }
          },
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "bitrate_kbps",
              "width",
              "height",
              "fps_max"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "h265"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "bitrate_kbps": {
                "type": "integer",
                "minimum": 64,
                "maximum": 20000
              },
              "width": {
                "const": 1080
              },
              "height": {
                "const": 1280
              },
              "fps_max": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              }
            }
          }
        ]
      },
      "ColorStreamConfig": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "quality",
              "width",
              "height"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "mjpeg"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "quality": {
                "type": "integer",
                "minimum": 1,
                "maximum": 99
              },
              "width": {
                "const": 1080
              },
              "height": {
                "const": 1280
              }
            }
          },
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "bitrate_kbps",
              "width",
              "height"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "h264"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "bitrate_kbps": {
                "type": "integer",
                "minimum": 64,
                "maximum": 20000
              },
              "width": {
                "const": 1080
              },
              "height": {
                "const": 1280
              }
            }
          },
          {
            "type": "object",
            "required": [
              "codec",
              "fps",
              "bitrate_kbps",
              "width",
              "height"
            ],
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "h265"
              },
              "fps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60
              },
              "bitrate_kbps": {
                "type": "integer",
                "minimum": 64,
                "maximum": 20000
              },
              "width": {
                "const": 1080
              },
              "height": {
                "const": 1280
              }
            }
          }
        ]
      },
      "ColorFrame": {
        "type": "object",
        "required": [
          "header",
          "pts_us",
          "random_access"
        ],
        "additionalProperties": false,
        "properties": {
          "header": {
            "type": "object",
            "required": [
              "seq",
              "stamp"
            ],
            "additionalProperties": false,
            "properties": {
              "seq": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,19})$",
                "description": "十进制uint64；最大18446744073709551615，接收端检查范围，不转JS Number。"
              },
              "stamp": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Stamp"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "pts_us": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,19})$",
                "description": "十进制uint64；最大18446744073709551615，接收端检查范围，不转JS Number。"
              },
              {
                "type": "null"
              }
            ],
            "description": "视频VENC呈现时间微秒，不等于曝光时间；MJPEG为null。"
          },
          "random_access": {
            "type": "boolean",
            "description": "JPEG为true；视频仅确认IDR且已交付有效参数集为true。CRA不作为本版恢复起点。"
          }
        }
      },
      "ColorMetadata": {
        "type": "object",
        "required": [
          "type",
          "connection_id",
          "stream",
          "config"
        ],
        "additionalProperties": false,
        "properties": {
          "type": {
            "const": "metadata"
          },
          "connection_id": {
            "const": "color"
          },
          "stream": {
            "type": "object",
            "required": [
              "source",
              "channels"
            ],
            "additionalProperties": false,
            "properties": {
              "source": {
                "type": "object",
                "required": [
                  "type"
                ],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "const": "live"
                  }
                }
              },
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 1,
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "format"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "const": 4
                    },
                    "name": {
                      "const": "color"
                    },
                    "format": {
                      "const": 7
                    }
                  }
                }
              }
            }
          },
          "config": {
            "$ref": "#/components/schemas/ColorStreamConfig"
          }
        }
      },
      "ColorJpegFrame": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ColorFrame"
          },
          {
            "properties": {
              "pts_us": {
                "type": "null"
              },
              "random_access": {
                "const": true
              }
            }
          }
        ]
      },
      "ColorVideoFrame": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ColorFrame"
          },
          {
            "properties": {
              "pts_us": {
                "type": "string"
              }
            }
          }
        ]
      },
      "RecordingCounts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "gray": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "十进制无符号整数；避免 JavaScript 精度损失"
          },
          "imu": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "十进制无符号整数；避免 JavaScript 精度损失"
          },
          "color": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "十进制无符号整数；避免 JavaScript 精度损失"
          },
          "odometry": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "十进制无符号整数；避免 JavaScript 精度损失"
          }
        },
        "required": [
          "gray",
          "imu",
          "color",
          "odometry"
        ]
      },
      "RecordingIdle": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "state": {
            "const": "idle"
          }
        },
        "required": [
          "state"
        ]
      },
      "RecordingActive": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "state": {
            "enum": [
              "starting",
              "recording",
              "saving"
            ]
          },
          "recording_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "channels": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "gray",
                "imu",
                "color",
                "odometry"
              ]
            }
          },
          "duration_s": {
            "type": "number",
            "minimum": 0
          },
          "bytes_written": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "十进制无符号整数；避免 JavaScript 精度损失"
          },
          "counts": {
            "$ref": "#/components/schemas/RecordingCounts"
          }
        },
        "required": [
          "state",
          "recording_id",
          "channels",
          "duration_s",
          "bytes_written",
          "counts"
        ]
      },
      "RecordingState": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/RecordingIdle"
          },
          {
            "$ref": "#/components/schemas/RecordingActive"
          }
        ]
      },
      "RecordingRequest": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "start"
              },
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 4,
                "uniqueItems": true,
                "items": {
                  "enum": [
                    "gray",
                    "imu",
                    "color",
                    "odometry"
                  ]
                }
              }
            },
            "required": [
              "action"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "stop"
              },
              "recording_id": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$"
              }
            },
            "required": [
              "action",
              "recording_id"
            ]
          }
        ]
      },
      "RecordingAccepted": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "action": {
            "enum": [
              "start",
              "stop"
            ]
          },
          "accepted": {
            "const": true
          },
          "recording_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          }
        },
        "required": [
          "action",
          "accepted",
          "recording_id"
        ]
      },
      "TfCard": {
        "type": "object",
        "description": "匹配系统镜像支持 FAT32/exFAT 自动检查与挂载；检查中或异常拒绝挂载时为 unmounted，容量为 null。不自动修复、格式化或恢复录制；没有安全弹出 HTTP 操作。",
        "additionalProperties": false,
        "properties": {
          "state": {
            "enum": [
              "ready",
              "missing",
              "unmounted",
              "read_only",
              "unavailable"
            ]
          },
          "total_bytes": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "十进制无符号整数；避免 JavaScript 精度损失"
              },
              {
                "type": "null"
              }
            ]
          },
          "available_bytes": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "十进制无符号整数；避免 JavaScript 精度损失"
              },
              {
                "type": "null"
              }
            ]
          },
          "read_bytes_per_sec": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "整张 TF 卡块设备完成的 I/O 字节增量 / 实际采样时间；512-byte sectors；约1秒平均。首采样、计数回退、不支持或失效时 null，不表示峰值带宽或掉电持久性。"
          },
          "write_bytes_per_sec": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "整张 TF 卡块设备完成的 I/O 字节增量 / 实际采样时间；512-byte sectors；约1秒平均。首采样、计数回退、不支持或失效时 null，不表示峰值带宽或掉电持久性。"
          }
        },
        "required": [
          "state",
          "total_bytes",
          "available_bytes",
          "read_bytes_per_sec",
          "write_bytes_per_sec"
        ]
      },
      "Monitor": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "tf_card": {
            "$ref": "#/components/schemas/TfCard"
          }
        },
        "required": [
          "tf_card"
        ]
      },
      "RecordingRecovery": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "policy": {
            "const": "contiguous_crc_prefix"
          },
          "damaged_tail": {
            "type": "boolean"
          },
          "source_files_preserved": {
            "const": true
          }
        },
        "required": [
          "policy",
          "damaged_tail",
          "source_files_preserved"
        ]
      },
      "RecordingResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "recording_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "state": {
            "enum": [
              "completed",
              "incomplete"
            ]
          },
          "complete": {
            "type": "boolean"
          },
          "end_reason": {
            "enum": [
              "user_stop",
              "empty_channel",
              "interrupted",
              "service_shutdown",
              "source_unavailable",
              "vio_unavailable",
              "resource_unavailable",
              "snapshot_failed",
              "source_failed",
              "source_timeout",
              "data_gap_or_source_error",
              "random_access_timeout",
              "write_failed",
              "storage_unavailable",
              "storage_full",
              "queue_overflow"
            ]
          },
          "duration_s": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "bytes_written": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "十进制无符号整数；避免 JavaScript 精度损失"
          },
          "counts": {
            "$ref": "#/components/schemas/RecordingCounts"
          },
          "recovery": {
            "$ref": "#/components/schemas/RecordingRecovery"
          }
        },
        "required": [
          "recording_id",
          "state",
          "complete",
          "end_reason",
          "duration_s",
          "bytes_written",
          "counts"
        ]
      },
      "RecordingConfig": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "format": {
            "const": "RBR1"
          },
          "version": {
            "const": 1
          },
          "recording_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "channels": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "gray",
                "imu",
                "color",
                "odometry"
              ]
            }
          },
          "clock": {
            "const": "monotonic_raw"
          },
          "calibration_file": {
            "const": "mono.conf"
          },
          "gray": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "codec": {
                "const": "jpeg"
              },
              "width": {
                "const": 544
              },
              "height": {
                "const": 640
              },
              "quality": {
                "const": 90
              }
            },
            "required": [
              "codec",
              "width",
              "height",
              "quality"
            ]
          },
          "imu": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "rate_hz": {
                "const": 200
              },
              "acceleration_unit": {
                "const": "m/s2"
              },
              "angular_velocity_unit": {
                "const": "rad/s"
              }
            },
            "required": [
              "rate_hz",
              "acceleration_unit",
              "angular_velocity_unit"
            ]
          },
          "color": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "codec": {
                    "enum": [
                      "h264",
                      "h265"
                    ]
                  },
                  "width": {
                    "const": 1080
                  },
                  "height": {
                    "const": 1280
                  },
                  "fps": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 60
                  },
                  "bitrate_kbps": {
                    "type": "integer"
                  }
                },
                "required": [
                  "codec",
                  "width",
                  "height",
                  "fps",
                  "bitrate_kbps"
                ]
              },
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "codec": {
                    "const": "mjpeg"
                  },
                  "width": {
                    "const": 1080
                  },
                  "height": {
                    "const": 1280
                  },
                  "fps": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 60
                  },
                  "quality": {
                    "type": "integer"
                  }
                },
                "required": [
                  "codec",
                  "width",
                  "height",
                  "fps",
                  "quality"
                ]
              }
            ]
          },
          "odometry": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "schema": {
                "const": "http"
              },
              "body": {
                "const": "imu"
              },
              "reference": {
                "const": "vio_world"
              }
            },
            "required": [
              "schema",
              "body",
              "reference"
            ]
          }
        },
        "required": [
          "format",
          "version",
          "recording_id",
          "channels",
          "clock",
          "calibration_file",
          "gray",
          "imu",
          "color",
          "odometry"
        ]
      },
      "DatasetSummary": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "channels": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "gray",
                "imu",
                "color",
                "odometry"
              ]
            }
          },
          "result": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecordingResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "current": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecordingActive"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "state": {
                    "const": "recovering"
                  }
                },
                "required": [
                  "state"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "channels",
          "result",
          "current"
        ]
      },
      "DatasetDetail": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "channels": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "gray",
                "imu",
                "color",
                "odometry"
              ]
            }
          },
          "result": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecordingResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "current": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecordingActive"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "state": {
                    "const": "recovering"
                  }
                },
                "required": [
                  "state"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "config": {
            "$ref": "#/components/schemas/RecordingConfig"
          }
        },
        "required": [
          "id",
          "channels",
          "result",
          "current",
          "config"
        ]
      },
      "DatasetPage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DatasetSummary"
            },
            "maxItems": 100
          },
          "next_offset": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          }
        },
        "required": [
          "datasets",
          "next_offset"
        ]
      },
      "CheckConfig": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "channels": {
            "type": "array",
            "items": {
              "enum": [
                "gray",
                "imu",
                "color",
                "odometry"
              ]
            },
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true
          },
          "vio_running": {
            "type": "boolean"
          },
          "gray": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "width": {
                    "const": 544
                  },
                  "height": {
                    "const": 640
                  },
                  "codec": {
                    "const": "jpeg"
                  },
                  "quality": {
                    "const": 90
                  },
                  "fps": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 60
                  }
                },
                "required": [
                  "width",
                  "height",
                  "codec",
                  "quality",
                  "fps"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "imu_rate_hz": {
            "enum": [
              200,
              null
            ]
          },
          "color": {
            "anyOf": [
              {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "codec": {
                        "const": "mjpeg"
                      },
                      "width": {
                        "const": 1080
                      },
                      "height": {
                        "const": 1280
                      },
                      "fps": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 60
                      },
                      "quality": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100
                      }
                    },
                    "required": [
                      "codec",
                      "width",
                      "height",
                      "fps",
                      "quality"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "codec": {
                        "enum": [
                          "h264",
                          "h265"
                        ]
                      },
                      "width": {
                        "const": 1080
                      },
                      "height": {
                        "const": 1280
                      },
                      "fps": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 60
                      },
                      "bitrate_kbps": {
                        "type": "integer",
                        "minimum": 64,
                        "maximum": 20000
                      }
                    },
                    "required": [
                      "codec",
                      "width",
                      "height",
                      "fps",
                      "bitrate_kbps"
                    ]
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "channels",
          "vio_running",
          "gray",
          "imu_rate_hz",
          "color"
        ]
      },
      "CheckMetrics": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "queue_peak_bytes": {
            "type": "integer",
            "minimum": 0
          },
          "queue_end_bytes": {
            "type": "integer",
            "minimum": 0
          },
          "queue_capacity_bytes": {
            "type": "integer",
            "minimum": 0
          },
          "write_max_ms": {
            "type": "integer",
            "minimum": 0
          },
          "flush_max_ms": {
            "type": "integer",
            "minimum": 0
          },
          "sync_max_ms": {
            "type": "integer",
            "minimum": 0
          },
          "drain_ms": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "queue_peak_bytes",
          "queue_end_bytes",
          "queue_capacity_bytes",
          "write_max_ms",
          "flush_max_ms",
          "sync_max_ms",
          "drain_ms"
        ]
      },
      "CheckResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "check_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "state": {
            "enum": [
              "passed",
              "risk",
              "failed",
              "incomplete"
            ]
          },
          "reason": {
            "type": "string"
          },
          "duration_s": {
            "type": "number",
            "minimum": 0
          },
          "bytes_written": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "counts": {
            "$ref": "#/components/schemas/RecordingCounts"
          },
          "rates_hz": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "gray": {
                "type": "number",
                "minimum": 0
              },
              "imu": {
                "type": "number",
                "minimum": 0
              },
              "color": {
                "type": "number",
                "minimum": 0
              },
              "odometry": {
                "type": "number",
                "minimum": 0
              }
            },
            "required": [
              "gray",
              "imu",
              "color",
              "odometry"
            ]
          },
          "metrics": {
            "$ref": "#/components/schemas/CheckMetrics"
          }
        },
        "required": [
          "check_id",
          "state",
          "reason",
          "duration_s",
          "bytes_written",
          "counts",
          "rates_hz",
          "metrics"
        ]
      },
      "CheckStatus": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "state": {
            "enum": [
              "untested",
              "testing",
              "saving",
              "passed",
              "risk",
              "failed",
              "incomplete"
            ]
          },
          "configuration": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CheckConfig"
              },
              {
                "type": "null"
              }
            ]
          },
          "active": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "check_id": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{32}$"
                  },
                  "state": {
                    "enum": [
                      "testing",
                      "saving"
                    ]
                  },
                  "configuration": {
                    "$ref": "#/components/schemas/CheckConfig"
                  },
                  "elapsed_s": {
                    "type": "number",
                    "minimum": 0
                  },
                  "target_duration_s": {
                    "const": 30
                  }
                },
                "required": [
                  "check_id",
                  "state",
                  "configuration",
                  "elapsed_s",
                  "target_duration_s"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CheckResult"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "state",
          "configuration",
          "active",
          "result"
        ]
      },
      "CheckRequest": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "start"
              },
              "channels": {
                "type": "array",
                "items": {
                  "enum": [
                    "gray",
                    "imu",
                    "color",
                    "odometry"
                  ]
                },
                "minItems": 1,
                "maxItems": 4,
                "uniqueItems": true
              }
            },
            "required": [
              "action"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "stop"
              },
              "check_id": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$"
              }
            },
            "required": [
              "action",
              "check_id"
            ]
          }
        ]
      },
      "CheckAccepted": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "action": {
            "enum": [
              "start",
              "stop"
            ]
          },
          "accepted": {
            "const": true
          },
          "check_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          }
        },
        "required": [
          "action",
          "accepted",
          "check_id"
        ]
      },
      "MountConfigWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "robot_type",
          "convention",
          "camera_in_robot"
        ],
        "properties": {
          "robot_type": {
            "type": "string",
            "enum": [
              "drone",
              "car",
              "custom"
            ]
          },
          "convention": {
            "type": "string",
            "enum": [
              "FRD",
              "FLU"
            ],
            "description": "必须明确提交；不按robot_type隐式转换。"
          },
          "camera_in_robot": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "position",
              "orientation"
            ],
            "properties": {
              "position": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "x",
                  "y",
                  "z"
                ],
                "properties": {
                  "x": {
                    "type": "number",
                    "minimum": -10,
                    "maximum": 10
                  },
                  "y": {
                    "type": "number",
                    "minimum": -10,
                    "maximum": 10
                  },
                  "z": {
                    "type": "number",
                    "minimum": -10,
                    "maximum": 10
                  }
                },
                "description": "相机光心在所选平台坐标系的位置，单位米；不是IMU安装偏移。"
              },
              "orientation": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "x",
                  "y",
                  "z",
                  "w"
                ],
                "properties": {
                  "x": {
                    "type": "number"
                  },
                  "y": {
                    "type": "number"
                  },
                  "z": {
                    "type": "number"
                  },
                  "w": {
                    "type": "number"
                  }
                },
                "description": "camera→robot旋转；具名xyzw。所有分量有限，范数平方与1之差≤1e-5，服务端归一化。"
              }
            }
          }
        }
      },
      "MountConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "robot_type",
          "convention",
          "camera_in_robot",
          "configured"
        ],
        "properties": {
          "robot_type": {
            "type": "string",
            "enum": [
              "drone",
              "car",
              "custom"
            ]
          },
          "convention": {
            "type": "string",
            "enum": [
              "FRD",
              "FLU"
            ],
            "description": "必须明确提交；不按robot_type隐式转换。"
          },
          "camera_in_robot": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "position",
              "orientation"
            ],
            "properties": {
              "position": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "x",
                  "y",
                  "z"
                ],
                "properties": {
                  "x": {
                    "type": "number",
                    "minimum": -10,
                    "maximum": 10
                  },
                  "y": {
                    "type": "number",
                    "minimum": -10,
                    "maximum": 10
                  },
                  "z": {
                    "type": "number",
                    "minimum": -10,
                    "maximum": 10
                  }
                },
                "description": "相机光心在所选平台坐标系的位置，单位米；不是IMU安装偏移。"
              },
              "orientation": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "x",
                  "y",
                  "z",
                  "w"
                ],
                "properties": {
                  "x": {
                    "type": "number"
                  },
                  "y": {
                    "type": "number"
                  },
                  "z": {
                    "type": "number"
                  },
                  "w": {
                    "type": "number"
                  }
                },
                "description": "camera→robot旋转；具名xyzw。所有分量有限，范数平方与1之差≤1e-5，服务端归一化。"
              }
            }
          },
          "configured": {
            "type": "boolean",
            "description": "true表示读取到已保存配置（包括兼容旧文件），false表示默认安装。不是补偿启用开关，也不表示当前运行的VIO已经加载该配置。"
          }
        }
      },
      "CalibrationParameters": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "camera",
          "T_cam_imu",
          "camera_imu_time_offset_s",
          "imu"
        ],
        "properties": {
          "camera": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "model",
              "width",
              "height",
              "intrinsics"
            ],
            "properties": {
              "model": {
                "type": "string",
                "const": "ds"
              },
              "width": {
                "type": "integer",
                "const": 544
              },
              "height": {
                "type": "integer",
                "const": 640
              },
              "intrinsics": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "fx",
                  "fy",
                  "cx",
                  "cy",
                  "xi",
                  "alpha"
                ],
                "properties": {
                  "fx": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "fy": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "cx": {
                    "type": "number"
                  },
                  "cy": {
                    "type": "number"
                  },
                  "xi": {
                    "type": "number"
                  },
                  "alpha": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "exclusiveMaximum": 1
                  }
                }
              }
            }
          },
          "T_cam_imu": {
            "type": "array",
            "minItems": 4,
            "maxItems": 4,
            "items": {
              "type": "array",
              "minItems": 4,
              "maxItems": 4,
              "items": {
                "type": "number"
              }
            },
            "description": "Row-major 4x4: p_camera=R*p_imu+t; t in metres. Last row [0,0,0,1], proper orthonormal rotation (tolerance 1e-5). Inverse translation components bounded by 10 m."
          },
          "camera_imu_time_offset_s": {
            "type": "number",
            "minimum": -0.1,
            "maximum": 0.1,
            "description": "t_imu=t_camera+offset; seconds. Does not change raw sample timestamps."
          },
          "imu": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "sample_rate_hz",
              "gyroscope_noise_density",
              "gyroscope_random_walk",
              "accelerometer_noise_density",
              "accelerometer_random_walk"
            ],
            "properties": {
              "sample_rate_hz": {
                "type": "integer",
                "const": 200,
                "description": "Fixed profile of averaged IMU output, not a hardware sampling control."
              },
              "gyroscope_noise_density": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(rad/s)/sqrt(Hz)"
              },
              "gyroscope_random_walk": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(rad/s)/sqrt(s), bias random walk"
              },
              "accelerometer_noise_density": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(m/s^2)/sqrt(Hz)"
              },
              "accelerometer_random_walk": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(m/s^2)/sqrt(s), bias random walk"
              }
            }
          }
        }
      },
      "ButtonsConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "short_action",
          "long_action",
          "long_press_ms",
          "recording_channels"
        ],
        "properties": {
          "short_action": {
            "type": "string",
            "enum": [
              "none",
              "vio_toggle",
              "vio_restart",
              "record_toggle"
            ]
          },
          "long_action": {
            "type": "string",
            "enum": [
              "none",
              "vio_toggle",
              "vio_restart",
              "record_toggle"
            ]
          },
          "long_press_ms": {
            "type": "integer",
            "enum": [
              1000,
              2000,
              3000,
              5000
            ]
          },
          "recording_channels": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "gray",
                "imu",
                "color",
                "odometry"
              ]
            }
          }
        }
      },
      "GrayStreamConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "encoding",
          "pixel_format",
          "width",
          "height",
          "stride",
          "fps"
        ],
        "properties": {
          "encoding": {
            "const": "raw"
          },
          "pixel_format": {
            "const": "mono8"
          },
          "width": {
            "const": 544
          },
          "height": {
            "const": 640
          },
          "stride": {
            "const": 544
          },
          "fps": {
            "const": 5
          }
        }
      },
      "GrayFrame": {
        "type": "object",
        "required": [
          "header"
        ],
        "additionalProperties": false,
        "properties": {
          "header": {
            "type": "object",
            "required": [
              "seq",
              "stamp"
            ],
            "additionalProperties": false,
            "properties": {
              "seq": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "十进制uint64；最大18446744073709551615，接收端检查范围，不转JS Number。"
              },
              "stamp": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Stamp"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        }
      },
      "GrayMetadata": {
        "type": "object",
        "required": [
          "type",
          "connection_id",
          "stream",
          "config"
        ],
        "additionalProperties": false,
        "properties": {
          "type": {
            "const": "metadata"
          },
          "connection_id": {
            "const": "gray"
          },
          "stream": {
            "type": "object",
            "required": [
              "source",
              "channels"
            ],
            "additionalProperties": false,
            "properties": {
              "source": {
                "type": "object",
                "required": [
                  "type"
                ],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "const": "live"
                  }
                }
              },
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 1,
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "format"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "const": 5
                    },
                    "name": {
                      "const": "gray"
                    },
                    "format": {
                      "const": 8
                    }
                  }
                }
              }
            }
          },
          "config": {
            "$ref": "#/components/schemas/GrayStreamConfig"
          }
        }
      },
      "GrayJpegConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "encoding",
          "pixel_format",
          "width",
          "height",
          "quality",
          "frame_rate_mode"
        ],
        "properties": {
          "encoding": {
            "type": "string",
            "const": "jpeg"
          },
          "pixel_format": {
            "type": "string",
            "const": "mono8"
          },
          "width": {
            "type": "integer",
            "const": 544
          },
          "height": {
            "type": "integer",
            "const": 640
          },
          "quality": {
            "type": "integer",
            "const": 90
          },
          "frame_rate_mode": {
            "type": "string",
            "const": "source"
          }
        }
      },
      "GrayJpegMetadata": {
        "type": "object",
        "required": [
          "type",
          "connection_id",
          "stream",
          "config"
        ],
        "additionalProperties": false,
        "properties": {
          "type": {
            "const": "metadata"
          },
          "connection_id": {
            "const": "gray_jpeg"
          },
          "stream": {
            "type": "object",
            "required": [
              "source",
              "channels"
            ],
            "additionalProperties": false,
            "properties": {
              "source": {
                "type": "object",
                "required": [
                  "type"
                ],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "const": "live"
                  }
                }
              },
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 1,
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "format"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "const": 6
                    },
                    "name": {
                      "const": "gray_jpeg"
                    },
                    "format": {
                      "const": 7
                    }
                  }
                }
              }
            }
          },
          "config": {
            "$ref": "#/components/schemas/GrayJpegConfig"
          }
        }
      },
      "MavlinkAccepted": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "accepted": {
            "const": true
          },
          "operation_id": {
            "type": "string"
          }
        },
        "required": [
          "accepted",
          "operation_id"
        ]
      },
      "SerialStatus": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "mode": {
            "const": "mavlink"
          },
          "baudrate": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Currently accepted requested UART bit/s, not a physical line-rate measurement. null when serial open failed."
          }
        },
        "required": [
          "mode",
          "baudrate"
        ]
      },
      "MavlinkError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              }
            },
            "required": [
              "code"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "MavlinkParameter": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": [
              "number",
              "null"
            ]
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "uint8",
              "int8",
              "uint16",
              "int16",
              "uint32",
              "int32",
              "uint64",
              "int64",
              "float32",
              "float64"
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "value",
          "type"
        ]
      },
      "MavlinkParameters": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "parameters": {
            "type": "object",
            "maxProperties": 32,
            "additionalProperties": {
              "$ref": "#/components/schemas/MavlinkParameter"
            }
          }
        },
        "required": [
          "parameters"
        ]
      },
      "MavlinkWriteRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "parameters": {
            "type": "object",
            "minProperties": 1,
            "maxProperties": 32,
            "propertyNames": {
              "pattern": "^[A-Za-z0-9_]{1,16}$"
            },
            "additionalProperties": {
              "type": "number"
            }
          }
        },
        "required": [
          "parameters"
        ]
      },
      "MavlinkParameterResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requested": {
            "type": "number"
          },
          "actual": {
            "type": [
              "number",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requested",
          "actual",
          "error"
        ]
      },
      "MavlinkWriteResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "parameters": {
            "type": "object",
            "maxProperties": 32,
            "additionalProperties": {
              "$ref": "#/components/schemas/MavlinkParameterResult"
            }
          }
        },
        "required": [
          "parameters"
        ]
      },
      "MavlinkRebootResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "command_ack": {
            "enum": [
              "accepted",
              "in_progress",
              "rejected",
              "not_received"
            ]
          },
          "reboot_confirmed": {
            "type": "boolean"
          },
          "reconnected": {
            "type": "boolean"
          }
        },
        "required": [
          "command_ack",
          "reboot_confirmed",
          "reconnected"
        ]
      },
      "MavlinkScanResult": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "baudrate": {
                "type": "integer"
              },
              "system_id": {
                "type": "integer"
              },
              "flight_controller": {
                "enum": [
                  "ardupilot",
                  "px4"
                ]
              }
            },
            "required": [
              "baudrate",
              "system_id",
              "flight_controller"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "recovery": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "restored": {
                    "type": "boolean"
                  },
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "baudrate": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Prior configured rate being restored; only restored=true confirms restoration."
                  }
                },
                "required": [
                  "restored",
                  "error",
                  "baudrate"
                ]
              },
              "detected_flight_controller": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  null,
                  "ardupilot",
                  "px4"
                ]
              }
            },
            "required": [
              "recovery",
              "detected_flight_controller"
            ]
          }
        ]
      },
      "MavlinkSystemResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "previous_system_id": {
            "type": "integer"
          },
          "requested_system_id": {
            "type": "integer"
          },
          "actual_system_id": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "previous_system_id",
          "requested_system_id",
          "actual_system_id"
        ]
      },
      "MavlinkComponentResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "previous_component_id": {
            "type": "integer"
          },
          "requested_component_id": {
            "type": "integer"
          },
          "actual_component_id": {
            "type": "integer"
          }
        },
        "required": [
          "previous_component_id",
          "requested_component_id",
          "actual_component_id"
        ]
      },
      "MavlinkLinkResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requested_baudrate": {
            "type": "integer"
          },
          "actual_baudrate": {
            "type": "integer"
          },
          "reboot_confirmed": {
            "type": "boolean"
          }
        },
        "required": [
          "requested_baudrate",
          "actual_baudrate",
          "reboot_confirmed"
        ]
      },
      "MavlinkOperation": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "operation_id": {
            "type": "string"
          },
          "action": {
            "enum": [
              "scan",
              "configure_link",
              "set_system_id",
              "set_component_id",
              "reboot_flight_controller",
              "set_parameters"
            ]
          },
          "state": {
            "enum": [
              "running",
              "waiting_reboot",
              "succeeded",
              "failed",
              "cancelled"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "result": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MavlinkWriteResult"
              },
              {
                "$ref": "#/components/schemas/MavlinkRebootResult"
              },
              {
                "$ref": "#/components/schemas/MavlinkScanResult"
              },
              {
                "$ref": "#/components/schemas/MavlinkSystemResult"
              },
              {
                "$ref": "#/components/schemas/MavlinkComponentResult"
              },
              {
                "$ref": "#/components/schemas/MavlinkLinkResult"
              }
            ]
          }
        },
        "required": [
          "operation_id",
          "action",
          "state",
          "error",
          "result"
        ]
      },
      "MavlinkStatus": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "connected": {
            "type": "boolean"
          },
          "flight_controller": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "ardupilot",
              "px4"
            ]
          },
          "system_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "flight_controller_component_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "neo_component_id": {
            "type": "integer",
            "minimum": 2,
            "maximum": 255
          },
          "firmware_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "flight_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "armed": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "active_operation_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "operation": {
            "$ref": "#/components/schemas/MavlinkOperation"
          }
        },
        "required": [
          "connected",
          "flight_controller",
          "system_id",
          "flight_controller_component_id",
          "neo_component_id",
          "firmware_version",
          "flight_mode",
          "armed",
          "active_operation_id"
        ]
      },
      "MavlinkAction": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "scan"
              },
              "target_system_id": {
                "type": "integer",
                "minimum": 1,
                "maximum": 255
              },
              "baudrate": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2147483647,
                "description": "Requested integer bit/s; actual hardware range depends on UART clock/divider. Out-of-range attempts fail asynchronously with baudrate_unsupported."
              },
              "expected_flight_controller": {
                "enum": [
                  "ardupilot",
                  "px4"
                ],
                "description": "Optional heartbeat type expectation for a fixed-baud attempt; requires baudrate."
              }
            },
            "required": [
              "action"
            ],
            "dependentRequired": {
              "expected_flight_controller": [
                "baudrate"
              ]
            },
            "description": "No baudrate: finite common-rate scan, up to 60 seconds. baudrate: one rate, up to 10 seconds for heartbeats; failure/cancellation restores prior settings within 5 additional seconds. Does not write FC parameters."
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "cancel_scan"
              },
              "operation_id": {
                "type": "string"
              }
            },
            "required": [
              "action",
              "operation_id"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "configure_link"
              },
              "port": {
                "type": "string",
                "pattern": "^(SERIAL[0-9]|TELEM[1-3])$"
              },
              "baudrate": {
                "type": "integer"
              },
              "protocol": {
                "const": "mavlink2"
              }
            },
            "required": [
              "action",
              "port",
              "baudrate",
              "protocol"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "set_system_id"
              },
              "system_id": {
                "type": "integer",
                "minimum": 1,
                "maximum": 255
              }
            },
            "required": [
              "action",
              "system_id"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "set_component_id"
              },
              "component_id": {
                "type": "integer",
                "minimum": 2,
                "maximum": 255
              }
            },
            "required": [
              "action",
              "component_id"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "const": "reboot_flight_controller"
              },
              "continue_operation_id": {
                "type": "string"
              }
            },
            "required": [
              "action"
            ]
          }
        ]
      },
      "VioStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "state",
          "tracking",
          "error",
          "warning"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "stopped",
              "starting",
              "running",
              "stopping",
              "restarting"
            ]
          },
          "tracking": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "initializing",
              "valid",
              "invalid"
            ],
            "description": "仅运行中且收到两秒内新鲜本机定位状态时可用；否则null。不是由浏览器订阅推断。"
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              }
            ],
            "description": "命令执行失败或观测到进程异常退出。下一条新受理命令清除；重复key不清除。"
          },
          "warning": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "const": "CALIBRATION_REQUIRED",
                    "type": "string"
                  }
                }
              }
            ],
            "description": "运行实例使用默认参数时的独立警告，不是错误。取自该实例的参数快照；停止或尚未收到实例元数据时为null，null本身不证明已标定。"
          }
        },
        "examples": [
          {
            "state": "stopped",
            "tracking": null,
            "error": null,
            "warning": null
          },
          {
            "state": "running",
            "tracking": "valid",
            "error": null,
            "warning": null
          },
          {
            "state": "running",
            "tracking": "initializing",
            "error": null,
            "warning": {
              "code": "CALIBRATION_REQUIRED"
            }
          }
        ]
      },
      "UpdateBuild": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "build_id"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "build_id": {
            "type": "string"
          }
        }
      },
      "UpdatePackageMetadata": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "product",
          "hardware",
          "version",
          "build_id",
          "notes"
        ],
        "properties": {
          "product": {
            "const": "RoboBaton-Neo"
          },
          "hardware": {
            "const": "robobaton-neo-board1"
          },
          "version": {
            "type": "string",
            "maxLength": 80
          },
          "build_id": {
            "type": "string",
            "maxLength": 96
          },
          "notes": {
            "type": "string",
            "maxLength": 2000
          }
        },
        "description": "只读更新包信息。本公开说明仅列出客户端展示字段；设备可能返回额外内部字段，客户端应忽略，不用于构造更新包。"
      },
      "UpdatePackage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "package_id",
          "metadata"
        ],
        "properties": {
          "package_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "metadata": {
            "$ref": "#/components/schemas/UpdatePackageMetadata"
          }
        }
      },
      "UpdateOperation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation_id",
          "state",
          "package_id",
          "error"
        ],
        "properties": {
          "operation_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "state": {
            "type": "string",
            "enum": [
              "accepted",
              "installing",
              "reboot_required",
              "rebooting",
              "succeeded",
              "failed",
              "recovery_required"
            ]
          },
          "package_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "error": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "UpdateStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "running",
          "gateway_running",
          "installed",
          "package",
          "operation",
          "maintenance",
          "upload",
          "limits",
          "available"
        ],
        "properties": {
          "running": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UpdateBuild"
              },
              {
                "type": "null"
              }
            ]
          },
          "gateway_running": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UpdateBuild"
              },
              {
                "type": "null"
              }
            ]
          },
          "installed": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UpdatePackage"
              },
              {
                "type": "null"
              }
            ]
          },
          "package": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UpdatePackage"
              },
              {
                "type": "null"
              }
            ]
          },
          "operation": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UpdateOperation"
              },
              {
                "type": "null"
              }
            ]
          },
          "maintenance": {
            "type": "boolean"
          },
          "upload": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "received_bytes",
                  "total_bytes"
                ],
                "properties": {
                  "received_bytes": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 536870912
                  },
                  "total_bytes": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 536870912
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "limits": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "max_package_bytes",
              "free_bytes",
              "reserve_bytes",
              "package_format"
            ],
            "properties": {
              "max_package_bytes": {
                "type": "integer",
                "minimum": 0,
                "maximum": 536870912
              },
              "free_bytes": {
                "type": "integer",
                "minimum": 0
              },
              "reserve_bytes": {
                "type": "integer",
                "minimum": 0,
                "maximum": 536870912
              },
              "package_format": {
                "const": 2
              }
            }
          },
          "available": {
            "type": "boolean"
          }
        }
      },
      "UpdateCommand": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action",
          "package_id"
        ],
        "properties": {
          "action": {
            "const": "install"
          },
          "package_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        }
      },
      "UpdateAccepted": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation_id",
          "state"
        ],
        "properties": {
          "operation_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "state": {
            "const": "accepted"
          }
        }
      },
      "BootConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "vio_autostart"
        ],
        "properties": {
          "vio_autostart": {
            "type": "boolean",
            "description": "默认 false。保存后下次系统启动生效；不改变当前 VIO，不在服务重启、手动停止或异常退出后重复自动启动。"
          }
        }
      },
      "DepthConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "encoding",
          "width",
          "height",
          "fps",
          "dtype",
          "byte_order",
          "layout",
          "value_type",
          "unit",
          "polarity",
          "pixel_mapping",
          "config_id",
          "source_size",
          "crop"
        ],
        "properties": {
          "encoding": {
            "const": "raw"
          },
          "width": {
            "const": 384
          },
          "height": {
            "const": 384
          },
          "fps": {
            "const": 5
          },
          "dtype": {
            "const": "float32"
          },
          "byte_order": {
            "const": "little"
          },
          "layout": {
            "const": "row_major"
          },
          "value_type": {
            "const": "relative"
          },
          "unit": {
            "const": null
          },
          "polarity": {
            "const": "unverified"
          },
          "pixel_mapping": {
            "const": "half_pixel"
          },
          "config_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{16}$"
          },
          "source_size": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "width",
              "height"
            ],
            "properties": {
              "width": {
                "const": 544
              },
              "height": {
                "const": 640
              }
            }
          },
          "crop": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "x",
              "y",
              "width",
              "height"
            ],
            "properties": {
              "x": {
                "type": "integer",
                "minimum": 0,
                "maximum": 640
              },
              "y": {
                "type": "integer",
                "minimum": 0,
                "maximum": 640
              },
              "width": {
                "type": "integer",
                "minimum": 0,
                "maximum": 640
              },
              "height": {
                "type": "integer",
                "minimum": 0,
                "maximum": 640
              }
            }
          }
        },
        "description": "固定384相对深度；crop正方形边长384..544且4对齐，居中于544x640；fps为上限，极性未验证、非米制。"
      },
      "DepthMetadata": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "connection_id",
          "stream",
          "source_epoch",
          "stream_epoch",
          "config"
        ],
        "properties": {
          "type": {
            "const": "metadata"
          },
          "connection_id": {
            "const": "depth"
          },
          "stream": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "source",
              "channels"
            ],
            "properties": {
              "source": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "const": "live"
                  }
                }
              },
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 1,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "name",
                    "format"
                  ],
                  "properties": {
                    "id": {
                      "const": 7
                    },
                    "name": {
                      "const": "depth"
                    },
                    "format": {
                      "const": 9
                    }
                  }
                }
              }
            }
          },
          "source_epoch": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "uint64十进制字符串，最大18446744073709551615"
          },
          "stream_epoch": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "uint64十进制字符串，最大18446744073709551615"
          },
          "config": {
            "$ref": "#/components/schemas/DepthConfig"
          }
        }
      },
      "DepthFrame": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "header",
          "pts_us"
        ],
        "properties": {
          "header": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "seq",
              "stamp"
            ],
            "properties": {
              "seq": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,9}$",
                "description": "深度输出uint32序号，最大4294967295，允许跳号"
              },
              "stamp": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "sec",
                      "nanosec"
                    ],
                    "properties": {
                      "sec": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9223372036
                      },
                      "nanosec": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 999999999
                      }
                    }
                  }
                ],
                "description": "CLOCK_MONOTONIC_RAW曝光中点；组合纳秒不超过INT64_MAX，未同步null"
              }
            }
          },
          "pts_us": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "uint64十进制字符串，最大18446744073709551615"
          }
        }
      },
      "EffectiveCalibrationParameters": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "camera",
          "T_cam_imu",
          "camera_imu_time_offset_s",
          "imu",
          "source"
        ],
        "properties": {
          "camera": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "model",
              "width",
              "height",
              "intrinsics"
            ],
            "properties": {
              "model": {
                "type": "string",
                "const": "ds"
              },
              "width": {
                "type": "integer",
                "const": 544
              },
              "height": {
                "type": "integer",
                "const": 640
              },
              "intrinsics": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "fx",
                  "fy",
                  "cx",
                  "cy",
                  "xi",
                  "alpha"
                ],
                "properties": {
                  "fx": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "fy": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "cx": {
                    "type": "number"
                  },
                  "cy": {
                    "type": "number"
                  },
                  "xi": {
                    "type": "number"
                  },
                  "alpha": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "exclusiveMaximum": 1
                  }
                }
              }
            }
          },
          "T_cam_imu": {
            "type": "array",
            "minItems": 4,
            "maxItems": 4,
            "items": {
              "type": "array",
              "minItems": 4,
              "maxItems": 4,
              "items": {
                "type": "number"
              }
            },
            "description": "Row-major 4x4: p_camera=R*p_imu+t; t in metres. Last row [0,0,0,1], proper orthonormal rotation (tolerance 1e-5). Inverse translation components bounded by 10 m."
          },
          "camera_imu_time_offset_s": {
            "type": "number",
            "minimum": -0.1,
            "maximum": 0.1,
            "description": "t_imu=t_camera+offset; seconds. Does not change raw sample timestamps."
          },
          "imu": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "sample_rate_hz",
              "gyroscope_noise_density",
              "gyroscope_random_walk",
              "accelerometer_noise_density",
              "accelerometer_random_walk"
            ],
            "properties": {
              "sample_rate_hz": {
                "type": "integer",
                "const": 200,
                "description": "Fixed profile of averaged IMU output, not a hardware sampling control."
              },
              "gyroscope_noise_density": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(rad/s)/sqrt(Hz)"
              },
              "gyroscope_random_walk": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(rad/s)/sqrt(s), bias random walk"
              },
              "accelerometer_noise_density": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(m/s^2)/sqrt(Hz)"
              },
              "accelerometer_random_walk": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "(m/s^2)/sqrt(s), bias random walk"
              }
            }
          },
          "source": {
            "type": "string",
            "enum": [
              "default",
              "saved"
            ],
            "readOnly": true,
            "description": "default 为代码固化默认值，尚未完成设备标定；saved 为已保存的合法 mono.conf。默认值不自动写入文件。"
          }
        }
      },
      "SystemRebootCommand": {
        "type": "object",
        "additionalProperties": false,
        "required": [],
        "properties": {}
      },
      "SystemRebootAccepted": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "state",
          "boot_id"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "state": {
            "const": "accepted"
          },
          "boot_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          }
        }
      },
      "SystemRebootOperation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "boot_id",
          "state",
          "update_operation_id",
          "error"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$"
          },
          "boot_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "state": {
            "type": "string",
            "enum": [
              "accepted",
              "rebooting",
              "succeeded",
              "failed"
            ]
          },
          "update_operation_id": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "enum": [
                      "REBOOT_FAILED",
                      "REBOOT_INTERRUPTED",
                      "REBOOT_STORAGE_FAILED"
                    ]
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "SystemStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "boot_id",
          "available",
          "reboot"
        ],
        "properties": {
          "boot_id": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "available": {
            "type": "boolean",
            "description": "重启模块及存储可用，不等于当前业务空闲。"
          },
          "reboot": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SystemRebootOperation"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "NetworkConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "subnet"
        ],
        "properties": {
          "subnet": {
            "type": "integer",
            "minimum": 11,
            "maximum": 255,
            "description": "192.168.subnet.1/24; default 11"
          }
        }
      }
    }
  },
  "x-device-service-errors": {
    "DEVICE_UNAVAILABLE": "503: 请求未发送到设备服务，可稍后重试",
    "DEVICE_REQUEST_UNCONFIRMED": "503: 请求已发送，结果未确认；先GET核对状态，重试需复用原Idempotency-Key，禁止盲目换key重发",
    "DEVICE_PROTOCOL_MISMATCH": "503: 本机协议或响应格式不兼容，需安装配套程序"
  }
}
