diff --git a/AGV海康litev1.5.md b/AGV海康litev1.5.md new file mode 100644 index 0000000..44d7c61 --- /dev/null +++ b/AGV海康litev1.5.md @@ -0,0 +1,1183 @@ +# 海康 RCS-Lite V1.5 对外任务接口文档 + +> 来源:杭州海康机器人股份有限公司《轻量级机器人调度平台软件 RCS-LITE V1.5 对外任务接口文档》 +> 整理时间:2026-10-17 +> 用途:项目对接 RCS-Lite 参考 + +--- + +## 1. 协议概述 + +协议统一使用 **JSON** 格式。 + +- 中文编码:`URLEncoder.encode("string", "UTF-8")` +- 中文解码:`URLDecoder.decode("string", "UTF-8")` + +**标注 `*` 的为常用接口**,初步对接只需调通以下三个: +1. 生成任务单 +2. 继续执行任务 +3. 取消任务 + +若上层系统需接收任务执行状态,需提供回调接口:**任务执行通知接口**。 + +### 1.1 超时约定 + +- 连接超时:默认 **30 秒** +- 数据返回超时:默认 **60 秒** +- 超时情况下,调度系统返回连接失败 + +### 1.2 对接约定 + +- 所有参数统一为**字符串**格式 +- AGV、robot、机器人术语为同一含义,不混淆 +- `reqCode` 传入与传出保持一致,使用 UUID 或其他唯一标识 +- 为兼容旧版本,消息上报字段可能多于文档列出字段,上层按需截取 + +### 1.3 请求公共参数 + +| 参数名 | 是否必填 | 描述 | +|---|---|---| +| reqCode | 选填 | 请求编号,每个请求需唯一 | +| reqTime | 选填 | 请求时间戳,格式 `yyyy-MM-dd HH:mm:ss` | + +### 1.4 返回值定义 + +| 参数名 | 是否必填 | 描述 | +|---|---|---| +| reqCode | 选填 | 请求编号返回,形成一一对应 | +| code | 必填 | `"0"`:成功;`1~N`:失败 | +| message | 必填 | `"0"`:成功;`1~N`:详细描述 | +| data | 选填 | 返回的数据结构 | + +### 1.5 结果码定义 + +| 结果码 | 说明 | +|---|---| +| 0 | 成功 | +| 1001 | 创建任务失败,站点集合数据类型不正确 | +| 1002 | RCS 接口调用返回失败 | +| 1003 | 未找到该任务或者任务已被执行完 | +| 1004 | 呼叫站点别名获取点位信息失败 | +| 1005 | 任务模板读取失败 | +| 1006 | 站点集合传的数量不对 | +| 1007 | 地码和站点集合传值都是空 | +| 1008 | 子任务触发传入值不正确 | +| 1009 | 地码不存在 | +| 1010 | 货架不存在 | +| 1011 | 小车不存在 | +| 1012 | 别名不存在 | +| 1013 | 站点集合数据错误 | +| 1014 | 呼叫站点不能为空(调用的模板中使用了呼叫站点配置) | +| 1015 | 获取货架信息失败 | +| 1016 | 通过库区编号查找点位失败 | +| 1017 | 未找到空闲的货架或者点位 | +| 1018 | 查找关联点失败 | +| 1019 | 查找关联区域失败 | +| 1020 | 查找关联库区失败 | +| 1021 | 固定点配置错误 | +| 1022 | 货架编号不能为空 | +| 1023 | 通过货架找点失败 | +| 1024 | 不支持连续相同的关联点配置 | +| 1025 | reqCode 重复 | +| 1026 | 解析模板得出空的地图编号 | +| 1027 | 货架正在出入库,被锁定 | +| 1028 | 指定货架不在目标库区内 | +| 1029 | 关联点配置错误 | +| 1030 | 容器类型错误 | +| 1031 | 容器类型信息获取失败 | +| 1032 | 通过仓位编号查找仓位信息失败 | +| 1033 | 仓位编号不正确 | +| 1034 | 通过巷道编号查询数据失败 | +| 1035 | 巷道编号错误 | +| 1036 | 无效的出库策略 | +| 1037 | 通过容器编号查询数据失败 | +| 1038 | 容器编号错误 | +| 1039 | 通过站点集合查询仓位信息失败 | +| 1040 | 容器编号不存在 | +| 1041 | 容器类型和容器编号不匹配 | +| 1042 | 需要传容器编号 | +| 1043 | 巷道配置错误 | +| 1044 | 任务模板配置错误 | +| 1045 | 可出库容量为 0 | +| 1046 | 可入库容量为 0 | +| 1047 | 巷道容量信息查询失败 | +| 1048 | 巷道预入库锁定失败 | +| 1049 | 巷道预出库锁定失败 | + +### 1.6 基础访问地址 + +**RCS-Lite:** + +``` +REST 协议:http://IP:PORT/rCMS/services/rest/hikRpcService +默认端口:8182 +``` + +**上层系统:** + +``` +REST 协议:http://IP:PORT/xxx/agv +``` + +--- + +## 2. 常用接口 * + +### 2.1 调度系统提供的接口 + +#### 2.1.1 生成任务单 * + +| 项 | 内容 | +|---|---| +| 接口名 | `genAvgSchedulingTask` | +| 功能说明 | 上层系统平台发送调度请求,RCS 通过请求参数生成调度 AGV 任务单 | +| 接口协议 | REST | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 否 | 请求编号,每请求唯一 | +| reqTime | String | 32 | 否 | 请求时间戳,格式 `yyyy-MM-dd HH:mm:ss` | +| taskTyp | String | 16 | 是 | 任务类型,与 RCS-LITE 端配置的主任务类型编号一致。内置:**F01 厂内货架搬运**;叉车专用:F11 高位货架到工作台、F12 工作台到高位货架、F13 巷道到工作台、F14 工作台到巷道 | +| ctnrTyp | String | 16 | 否 | 容器类型(叉车专用,叉车项目必传) | +| ctnrCode | String | 32 | 否 | 容器编号(叉车专用) | +| wbCode | String | 32 | 否 | 工作位,一般为机台或工作台位置,与 RCS-LITE 端配置的位置名称一致,字母/数字/组合,≤32 位 | +| priority | String | 4 | 否 | 优先级(1-127),默认 1,最高 127 | +| materialLot | String | 16 | 否 | 物料批次,下发任务时携带货架编号或呼叫站点,会将物料批次和货架绑定 | +| positionCodePath | Object[] | 列表≤64 | 否 | 位置路径:AGV 关键路径位置集合,与任务类型模板配置的位置路径一一对应 | +| podCode | String | 16 | 否 | 货架编号,不指定可为空 | +| podDir | String | 4 | 否 | `"180"`/`"0"`/`"90"`/`"-90"` 分别对应地图的"左"/"右"/"上"/"下",不指定可为空 | +| podTyp | String | 16 | 否 | 货架类型,传空时随机找货架。只找该类型的空货架 | +| taskCode | String | 64 | 否 | 任务单号,选填,不填系统自动生成,UUID ≤64 位 | +| agvCode | String | 16 | 否 | AGV 编号,指定某编号 AGV 执行该任务 | + +**positionCodePath 子字段:** + +| 字段 | 说明 | +|---|---| +| positionCode | 位置编号,单个编号 ≤64 位 | +| type | `00` 位置编号;`02` 库区编号;`03` 货架编号;`05` 仓位编号(叉车专用);`06` 巷道编号(叉车专用);`07` 容器编号(叉车专用) | + +**响应参数:** + +| 参数名 | 类型 | 必填 | 说明 | +|---|---|---|---| +| code | String | 是 | 返回码 | +| message | String | 是 | 返回消息 | +| reqCode | String | 是 | 请求编号 | + +**备注:** `wbCode` 和 `positionCodePath` 至少填写其中一项,以确定任务中的位置信息。若需多个位置信息(起点、终点),使用 `positionCodePath`。 + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/genAgvSchedulingTask +{ + "reqCode": "468513", + "reqTime": "2020-05-03 03:22:33", + "taskTyp": "F01", + "wbCode": "", + "positionCodePath": [ + { "positionCode": "p01", "type": "00" }, + { "positionCode": "x02", "type": "02" } + ], + "priority": "", + "podCode": "100001", + "podDir": "0", + "podTyp": "1", + "agvCode": "9000", + "taskCode": "xxxxx_ECS" +} +``` + +**示例应答:** + +```json +{ + "code": "0", + "message": "成功", + "reqCode": "468513" +} +``` + +--- + +#### 2.1.2 继续执行任务 * + +| 项 | 内容 | +|---|---| +| 接口名 | `continueTask` | +| 功能说明 | 上层系统平台发送继续调度请求,RCS-LITE 获取 AGV 下一个动作,继续执行 | +| 接口协议 | REST | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 否 | 请求编号,每请求唯一 | +| reqTime | String | 32 | 否 | 请求时间戳,格式 `yyyy-MM-dd HH:mm:ss` | +| wbCode | String | 32 | 否 | 工作位,与 RCS-LITE 端配置的位置名称一致 | +| podCode | String | 16 | 否 | 货架号,采用货架号触发方式 | +| agvCode | String | 16 | 否 | AGV 编号,采用 AGV 编号触发方式 | +| taskCode | String | 64 | 否 | 任务单号,采用任务编号触发方式 | + +**响应参数:** + +| 参数名 | 类型 | 必填 | 说明 | +|---|---|---|---| +| code | String | 是 | 返回码 | +| message | String | 是 | 返回消息 | +| reqCode | String | 是 | 请求编号 | + +**备注:** `taskCode`、`agvCode`、`wbCode`、`podCode` 四选一,需与任务模板配置的触发类型一致,**推荐 taskCode**。 + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/continueTask +{ + "reqCode": "123", + "reqTime": "2020-05-03 03:22:33", + "wbCode": "020000XY030000", + "podCode": "600001", + "agvCode": "9000", + "taskCode": "123456" +} +``` + +**示例应答:** + +```json +{ + "code": "0", + "message": "成功", + "reqCode": "123" +} +``` + +--- + +#### 2.1.3 取消任务 * + +| 项 | 内容 | +|---|---| +| 接口名 | `cancelTask` | +| 功能说明 | 通过正在执行的任务编号取消任务,不再执行。潜伏车背着货架时会把货架直接放在路上;叉车背着容器时会把容器放在路上,同时小车状态置为空闲 | +| 接口协议 | REST | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 否 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| agvCode | String | 16 | 否 | 取消该 AGV 正在执行的任务单(与 taskCode 二选一) | +| taskCode | String | 64 | 否 | 任务单编号(与 agvCode 二选一) | +| forceCancel | String | 1 | 否 | `0` 取消后货架放地上;`1` AGV 仍背货架,根据回库区域执行回库(仅潜伏车支持)。不传默认 0 | +| matterArea | String | 16 | 否 | `forceCancel=1` 时有意义,回库区域编号 | + +**响应参数:** + +| 参数名 | 类型 | 必填 | 说明 | +|---|---|---|---| +| code | String | 是 | 返回码 | +| message | String | 是 | 返回消息 | +| reqCode | String | 是 | 请求编号 | + +**备注:** `taskCode` 和 `agvCode` 选一项填写。都传时**优先 agvCode**。 + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/cancelTask +{ + "reqCode": "1541954B96B1112", + "reqTime": "", + "clientCode": "", + "tokenCode": "", + "forceCancel": "1", + "matterArea": "abc", + "agvCode": "", + "taskCode": "123456" +} +``` + +--- + +### 2.2 上层平台提供的接口 + +#### 2.2.1 任务执行通知 * + +| 项 | 内容 | +|---|---| +| 接口名 | `agvCallback` | +| 功能说明 | AGV 执行回调方法,包含任务开始、走出储位、任务完成、任务取消 | +| 接口协议 | REST | +| 提供方 | 上层平台 | +| 调用方 | RCS-LITE | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 否 | 请求编号 | +| reqTime | String | 32 | 是 | 请求时间戳 | +| cooX | String | 8 | 否 | 地码 X 坐标(mm),任务完成时有值 | +| cooY | String | 8 | 否 | 地码 Y 坐标(mm),任务完成时有值 | +| currentPositionCode | String | 32 | 是 | 当前位置编号:任务开始=起点;走出储位=起点;任务取消=工作位;任务结束=终点 | +| mapCode | String | 16 | 否 | 地图编号 | +| mapDataCode | String | 32 | 否 | 地码编号,任务完成时有值 | +| method | String | 16 | 是 | 方法名,默认:`start` 任务开始 / `outbin` 走出储位 / `end` 任务结束 / `cancel` 任务单取消 | +| podCode | String | 16 | 否 | 货架编号,背货架时有值 | +| podDir | String | 4 | 否 | 货架方向 `"180"`/`"0"`/`"90"`/`"-90"`,任务完成时有值 | +| robotCode | String | 16 | 是 | AGV 编号 | +| taskCode | String | 64 | 是 | 当前任务单号 | +| wbCode | String | 32 | 否 | 工作位 | + +**响应参数:** + +| 参数名 | 类型 | 必填 | 说明 | +|---|---|---|---| +| code | String | 是 | 返回码 | +| message | String | 是 | 返回消息 | +| reqCode | String | 是 | 请求编号 | + +**示例请求:** + +```http +POST http://IP:PORT/xxx/agv/agvCallbackService/agvCallback +{ + "reqCode": "1541954B96B1112", + "reqTime": "2019-04-03 10:08:06", + "cooX": "3000", + "cooY": "21999", + "currentPositionCode": "p02", + "mapCode": "AA", + "mapDataCode": "002069AA015172", + "method": "end", + "podCode": "100001", + "podDir": "0", + "robotCode": "9001", + "taskCode": "123456", + "wbCode": "" +} +``` + +--- + +## 3. 可选接口 + +### 3.1 调度系统提供的接口 + +#### 3.1.1 货架与位置绑定、解绑 + +| 项 | 内容 | +|---|---| +| 接口名 | `bindPodAndBerth` | +| 功能说明 | 货架与储位的关系绑定,系统可通过货架找到对应位置 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | +| 备注 | 解绑时货架与位置都要传,用于检验,避免误操作 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 否 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| podCode | String | 16 | 是 | 货架编号 | +| positionCode | String | 32 | 是 | 位置编号,地图位置的别名,字母+数字,需唯一,由 RCS-LITE 界面配置 | +| podDir | String | 1 | 否 | `"0"` 横向(货架长与 X 轴一致);`"1"` 纵向(货架宽与 X 轴一致)。不传默认横向 | +| indBind | String | 1 | 是 | `"1"` 绑定;`"0"` 解绑 | + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/bindPodAndBerth +{ + "reqCode": "12345678", + "reqTime": "2020-05-03 03:22:33", + "podCode": "100001", + "positionCode": "p05", + "podDir": "0", + "indBind": "1" +} +``` + +--- + +#### 3.1.2 释放 AGV + +| 项 | 内容 | +|---|---| +| 接口名 | `freeRobot` | +| 功能说明 | 释放指定 AGV 或全部 AGV | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 否 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| robotCount | String | 64 | 否 | 释放机器人数,`-1` 表示全部 | +| mapShortName | String | 32 | 否 | AGV 所在地图简称。`robotCount=-1` 时必填 | +| robots | String | 16 | 否 | 具体机器人编号列表 | + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/freeRobot +{ + "reqCode": "12345678", + "reqTime": "2020-05-03 03:22:33", + "robotCount": "2", + "mapShortName": "", + "robots": ["1001", "1002"] +} +``` + +--- + +#### 3.1.3 查询任务状态 + +| 项 | 内容 | +|---|---| +| 接口名 | `queryTaskStatus` | +| 功能说明 | 通过任务编号查询任务当前执行状态,支持批量查询 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | +| 备注 | 参数错误或任务单未找到均返回成功。agvCode 不为空时查该 AGV 历史任务,否则按 taskCodes 查询 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号,同请求重复提交用同一编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号,如 PDA、HCWMS | +| tokenCode | String | 64 | 否 | 令牌号,由调度系统颁发 | +| taskCodes | String[] | 64 | 否 | 任务单编号数组(与 agvCode 至少传一个) | +| agvCode | String | 16 | 否 | AGV 编号(与 taskCodes 至少传一个) | + +**响应 data 列表字段:** + +| 参数名 | 类型 | 必填 | 说明 | +|---|---|---|---| +| taskCode | String | 是 | 任务单编号 | +| taskTyp | String | 是 | 任务类型 | +| taskStatus | String | 是 | 任务状态:`1` 已创建;`2` 正在执行;`5` 取消完成;`9` 已结束 | +| agvCode | String | 否 | AGV 编号,任务分配车后有值 | + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/queryTaskStatus +{ + "reqCode": "1541954B96B1110", + "reqTime": "", + "clientCode": "", + "tokenCode": "", + "agvCode": "", + "taskCodes": ["123", "234"] +} +``` + +**示例应答:** + +```json +{ + "code": "0", + "message": "成功", + "reqCode": "1541954B96B1110", + "data": [ + { "taskCode": "234", "taskStatus": "2", "agvCode": "", "taskTyp": "F01" }, + { "taskCode": "123", "taskStatus": "9", "agvCode": "", "taskTyp": "F01" } + ] +} +``` + +--- + +#### 3.1.4 容器与仓位绑定、解绑 + +| 项 | 内容 | +|---|---| +| 接口名 | `bindCtrAndBin` | +| 功能说明 | 仓位与容器的关系绑定,容器类型编号写入仓位表 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号 | +| tokenCode | String | 64 | 否 | 令牌号 | +| ctnrCode | String | 16 | 否 | 容器编号 | +| ctnrTyp | String | 4 | 是 | 容器类型 | +| stgBinCode | String | 32 | 否 | 仓位编号(与仓位绑定解绑必填) | +| binName | String | 32 | 否 | 客仓编号,对应多个仓位编号时报错 | +| indBind | String | 1 | 是 | `"1"` 绑定;`"0"` 解绑 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/bindCtnrAndBin +{ + "reqCode": "12345678", + "reqTime": "...", + "clientCode": "...", + "tokenCode": "...", + "ctnrCode": "...", + "ctnTyp": "C1", + "stgBinCode": "p05", + "indBind": "1" +} +``` + +--- + +#### 3.1.4(重复编号)巷道与容器绑定、解绑 + +| 项 | 内容 | +|---|---| +| 接口名 | `bindCtnrAndTunnel` | +| 功能说明 | 巷道与容器的关系绑定,容器类型编号写入该巷道中所有仓位 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号 | +| tokenCode | String | 64 | 否 | 令牌号 | +| tunnelCode | String | 32 | 是 | 巷道编号 | +| indBind | String | 1 | 是 | `"1"` 绑定;`"0"` 解绑 | + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/bindCntrAndBin +{ + "reqCode": "12345678", + "reqTime": "", + "clientCode": "", + "tokenCode": "", + "tunnelCode": "1", + "indBind": "1" +} +``` + +--- + +#### 3.1.5 清空区 + +| 项 | 内容 | +|---|---| +| 接口名 | `blockArea` | +| 功能说明 | 封锁/解封指定区域 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | +| 备注 | 区域在 RCS-LITE 中配置;封锁后区域内 AGV 停止,即将进入区域的 AGV 线路改道 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号 | +| tokenCode | String | 64 | 否 | 令牌号 | +| matterArea | String | 16 | 是 | 被封锁或解封的区域名称 | +| indBind | String | 1 | 是 | `"1"` 封锁/清空;`"0"` 解封 | +| pause | String | 4 | 是 | 清空后小车是否暂停:`0` 不暂停(默认);`1` 暂停 | +| controlMod | String | 4 | 是 | 调度模式:`0` 调度到区域外(默认);`1` 调度到区域外暂住区;`2` 调度到指定区域(暂不支持);`3` 封锁区 | +| targetArea | String | 16 | 否 | 目标区域编码(controlMod=2 时需传,暂不支持) | +| effect | String | 4 | 是 | 需要调度的车种类:`1` 需要;`0` 不需要 | +| idle | String | 4 | 否 | 空闲车:`0` 不处理;`1` 处理(effect=1 时生效) | +| execute | String | 4 | 否 | 执行任务中:`0` 不处理;`1` 不需要放货架;`2` 需要放货架(effect=1 时生效) | +| charge | String | 4 | 否 | 充电车:`0` 不处理;`1` 处理(effect=1 时生效) | +| stay | String | 4 | 否 | 锁定车:`0` 不处理;`1` 处理(effect=1 时生效) | +| work | String | 4 | 否 | 工作台检货车:`0` 不处理;`1` 不需要放货架;`2` 需要放货架(effect=1 时生效) | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/blockArea +{ + "reqCode": "1541954B96B1112", + "reqTime": "", + "clientCode": "", + "tokenCode": "", + "matterArea": "2", + "indBind": "1", + "pause": "0", + "controlMod": "2", + "targetArea": "HF002", + "effect": "1", + "idle": "1", + "execute": "1", + "charge": "1", + "stay": "1", + "work": "20" +} +``` + +--- + +#### 3.1.6 设置优先级 + +| 项 | 内容 | +|---|---| +| 接口名 | `setTaskPriority` | +| 功能说明 | 通过传入任务单号和优先级,设置任务优先级 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号 | +| tokenCode | String | 64 | 否 | 令牌号 | +| priorities | 数组 | — | 是 | 优先级列表 | +| priorities[].priority | String | 4 | 是 | 优先级(1-127),默认 1,最高 127 | +| priorities[].taskCode | String | 16 | 是 | 任务单号 | + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/setTaskPriority +{ + "clientCode": "", + "priorities": [ + { "priority": "21", "taskCode": "32ECB3A7-BCAC-413C-A249-301CEC176339_ECS" } + ], + "reqCode": "AFEF5C5A28D492DE", + "reqTime": "", + "tokenCode": "" +} +``` + +--- + +#### 3.1.7 AGV 状态获取接口 + +| 项 | 内容 | +|---|---| +| 接口名 | `queryAgvStatus` | +| 功能说明 | 通过地码名称查询当前地图中 AGV 状态信息 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | +| 调用路径 | `http://IP:8182/rcms-dps/rest/queryAgvStatus` | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | — | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号 | +| tokenCode | String | 64 | 否 | 令牌号 | +| mapShortName | String | 2 | 是 | 地图编号,地码名称 | + +**响应 data 字段:** + +| 参数名 | 类型 | 必填 | 说明 | +|---|---|---|---| +| robotCode | String | 是 | 机器人编号 | +| robotDir | String | 是 | 机器人方向(-180~360 度) | +| robotIp | String | 是 | 机器人 IP | +| battery | String | 是 | 机器人电量(0-100) | +| posX | String | 是 | 机器人 x 坐标(mm) | +| posY | String | 是 | 机器人 y 坐标(mm) | +| mapCode | String | 是 | 机器人所在地图 | +| speed | String | 是 | 机器人当前速度(mm/s) | +| status | String | 是 | 机器人状态(见附件 5.1) | +| exclType | String | 是 | 是否已被排除:`1` 排除;`0` 正常 | +| stop | String | 是 | 是否暂停:`0` 否;`1` 是 | +| podCode | String | 否 | 背货架编号 | +| podDir | String | 否 | 背货架方向 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms-dps/rest/queryAgvStatus +{ + "reqCode": "1756727ryryr6861110", + "reqTime": "", + "clientCode": "", + "tokenCode": "", + "mapShortName": "AA" +} +``` + +**示例应答:** + +```json +{ + "code": 0, + "data": [{ + "battery": "99", + "exclType": "0", + "mapCode": "AA", + "podCode": "0", + "podDir": "", + "posX": "20000", + "posY": "20000", + "robotCode": "9001", + "robotDir": "", + "robotIp": "10.110.103.12", + "speed": "0", + "status": "4", + "stop": "0" + }] +} +``` + +--- + +#### 3.1.8 告警推送接口 + +| 项 | 内容 | +|---|---| +| 接口名 | `warnCallback` | +| 功能说明 | 调度系统将导致 AGV 停止运行的严重告警推送给上层系统 | +| 提供方 | 上层系统 | +| 调用方 | RCS-LITE | +| 推送频率 | **10 秒一次** | + +**请求 data 字段:** + +| 参数名 | 类型 | 说明 | +|---|---|---| +| agvCode | String | AGV 编号 | +| beginTime | String | 告警开始时间 | +| edTime | String | 告警结束时间 | +| mainCode | String | 主告警码 | +| mainName | String | 主告警名称 | +| mapCode | String | 地图编号 | +| subCode | String | 子告警码 | +| subName | String | 子告警名称 | +| xPos | String | 告警实时位置 x | +| yPox | String | 告警实时位置 y | + +**示例请求:** + +```http +POST http://IP:PORT/service/rest/agvCallbackService/warnCallback +{ + "data": { + "agvCode": "9001", + "beginTime": "2023-04-07 09:29:45", + "edTime": "...", + "mainCode": "7", + "mainName": "安全告警", + "mapCode": "AA", + "subCode": "7", + "subName": "急停告警", + "xPos": "0", + "yPox": "0" + }, + "reqCode": "86A2CBEE1633635E", + "reqTime": "2023-04-07 09:34:14" +} +``` + +--- + +#### 3.1.9 货架与物料的绑定 + +| 项 | 内容 | +|---|---| +| 接口名 | `bindPodAndMat` | +| 功能说明 | 货架与物料绑定,系统可通过货架找到对应物料 | +| 提供方 | 上层系统 | +| 调用方 | RCS-LITE | +| 备注 | 解绑时货架与物料都要传 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 32 | 否 | 请求时间戳 | +| podCode | String | 16 | 是 | 货架编号 | +| materialLot | String | 32 | 是 | 物料编号 | +| indBind | String | 1 | 是 | `"1"` 绑定;`"0"` 解绑 | + +**示例请求:** + +```http +POST http://IP:PORT/service/rest/avgCallbackService/warnCallback +{ + "reqCode": "12345678", + "reqTime": "2020-05-03 03:22:33", + "podCode": "100001", + "materialLot": "333333", + "indBind": "1" +} +``` + +--- + +### 3.2 上层平台提供的接口 + +#### 3.2.0 通知 CTU 继续执行取放货 + +| 项 | 内容 | +|---|---| +| 接口名 | `boxApplyPass` | +| 功能说明 | 通知 CTU 继续执行取放货(用于 CTU 取放货申请通过回复) | +| 提供方 | 上层系统 | +| 调用方 | RCS-LITE | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 64 | 是 | 请求编号 | +| taskCode | String | 64 | 是 | 任务单号 | +| eqpType | String | 32 | 是 | 设备类型名称 | +| type | String | 32 | 是 | `applyFromAgv` 放申请通过;`applyToAgv` 取申请通过 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/boxApplyPass +{ + "reqCode": "12345678", + "taskCode": "", + "eqpType": "100001", + "type": "333333" +} +``` + +--- + +#### 3.2.1 外部通知 CMS 任务执行状态 + +| 项 | 内容 | +|---|---| +| 接口名 | `thirdNotifyExecuteRetInfo` | +| 功能说明 | 外部通知 CMS 任务执行状态 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| des | String | 32 | 否 | 电梯使用:目标楼层(当前未使用) | +| data | String | 32 | 否 | 多托电梯使用:分配的点位(当前未使用) | +| deviceIndex | String | 32 | 否 | 设备编号 | +| actionStatus | String | 32 | 是 | 任务执行状态:电梯 `3` 开门到位 / `4` 物料到达目标楼层;自动门 `1` 开门到位 / `2` 关门到位 | +| deviceType | String | 32 | 是 | 设备类型:`lift` 电梯;`door` 自动门 | +| uuid | String | 32 | 是 | UUID | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/thirdNotifyExecuteRetInfo +{ + "des": "1", + "data": "", + "deviceIndex": "100001", + "actionStatus": "3", + "deviceType": "lift", + "uuid": "1231321323132" +} +``` + +--- + +#### 3.2.2 停止 AGV + +| 项 | 内容 | +|---|---| +| 接口名 | `stopRobot` | +| 功能说明 | 停止指定 AGV 或全部 AGV | +| 提供方 | RCS-2000 | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 20 | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号 | +| tokenCode | String | 64 | 否 | 令牌号 | +| robotCount | String | 64 | 否 | 停止机器人数,`-1` 全部 | +| mapCode | String | 32 | 否 | AGV 所在地图简称 | +| robots | String | 16 | 否 | 机器人编号列表 | + +**示例请求:** + +```http +POST http://IP:PORT/rCMS/services/rest/hikRpcService/stopRobot +{ + "clientCode": "", + "mapCode": "AA", + "reqCode": "BFDEBDE338FF73C", + "reqTime": "", + "robotCount": "2", + "robots": [9001, 10001], + "tokenCode": "" +} +``` + +--- + +#### 3.2.3 恢复 AGV + +| 项 | 内容 | +|---|---| +| 接口名 | `resumeRobot` | +| 功能说明 | 恢复 AGV,恢复后继续执行未完成任务 | +| 提供方 | RCS-2000 | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 20 | 否 | 请求时间戳 | +| clientCode | String | 16 | 否 | 客户端编号 | +| tokenCode | String | 64 | 否 | 令牌号 | +| robotCount | String | 64 | 否 | 恢复机器人数,`-1` 全部 | +| mapCode | String | 32 | 否 | AGV 所在地图简称 | +| robots | String[] | 16 | 否 | 具体机器人编号列表 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/resumeRobot +{ + "clientCode": "", + "mapCode": "AA", + "reqCode": "BFDEBDE338FF73C", + "reqTime": "", + "robotCount": "2", + "robots": [9001, 10001], + "tokenCode": "" +} +``` + +--- + +## 4. 牵引车专用接口 + +### 4.1 调度系统提供的接口 + +#### 4.1.1 CMR 控制 + +| 项 | 内容 | +|---|---| +| 接口名 | `AgvCommand` | +| 功能说明 | 针对牵引车的控制调度功能 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | +| 备注 | 会根据小车编号和位置编号对小车下发控制命令,两者都存在时**只使用小车编号** | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| shutDownTime | int32 | 否 | 关机时长(s),最长 7 天(commandType=3 时必填) | +| commandType | String | 4 | 是 | 控制命令:`0` 继续;`1` 暂停;`2` 恢复;`3` 关机;`5` 更新地图 | +| posCode | String | 16 | 是 | 位置编号 | +| agvId | idInt32 | 是 | AGV 编号列表 | + +**示例请求:** + +```http +POST http://IP:PORT/rrcms/services/rest/hikRpcService/AgvCommand +{ + "agvId": [{ "id": 8877 }], + "commandType": "2", + "posCode": "...", + "reqCode": "B5616A500A7F9EB9", + "shutDownTime": 0 +} +``` + +--- + +#### 4.1.2 CMR 数据替换 + +| 项 | 内容 | +|---|---| +| 接口名 | `CmrReplace` | +| 功能说明 | 针对牵引车的小车异常后数据替换功能 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | +| 备注 | 当小车异常后,可将异常小车的数据同步到新小车 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| oldCmrCode | String | 8 | 是 | 异常 AMR 编号 | +| newCmrCode | String | 8 | 是 | 新 AMR 编号 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/CmrReplace +{ + "newCmrCode": "313", + "oldCmrCode": "13", + "reqCode": "949D9C11B34BC8B3" +} +``` + +--- + +#### 4.1.3 CMR 数据设置 + +| 项 | 内容 | +|---|---| +| 接口名 | `CmrSetData` | +| 功能说明 | 针对牵引车的小车数据设置功能 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| data | String | 128 | 是 | 上层系统希望车中存放的数据 | +| agvId | String | 8 | 是 | 需要设置的 AMR 编号 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/CmrSetData +{ + "agvId": "9001", + "reqCode": "8311AD8832C1F67C", + "data": "dadioadhow" +} +``` + +--- + +#### 4.1.4 CMR 小车区域进入申请 + +| 项 | 内容 | +|---|---| +| 接口名 | `RobotApplyEnterArea` | +| 功能说明 | 针对牵引车的小车区域进入申请 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 否 | 请求编号 | +| reqTime | String | 128 | 否 | 请求时间 | +| robotId | int8 | — | 是 | 需要申请的 AMR 编号 | +| areaCode | String | 8 | 是 | 需要申请的区域编号 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/RobotApplyEnterArea +{ + "robotId": 9001, + "reqCode": "8311AD8832C1F67C", + "areaCode": "1" +} +``` + +--- + +#### 4.1.5 CMR 小车区域释放申请 + +| 项 | 内容 | +|---|---| +| 接口名 | `RobotApplyReleaseArea` | +| 功能说明 | 针对牵引车的小车区域释放申请 | +| 提供方 | RCS-LITE | +| 调用方 | 上层系统 | + +**请求参数:** + +| 参数名 | 类型 | 最大长度 | 必填 | 备注 | +|---|---|---|---|---| +| reqCode | String | 32 | 是 | 请求编号 | +| reqTime | String | 128 | 否 | 请求时间 | +| robotId | int8 | — | 是 | 需要申请释放的 AMR 编号 | +| areaCode | String | 8 | 是 | 需要申请释放的区域编号 | + +**示例请求:** + +```http +POST http://IP:PORT/rcms/services/rest/hikRpcService/RobotApplyReleaseArea +{ + "robotId": 9001, + "reqCode": "8311AD8832C1F67C", + "areaCode": "1" +} +``` + +--- + +## 5. 更新说明 + +| 版本 | 修订内容 | 修订者 | 日期 | +|---|---|---|---| +| 1 | 初版文档 | 曹明勤 | 2022-05-22 | +| 2 | 根据评审进行修改 | 曹明勤 | 2022-05-24 | +| 3 | 增加 3.1.3 查询任务状态 | 曹明勤 | 2022-08-09 | +| 4 | 增加叉车相关接口 | 曹明勤 | 2022-08-20 | +| 5 | 增加清空区/封锁区接口报文 | 王超 | 2023-03-08 | +| 6 | 增加优先级/AGV 状态获取接口 | 唐虎 | 2023-03-08 | +| 7 | 修改接口参数长度 | 郭书成 | 2024-01-02 | +| 8 | 外部通知 CMS 执行状态新增自动门 | 李祥 | 2024-07-03 | + +--- + +## 附件:AGV 常见状态列表 + +| 状态编号 | 中文描述 | 英文描述 | +|---|---|---| +| 1 | 任务完成 | Task completed | +| 2 | 任务执行中 | Executing task | +| 3 | 任务异常 | Abnormal task | +| 4 | 任务空闲 | Idle task | +| 5 | 机器人暂停 | Robot stopped | +| 6 | 举升货架状态 | Lifting shelf status | +| 7 | 充电状态 | Charging status | +| 8 | 弧线行走中 | Battery arcing in progress | +| 9 | 充满维护 | Fully charged, entering maintenance mode | +| 11 | 背货未识别 | Carried item not recognized | +| 12 | 货架偏角过大 | Excessive shelf angle divergence | +| 13 | 运动库异常 | Motion library exception | +| 14 | 货码无法识别 | Unable to recognise product code | +| 15 | 货码不匹配 | Product code mismatch | +| 16 | 举升异常 | Lift abnormal | + +--- diff --git a/bj_power_mes/ent/agvtask.go b/bj_power_mes/ent/agvtask.go index c30f5c6..1dabe32 100644 --- a/bj_power_mes/ent/agvtask.go +++ b/bj_power_mes/ent/agvtask.go @@ -18,7 +18,7 @@ type AgvTask struct { ID int `json:"id,omitempty"` // 我方任务号(内部) TaskNo string `json:"task_no,omitempty"` - // 海康返回 robotTaskCode(MOCK- 开头为模拟) + // RCS-Lite 任务单号(即我方 task_no,下发时透传 taskCode) HikTaskCode string `json:"hik_task_code,omitempty"` // 起点接驳台(常为 DOCK21 库房) SourceDock string `json:"source_dock,omitempty"` @@ -30,7 +30,7 @@ type AgvTask struct { RelatedRequestNo string `json:"related_request_no,omitempty"` // 关联出库单号(可选, WMS 回传) RelatedOutboundNo string `json:"related_outbound_no,omitempty"` - // PENDING/DISPATCHED/DELIVERING/DONE/FAILED/CANCELLED + // PENDING/FAILED/1已创建/2执行中/5已取消/9已结束 Status string `json:"status,omitempty"` // 下发人 Operator string `json:"operator,omitempty"` diff --git a/bj_power_mes/ent/migrate/schema.go b/bj_power_mes/ent/migrate/schema.go index f6ca028..bd66cc0 100644 --- a/bj_power_mes/ent/migrate/schema.go +++ b/bj_power_mes/ent/migrate/schema.go @@ -13,13 +13,13 @@ var ( AgvTasksColumns = []*schema.Column{ {Name: "id", Type: field.TypeInt, Increment: true}, {Name: "task_no", Type: field.TypeString, Unique: true, Size: 64, Comment: "我方任务号(内部)"}, - {Name: "hik_task_code", Type: field.TypeString, Size: 64, Comment: "海康返回 robotTaskCode(MOCK- 开头为模拟)", Default: ""}, + {Name: "hik_task_code", Type: field.TypeString, Size: 64, Comment: "RCS-Lite 任务单号(即我方 task_no,下发时透传 taskCode)", Default: ""}, {Name: "source_dock", Type: field.TypeString, Size: 20, Comment: "起点接驳台(常为 DOCK21 库房)", Default: ""}, {Name: "target_dock", Type: field.TypeString, Size: 20, Comment: "终点接驳台 DOCK01..20", Default: ""}, {Name: "materials_json", Type: field.TypeString, Size: 4000, Comment: "物料清单 JSON", Default: ""}, {Name: "related_request_no", Type: field.TypeString, Nullable: true, Size: 64, Comment: "关联叫料单号(MES material_request.requestNo)", Default: ""}, {Name: "related_outbound_no", Type: field.TypeString, Nullable: true, Size: 64, Comment: "关联出库单号(可选, WMS 回传)", Default: ""}, - {Name: "status", Type: field.TypeString, Size: 20, Comment: "PENDING/DISPATCHED/DELIVERING/DONE/FAILED/CANCELLED", Default: "PENDING"}, + {Name: "status", Type: field.TypeString, Size: 20, Comment: "PENDING/FAILED/1已创建/2执行中/5已取消/9已结束", Default: "PENDING"}, {Name: "operator", Type: field.TypeString, Size: 64, Comment: "下发人", Default: ""}, {Name: "dispatched_at", Type: field.TypeInt64, Comment: "下发时间 unix秒", Default: 0}, {Name: "arrived_at", Type: field.TypeInt64, Comment: "到位时间 unix秒", Default: 0}, diff --git a/bj_power_mes/etc/bj_power_mes-api.yaml b/bj_power_mes/etc/bj_power_mes-api.yaml index e96f4eb..fe69c8e 100644 --- a/bj_power_mes/etc/bj_power_mes-api.yaml +++ b/bj_power_mes/etc/bj_power_mes-api.yaml @@ -56,13 +56,14 @@ Plc: Host: 127.0.0.1 Port: 102 -# 海康 AGV(RCS-2000) 对接(2026-10-14 由 WMS 迁至 MES 为唯一真源):未接真实 RCS 前保持 mock -# 现场对接时填 EnableMock: false + RCS 服务地址(BaseURL 已含 /rcs/rtas) + appKey/appSecret +# 海康 AGV(RCS-Lite V1.5) 对接(2026-10-17 由 RCS-2000 改为 RCS-Lite 1.5):无签名鉴权 +# 未接真实 RCS-Lite 前保持 mock(EnableMock: true);现场对接时填 EnableMock: false + BaseURL(默认端口 8182,含 /rCMS/services/rest/hikRpcService) Agv: EnableMock: true BaseURL: "" - AppKey: "" - AppSecret: "" + CarrierCode: "" + MapCode: "" + Priority: "1" # 扫码中间件(键盘 HID 注入):默认关闭。需用扫码枪注入时才改 Enabled: true 并重启。 # 注意:若 MES 与 WMS 同机且都开,7757 谁先启动谁监听,后到的只记日志(不退出、不影响主进程)。 diff --git a/bj_power_mes/frontend/src/components/AttachmentPanel.vue b/bj_power_mes/frontend/src/components/AttachmentPanel.vue index 994777f..32f0dd6 100644 --- a/bj_power_mes/frontend/src/components/AttachmentPanel.vue +++ b/bj_power_mes/frontend/src/components/AttachmentPanel.vue @@ -135,7 +135,7 @@ defineExpose({ load }) - + - +