Skip to main content

接口目标

将设备的操作与数据统一封装为标准接口,使上层系统(FSP 模块或其适配器)能够稳定、便捷地控制设备并获取结果、状态或诊断。
设备底层可以使用 HTTP、RPC、SDK 或设备协议实现;本页不规定内部 URL、驱动或通信帧格式。

技能接口的三个维度

对象描述“操作谁”,控制描述“做什么”,系统描述“现在能不能做”。三个维度共同说明同一项设备技能,设备可以在一个既有接口中同时提供这些事实。

被动调用要求

设备或其适配器必须能够接收 FSP 模块已经确定的目标对象、技能参数与任务控制请求。
设备返回的状态、结果和诊断必须来自实际执行或可确认的当前状态;设备不能把预期状态、缓存猜测或自然语言推断当作事实结果。FSP 对外方法、设备发现、技能披露、统一标识和版本语义见设备发现

内容要求

对象信息

对象事实必须能说明容器类型、形状、长宽高或直径、材质、标称容积、允许工作容积以及适用时的孔数和孔径;同时返回设备能够读取或改变的状态及允许值。完整目录和字段定义见对象 例如,container_status: ["有盖", "无盖"] 表示设备能区分这两种容器状态,也为操作的前置条件提供可验证的依据。

控制信息

每个技能接口必须有明确名称、请求分类、执行方式、参数、前置状态、状态变化、返回值和诊断。参数必须给出名称、类型、是否必填、用途,以及适用时的范围、单位、枚举值或跨字段约束。 例如,container_count 的类型为 int、范围为 1..10container_idsmax(container_ids) <= container_count 约束;设备或适配器必须据此拒绝不符合已声明范围或跨字段约束的控制请求。

系统信息

系统事实必须说明该技能所需的设备状态、安全围栏和结果验证规则。设备或适配器在执行前检查安全围栏,例如“设备必须处于空闲状态”“容器必须无盖”或“参数不得超过物理上限”。任何上层说明都不能覆盖安全围栏。

加液接口示例

以下非规范性示例以 HTTP 表示设备的被动加液接口。接口路径只是示例;设备可以使用 RPC、SDK 或其他底层协议实现相同语义。
设备接收成功后返回任务标识,不将计划状态当作执行结果:
任务完成后,设备返回实际加液结果、对象状态和诊断;若校验或执行失败,则返回失败原因,并保持未确认的对象状态不变。

设备侧最低要求

设备侧服务或映射层必须:
  1. 为每项设备技能提供或可映射对象、控制和系统三个维度的事实;
  2. 被动响应 FSP 下发的读取、写入、调用与异步任务控制;
  3. 按请求分类执行不同安全约束,尤其在物理动作前强制检查对象状态、参数约束和安全围栏;
  4. 同步返回实际状态变化或异步任务标识;
  5. 对写入和物理动作返回可验证结果,对任务查询、完成、失败和取消返回实际进度或结构化诊断。
设备不需要原生实现发现、能力获取、统一身份或版本接口;FSP 模块负责这些对外协议职责,并将设备纳入设备能力流程。