SunYF/bj_power
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
665ff257dc6d621ac580b75e3ddb2cb40aec75f1
bj_power/AGV海康.md
T
SunYF c85c3bd6f1 docs: update project docs and add new reference documents 
1. 修正项目说明文档中关于项目D、E的技术栈与部署描述
2. 新增完整的需求规格与开发规划文档
3. 新增海康RCS-2000 V4.2接口协议文档
2026-08-27 15:46:15 +08:00

20 KiB
Raw Blame History

海康机器人 RCS‑2000 V4.2 接口协议（对外发布）

文档类别：厂内物流机器人控制系统 文档编号：RCS‑2000 V4.2 版权所有 ©杭州海康机器人股份有限公司

版权声明

本文档由海康机器人公司开发，其版权受中华人民共和国版权法保护。海康机器人拥有本文的全部版权，未经本公司许可，任何单位及个人不得对本文中的任何部分进行转印、影印或复印。

信息反馈

海康机器人尽最大的努力保证本手册的准确性和完整性。如果您在使用中发现问题，希望及时将情况反馈给我们以完善产品，我们将非常感谢您的支持。

总公司联系方式

  • 公司总机：0571‑88967998
  • 技术支持电话：0571‑86611880(工作日9:30‑17:30)
  • 传真：0571‑88805843
  • 地址：中国杭州市滨江区东流路700号
  • 邮编：310052
  • 公司E‑mail：hikrobot@hikrobotics.com
  • 公司网站：www.hikrobotics.com

目录

  1. 协议概述
    • 1.1 请求首部字段
    • 1.2 请求报文消息体
    • 1.3 加密签名
    • 1.4 响应首部字段
    • 1.5 响应报文消息体
    • 1.6 响应状态码
    • 1.7 响应报文消息体通用code
  2. 业务接口说明
    • 2.1 机器人调度API 接口说明
    • 2.2 反馈接收SPI 接口说明
  3. 任务下发接口调用示例
  4. 典型调度场景
  5. 更新说明

1 协议概述

海康调度系统调用上层系统的接口，获取连接超时时间默认为30 秒，数据返回超时时间默认为60 秒，超时情况下，调度系统会返回连接失败。

1.1 请求首部字段

字段名 数据类型 最大字节数 是否必需 说明
Authorization 字符串 N/A 否 固定格式：nonce="wab1tkh",method="HMAC‑SHA256",timestamp="2021‑01‑01T00:00:00+08:00"
Content‑Type 字符串 N/A 否 固定取值：application/json;charset=UTF‑8
X‑lr‑appkey 字符串 32 否 由调度系统颁发给业务系统的唯一标识
X‑lr‑request‑id 字符串 16 是 业务请求的唯一标识
X‑lr‑version 字符串 12 否 API 接口版本，为了保证接口的向下兼容，同样的 API 接口可能存在多个版本实现
X‑lr‑trace‑id 字符串 32 否 全链路追踪标识，用于协查上下游故障，需要在响应中原样返回。建议使用 UUID
X‑lr‑source 字符串 32 否 指令的来源，便于调试和故障定位

1.2 请求报文消息体

只能使用**JSON格式(UTF‑8编码方式)**或空字符串(无字符)。不能使用JSON对象数组或其他格式。业务请求的参数信息应当放在请求报文消息体当中。

请求报文样例

POST /api/robot/controller/tasks HTTP/1.1 
Host: 10.10.10.10:1010
Authorization: nonce="wab1tkh",method="HMAC‑SHA256",timestamp="2021‑01‑01T00:00:00+08:00"
X‑lr‑appkey: a4f********b324
X‑lr‑version: v1.0 
X‑lr‑trace‑id: 605****8a0b
X‑lr‑request‑id: 393****a6c1 
Content‑Type: application/json;charset=UTF‑8 
Content‑Length: 512 
Date: Fri, 26 Mar 2021 06:46:14 GMT 

{"warehouseId":"371****b108",……,"zoneCode":"c7a6****371b"}

1.3 加密签名

应用注册中的第三方应用，如开启加密，请求时需带上签名。appSecret为应用注册中的私钥。

请求完整示例如上所示，其中只有请求行、特定的首部字段、空行、报文消息体参与签名，即需要从请求报文原文中去除不参与签名的首部字段，将参与签名的首部字段名按下表编号的顺序排序，同时首部字段名改为大写。

参与签名的首部字段

