机器人对接协议V1.0.4

1. 接口说明

1.1 概述

为方便各种智能设备对机器人平台，制定标准的接入规范，特撰写该文档，帮助研发人员快速开展工作。

1.2 基本规则

设备通过 HTTP 对接平台，上下行消息响应的超时，时间为 30 秒。
接入用户通过分配：AK，SK，完成身份认证：数字、大小写字母组成，长度不超过 32。
本协议为机器人平台通用定义，需根据自身能力实现对应部分。

1.3 签名校验值说明

签名校验值的计算方式为：签名检验值 = SHA256(ak + sk + timestamp + nonce)

如 ak:ak，sk:sk ，timestamp: 1652428470，nonce: 12AKz789 SHA256(aksk165242847012AKz789)，值为：ee5c4cbef3ccb944dc4472c44364120235307f56ae37e121d19dcc43d6a153d7

以 x-onewo-* 的形式放在 Header 中

参数名称	说明
x-onewo-ak	Access Key ID
x-onewo-nonce	八位随机数（0-9 a-z A-Z）如:12AKz789
x-onewo-timestamp	timestamp：时间戳，精确到秒，与服务器时间相差不能大于 120 秒
x-onewo-sign	安全签名，签名检验值 SHA256(ak+sk+timestamp+nonce)

2. 协议定义

2.1 查询地图接口

接口功能

根据机器人 ID 查询该机器人支持的地图数量和详情

调用方法

POST

接口路径

http://server:port/api/robot/map/query

注意事项

机器人 ID 为必填唯一标识
返回结果中包含地图所属场景、创建信息等核心字段

参数说明

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识，示例：1924706921705771012

返回结果

字段	类型	必选/可选	位置	描述
code	int	必选	body	0 为成功，参照附录A
data	Array		body	地图列表数据
city	String	可选	data	地图所属城市
createBy	String	可选	data	创建人 ID
createTime	String		data	创建时间，格式：yyyy-MM-dd HH:mm:ss
id	String	必选	data	地图 ID
robotCount	int	必选	data	支持该地图的机器人数量
sceneLabel	String	可选	data	场景标签
sceneName	String	可选	data	场景名称
sceneType	String	可选	data	场景类型（如：小区）
serialNumbers	String	可选	data	设备序列号
tenantId	String	可选	data	租户 ID
tenantName	String	可选	data	租户名称
updateBy	String	可选	data	更新人 ID
updateTime	String		data	更新时间，格式：yyyy-MM-dd HH:mm:ss

消息示例

Request body：

json

{
  "robotId": "1924706921705771012"
}

Response body：

json

{
  "code": 0,
  "data": [
    {
      "city": "青岛",
      "createBy": "1",
      "createTime": "2025-04-15 18:01:13",
      "id": "1",
      "robotCount": 1,
      "sceneLabel": "魅力新城1期",
      "sceneName": "test67",
      "sceneType": "小区",
      "serialNumbers": "LGMCABHB4R1000067",
      "tenantId": "123",
      "tenantName": "青岛-魅力新城1期",
      "updateBy": "1",
      "updateTime": "2025-11-12 13:43:35"
    }
  ]
}

2.2 查询作业区域

接口功能

根据机器人 ID 和地图 ID 返回作业区域

调用方法

POST

接口路径

http://server:port/api/robot/work-areas/query

注意事项

需同时传入机器人 ID 和地图 ID，二者为关联查询核心参数

参数说明

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识
mapId	必选	String	body	地图 ID（场景名称），示例：test67

返回结果

字段	类型	位置	描述
code	int	body	0 为成功，参照附录A
data	Array	body	线路列表数据
createTime	String	data	创建时间，格式：yyyy-MM-dd HH:mm:ss
areaId	String	data	区域 ID
areaName	String	data	区域名称

消息示例

Request body：

json

{
  "robotId": "1924706921705771012",
  "mapId": "test67"
}

Response body：

json

{
  "code": 0,
  "data": [
    {
      "createTime": "2025-11-27 11:16:21",
      "areaId": "26697",
      "areaName": "创智云演示1_fusion"
    },
    {
      "createTime": "2025-11-27 11:16:21",
      "areaId": "26698",
      "areaName": "演示1_fusion"
    }
  ]
}

2.3 查询排班任务

接口功能

查询某段时间范围内排班任务

调用方法

POST

接口路径

http://server:port/api/robot/query/tasks

注意事项

需提前确认地图 ID 和线路 ID 的有效性
默认巡逻模式为无限循环，无圈数限制

