WATER（水滴）软件API手册

北京云迹科技有限公司

文档版本: v1.8.9
**修订日期: 2022-12-26 **

各版本重要改动说明:

v1.3.1 (2016-11-3)

添加部分解释性文字。
接口3 获取机器人当前全局状态中添加了字段"move_retry_times"用于反馈机器人移动中的内部重试次数。
接口5 点位功能接口中修改了三个字段：name->marker_name, location->pose, type->key 。

v1.4.0 (2017-1-6)
针对软件0.4.0版本修改了以下内容：

api指令前去掉http://192.168.10.10:8808字样。（原来的api格式仍可使用）

server端发出的json中增加"type"等字段, 用以区分packet类别。

增加接口使server能以一定频率发送"robot status", 见接口9 请求机器人实时数据。

增加server端主动发出状态通知的功能，见接口10 机器人主动通知。

v1.5.0 (2017-1-17)

增加接口11 设置参数、接口12 获取参数，可以设置/获取机器人参数。(目前仅支持机器人最大行进速度参数)

v1.6.0 (2017-5-29)

接口11 设置参数、接口12 获取参数中，将机器人最大行进速度参数更改为机器人最大行进速度百分比。

接口3 获取机器人当前全局状态中，增加软硬急停状态。

增加接口13 无线网络接口、接口14 地图接口、接口15 关机重启接口。

接口10 机器人主动通知接口中新增电梯相关通知。

v1.6.3 (2017-7-4)

增加接口16 软件更新接口。

v1.6.4 (2017-7-14)

更新接口15 关机重启接口。

接口10 机器人主动通知中增加poweroff/急停/充电状态/回充电失败通知。

v1.6.5 (2017-9-30)

增加接口17 设置灯带接口。

v1.6.7 (2017-10-19)

合并[接口4 插入新的marker点位]和[接口5 获取marker点位列表] 到接口5 点位(marker)功能接口

增加 [接口5.3 删除marker点位]

增加接口4 获取机器人信息

v1.6.8 (2018-04-09)
针对软件0.7.3版本增加了以下内容：

接口1 机器人移动功能，接口调用成功后，在response里增加一个字段表示任务ID。

接口10 机器人主动通知,新增机器人移动时被困住的警告和移动重试通知的说明。

接口10 机器人主动通知,新增机器人触发姿态校正的通知。

接口10 机器人主动通知,新增电梯空间不够的情况下，乘坐下一趟电梯的通知。

v1.7.1 (2018-05-29)
针对软件0.7.4版本增加了以下内容：

接口1 机器人移动功能中新增巡游接口。

接口10 机器人主动通知,新增巡游通知, 新增闸机/电子门控制通知。新增data字段作为通知的补充信息。

接口5.2获取marker点位列表, 增加参数可以按楼层查询点位。增加接口5.4获取点位个数，增加接口5.5获取点位摘要信息。

v1.7.2 (2018-07-10)
针对软件0.7.6版本增加了以下内容：

接口10 机器人主动通知,新增两种机器人被困类型的通知。任务结束的通知里增加字段表示本次任务行走的距离。

v1.7.3 (2018-07-27)
针对软件0.7.7版本增加了以下内容：

接口3 获取机器人当前全局状态返回的状态中，增加"error_code"字段。

接口9 请求机器人实时数据新增人检测数据接口。

增加接口13.5 获取机器人当前可用的无线列表详细信息。

v1.7.4 (2018-08-17)
针对软件0.7.8版本增加了以下内容：

接口14.3 获取当前地图中增加地图分辨率等信息。

v1.7.5 (2018-09-04)
针对软件0.7.9版本增加了以下内容：

增加接口19获取电源状态接口。

接口10 机器人主动通知,新增全局路径规划失败的通知。

v1.7.6 (2018-09-07)

修改接口11 设置参数中机器人行进速度比例参数取值范围,增加对参数的描述。

v1.7.7 (2018-11-15)

增加9.3获取机器人实时速度接口。

增加5.6指定坐标标记marker接口。

增加8.2指定坐标校正机器人位置接口。

v1.7.8 (2019-02-19)

接口1 机器人移动功能中增加最大连续重试次数参数。

接口1.1 单目标点移动中增加距离和角度容差参数。

接口3 获取机器人当前全局状态中增加"running_status"字段。

v1.7.9 (2019-06-15)

接口15 关机重启接口中增加参数设定延迟重启的时间。

接口10 机器人主动通知中增加等待电梯解锁的通知。

接口3 获取机器人当前全局状态running_status字段中增加等待电梯解锁状态。

v1.8.0 (2019-09-16)

接口1.1 单目标点移动中增加角度偏移参数。

接口10 机器人主动通知中增加软件服务即将关闭的通知。

v1.8.1 (2019-10-26)

增加16.4 重启服务接口。

增加20 获取机器人全局路径接口

v1.8.2 (2020-03-16)

增加21 获取电梯状态接口

更新接口11 设置参数，增加设置机器人运行最大线速度、角速度接口。

v1.8.3 (2020-07-16)

接口1.1 单目标点移动中增加是否允许双向停靠参数，仅对支持双向行走的机器人生效。

接口1.1 单目标点移动中增加让步停靠距离参数，提高某些场景下机器人完成任务的灵活性。

增加17.2 设置灯带颜色接口。

v1.8.4 (2021-02-23)

增加22. 获取两点间路径接口。

接口10 机器人主动通知中增加因找不到可用路径导致移动任务直接失败的通知。

v1.8.5 (2021-03-11)

增加14.4 获取地图列表详情接口。

v1.8.6 (2021-05-19)

接口10 机器人主动通知中增加"机器人可能迷路"的通知。

接口10 机器人主动通知中增加"回充超时失败"的通知。

v1.8.7 (2021-11-02)

增加接口14.5给定目标点，在目标点附近寻找可到点的位置

增加接口14.6 给定目标点，查询到静态地图障碍和传感器探测障碍物的距离

v1.8.8 (2022-03-18)

接口10 机器人主动通知中增加code="01210"通知。

v1.8.9 (2022-12-26)

增加接口23 获取机器人当前位置接口

适用环境:

基于TCP socket的网络通信。

协议形式和连接方式:

协议形式：接口内容采用类url的字符串格式，接口反馈数据统一采用json格式，同级字段间没有前后关系，解析时请使用json的标准解析方式。

连接方式：TCP连接

网络设置：TCP客户端
服务器IP地址：

a) 192.168.10.10(这个是底盘主机的静态IP地址，TCP客户端主机需要通过路由器等设备与底盘主机建立局域网连接，有相同网段192.168.10.*)
b) 底盘通过API连接上局域网WiFi, 然后通过API获取的局域网IP。

服务器端口：31001

建议使用socket连接方式，因为串口通信有一定概率使数据传输错误。

接口使用说明：

通用解释:

通用参数"uuid"
- 如不做特殊说明，以下指令中均可携带uuid作为可选参数, server端执行完指令后在response中将其原样返回。
对于json中"type"字段的解释：
- "response" 表示对一条指令的响应
- "callback" 表示由server端以一定频率发送的数据
- "notification" 表示由server端发起的主动通知

示例：
客户端发送字符串: "/api/move?marker=target_name&uuid=123456"

返回:

{
    "type": "response",      // package类型
    "command": "/api/move",  // 源指令
    "error_message": "",	 // 错误消息
    "status": "OK",          // 执行结果
    "uuid": "123456"	     // 用户定义的uuid
}

1.机器人移动功能

1.1单目标点移动

指令：

/api/move

参数：