编号 参与签名的首部字段 是否必填
1 AUTHORIZATION 是
2 HOST 是
3 X‑LR‑APPKEY 是
4 X‑LR‑REQUEST‑ID 是
5 X‑LR‑SOURCE 否
6 X‑LR‑TRACE‑ID 否
7 X‑LR‑VERSION 是

签名生成逻辑：

签名 = MD5( 加盐哈希算法(appSecret,请求报文拼接后的原串) ) 加盐哈希算法可选： 1）HMAC‑SHA256（推荐） 2）HMAC‑SHA512 使用MD5对加盐哈希算法的散列值再次哈希，产生128(16字节)的散列值。

请求的签名应当携带在查询参数的最后，参数名为sign。

Authorization头部参数说明

参数名 数据类型 字节数 是否必须 说明
nonce 字符串 8 是 随机数。建议每次请求都不同，以便于更有效的抵御彩虹表攻击；也可以定时更换
method 字符串 N/A 是 加盐哈希算法，固定枚举值：HMAC‑SHA256、HMAC‑SHA512
timestamp 字符串 N/A 是 请求发出的时间，遵循本文档关于时间格式秒精度的定义

重放攻击验证：服务端取出timestamp，加上业务允许合法请求时间，建议不超过120秒，判断请求是否超时。

1.4 响应首部字段

字段名 数据类型 最大字节数 是否必须 说明
Content‑Type 字符串 N/A 否 固定取值：application/json;charset=UTF‑8
X‑lr‑request‑id 字符串 16 是 业务请求的唯一标识
X‑lr‑version 字符串 12 否 API接口版本
X‑lr‑trace‑id 字符串 32 否 全链路追踪标识，原样返回请求入参

1.5 响应报文消息体

当HTTP 响应状态码为200时，响应报文消息体JSON对象格式：

中文名称 字段名 数据类型 最大字节数 是否必须 说明
消息码 code 字符串 32 是 参见 1.6 章节通用响应 code 定义和各接口的消息码定义
提示消息 message 字符串 256 否 异常描述
业务数据 data JSON 对象 10MB 否 返回的业务属性对象

正常响应报文样例

{
    "code":"SUCCESS",
    "message":"成功",
    "data": {
        "robotTaskCode": "abc**13"
    }
}

业务异常响应报文样例

{
    "code":"Err_Internal",
    "message":"内部未知错误",
    "data":null
}

1.6 响应状态码

状态码 说明
200 HTTP协议层面处理成功，但是仍可能出现业务异常，需要根据响应报文消息体的消息码判断
401 签名认证失败。原因可能是签名无效、签名过期、appKey和appSecret失效，需要重新更新请求时间后加签，或需要调度系统重新颁发appKey和appSecret
403 权限不足。例如业务系统试图取消不由其创建的任务
406 请求的Content‑Type不符合要求
400 其他由于客户端请求错误导致的异常，无法通过重试解决，需要检查请求的格式是否符合要求
500 服务端的异常，可以通过重试请求解决，重试次数与间隔需要根据业务实际情况设定

其余未列出状态码均按照标准HTTP协议处理即可。

1.7 响应报文消息体通用code

Code message
SUCCESS 成功
Err_Internal 内部未知错误
Err_DataValidationFailed 数据格式验证失败
Err_RequestDuplicate 请求重复
Err_InvalidVersion 请求版本不合法

2 业务接口说明

服务前缀统一：/rcs/rtas，完整请求路径 = 服务前缀 + 路径。

2.1 机器人调度API 接口说明

WMS/MES作为调用方，主动调用RCS‑2000这一组API。

2.1.1【国标】任务组接口

  • 接口路径：/api/robot/controller/task/group
  • 请求方式：POST
  • 幂等性：是

接口说明

  1. 任务组是任务的集合，当任务间有相互关系时，需要先调用任务组接口，描述任务组的策略，任务间的关系组合，再调用任务下发接口。
  2. 任务策略包括按组顺序出库策略、按组分配策略。
  3. 顺序出库下发规则：上层系统将 groupSeq 从小到大下发给 RCS‑2000，上层系统需要控制下发顺序，不支持先调接口发 groupSeq 大的，再调接口发 groupSeq 小的执行顺序出库。

请求体字段