参数说明

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识
startDateTime	必选	String	body	地图 ID，示例：2025-12-11 11:21:00
endDateTime	必选	String	body	线路 ID，示例：2025-12-11 15:21:00

返回结果

字段	类型	位置	描述
code	int	body	0 为成功，参照附录A
data	array	body
taskId	String	String	任务ID
mapId	String	String	MapID
planDateTime	String	data	计划开始时间：2025-12-11 15:21:00
areaList	data	data	区域列表
areaId	String	areaList	区域ID
areaName	String	areaList	区域名

消息示例

Request body：

json

{
  "robotId": "1924706921705771012",
  "startDateTime": "2025-12-11 11:21:00",
  "endDateTime": "2025-12-11 11:21:00"
}

Response body：

json

{
  "code": 0,
  "data": [
    {
      "taskId": "cb2b59b0-eee6-11f0-bd2b-dd74bb160049",
      "mapId": "aea1111a-a1f3-4a30-8421-888f8ce8b51e",
      "planDateTime": "2025-12-11 15:21:00",
      "areaList": [
        {
          "areaId": "1",
          "areaName": "监控区"
        },
        {
          "areaId": "2",
          "areaName": "麦当劳"
        },
        {
          "areaId": "3",
          "areaName": "tower1"
        },
        {
          "areaId": "4",
          "areaName": "楼栋后道"
        }
      ]
    },
    {
      "taskId": "d87e2310-8a5c-4789-b12e-9876543210ab",
      "mapId": "b822222b-b2f4-5b41-9522-999g8df9662f",
      "planDateTime": "2025-12-12 09:30:00",
      "areaList": [
        {
          "areaId": "5",
          "areaName": "美宜家"
        },
        {
          "areaId": "6",
          "areaName": "垃圾测试区"
        }
      ]
    }
  ],
  "msg": "SUCCESS"
}

2.4 启动与停止接口

接口功能

通过 control 参数控制机器的启动和停止状态

调用方法

POST

接口路径

http://server:port/api/robot/control/startstop

注意事项

control 参数取值：1 = 启动，0 = 停止

参数说明

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识
control	必选	int	body	控制状态（1 = 启动，0 = 停止）
taskId	必选	String	body	任务id

返回结果

字段	类型	位置	描述
code	int	body	0 为成功，参照附录A
msg	String	body	状态码描述

消息示例

Request body：

json

{
  "robotId": "1924706921705771012",
  "taskId": "1924706921705",
  "control": 1
}

Response body：

json

{
  "code": 0,
  "msg": "SUCCESS"
}

2.5 返航与充电接口

接口功能

通过 taskMode 参数控制机器人返航到充电桩

调用方法

POST

接口路径

http://server:port/api/robot/task/returncharge

注意事项

taskMode=4 固定为返航充电指令

参数说明

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识，示例：1924706921705771000
taskMode	必选	int	body	任务模式（4 = 返航充电）

返回结果

字段	类型	位置	描述
code	int	body	0 为成功，参照附录A
msg	string	body	状态码描述（0 表示无异常）

消息示例

Request body：

json

{
  "robotId": 1924706921705771000,
  "taskMode": 4
}

Response body：

json

{
  "code": 0,
  "msg": "SUCCESS"
}

2.6 状态事件查询与推送接口

接口功能

实时查询或推送机器的运行状态、位置、任务执行情况等核心信息

调用方法

POST（查询）/ Push（推送）

接口路径

查询路径：http://server:port/api/robot/status/query
推送路径：http://server:port/api/robot/event/statuspush（采用 WebSocket/MQ 方式）

注意事项

包含位置信息、任务信息、设备状态三大核心模块
经纬度、姿态角等参数为实时定位数据
鉴权和其他接口一致

查询参数

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识

返回/推送结果