名称	说明	是否必选	备注	从以下版本开始
marker	目标点位代号	与location必选其一	优先级低于location
location	x<地图中x轴坐标>,y<地图中y轴坐标>,theta<地图中相对theta值>	与marker必选其一
max_continuous_retries	原地最大连续重试次数（机器人原地不动时，重试次数超过此值则任务失败)	可选	默认30次	0.7.11
distance_tolerance	距离容差,类型float,单位米。(当目标位置被占据等原因无法到达时，机器人移动到目标此距离之内也算任务成功。)	可选	默认值跟机器人型号相关	0.7.12
theta_tolerance	角度容差，类型float，单位弧度。(到达目标点位后，角度小于此值后任务成功)	可选	默认值跟机器人型号相关	0.7.12
angle_offset	到达位置后的角度偏移, 例如使用marker=m1发送任务时,会以m1的角度+angle_offset的角度作为最终方向执行任务.	可选	单位弧度, 范围[-3.14, 3.14], 默认0	0.8.2
yaw_goal_reverse_allowed	双向停靠控制参数，取值1或0或-1。对于双向行走的机器人，此参数用于机器人停靠到点位时，是否允许尾部跟点位方向一致。	可选	1:允许；0:不允许；其他: 使用默认	0.8.7
occupied_tolerance	让步停靠距离参数，单位米。当目标点位被占用时，设置此参数机器人会直接在点位附近停靠以完成任务，而不再尝试移动到点位上。距离以占用物边缘至机器人中心计算。	可选	[0.1, )	0.8.7

接口描述：

可使机器人从当前位置移动至地图中已经标定的某个目标点。

协议中对于移动指令部分包括两大主要的形式：

对于需要使机器人在运动过程中使用自动导航和避障功能的，请使用此接口；

如果需要使用诸如手柄遥控功能的，请使用接口6，会直接操控机器人两轮的速度;

在使用此接口之前还有必要的扫图工作需要使用者提前安排（云迹提供一套通过局域网连接机器人，然后登入浏览器进行扫图的方案，具体操作参考《WATER（水滴）用户使用手册》）。
参数中的location的坐标是相对于“地图”坐标系的，由于直接调用(x、y、theta)在使用中不够直观和方便，云迹提供“事先标锚点，而后使机器人重返锚点”的工作形式。之后“锚点”统一用marker代称，设置和查询已设锚点的方式见接口4、接口5。

机器人采用自动导航和避障的过程中，机器人会自动规划路径和调节速度，过程中不需要操作者干预。操作者可以监听robot_status(机器人整体和行进状态)，或者等待相应的notification，以了解任务完成情况和整机状态。

示例:

发送:

/api/move?marker=target_name
// 调用移动接口，移动至代号为"target_name"的目标点
/api/move?location=15.0,4.0,1.5707963
// 调用移动接口，移动至location(15.0, 4.0, pai/2)的目标点

返回:

{
    "type": "response",
    "command": "/api/move",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "task_id": "xxx" // （软件版本0.7.3之后新增） 32个字节的uuid，例如：436253D1D6284ACC984620CCB94EB5E5
}

1.2多目标点移动

指令：

/api/move

参数：

名称	说明	是否必选	备注	从以下版本开始
markers	想要巡游的点位列表，点位名称之间用英文逗号分开	必选	不能少于两个点位，不支持跨楼层
count	巡游的次数，所有点位走过一遍之后计为一次	可选	不选时为默认一次，-1表示无限循环。
distance_tolerance	点位到达时的容差，表示靠近点位多少距离时继续下一个点位。	可选	默认0.5(米),最小0.5
max_continuous_retries	原地最大连续重试次数（机器人原地不动时，重试次数超过此值则去当前巡游点位任务失败)	可选	默认5次	0.7.11

接口描述：

作为接口1.1单目标点移动的扩展，实现了多个点之间不间断的循环移动。考虑从充电桩出发的情况，不支持多楼层间移动，v0.7.11版本后支持回充电桩。
在整个巡游过程中任务状态都是"running", 在巡游开始和结束时会有巡游通知发出，在点位间会有普通移动通知发出。单个巡游目标点移动失败后，会继续去往下个目标点。
结束巡游指令跟结束单点移动任务指令一样，都是通过接口2 移动取消功能。

示例:

发送:

/api/move?markers=m1,m2,m3&distance_tolerance=1.0&count=-1

返回:

{
    "type": "response",
    "command": "/api/move",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "task_id": "xxx" // （软件版本0.7.3之后新增） 32个字节的uuid，例如：436253D1D6284ACC984620CCB94EB5E5
}

2.移动取消功能

指令：

/api/move/cancel

参数：

N/A

接口描述：

使机器人主动放弃当前正在执行的移动任务，成功取消后可使机器人进入新的待命状态。
在机器人执行接口1-机器人移动命令过程中，如果需要终止机器人当前的移动状态，可以调用此接口。机器人会在接收“移动取消”命令之后，原地停止，等待再次的move指令。

示例:

发送:

/api/move/cancel
// 取消当前正在进行的移动指令

返回:

{
    "type": "response",
    "command": "/api/move/cancel",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

3.获取机器人当前全局状态

本接口作为兼容用户以前的软件版本保留，新用户推荐使用接口9----请求机器人实时数据。

指令：

/api/robot_status

参数：

N/A

接口说明：

获取机器人当前全局状态，包括移动任务的状态。
除配合接口1周期监听move的反馈之外，也可从此接口中监听机器人整机的其他信息，包括“是否处于充电状态”、“是否处于急停状态”、“所剩电池点量百分比”、“当前相对于地图的位置”、“当前楼层”，具体见示例。
建议调用频率为1-2HZ，可以实时监控任务状态，作为流程控制的逻辑判断。

示例：

发送:

/api/robot_status
// 获得机器人当前的全局状态

成功时返回:

{
    "type": "response",
    "command": "/api/robot_status",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
        "move_target": "target_name", // 移动指令指定的目标点位名称
        "move_status": "running", // 移动指令的执行状态。详细解释见后边
        "running_status": "running", // v0.7.12新增，移动任务的具体状态， 详细见后面解释
        "move_retry_times": 3, //此次数每增加1，表示机器人进行了新一轮的路径重试；路径规划一次性成功此值默认为0

        "charge_state": bool, //true->充电中状态。false->未充电状态。
        "soft_estop_state": bool, // 通过API接口设置的软急停状态, true->急停中，false->非急停中
        "hard_estop_state": bool, // 通过硬件急停按钮设置的硬急停状态, true->急停中，false->非急停中
        "estop_state": bool,  // hard_estop_state || sofpt_estop_state, true->急停中，false->非急停中
        "power_percent": 100, //电量百分比，单位：%
        "current_pose": {
            "x": 11.0,     // 单位：m
            "y": 11.0,	   // 单位：m
            "theta": 0.5, //单位：rad
        }
        "current_floor": 16,
        "chargepile_id": "1234", // v0.9.6新增。充电状态下表示当前正在充电的充电桩ID，非充电状态下返回“0”。注：此字段仅在部分产品中有效，其余返回“0”。
        "error_code": "00000000"   // v0.7.7新增，16进制错误码，总共8个字节表示，非0表示机器人异常
    }
}

失败时返回:

{
    "type": "response",
    "command": "/api/robot_status",
    "uuid": "",
    "status": "UNKNOWN_ERROR",
    "error_message": "Can't catch current robot status"
    "results"
}
失败时请检查地图是否设置正确或者硬件是否有故障。

对于移动任务相关字段的解释：

以下字段对应于机器人移动功能指令的状态查询。

move_target表示移动指令指定的点位名称。
当以"location"调用移动接口时，此字段值为空
当调用巡游接口时，此字段为当前正在前往的点位名称
move_status表示当前机器人去move_target的执行状态。。其取值及解释如下。

字段值	解释
idle	表示机器人服务启动后尚未收到任何移动指令。
running	表示机器人正在去往move_target,此时会拒绝接受新的移动指令。
succeeded	表示移动任务已经成功完成。
failed	表示移动任务失败了。
canceled	表示移动任务被取消了。

running_status表示当前机器人移动任务的具体状态, 底层实现是由通知触发, 在不能确保一定能收到通知的情况下, 可以以此字段作为判断条件。