参数名 数据类型 最大字节数 是否必须 说明
groupCode 字符串 32 是 任务组编号，全局唯一
strategy 字符串 16 是 执行策略。枚举：GROUP_SEQ按组顺序出库；GROUP_ASSIGN按组分配任务(CTU专用)；GROUP_CARRIER_ADJUST载具整理(CTU理库)
strategyValue 字符串 32 否 GROUP_SEQ时必填：0组间无序组内无序；1组间及组内都有序；2组间有序组内无序；3组间无序组内有序；GROUP_CARRIER_ADJUST理库时必填
groupSeq 整数 8 否 组顺序(数字)，从1~9999999999
data JSON对象数组 N/A 是 子任务集合，每个元素：robotTaskCode(任务号),sequence(组内顺序)

响应公共字段：code/message/data，data内返回任务组信息。 专用消息码：Err_TaskNotStart上一组任务未下发；Err_DataValidationFailed任务序列号有误。

请求示例

{
    "groupCode": "2e0d1ae0481f48b78b6a217ac2b54eb4",
    "strategy": "GROUP_SEQ",
    "strategyValue": "1",
    "groupSeq": 10,
    "targetRoute": {
        "type": "ZONE",
        "code": "A2"
    },
    "data": [
        {"robotTaskCode": "0a17e361eb5248bfab0508e4709f085e","sequence": 1},
        {"robotTaskCode": "1b30143f32914155ab194d55a95d54da","sequence": 2},
        {"robotTaskCode": "6541e925d1de4c448188068fcee75de5","sequence": 3}
    ]
}

2.1.2【国标】 任务下发接口

  • 接口路径：/api/robot/controller/task/submit
  • 请求方式：POST
  • 幂等性：是

接口说明：业务系统发送任务请求，物流机器人调度系统生成任务执行单，并下发执行。

请求体字段

参数名 数据类型 最大字节数 是否必须 说明
taskType 字符串 16 是 任务类型，预制枚举：PF‑LMR‑COMMON普通搬运
targetRoute 对象数组 N/A 是 执行步骤集合，机器人关键路径（起点、终点）
initPriority 整数 8 否 初始优先级1‑120，数值越大优先级越高；调度会动态修正实际优先级
deadline 时间 N/A 否 任务截止时间，秒精度，优先级修正条件之一
robotType 字符串 N/A 否 GROUPS资源组 / ROBOTS机器人编号
robotCode 字符串数组 N/A 否 机器人编号集合
robotTaskCode 字符串 64 否 外部任务唯一编号；不传则调度系统生成返回
extra JSON对象 N/A 否 自定义扩展透传字段

targetRoute子对象：

  • type：SITE站点；ZONE区域；STORAGE仓位；CARRIER载具等
  • code：对应编号
  • operation：COLLECT取货，DELIVERY送货，ROTATE旋转
  • carrierInfo[]：载具信息（载具类型、编号、层号）
  • angleInfo：角度信息

响应data字段：robotTaskCode（全局唯一任务号） 专用错误码：Err_TaskTypeNotSupport任务类型不支持；Err_RobotGroupsNotMatch机器人资源组不匹配；Err_TargetRouteError路径参数错误。

2.1.3 任务继续执行接口

  • 路径：/api/robot/controller/task/extend/continue
  • POST，幂等：是

说明：一个任务包含多个步骤，每个步骤完成后，上层调用本接口驱动下一步骤；第一个步骤也需要调用此接口启动。若步骤设置autoStart自动开始，则可不调用；重复调用做幂等处理。

请求入参：

  • triggerType：SITE站点 / ROBOT车号 / TASK任务链编号
  • triggerCode：对应编号
  • targetRoute：下一步目标路径对象
  • extra：扩展字段

错误码：Err_TaskNotStart任务尚未开始；Err_TaskFinished任务已结束；Err_TaskNotFound任务找不到。

2.1.4【国标】任务取消接口

  • 路径：/api/robot/controller/task/cancel
  • POST，幂等：是

说明：取消任务；软取消可下发回库任务；支持按任务号、机器人编号、载具编号批量取消。

请求体关键字段

参数 说明
robotTaskCode 任务号，可选
cancelType CANCEL软取消；DROP人工介入硬取消
carrierCode 载具编号，批量取消用
robotCode 机器人编号，批量取消用
reason 取消原因
returnTaskType 软取消回库流程类型，默认PF‑TASK‑CANCEL‑RETURN
targetRoute 取消后机器人目标位置

2.1.5【国标】任务优先级设置接口

  • 路径：/api/robot/controller/task/priority
  • POST，幂等：是