字段	类型	必选/可选	位置	描述
code	int	必选	body	0 成功
bid	String		body	业务 ID
ts	String		body	数据时间戳，格式：yyyy-MM-dd HH:mm:ss
locationInfo	Object		data	位置信息
latitude	double	必选	locationInfo	纬度
longitude	double	必选	locationInfo	经度
x	double	必选	body	地图 x 坐标
y	double	必选	body	地图 y 坐标
height	double	可选	locationInfo	高度
pitch	double	可选	locationInfo	俯仰角
roll	double	可选	locationInfo	横滚角
yaw	double	可选	locationInfo	偏航角
rtkStatus	int	可选	locationInfo	RTK 状态
rtkVel	double	可选	locationInfo	RTK 速度
taskInfo	Object	可选	data	任务信息（可能存在无任务状态）
taskId	Object	必选	data	任务ID
businessStatus	int	必选	taskInfo	业务状态：0未知,1取消,2开始,3暂停 4 结束
mapName	String	必选	taskInfo	当前地图名称
curKeypointName	String	可选	taskInfo	当前关键点名称
nextKeypointName	String	可选	taskInfo	下一个关键点名称
allAlarmCount	int	可选	taskInfo	总报警次数
businessRemainTime	double	可选	taskInfo	剩余运行时间（秒）
vehicleInfo	Object		data	设备信息
socEnergy	int	必选	vehicleInfo	剩余电量（%）
speed	double	可选	vehicleInfo	当前速度
status	int	必选	vehicleInfo	设备状态（1:正常运行、0：离线）
batteryStatus	int	必选	vehicleInfo	0：IDLE(空闲)、1：CHARGING(充电中)、2：CHARGE_FULL(充满电)、3：CHARGE_ERROR_CONTACT(充电连接异常)、4：CHARGE_ERROR_ELECTRIC(电流异常)、5：ERROR_BATTERY_PACK_COMM(通讯异常)、6：ERROR_OVER_VOLT(电压异常)、7：ERROR_OVER_ELECTRIC(电流异常)、8：ERROR_OVER_TEMPERATURE(温度异常)、9：ERROR_OVER_TIME(超时异常)
serialNumber	String	可选	vehicleInfo	设备序列号

消息示例

查询 Request body：

json

{
  "robotId": "1924706921705771012"
}

返回/推送 Response body：

json

{
  "code": 0,
  "bid": "305502",
  "data": {
    "locationInfo": {
      "diffAgeTime": -999,
      "gnssSateNum": 0,
      "height": 16.630322911104443,
      "inspvaxDeviation": "0.030443",
      "inspvaxStatus": "INS_ALIGNMENT_COMPLETE&INS_RTKFLOAT",
      "latitude": 36.28666815758092,
      "longitude": 120.39769443553882,
      "pitch": 1.9935941906465906,
      "roll": -5.101920388666848,
      "rtkStatus": 6,
      "rtkVel": 0.0,
      "rtkVelDirection": 0.0,
      "slaveAntGnssQuality": -999,
      "x": 266287.88528354245,
      "y": 4018887.2495166436,
      "yaw": 273.2594422053095,
      "z": 16.630322911104443
    },
    "taskInfo": {
      "alarmCaptureDangersCount": 0,
      "alarmCaptureIllegalCount": 0,
      "alarmCaptureKeypointCount": 0,
      "alarmCapturePersonCount": 21,
      "alarmCaptureVehicleCount": 176,
      "alarmEmergencyStopCount": 0,
      "alarmShoutCount": 0,
      "alarmSosCount": 0,
      "allAlarmCount": 197,
      "businessAllPowerConsumption": 257.3809110000075,
      "businessCompletionPercent": 0.0,
      "businessFinishTime": 1758156674442,
      "businessMode": 5,
      "businessPowerConsumption": 0.0,
      "businessRemainTime": 80150.93,
      "businessRunningTime": 26506.0,
      "businessStartTime": 1758130169000,
      "businessStatus": 2,
      "businessTaskName": "",
      "businessTotalMileage": 0.0,
      "controlMode": 0,
      "curKeypointIndex": 1228,
      "curKeypointName": "进车库道闸",
      "curPatrolPointIndex": -1,
      "curPlanedPatrol": "",
      "globalPathIndex": -1,
      "isArrivePatrolPoint": false,
      "isPatrolPointActionFinish": false,
      "loops": 0,
      "mapName": "魅力新城1期北侧全覆盖巡逻_fusion",
      "mapRecordMapName": "",
      "mapRecordMapSceneName": "",
      "mapVersion": "2_0_0",
      "nextKeypointIndex": 1663,
      "nextKeypointName": "3楼-3消174垃",
      "preKeypointIndex": 145,
      "preKeypointName": "起点",
      "prePlanedPatrol": "",
      "sceneId": "test67",
      "takeoverCount": 0,
      "taskEndSoc": 0,
      "taskId": "LGMCABHB4R1000067_20250918012759",
      "taskStartSoc": 0
    },
    "vehicleInfo": {
      "alarmCodes": "",
      "alarmLevels": "",
      "alarmNames": "",
      "alarmStatus": "0",
      "batteryStatus": 0,
      "cameraPtk": "{\"ptk_focus\":\"291.310000\",\"ptk_vertical\":\"0.000000\",\"camera_ptk_20250918085114\":\"open\",\"ptk_horizontal\":\"180.000000\",\"ptk_zoom\":\"0.000000\"}",
      "capture": 0,
      "deviceId": 403,
      "emergencyStop": 0,
      "firmwareVersion": "{\"system\":\"\",\"business\":\"\",\"decision\":\"\",\"selfdriving\":\"\",\"control\":\"\",\"communication\":\"\",\"perception\":\"\"}",
      "frontLight": 0,
      "gear": 1,
      "lowBatteryStatus": 0,
      "mileageDevActivation": 859.0,
      "mileagePowerOn": "31.0",
      "net4gDelay": "0",
      "net4gLoss": "103.670",
      "obstacleStatus": 0,
      "productId": 156,
      "rainMode": 0,
      "serialNumber": "LGMCABHB4R1000067",
      "slideBarMode": 0,
      "socAmpere": 2.6,
      "socEnergy": 99,
      "socVoltage": 2.6,
      "speaker": 1.0,
      "speed": 0.0,
      "status": 1,
      "steerAngle": 0.019999999552965164,
      "tenantId": 1,
      "timeDevActivation": 2419.0,
      "timePowerOn": "85.3",
      "timePowerOnTimestamp": 1757849519000,
      "userId": 1,
      "vehicleRunningMode": 0,
      "warnLight": 0,
      "warnVoice": 0
    }
  },
  "ts": "2025-09-18 08:51:14"
}