字段值	对应move_status	解释	从以下版本开始	特别说明
idle	idle/suceeded/failed/canceld	机器人当前空闲,可以接受新的移动任务。	v0.7.12
leave_charging_pile	running	正在离开充电桩。	v0.7.12
leave_container	running	正在离开货柜。	v0.10.25C
leave_cabin	running	正在离开架子。	v0.10.25C
dock_to_charging_pile	running	正在自动停靠到充电桩。	v0.7.12
dock_to_container	running	正在自动停靠到货柜。	v0.10.25C
dock_to_cabin	running	正在自动停靠到架子。	v0.10.25C
goto_lift	running	正在去往电梯。	v0.7.12
wait_lift_unlock	running	等待电梯解锁。	v0.8.1	当有多台机器人需要乘坐同一部电梯时会触发此状态。
wait_lift_outside	running	正在电梯外等候电梯。	v0.7.12
enter_lift	running	正在进入电梯。	v0.7.12	此时最好不要随便调用移动取消功能，以免流程出错。
avoid_lift	running	进入电梯失败后正在避让电梯。	v0.7.12	此时最好不要随便调用移动取消功能，以免流程出错。
take_lift	running	正在乘坐电梯。	v0.7.12	此时最好不要随便调用移动取消功能，以免流程出错。
exit_lift	running	正在出电梯。	v0.7.12	此时最好不要随便调用移动取消功能，以免流程出错。
back_to_lift	running	出电梯失败正在回到电梯。	v0.7.12	此时最好不要随便调用移动取消功能，以免流程出错。
running	running	其它非关键性状态	v0.7.12

4.获取机器人信息接口

本接口至少需要软件版本0.6.3.3

指令：

/api/robot_info

参数：

N/A

指令说明：

调用接口可以获取机器人的一些基本信息。

示例：

发送：

/api/robot_info

返回：

{
    "type": "response",
    "command": "/api/robot_info",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
        "product_id": "WATER-xxxx-xxxxx"  // 机器人编号
     }
}

返回结果字段解释：

结果字段 | 解释 | 备注 | 从以下版本开始
----|------
product_id | 产品编号 | | 0.6.3.3

5.点位功能接口

5.1在机器人当前位置标记marker

指令：

/api/markers/insert

指令说明：

在机器人的当前位置和楼层标记锚点(marker)。

参数：

名称	说明	是否必选	备注
name	点位名字(string类型,不支持特殊字符)	必选	如果name已经存在，则更新坐标。
type	点位类型(int类型)	可选，默认为0	常用类型有：0(一般点位)，1(前台点)，7(闸机),3(电梯外),4(电梯内),11(充电桩)等等。每种类型的点位都具有特定的功能和各自的属性，除普通类型外其他类型请尽可能使用机器人监控页面进行添加，避免属性值异常造成程序运行的异常。在通常情况下不建议用户自定义类型，如果使用自定义类型请使用大于1000的值，以免跟机器人定义的类型产生冲突。随着机器人软件版本不同后续可能会增加新的类型以及类型对应的属性，请以监控页面建图工具里的标记点位为准。
num	点位编号(int类型)	可选，默认为1	某些类型的点位具有num(编号)属性，例如电梯点,闸机点，充电桩点等。

接口说明：

在当前地图中标记点位，让机器人记住这个点位（marker）。
调用此接口时，机器人会捕捉当前相对于地图坐标系的(x,y,theta)，并自动把捕捉到的锚点位置，存储在机器人的锚点列表中，以随时响应move的调用。如果不使用充电功能，接口中的type可以不设置。

示例：

发送：

/api/markers/insert?name=205_room
//调用该接口，将机器人当前位置设为marker点位，名字为205_room。默认为1层一般点位。
/api/markers/insert?name=charge_dock_2&type=11
//调用该接口，将机器人当前位置设为marker点位，名字为charge_dock_2，类型为充电桩。

返回：

操作成功时返回：
{
    "type": "response",
    "command": "/api/markers/insert",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

5.2获取marker点位列表

指令：

/api/markers/query_list

参数：

名称	说明	是否必选	备注	从以下版本开始
floor	想要查询的楼层	可选	如果不选则返回所有楼层的点位信息	0.7.4

接口说明：

获取机器人在当前地图中的所有点位(marker)信息, 每个点位信息中包括"点位名称"、"楼层"、"点位坐标"、"点位方向"和"点位类型"。
其中orientation以四元数的形式保存点位的方向，可以转化成前文阐述的坐标系中的theta

示例：

发送：

/api/markers/query_list

返回：

{
    "type": "response",
    "command": "/api/markers/query_list",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":{
    	"meeting_room": {
            "floor": 1, 
            "pose": {
                "orientation": {
                    "w": -0.899999976158142, 
                    "x": 0, 
                    "y": 0, 
                    "z": -0.430000007152557
                }, 
                "position": {
                    "x": -8.57999992370605, 
                    "y": 6.3600001335144, 
                    "z": 0
                }
            }, 
            "marker_name": "meeting_room", 
            "key": 0
        }, 
        ... // 其它点位信息
    }
}
// "marker_name"表示点位名称。"key"表示点位类型：0(一般点位)，11（充电桩）。"floor"表示点位所属楼层。"pose"表示具体坐标点。

点位不存在时返回：

{
    "type": "response",
    "command": "/api/markers/query_list",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": null
}

5.3删除marker点位

指令：

/api/markers/delete

参数：

名称	说明	是否必选	备注	从以下版本开始
name	点位名字	必选		0.6.3.4

接口说明：

删除已经标记的marker点位，如果点位名称不存在则返回失败。

示例：

发送：

/api/markers/delete?name=205_room

成功时返回：

{
    "type": "response",
    "command": "/api/markers/delete",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

失败时返回：

{
    "type": "response",
    "command": "/api/markers/delete",
    "uuid": "",
    "status": "INVALID_REQUEST",
    "error_message": "Marker Not Found"
}

5.4获取点位个数

本接口至少需要软件版本v0.7.4

指令：

/api/markers/count

参数：

N/A

接口说明：

获取当前地图中的点位数量。

示例：

发送：

/api/markers/count

返回：

{
    "type": "response",
    "command": "/api/markers/count",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
      "count": 10  // 当前地图中点位的数量
    }
}

5.5获取点位摘要信息

本接口至少需要软件版本v0.7.4

指令：

/api/markers/query_brief

参数：

N/A

接口说明：

查询当前地图所有点位的摘要信息，此接口返回比5.2获取marker点位列表更加简洁的点位信息。

示例：

发送：

/api/markers/query_brief

返回：

{
    "type": "response",
    "command": "/api/markers/query_brief",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
      "meeting_room": "0-1", // 点位名称：点位类型-楼层 
      "205_room": "0-1",
      ... // 其它点位信息
     }
}

5.6指定坐标标记marker

本接口至少需要软件版本v0.7.11

指令：

/api/markers/insert_by_pose

参数：

名称	说明	是否必选	备注
name	点位名字(string类型,不支持特殊字符)	必选	如果name已经存在，则更新坐标。
type	点位类型(int类型)	可选，默认为0	常用类型有：0(一般点位)，1(前台点)，7(闸机),3(电梯外),4(电梯内),11(充电桩)等等。每种类型的点位都具有特定的功能和各自的属性，除普通类型外其他类型请尽可能使用机器人监控页面进行添加，避免属性值异常造成程序运行的异常。在通常情况下不建议用户自定义类型，如果使用自定义类型请使用大于1000的值，以免跟机器人定义的类型产生冲突。随着机器人软件版本不同后续可能会增加新的类型以及类型对应的属性，请以监控页面建图工具里的标记点位为准。
num	点位编号(int类型)	可选，默认为1	某些类型的点位具有num(编号)属性，例如电梯点,闸机点，充电桩点等。
floor	楼层(int类型非0)	可选	默认为机器人当前楼层,如果楼层不存在则会返回错误.
x	地图坐标x(float类型)	必选	-
y	地图坐标y(float类型)	必选	-
theta	点位的方向(float类型)	必选	取值范围[-π, π]

theta与四元数转换关系C++ 示例:
假设四元数表示的方向为: o{x: 0, y:0, z: -0.430000007152557, w:-0.899999976158142}

double theta = 2*atan2(o.z, o.w)
if (theta > M_PI && theta <= (2*M_PI))
{
	theta -= 2*M_PI;
}
else if(theta < (-1*M_PI) && theta >= (-2*M_PI))
{
	theta += 2*M_PI;
}