说明：任务创建后，修改初始优先级、截止时间；调度系统会综合工况动态调整实际执行优先级。

入参：

  • robotTaskCode：任务编号（必填）
  • initPriority：1‑120
  • deadline：截止时间（可选）
  • extra：扩展

2.1.6【国标】区域暂停与恢复机器人接口

  • 路径：/api/robot/controller/zone/pause
  • POST，幂等：是

入参：

  • zoneCode：管控区域编号
  • invoke：FREEZE急停暂停；RUN恢复运行

2.1.7【国标】区域归巢机器人接口

  • 路径：/api/robot/controller/zone/homing
  • POST，幂等：是

让指定区域机器人前往归巢点位，支持归巢后关机、定时开机。

入参关键字段

  • zoneCodes：区域编号集合
  • autoShutdown：YES关机 / NO不关机
  • bootTime：预设开机时间（autoShutdown=YES生效）
  • expireTime：归巢超时时间

返回data：homingCode归巢指令编号；robotCount接收到指令的机器人数量。

2.1.8【国标】 区域驱离机器人接口

  • 路径：/api/robot/controller/zone/banish
  • POST，幂等：是

将区域内机器人驱离，禁止进入该区域。 返回banishCode驱离指令编号。

2.1.9【国标】区域封锁与恢复接口

  • 路径：/api/robot/controller/zone/blockade
  • POST，幂等：是

封锁：禁止机器人进入该区域；不强制区内机器人离开。 invoke枚举：BLOCKADE封锁；OPENUP解封。

2.1.10【国标】载具与站点绑定接口

  • 路径：/api/robot/controller/carrier/bind
  • POST，幂等：是

代表载具放置在该站点；前提：载具、站点无占用任务。 入参：carrierCode载具编号，siteCode站点编号，carrierDir载具角度。

2.1.11【国标】载具与站点解绑接口

  • 路径：/api/robot/controller/carrier/unbind
  • POST，幂等：是

解绑载具‑站点；carrierCode/siteCode至少传一个。

2.1.12 存储对象与搬运对象绑定解绑接口

  • 路径：/api/robot/controller/site/bind
  • POST，幂等：是

slot：仓位/站点；invoke=BIND绑定 / UNBIND解绑；支持料箱、载具绑定解绑。

2.1.13【国标】 载具禁用与启用

  • 路径：/api/robot/controller/carrier/lock
  • POST，幂等：是

invoke：LOCK禁用；UNLOCK启用；传入carrierCode。

2.1.14【国标】站点禁用与启用

  • 路径：/api/robot/controller/site/lock
  • POST，幂等：是

invoke：LOCK禁用；UNLOCK启用；传入siteCode站点编号。

2.1.15 外设执行通知接口【返回0】

  • 路径：/rcs/rtas/spi/wcs/robot/eqpt/notify
  • POST，幂等：是

上层通知调度：电梯、自动门等外设动作完成。 旧版本返回code=0；V4.2.8使用notifyGbt接口返回SUCCESS。

2.1.16【国标】预调度任务下发接口

  • 路径：/api/robot/controller/task/pretask
  • POST，幂等：是

提前调度机器人到达点位等待业务任务。 入参：siteCode站点；nextTaskTime预计多久后执行真实任务，单位秒。

2.1.17【国标】查询任务状态接口

  • 路径：/api/robot/controller/task/query
  • POST，幂等：是

根据robotTaskCode查询单条任务状态。 返回taskStatus枚举：QUEUE队列中；WAIT等待；EXECUTING执行；MANUALED人工完成；FINISHED已完成；CANCELLED已取消。

2.1.18【国标】查询机器人状态接口

  • 路径：/api/robot/controller/robot/query
  • POST，幂等：是

传入singleRobotCode机器人编号，返回：电量、坐标、速度、在线状态、任务状态、携带载具编号、告警信息。

2.1.19【国标】查询载具状态接口

  • 路径：/api/robot/controller/carrier/query
  • POST，幂等：是

传入carrierCode，返回：所在站点、绑定任务号、坐标、载具状态、仓位编号、所属机器人编号。

2.1.20 物料绑定接口

  • 路径：/api/robot/controller/matlabel/bind
  • POST，幂等：是

载具绑定物料标签。入参：carrierCode，matLabel物料标签。

2.1.21 物料解绑接口

  • 路径：/api/robot/controller/matlabel/unbind
  • POST，幂等：是