2.7 定点清洁任务

接口功能

指定目标坐标后，机器人从当前位置移动到目标点位，进行清扫任务

调用方法

POST

接口路径

http://server:port/api/robot/move/pointtopoint

注意事项

x/y 为目标点位的平面坐标，需与当前地图坐标系一致

参数说明

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识，示例：1996406593067028517
mapId	必选	String	body	当前地图 ID，示例：26791
x	必选	String	body	目标点位 X 坐标，示例：1.2564
y	必选	String	body	目标点位 Y 坐标，示例：-2.4973
radius	可选	Float	body	作业半径，单位米

返回结果

字段	类型	位置	描述
code	int	body	0 为成功，参照附录A
data	Object	body
taskId	String	Data	任务ID
status	Int	Data	0未知,1取消,2开始,3暂停 4 结束
msg	String	body	状态码描述

消息示例

Request body：

json

{
  "robotId": 1996406593067028517,
  "sourceMapId": "26791",
  "x": 1.2564,
  "y": -2.4973,
  "radius": 25.0
}

Response body：

json

{
  "code": 0,
  "data": {
    "taskId": "122331244",
    "status": 0
  },
  "msg": "SUCCESS"
}

2.8 作业计划排班配置

接口功能

配置机器人作业计划的排班规则，包括重复类型、执行时间及生效日期范围。

2.9 文件上传下载说明

此部分主要描述文件的传输认证。本文档涉及到的图片上传和下载、日志文件上传，均需要增加认证信息在 HTTP Header 中。

2.9.1 上传路径生成规则

上传路径为：{ossPreUrl}/{resource}/

ossPreUrl：获取配置中 ossPreUrl 值

/{resource}/{action} 为：resource 对应业务的值。如果值不存在，置为 unknown 字符串。action 1 表示上传

如：上传拍照，resource：capture，action：1。假设 ossPreUrl 值为：https://xxx.com/upload/

上传的路径为：https://xxx.com/upload/capture/1

2.9.2 文件上传请求示例

bash

curl --location --request POST 'https://***com/v1/uploadFile4Device/10/pass/1' \
--header 'x-onewo-nonce: ***456' \
--header 'x-onewo-timestamp: 1656657073' \
--header 'x-onewo-ak: ***99' \
--header 'x-onewo-sign: afa3bdb72cc421e85c0d5b730b889fea0975bceac8d85c46e7***' \
--form 'image=@"******.jpg"'

json

{
  "code": 0,
  "msg": "上传成功",
  "data": "capture/20220722/daddf1637894c54d3d9643e286ef040e"
}

2.10 查询清洁任务状态

接口功能

进行清扫任务的任务状态查询

调用方法

POST

接口路径

http://server:port/api/robot/move/pointtopoint/status

注意事项

无

参数说明

参数	必选/可选	类型	位置	描述
robotId	必选	String	body	机器人唯一标识
taskId	必选	String	body	任务id

返回结果

字段	类型	位置	描述
code	int	body	0 为成功，参照附录A
data	Object	body
taskId	String	Data	任务ID
status	Int	Data	0未知,1取消,2开始,3暂停 4 结束
msg	String	body	状态码描述