接口说明：

在指定位置添加marker.

示例：

发送：

/api/markers/insert_by_pose?name=205_room&x=-0.1&y=1.0&theta=0.0&floor=2&type=0
//调用该接口，在位置(0.1,1.0), 方向(0.0), 楼层为2的位置添加名字为205_room的marker, 类型为一般点位。

返回：

操作成功时返回：
{
    "type": "response",
    "command": "/api/markers/insert_by_pose",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

6.机器人直接控制指令

指令：

/api/joy_control

参数：

名称	说明	是否必选	备注
angular_velocity	角速度	必选
linear_velocity	线速度	必选

接口说明：

对机器人进行部分的直接控制，如自转或停止（此控制优先级高于move指令），返回succeeded表示机器人已成功接收并开始运行此指令

接口1已提供了机器人带路径规划和自动避障的移动功能，相对而言，此接口提供人工控制的遥控移动功能。遥控的方式为控制机器人行进的线速度和角速度，其单位分别为m/s和rad/s；通过两值设置可以自行控制转弯半径等机器人运动表现形式

机器人运动方向和角速度、线速度符号说明如下：

线速度	角速度	机器人行进表现	备注
0	正	机器人原地左转	机器人角速度设值范围为 (-1.0 ~ 1.0)rad/s
0	负	机器人原地右转
正	0	机器人前进	机器人线速度设值范围为 (-0.5 ~ 0.5)m/s
负	0	机器人后退
正	正	机器人前进且左转
正	负	机器人前进且右转
负	正	机器人倒车且左转
负	负	机器人倒车且右转

如果传入的参数超出限定范围，模块内部会按最大预设工作
从安全方面考虑，单个命令的持续时间为0.5秒，但输入频率可以大于2Hz。连续的指令发送可使机器人运动连贯，比如把命令映射到手柄控制键位上

示例：

发送：

/api/joy_control?angular_velocity=0.5&linear_velocity=0.2  
// 调用移动接口,机器人以角速度0.5rad/s逆时针转动，同时以线速度0.2m/s前进。

返回：

{
    "type": "response",
    "command": "/api/joy_control",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

7.机器人急停控制指令

指令：

/api/estop

参数：

名称	说明	是否必选	取值范围	备注
flag	进入或退出急停模式	必选	true/false

接口说明：

使机器人进入自由停止模式，机器人可被推动。

机器人硬件平台提供了一个急停控制按钮，按动此按钮可使机器人进行自动停车状态。除此硬件按钮之外，软件接口等价的提供一个急停控制指令，软件开启急停模式之后，也可使机器人进入自由停止模式。需要注意的是，软件和硬件的急停接口是分别控制机器人急停状态的，不可以相互解锁。

注：软件重启或者整机重启后将重置急停状态为False(v0.6.4版本后)

示例：

发送：

/api/estop?flag=true  //进入急停模式
/api/estop?flag=false  //退出急停模式

返回：

{
    "type": "response",
    "command": "/api/estop",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

8.校正机器人当前位置

当机器人位置在地图中已经偏移时,为了保证机器人运行稳定, 需要帮助机器人校正位置.
注:此类接口在开发过程中一般用不到，特别是在移动任务过程中无需调用此接口校正位置。普通情况下使用前端提供的校正功能即可

8.1指定marker校正机器人位置

指令：

/api/position_adjust

参数：

名称	说明	是否必选	取值范围	备注
marker	用以校定位置的marker名	必选	已经标定的marker点

接口说明：

使用此接口可将机器人位置校正到marker所标记的位置。使用时可先将机器人推至marker标记的位置，然后用调用此接口进行位置校正。

示例：

发送：

/api/position_adjust?marker=001
//告知机器人当前处于代号为001的marker点位上

返回:

{
    "type": "response",
    "command": "/api/position_adjust",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

8.2指定坐标校正机器人位置

本接口至少需要软件版本v0.7.11

指令：

/api/position_adjust_by_pose

参数：

名称	说明	是否必选	取值范围	备注
x	坐标x	必选
y	坐标y	必选
theta	方向	必选
floor	楼层	可选	当前地图中存在的楼层	不填则默认为机器人当前楼层

接口说明：

使用此接口可将机器人位置校正到指定坐标的位置。

示例：

发送：

/api/position_adjust_by_pose?x=0.3&y=0.3&theta=2.6
// 将机器人位置校正到指定坐标

返回:

{
    "type": "response",
    "command": "/api/position_adjust_by_pose",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

9.请求机器人实时数据

指令：

/api/request_data

接口说明：

请求server端以一定频率发送topic类型的数据。当请求成功后，server端会以一定频率发送数据给请求的client。

9.1请求机器人实时全局状态

本接口至少需要软件版本v0.4.0

参数：

名称	说明	是否必选	取值范围	备注	从以下版本开始
topic	请求的实时数据类型	必选	robot_status		v0.4.0
switch	开启/停止数据发送	必选	on/off	已弃用	v0.4.0-v0.7.6.3
frequency	发送频率	可选	>0.0	默认2HZ	v0.4.0

示例：

发送请求：

/api/request_data?topic=robot_status&frequency=1
// 请求server以1HZ的频率发送机器人全局状态

返回:

{
    "type": "response",
    "command": "/api/request_data",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

成功请求后，server以1HZ的频率发送topic为robot_status的数据, type为callback

{
    "type": "callback",
    "topic": "robot_status",
    "results":
    {
    ...   // 详见接口3里“results”的内容和解释
	}
}

9.2请求人检测实时数据

本接口至少需要软件版本v0.7.7

注: 本接口需配置并启用人腿识别模块

参数：

名称	说明	是否必选	取值范围	备注	从以下版本开始
topic	请求的实时数据类型	必选	human_detection		v0.7.7
frequency	发送频率	可选	>0.0	默认1HZ	v0.7.7

示例：

发送请求：

/api/request_data?topic=human_detection&frequency=0.5
// 请求server以0.5HZ的频率发送人检测结果

返回:

{
    "type": "response",
    "command": "/api/request_data",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

成功请求后，server以0.5HZ的频率发送topic为human_detection, type为callback

{
    "type": "callback",
    "topic": "human_detection",
    "results": {
    	"legtrack 0": {   // 识别ID
        	"position": {  // 位置， 机器人正前方为x轴正向，右手坐标系
            	"x": -0.4504653354557998,
                "y": -0.6021136068883720
            },
            "velocity": { // 速度
            	"x": 0.0002109676660555934,
                "y": :0.0001660708499816679
            }
        },
    	"legtrack 1": {
        	"position": {
            	"x": -0.4504653354557998,
                "y": -0.6021136068883720
            },
            "velocity": {
            	"x": 0.0002109676660555934,
                "y": :0.0001660708499816679
            }
        }
	}
}

9.3获取机器人实时速度

本接口至少需要软件版本v0.7.10

参数：

名称	说明	是否必选	取值范围	备注	从以下版本开始
topic	请求的实时数据类型	必选	robot_velocity		v0.7.10
frequency	发送频率	可选	>0.0	默认1HZ	v0.7.10

示例：

发送请求：

/api/request_data?topic=robot_velocity&frequency=0.5
// 请求server以0.5HZ的频率发送机器人当前速度

返回:

{
    "type": "response",
    "command": "/api/request_data",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

成功请求后，server以0.5HZ的频率发送topic为robot_velocity, type为callback

{
    "type": "callback",
    "topic": "robot_velocity",
    "results": {
    	"angular": 0.1,   // 机器人角速度, 大于0表示左转, 小于0表示右转
        "linear": 0.1     // 机器人线速度, 大于0表示前进, 小于0表示后退
	}
}

10.机器人主动通知

接口说明：

机器人主动发出通知给所有连接的client，客户端在收到通知后可以进行相应的动作，比如语音播报等。
注: 不建议作为流程控制的逻辑判断，因为网络等原因可能会造成收不到通知。建议通过接口3 获取机器人当前全局状态获取实时状态作为流程的逻辑判断。

通知列表：

code	description	中文解释	level	从以下版本开始	说明
通用移动任务：					需要调用接口1 机器人移动功能才会触发下列通知
"01001"	The move task is started.	移动任务开始了。	info	0.4.0
"01002"	The move task is finished.	移动任务完成了。	info	0.4.0
"01003"	The move task is failed.	移动任务失败了。	warning	0.4.0	在连续移动重试(01004)一定次数机器人都几乎没有移动后，会发出此通知并且判定任务失败。
"01004"	The move task is canceled.	移动任务被取消了。	info	0.4.0	调用接口2 移动取消功能成功取消掉移动任务后，会发出此通知。
"01005"	The move task is retried.	移动重试。	info	0.4.0	机器人每次尝试移动失败,并且没有达到移动失败(01003)条件，会发出此通知，之后会重新规划路径去目标点。
"01006"	The robot may be trapped.	机器人可能被困住了。	warning	0.7.3	在连续移动重试(01004)一定次数机器人都几乎没有移动后，会发出此通知，此时可能需要人为介入帮助机器人脱困。
"01007"	Failed to find available path.	找不到可用的路径。	warning	0.9.6	机器人在每次移动任务开始前, 如果判断出当前位置无法到达目标位置, 会直接发出此通知,然后发送"01003"移动任务失败通知,不再进行移动重试.此通知每次移动任务最多触发一次. 触发此通知时主要有以下原因:机器人当前位置或者任务目标处于不能移动的区域(地图灰色区域、地图黑线上、地图外),或者需要乘坐电梯时找不到可用的电梯.
"01010"	Start to leave charging pile.	开始离开充电桩。	info	0.5.2
"01011"	Succeed to leave charging pile.	离开充电桩成功了。	info	0.5.2
"01012"	Failed to leave charging plie.	离开充电桩失败了。	warning	0.5.2
"01013"	Leave charging pile retry.	重试离开充电桩。	warning	0.10.25C	因急停或被挡住等原因导致机器人在10秒内无法离开充电桩,会触发一次重试通知,重试次数达到上限后会触发失败.
"01020"	Start to auto dock to charging pile.	开始自动停靠到充电桩。	info	0.5.2
"01021"	Succced to auto dock to charging pile.	自动停靠到充电桩上成功了。	info	0.5.2
"01022"	Failed to auto dock to charging pile.	自动停靠到充电桩上失败了。	warning	0.5.2
"01023"	Failed to to receive valid data.	停靠(充电桩/货柜/cabin)失败，数据异常。	warning	0.5.10
"01024"	Failed to find any feature around the robot.	停靠(充电桩/货柜/cabin)失败,没找到特征。	warning	0.5.10
"01025"	Failed to catch power status.	回充失败，没收到上电信号。	warning	0.5.10
"01026"	Failed to catch infrared signal.	回充失败，没收到红外信号。	warning	0.5.10
"01027"	Failed to dock with timeout.	停靠(充电桩/货柜/cabin)失败,超时。	warning	0.9.8
"01028"	The cabin ID is wrong.	cabin ID错误。	warning	0.10.25C
"01029"	Failed to switch to lateral mode.	切换到横向模式失败。	warning	0.10.25C
"01030"	Start controlling the electronic door.	开始控制电子门/闸机。	info	0.7.4
"01031"	Finish controlling the electronic door.	结束控制电子门/闸机。	info	0.7.4
"01032"	Control the electronic door for too long, forced release control.	控制电子门/闸机已经超时，强制释放控制。	warning	0.7.4
"01033"	congestion searched in narrow area, start waiting.	开始狭窄区等待。	info	0.10.25C
"01034"	no congestion, back to work.	狭窄区等待结束。	info	0.10.25C
"01040"		预留	info	0.10.25C
"01041"		预留	info	0.10.25C
"01050"	Start to leave container.	开始离开货柜	info	0.10.25C
"01051"	Succeed to leave container.	离开货柜成功	info	0.10.25C
"01052"	Failed to leave container.	离开货柜失败	warning	0.10.25C
"01053"	Leave container retry.	离开货柜重试	warning	0.10.25C
"01060"	Start to auto dock to container.	开始对接货柜	info	0.10.25C
"01061"	Succeed to auto dock to container.	对接货柜成功	info	0.10.25C
"01062"	Failed to auto dock to container.	对接货柜失败	warning	0.10.25C
"01070"	Start to leave cabin.	开始离开移动仓	info	0.10.25C
"01071"	Succeed to leave cabin.	离开移动仓成功	info	0.10.25C
"01072"	Failed to leave cabin.	离开移动仓失败	warning	0.10.25C
"01073"	Leave cabin retry.	离开移动仓重试	warning	0.10.25C
"01080"	Start to auto dock to cabin.	开始对接移动仓	info	0.10.25C
"01081"	Succeed to auto dock to cabin.	对接移动仓成功	info	0.10.25C
"01082"	Failed to auto dock to cabin.	对接移动仓失败	warning	0.10.25C
"01101"	The cruise is started.	巡游任务开始了。	info	0.7.4
"01102"	The cruise is finished.	巡游任务完成了。	info	0.7.4
"01103"	The cruise is failed.	巡游任务失败了。	warning	0.7.4	当最后一个移动任务失败时，发送此通知
"01104"	The cruise is canceled.	巡游任务被取消了。	info	0.7.4	调用接口2 移动取消功能成功取消掉巡游任务后，会发出此通知。
"01200"	Traffic is busy.	交通繁忙	info	0.10.25C
"01201"	Trapped in unknown area.	被困在未知区域(地图中灰色区域)	warning	0.7.6
"01202"	Trapped in obstacle.	被困在障碍物附近(地图中黑线)	warning	0.7.6
"01203"	Failed to make global plan.	全局路径规划失败(困在灰色区域、被挡死时大概每５s触发一次)	info	0.7.9
"01204"	Failed to make local plan.	局部路径规划失败	info	0.10.25C
"01205"		预留	info	0.10.25C
"01206"		预留	info	0.10.25C
"01207"		预留	info	0.10.25C
"01208"		预留	info	0.10.25C
"01209"		预留	info	0.10.25C
"01210"	Detect no entry, zero velocity control.	检测到禁止通行标志,执行零速控制	warning	0.3.8	部分产品具有此功能
"01301至01308"		预留	info	0.10.25C
电梯任务：					需要调用接口1 机器人移动功能才会触发下列通知
"04000"	Start to go to lift.	开始去电梯门口。	info	0.5.2
"04001"	Succeed to go to lift.	去电梯门口成功了。	info	0.5.2
"04002"	Failed to go to lift.	去电梯门口失败了。	info	0.5.2
"04010"	Start to call lift.	开始呼叫电梯。	info	0.5.2
"04011"	Succeed to call lift.	呼叫电梯成功了。	info	0.5.2
"04013"	Call lift more than 3 minutes.	呼叫电梯超过3分钟了还没来。	warning	0.5.2
"04020"	Start to take lift.	开始乘坐电梯。	info	0.5.2
"04021"	Succeed to take lift.	乘坐电梯成功，准备出电梯。	info	0.5.2
"04023"	Take lift more than 3 minutes."	乘坐电梯超过3分钟了还没到。	warning	0.5.2
"04030"	Start to enter lift.	开始进电梯。	info	0.5.2
"04031"	Succeed to enter lift.	进电梯成功。	info	0.5.2
"04032"	Failed to enter lift.	进电梯失败。	info	0.5.2
"04033"	There is not enough space in the lift,take the next lift.	电梯里空间不够,等待乘坐下一趟电梯。	info	0.7.3
"04040"	Start to avoid liftt.	进电梯失败，开始回避电梯。	info	0.5.2
"04041"	Finish to avoid lift.	回避电梯成功。	info	0.5.2
"04050"	Start to exit lift.	开始出电梯。	info	0.5.2
"04051"	Succeed to exit lift.	出电梯成功了。	info	0.5.2
"04052"	Failed to exit lift.	出电梯失败了。	warning	0.5.2
"04060"	Start to back to lift.	出电梯失败，开始回到电梯。	info	0.5.2
"04061"	Succeed to back to lift.	回到电梯成功了。	info	0.5.2
"04062"	Failed to back to lift.	回到电梯失败了。	warning	0.5.2
"04070"	Start waiting for the lift to unlock.	开始等待电梯解锁。	info	0.8.1
"04071"	End waiting for the lift to unlock.	等待电梯解锁结束(成功)。	info	0.8.1
状态相关：					下列通知不需移动任务触发
"02000"	Poweroff notice.	将关机断电	"info"	0.5.6
"02001"	Charge status on.	未充电状态=>充电状态	"info"	0.5.6
"02002"	Charge status off.	充电状态=>未充电状态	"info"	0.5.6
"02003"	Estop on.	未急停状态=>急停状态	"info"	0.5.6
"02004"	Estop off.	急停状态=>未急停状态	"info"	0.5.6
"02005"	Triggered attitude correction.	姿态校正被触发（此时机器人可能被搬动了）	"warning"	0.7.3
"02006"	Software shutdown notice.	软件即将关闭	"info"	0.8.2
"02010"	The robot maybe lost.	机器人可能迷路了	"warning"	0.9.9	此通知存在误报可能。
异常状态：					下列通知不需移动任务触发
"03001"	Abnormal object was detected in the robot.	机器人体内检测到异常物体(激光槽内有异物).	"warning"	0.8.2

字段解释：

字段	说明	备注
code	通知的ID	作为唯一标识，同一通知所使用的代码不会发生改变，后续将扩展新的通知
description	通知的英文解释	可作为打印信息
level	通知的级别	限定为info/warning/error类型, 每个code的划分以后可能会改
data	通知附带的参考信息	软件版本v0.7.4新增
中文解释	通知的中文解释	仅存在于文档内,实际通知并不会发出这个字段

从软件版本0.7.4开始，通知新增data字段作为附加信息,具体见下:

code	data	说明	从以下版本开始
01001至01031	"target":"room_205"	当前移动的目标点位名称	0.7.4
01002/010023/01004	"distance": 0.2	任务行走的距离(m)	0.7.6
01101至01104	"markers":["m1","m2"]	巡游的点位	0.7.4
*	"count":-1	巡游的圈数	0.7.4
*	"distance_tolerance":1	点位到达距离容差	0.7.4

示例：

{
    "type": "notification",
    "code": "01001",
    "level": "info",
    "description": "The move task is started.",
    "data":{"target":"room_205"}
}

11.设置参数

本接口至少需要软件版本v0.4.2

指令：

/api/set_params

参数：

名称	说明	是否必选	取值范围	备注	从以下版本开始版本
max_speed	机器人最大行进速度(百分比)	可选	[0.3, 0.7]	小于0.3取0.3，大于0.7取0.7	v0.4.2-v0.5.1（已弃用）
max_speed_ratio	机器人最大行进速度百分比	可选	[0.3, 1.4]	小于0.3取0.3，大于1.4取1.4	v0.5.2-v0.8.5.1(已弃用)
max_speed_linear	机器人最大直线速度	可选	[0.1, 1.0] (m/s)	小于0.1取0.1，大于1.0取1.0	v0.8.6
max_speed_angular	机器人最大角速度	可选	[0.5, 3.5] (rad/s)	小于0.5取0.5，大于3.5取3.5	v0.8.6

注: 此接口设置的最大线/角速度会结合机器人内部参数，最终运行中使用最小值生效
此接口设置参数成功后有效期限为重启软件或整机前有效，重启软件或整机后失效。如果需要永久生效可通过监控页面配置管理手动修改

接口说明：

设置机器人的参数。
需要注意的是：调用此接口后无论是否成功，返回的json中“status”字段都是“OK”。如果想确定参数是否设置成功，请调用接口12 获取参数获取参数后查看参数的当前值。

示例：

发送：

/api/set_params?max_speed_linear=0.5
// 设置机器人最大行进速度为0.5米/秒

返回:

{
    "type": "response",
    "command": "/api/set_params",
    "uuid": "",
    "status": "OK",
    "error_message": ""
}

12.获取参数

本接口至少需要软件版本v0.4.2

指令：

/api/get_params

参数：

N/A

接口说明：

获取已设置的参数列表以及当前值。各版本支持的参数见接口11 设置参数。

示例：

发送：

/api/get_params
// 获取参数列表和当前值

返回:

{
    "type": "response",
    "command": "/api/get_params",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
        "max_speed_linear": 0.5
	}
}

13.无线网络接口

13.1获取机器人当前可用的WiFi列表

本接口至少需要软件版本v0.5.2

指令：

/api/wifi/list

参数：

N/A

接口说明：

获取机器人当前可用的WiFi列表，返回中包含SSID和信号强度。

示例：

发送：

/api/wifi/list

返回:

{
    "type": "response",
    "command": "/api/wifi/list",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
        "SSID1": 50,
        "SSID2": 30,
        "SSID3": 80,
	}
}

13.2连接WiFi

本接口至少需要软件版本v0.5.2

指令：

/api/wifi/connect

参数：

名称	说明	是否必选	取值范围	备注	从以下版本开始
SSID	WiFi的SSID	必选	当前的环境WiFi		v0.5.2
password	WiFi密码	可选	SSID对应	如果已经连接过，可以不填	v0.5.2

接口说明：

使机器人连接到环境WiFi或切换当前连接的环境WiFi。

示例：

发送：

/api/wifi/connect?SSID=SSID1&password=123456

返回:

{
    "type": "response",
    "command": "/api/wifi/connect",
    "uuid": "",
    "status": "OK",
    "error_message": "",
}

13.3获取当前连接的WiFi

本接口至少需要软件版本v0.5.2

指令：

/api/wifi/get_active_connection

参数：

N/A

接口说明：

获取机器人当前连接的WiFi的SSID.

示例：

发送：

/api/wifi/get_active_connection

返回:

{
    "type": "response",
    "command": "/api/wifi/get_active_connection",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":"SSID1"   // 如果当前未连接到WiFi，则results为空""
}

13.4获取机器人IP和无线网卡地址

本接口至少需要软件版本v0.5.2

指令：

/api/wifi/info

参数：

N/A

接口说明：

获取机器人当前通过环境WiFi分配到的IP地址和无线网卡的物理地址。

示例：

发送：

/api/wifi/info

返回:

{
    "type": "response",
    "command": "/api/wifi/info",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":{
    	"IPaddr": "192.168.XXX.XXX", // 如果未连接WiFi则为空“”
        "HWaddr": "xx:xx:xx:xx:xx:xx", // 连接WiFi网卡的物理地址
        },
}

13.5获取机器人当前可用的无线列表详细信息

本接口至少需要软件版本v0.7.7

指令：

/api/wifi/detail_list

参数：

N/A

接口说明：

获取机器人当前可用的WiFi列表详细信息。

示例：

发送：

/api/wifi/detail_list

返回:

{
    "type": "response",
    "command": "/api/wifi/detail_list",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {     // 注： 未检测到可用WiFi时 results={}
        "SSID1": {
        	"SSID": "SSID1",  // SSID
            "SIGNAL": 100,  // 信号强度
            "ACTIVE": False, // 连接状态  True->已连接， False->未连接
            "FREQ": "2462 MHz", // 频段， 2.4G/5G
            "SECURITY": "WPA2"  // 加密方式。 空表示无加密
         },
        "SSID2": {
        	"SSID": "SSID2",
            "SIGNAL": 80,
            "ACTIVE": False,
            "FREQ": "2412 MHz",
            "SECURITY": ""
         },
        "SSID1_5G": {
        	"SSID": "SSID1_5G",
            "SIGNAL": 90,
            "ACTIVE": True,
            "FREQ": "5260 MHz",
            "SECURITY": "WPA WPA2"
         }
	}
}

14.地图接口

14.1获取地图列表

本接口至少需要软件版本v0.5.2

指令：

/api/map/list

参数：

N/A

接口说明：

获取机器人中所有的地图名称和楼层。

示例：

发送：

/api/map/list

返回:

{
    "type": "response",
    "command": "/api/map/list",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":{
    	"map_name_1": [1,2,3,4,5], // 地图map_name_1中有1-5层
        "map_name_2": [10],
        },
}

14.2设置当前地图

本接口至少需要软件版本v0.5.2

指令：

/api/map/set_current_map

参数：

名称	说明	是否必选	从以下版本开始
hotel_id	地图名	必选	v0.5.2-v0.5.9(已弃用,用map_name取代)
map_name	地图名	必选	v0.5.10
floor	楼层	必选	v0.5.2

接口说明：

设置机器人当前地图。
注:设置成功后会重启water服务，所以有可能收不到response。

示例：

发送：

/api/map/set_current_map?hotel_id=map_name_1&floor=5

返回:

{
    "type": "response",
    "command": "/api/map/set_current_map",
    "uuid": "",
    "status": "OK",
    "error_message": "",
}

14.3获取当前地图

本接口至少需要软件版本v0.5.2

指令：

/api/map/get_current_map

参数：

N/A

接口说明：

获取机器人当前地图。

示例：

发送：

/api/map/get_current_map

返回:

{
    "type": "response",
    "command": "/api/map/get_current_map",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":{
    	"hotel_id": "map_name_1",  // v0.5.2-v0.5.9(已弃用)
    	"map_name": "map_name_1",  // v0.5.10以后
        "floor": "5"
        "info": {   // v0.7.8新增, 注:地图加载失败时没有info字段
        	"resolution": 0.05,    	// v0.7.8  分辨率(米/像素)
            "width": 1024, 		 	// v0.7.8 宽度
            "height": 768,        	// v0.7.8 高度
            "origin_x": -24.04,		// v0.7.8 左下角坐标x
            "origin_y": -12.52		// v0.7.8 左下角坐标y
        }
    },
}

14.4获取地图列表详情

本接口至少需要软件版本v0.8.6

指令：

/api/map/list_info

参数：

N/A

接口说明：

获取机器人中所有的地图的详细信息。

示例：

发送：

/api/map/list_info

返回:

{
    "type": "response",
    "command": "/api/map/list_info",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":{
    	"map_name_1": [{"floor": 1, "resolution": 0.02, "height": 1024, "width": 768, "origin_x": -24.04, "origin_y": -12.52}, {"floor": 2, ...}, ...], // 地图map_name_1中所有地图信息
        "map_name_2": [{"floor": 1, ...}, ...], // 地图map_name_2中所有地图信息
        ...
        },
}

14.5给定目标点，在目标点附近寻找可到点的位置

本接口至少需要软件版本v0.10.7

指令：

/api/map/accessible_point_query

参数：

名称	说明	是否必选	备注	从以下版本开始
x	目标点在地图坐标系下的x坐标(单位:m)	必选		v0.10.7
y	目标点在地图坐标系下的y坐标(单位:m)	必选		v0.10.7

接口说明：

给定目标点，根据传感器探测结果,在目标点附近寻找可到点的位置.
注意: 此接口仅适用于当前地图的当前楼层.

示例：

发送：

/api/map/accessible_point_query?x=-0.5&y=-0.5

返回:

{
    "type": "response",
    "command": "/api/map/accessible_point_query",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":
     {
         "position": {"y": -0.5, "x": -0.5}
     },
}

14.6给定目标点，查询到静态地图障碍和传感器探测障碍物的距离

本接口至少需要软件版本v0.10.7

指令：

/api/map/distance_probe

参数：

名称	说明	是否必选	备注	从以下版本开始
x	目标点在地图坐标系下的x坐标(单位:m)	必选		v0.10.7
y	目标点在地图坐标系下的y坐标(单位:m)	必选		v0.10.7

接口说明：

给定目标点，查询到静态地图障碍和传感器探测障碍物的距离.
返回结果中:
obstacle代表目标点到传感器探测到的障碍的距离, -1:表示目标点太远,无法获取到距离信息
static:代表目标点到静态地图障碍的距离.

示例：

发送：

/api/map/distance_probe?x=-0.5&y=-0.5

返回:

{
    "type": "response",
    "command": "/api/map/accessible_point_query",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":
     {
         "env_dist": 
         {
         	"obstacle": 0.307566, "static": 0.34
         }
     },
}

15.关机重启接口

本接口至少需要软件版本v0.5.10

指令：

/api/shutdown

参数：

名称	说明	是否必选	取值范围	备注	软件版本
reboot	关机后是否重启	可选	true/false	缺省为false	v0.5.10
delay	关机后多久重启	可选	[0, 14400] (单位分钟)	reboot为true时才生效	v0.8.1

接口说明：

调用接口关闭或者重新启动机器人,在电源关闭之前会有通知发出(见接口10 机器人主动通知)，在通知发出后10s电源关闭。如果是重启的话, 重新上电与电源关闭间会有5s间隔。
注:可能会收不到response。

示例：

发送：

/api/shutdown   // 关机

或者

/api/shutdown?reboot=true   	// 重启

返回:

{
    "type": "response",
    "command": "/api/shutdown",
    "uuid": "",
    "status": "OK",
    "error_message": "",
}

16.软件更新接口

16.1 获取当前软件版本

本接口至少需要软件版本v0.5.5

指令：

/api/software/get_version

参数：

N/A

接口说明：

获取当前软件版本。

示例：

发送：

/api/software/get_version

成功返回:

{
    "type": "response",
    "command": "/api/software/get_version",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":"x.x,x",    // 当前软件版本
}

失败返回:

{
    "type": "response",
    "command": "/api/software/get_version",
    "uuid": "",
    "status": "UNKNOWN_ERROR",
    "error_message": "xxx",    // 失败原因
}

16.2 检查更新

本接口至少需要软件版本v0.5.5

指令：

/api/software/check_for_update

参数：

N/A

接口说明：

检查是否有新版本可以更新，返回当前版本、最新版本和是否可以更新。
注：

本功能需要机器人接入网络，否则返回失败。
本接口是阻塞执行。

示例：

发送：

/api/software/check_for_update

成功返回:

{
    "type": "response",
    "command": "/api/software/check_for_update",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results":{
        "version_latest":"x,x,x",   // 当前版本
        "version_current":"x.x.x",  // 最新版本
        "enable_update":bool,  // 能否更新，true->能更新，false->不能更新
    },
}

失败返回:

{
    "type": "response",
    "command": "/api/software/check_for_update",
    "uuid": "",
    "status": "UNKNOWN_ERROR",
    "error_message": "xxx",    // 错误消息
}

16.3 更新

本接口至少需要软件版本v0.5.5

指令：

/api/software/update

参数：

N/A

接口说明：

更新软件到最新版本。
注：

本功能需要机器人接入网络，否则返回失败。
本接口是阻塞执行。
升级成功后将自动重启软件服务, 所有tcp socket需要重新连接。

示例：

发送：

/api/software/update

成功返回:

{
    "type": "response",
    "command": "/api/software/update",
    "uuid": "",
    "status": "OK",
    "error_message": "",
}

失败返回:

{
    "type": "response",
    "command": "/api/software/update",
    "uuid": "",
    "status": "UNKNOWN_ERROR",
    "error_message": "xxx",    // 错误消息
}

16.4重启服务

本接口至少需要软件版本v0.8.2

指令：

/api/software/restart

参数：

N/A

接口说明：

重启软件服务
注：

重启软件服务后, 所有tcp socket需要重新连接。

示例：

发送：

/api/software/restart

成功返回:

{
    "type": "response",
    "command": "/api/software/restart",
    "uuid": "",
    "status": "OK",
    "error_message": "",
}

17.设置灯带接口

17.1设置灯带亮度

此接口可以被17.2设置灯带颜色接口取代
本接口至少需要软件版本v0.6.3

指令：

/api/LED/set_luminance

参数：

名称	说明	是否必选	取值范围	备注	软件版本
value	亮度百分比	必选	[0,100]	非均匀变化	v0.6.3

接口说明：

设置LED灯带的亮度,设置完将永久改变灯带正常/闪烁/呼吸时的最大亮度。
注:急停或者充电状态下此接口虽然返回成功，但是设置有可能不生效。

示例：

发送：

/api/LED/set_luminance

成功返回:

{
    "type": "response",
    "command": "/api/LED/set_luminance?value=50",
    "uuid": "",
    "status": "OK",
    "error_message": "",
}

失败返回:

{
    "type": "response",
    "command": "/api/LED/set_luminance",
    "uuid": "",
    "status": "UNKNOWN_ERROR",
    "error_message": "xxx",    // 失败原因
}

17.2设置灯带颜色

本接口至少需要软件版本v0.8.7

指令：

/api/LED/set_color

参数：

名称	说明	是否必选	取值范围	软件版本
r	红色值	必选	[0,100]	v0.8.7
g	绿色值	必选	[0,100]	v0.8.7
b	蓝色值	必选	[0,100]	v0.8.7

接口说明：

设置LED灯带的颜色,设置完将永久改变灯带正常/闪烁/呼吸时的颜色，可以根据r/g/b的值组合出不同的颜色。需要注意的是，当rgb全为0时,不能生效。此设置会读写硬件设备的flash,不推荐高频率使用。
注:急停或者充电状态下此接口虽然返回成功，但是设置有可能不生效。

示例：

发送：

/api/LED/set_color?r=0&g=100&b=0  // 设置灯带颜色为绿色

成功返回:

{
    "type": "response",
    "command": "/api/LED/set_color",
    "uuid": "",
    "status": "OK",
    "error_message": "",
}

失败返回:

{
    "type": "response",
    "command": "/api/LED/set_color",
    "uuid": "",
    "status": "UNKNOWN_ERROR",
    "error_message": "xxx",    // 失败原因
}

18.自诊断接口

18.1获取自诊断结果

本接口至少需要软件版本v0.6.7

指令：

/api/diagnosis/get_result

参数：

N/A

接口说明：

获取自诊断结果。

示例：

发送：

/api/diagnosis/get_result

成功返回:

{
    "type": "response",
    "command": "/api/diagnosis/get_result",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
    	"sensor_core": {  // 诊断项:传感器板
        	"status": bool,   // 最近一次诊断结果，true->成功 false->失败
            "time_stamp": 1511235083.066043,  // 最近一次诊断时间
            "total_count": 4,  // 总诊断次数
            "success_count": 4}, // 诊断成功次数
        "motor_core_right": {...},  // 诊断项:右电机板
        "motor_core_left": {...},  // 诊断项:左电机板
        "radio_core": {...},  // 诊断项:无线板
        "power_core": {...}, // 诊断项:电源板
        "depth_camera": {...}, // 诊断项：深度摄像头
        "laser": {...}, // 诊断项：激光
        "IMU": {...}, // 诊断项: IMU
        "CAN": {...}, // 诊断项: CAN模块
        "internet": {...}, 诊断项: 互联网（ping baidu)
        ... // 待添加
    }
}