2.1.22 外设执行通知接口【V4.2.8 返回SUCCESS】

  • 路径：/rcs/rtas/spi/wcs/robot/eqpt/notifyGbt
  • POST，幂等：是

新版本国标外设通知，返回code=SUCCESS，兼容电梯、自动门。

2.2 反馈接收SPI 接口说明

SPI：RCS‑2000作为调用方，主动回调上层WMS/MES服务地址，推送事件、告警、状态。需要在RCS后台配置上层回调地址。

2.2.1【国标】任务执行过程回馈接口

  • 回调路径示例：/api/robot/reporter/task

任务事件上报：任务开始、离开储位、任务完成等事件。 values.method：start任务开始；outbin走出储位；end任务完成。

2.2.2 请求资源接口

  • 回调路径：/api/robot/reporter/resource

RCS向上层申请资源：申请站点、仓位、载具。applyType：APPLY_SITE申请站点、APPLY_BIN申请仓位。上层返回目标点位信息。

2.2.3 请求外设接口

  • 回调路径：/api/robot/reporter/eqpt

RCS向上层请求电梯、自动门外设资源。

2.2.4【国标】 机器人归巢完成回馈接口

  • 回调路径示例：/api/robot/reporter/zone/homing

归巢全部完成/超时回调通知上层。后台需要开启业务通知开关ZONE_HOMING。

2.2.5【国标】区域驱离机器人完成回馈接口

  • 回调路径示例：/api/robot/reporter/zone/banish 驱离全部完成或超时通知；后台开启开关ZONE_BANISH。

2.2.6【国标】机器人异常告警上报接口

  • 回调路径示例：/api/robot/reporter/robot/warning

机器人严重故障告警上报，仅推送一次；后台开启开关AMR_ALARM。

2.2.7【国标】任务异常告警上报接口

  • 回调路径示例：/api/robot/reporter/task/warning

任务执行异常告警上报，仅推送一次；后台开启开关TASK_ALARM。

2.2.8 绑定解绑通知

  • 回调路径示例：/api/robot/reporter/bind

载具/仓位发生绑定、解绑动作时RCS回调上层；后台开启开关BIND。 invoke=BIND绑定 / UNBIND解绑。

3 任务下发接口调用示例

文档包含潜伏车、CTU、叉车、滚筒车等各类机器人task/submit完整http+json请求样例，详见原始PDF文档3章节。

4 典型调度场景

  1. 场景一：背货架AMR 在货架底下待命任务调度场景
  2. 场景二：普通背货架任务调度场景
  3. 场景三：辊筒AMR 任务调度场景
  4. 场景四：CTU 输送线预调度+入库
  5. 场景五：CTU 梳齿式工作站入库
  6. 场景六：潜伏车顺序出库场景（任务组GROUP_SEQ典型用法）
  7. 场景七：潜伏车搬运与外设交互场景

每个场景给出：上层系统 ↔ HIK调度系统交互步骤、对应接口编号。

潜伏车顺序出库重点说明

方式一（推荐） 1）先调用任务组接口2.1.1，定义groupCode、策略、顺序； 2）多次调用任务下发2.1.2，传入groupCode下发子任务。

方式二（不推荐）：任务下发接口直接携带groupCode、sequence、seqType。

5 更新说明

更新时间 更新人员 更新内容
2024/8/30 王勇52 1.编写4.2 接口文档
2024/9/3 王勇52 1.增加典型调度场景
2025/8/11 王勇52 1.修改预调度接口任务数字段描述

说明：本Markdown为文档结构化转写，部分超长http请求样例做简化；实际开发请以PDF原始报文样例复制使用。 核心关键点总结（开发提示）

  1. API（WMS调用RCS）：2.1开头；SPI回调（RCS调用WMS）：2.2开头，需要RCS后台配置上层回调地址。
  2. 全部POST，JSON；签名使用HMAC‑SHA256，签名放url query参数sign。
  3. 任务顺序出库：优先使用任务组接口2.1.1。
  4. 外设交互两套通知接口：旧版notify（code=0）；新版notifyGbt（code=SUCCESS）V4.2.8+。
  5. 告警、归巢、驱离、绑定解绑回调，需要在RCS后台业务通知开启对应开关，否则不会推送SPI。

如果你需要，我可以进一步输出一份：WMS对接海康RCS‑2000V4.2极简对接清单（字段清单+时序）。

Reference in New Issue View Git Blame Copy Permalink