消息示例

Request body：

json

{
  "robotId": 1996406593067028517,
  "taskId": "26791"
}

Response body：

json

{
  "code": 0,
  "data": {
    "taskId": "122331244",
    "status": 0
  },
  "msg": "SUCCESS"
}

附录A

A.1 编码规则说明

共用编码

0 为正常，其他为异常

0-999 为所有子系统共用编码

100-199 用于指定客户端应相应的某些动作。

400-499 用于指出客户端的错误。

500-599 用于支持服务器错误。

业务系统编码

业务系统编码共六位格式如：100000

一到二位即 10-99 各业务系统编码 10: 扫地机器人 11:巡检机器人 12：梯控

三位表示异常类型级别 0-9 值越大表示异常越严重

4-6位各业务系统内部定义编码

如：104000 机器人ID错误。10（1-2位）表示机器人编码、4（第三位）表示异常等级、000（4-6位）表示业务系统自定义编码

A.2 编码分类

编码大类	编码	说明
共用编码	0	成功
	-1	失败
	401	未授权
	402	sign签名验证失败，x-onewo-timestamp或AK或SK错误，验证失败
	403	禁止访问
	404	服务未找到，command或resource或action错误
	405	发送超时
	406	设备未在线
	407	权限异常
	413	body超长
	414	JSON格式不合法
	415	时间异常
	500	服务内部异常错误
	502	Bad Gateway
	503	服务不可用（无此服务）
	600	未登陆（token过期）
	602	用户或密码错误
	603	登陆验证受限制
扫地机器人	104000	机器人ID错误
	101001	照片不合规
	107002	子系统未在线
	104003	用户不存在
	104500	子系统异常
	104501	空间参数错误
	104502	前端软件接口异常

机器人对接协议V1.0.4 ​

1. 接口说明 ​

1.1 概述 ​

1.2 基本规则 ​

1.3 签名校验值说明 ​

1.3.1 认证 Header 公共参数 ​

2. 协议定义 ​

2.1 查询地图接口 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

参数说明 ​

返回结果 ​

消息示例 ​

2.2 查询作业区域 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

参数说明 ​

返回结果 ​

消息示例 ​

2.3 查询排班任务 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

参数说明 ​

返回结果 ​

消息示例 ​

2.4 启动与停止接口 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

参数说明 ​

返回结果 ​

消息示例 ​

2.5 返航与充电接口 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

参数说明 ​

返回结果 ​

消息示例 ​

2.6 状态事件查询与推送接口 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

查询参数 ​

返回/推送结果 ​

消息示例 ​

2.7 定点清洁任务 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

参数说明 ​

返回结果 ​

消息示例 ​

2.8 作业计划排班配置 ​

接口功能 ​

2.9 文件上传下载说明 ​

2.9.1 上传路径生成规则 ​

2.9.2 文件上传请求示例 ​

2.10 查询清洁任务状态 ​

接口功能 ​

调用方法 ​

接口路径 ​

注意事项 ​

参数说明 ​

返回结果 ​

消息示例 ​

附录A ​

A.1 编码规则说明 ​

共用编码 ​

业务系统编码 ​

机器人对接协议V1.0.4

1. 接口说明

1.1 概述

1.2 基本规则

1.3 签名校验值说明

1.3.1 认证 Header 公共参数

2. 协议定义

2.1 查询地图接口

接口功能

调用方法

接口路径

注意事项

参数说明

返回结果

消息示例

2.2 查询作业区域

接口功能

调用方法

接口路径

注意事项

参数说明

返回结果

消息示例

2.3 查询排班任务

接口功能

调用方法

接口路径

注意事项

参数说明

返回结果

消息示例

2.4 启动与停止接口

接口功能

调用方法

接口路径

注意事项

参数说明

返回结果

消息示例

2.5 返航与充电接口

接口功能

调用方法

接口路径

注意事项

参数说明

返回结果

消息示例

2.6 状态事件查询与推送接口

接口功能

调用方法

接口路径

注意事项

查询参数

返回/推送结果

消息示例

2.7 定点清洁任务

接口功能

调用方法

接口路径

注意事项

参数说明

返回结果

消息示例

2.8 作业计划排班配置

接口功能

2.9 文件上传下载说明

2.9.1 上传路径生成规则

2.9.2 文件上传请求示例

2.10 查询清洁任务状态

接口功能

调用方法

接口路径

注意事项

参数说明

返回结果

消息示例

附录A

A.1 编码规则说明

共用编码

业务系统编码