失败返回:

{
    "type": "response",
    "command": "/api/diagnosis/get_result",
    "uuid": "",
    "status": "UNKNOWN_ERROR",
    "error_message": "xxx",    // 失败原因
}

19.获取电源状态接口

本接口至少需要软件版本v0.7.9

指令：

/api/get_power_status

参数：

N/A

接口说明：

获取电池的电压、充电电压、电流、电量等信息。

示例：

发送：

/api/get_power_status

返回:

{
    "type": "response",
    "command": "/api/get_power_status",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
		"battery_capacity": 100, // 电量百分比
		"battery_current": 0.1, // 电池电流
		"battery_voltage": 29.5, // 电池电压
		"charge_voltage": 28.9,  // 充电电压
		"charger_connected_notice": true, // 是否正在充电。true->充电中状态。false->未充电状态
		"head_current": 0,   		// 上位机耗电电流
    }
}

注：
电池电流符号为正表示充电，负表示放电。

20.获取机器人全局路径接口

本接口至少需要软件版本v0.8.2

指令：

/api/get_planned_path

参数：

N/A

接口说明：

获取机器人当前规划的全局路径。
注:
返回的路径上点的最大数量有限制，如果超过上限则在路径上平均取一定数量的点返回；如果当前没有任务，则返回空的路径。

示例：

发送：

/api/get_planned_path

返回:

{
    "type": "response",
    "command": "/api/get_planned_path",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
		"path": [[17.8172,-32.7272], ... [17.8166,-32.7169]]  // 已规划路径上的点，最多返回2000个
    }
}

21.获取电梯状态接口

本接口至少需要软件版本v0.8.5

指令：

/api/lift_status

参数：

N/A

接口说明：

获取机器人当前所乘坐电梯的状态。
注:
此接口的调用时机为"开始呼叫电梯"到"出电梯成功", running_status为"wait_lift_outside"开始至"exit_lift"结束，其他时间调用会返回超时的错误。

示例：

发送：

/api/lift_status

成功返回:

{
    "type": "response",
    "command": "/api/lift_status",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
		"current_floor": 1  // 当前电梯所在楼层, 注:0表示获取楼层失败
    }
}

22.获取两点间路径接口

本接口至少需要软件版本v0.9.6

指令：

/api/make_plan

参数：

名称	说明	是否必选
start_x	起始位置的坐标x	必选
start_y	起始位置的坐标y	必选
start_floor	起始位置的楼层	必选
goal_x	目标位置的坐标x	必选
goal_y	目标位置的坐标y	必选
goal_floor	目标位置的楼层	必选

接口说明：

从起始位置到目标位置规划出一条最短路径, 返回路径的长度.

示例：

发送：

/api/make_plan?start_x=1.0&start_y=1.0&start_floor=1&goal_x=1.0&goal_y=2.0&goal_floor=1

成功时返回:

{
    "type": "response",
    "command": "/api/make_plan",
    "uuid": "",
    "status": "OK",
    "error_message": "",
    "results": {
		"distance": 1.0  // 路径长度为1.0米
    }
}

规划失败时返回(0.10.8新增):

{
    "type": "response",
    "command": "/api/make_plan",
    "uuid": "",
    "status": "GOAL_CAN_NOT_BE_REACHED", // 目标无法到达:表示机器人无法规划出路径到目标点,可能原因有: 1.目标点标记在无法到达的位置(如灰色区域) 2.中间路线被黑线或者禁行线挡住 3.无可用电梯
    "error_message": "goal can not be reached"
}

23.获取机器人当前位置接口

本接口至少需要软件版本v0.10.109D

指令：

/api/get_current_location

参数：

名称	说明	是否必选	取值范围	备注	从以下版本开始
distance_threshold	查找附近点位时的距离阈值	可选，默认2.0米	[0.01, +∞]		0.10.109D

接口说明：

获取机器人当前的位置和最近的点位信息。

示例：

发送：

获取机器人两米内最近的点位
/api/get_current_location?distance_threshold=2

成功时返回:

{
  "command":"/api/get_current_location",
  "error_message":"",
  "results":{
    "current_floor":5,  // 机器人所在楼层
    "current_pose":{    // 机器人坐标
       "theta":-3.1086,
       "x":-48.1103,
       "y":-18.2784
     },
    "near_markers":[
      {
        "distance":0.0184,   // 与点位的距离
        "key":11,            // 点位类型
        "marker_name":"cdz"  // 点位名称
      }
    ],  // 机器人最近的点位，如果没找到则返回空数组
    "running_status":"idle"}, // 机器人运行状态
  "status":"OK",
  "type":"response",
  "uuid":""
}

a. 状态代码返回说明（针对返回数据的status）

返回码	定义描述
OK	表示响应包含有效的 results
INVALID_REQUEST	表示提供的请求无效。这一状态的常见原因包括参数或参数值无效
REQUEST_DENIED	表示系统已拒绝您的请求
UNKNOWN_ERROR	表示由于服务器发生错误而无法处理请求。如果您重试一次，请求可能会成功
GOAL_CAN_NOT_BE_REACHED	目标无法到达

b. 错误消息返回说明（针对返回数据的error_message）

如果状态代码不是 OK，在响应对象包含附加的 error_message 字段中更详细地说明了给定状态代码背后的原因。
注：此字段不保证始终有内容，并且其内容可能会更改。