上层 · 通信与通用协议

3 上层应用开发接口

3.1 概述

在上层开发者模式下机器人通过WebSocket通信端口5000来接收用户端请求指令，例如让机器人站起、蹲下、行走等。WebSocket是一种实时通信协议，在机器人和用户端之间建立长连接，以便快速有效地传输控制信息和数据。如下图所示：

3.2 通信协议格式

当机器人通过 WebSocket 接收客户端指令时，采用 JSON 数据协议进行信息传递。这种方式具有显著优势：WebSocket 是一种全双工通信协议，能够在客户端与服务器之间建立实时、低延迟的连接，特别适合频繁交互的应用场景。JSON 数据协议则以其简洁、可读性强的结构，确保数据传输直观明了，且具有跨平台、跨语言的兼容性。WebSocket 与 JSON 的结合不仅与编程语言无关，适用于各种设备和系统，还能提升开发的灵活性和维护的便利性。

• 请求数据格式包含以下字段：
  • accid：机器人序列号，注意修为您机器人的序列号；
  • title：指令名称，以“request_”为前缀；
  • timestamp：指令发出时间戳，单位为毫秒；
  • guid：指令的唯一标识符，用于区分不同的请求指令。如果是同步接口，则需要在“response_xxx”响应消息中通过guid字段将值带回给客户端。客户端接收到响应消息后，可以通过比较guid字段的值是否与请求指令中的值相同来判断指令是否执行完成；
  • data：存放请求指令的数据内容。可以根据具体需求包含多个子字段，以存放请求指令所需的数据内容，例如执行动作的参数、发送消息的文本内容等等；
  • 示例如下：

{
  "accid": "WF_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号
  "title": "request_xxx",   // 指令名称，以“request_”为前缀
  "timestamp": 1672373633989, // 指令发出时间戳，单位为毫秒
  "guid": "746d937cd8094f6a98c9577aaf213d98", // 指令的唯一标识符，用于区分不同的请求指令
  "data": {}  // 存放请求指令的数据内容
}

• 响应数据格式包含以下字段：
  • accid：机器人序列号，注意修为您机器人的序列号；
  • title：指令名称，以“response_”为前缀；
  • timestamp：指令发出时间戳，单位为毫秒；
  • guid：与对应请求指令的guid值相同；
  • data：至少应该包含一个“result”子字段，用于存放请求指令的执行结果数据。如果有需要，还可以包含其他子字段，例如错误码、错误信息等用于描述操作结果的信息；
  • 示例如下：

{
  "accid": "WF_TRON2A_001",   // 机器人序列号，注意修为您机器人的序列号
  "title": "response_xxx",  // 指令名称，以“response_”为前缀
  "timestamp": 1672373633989, // 指令发出时间戳，单位为毫秒
  "guid": "746d937cd8094f6a98c9577aaf213d98", // 与对应请求指令的guid值相同
  "data": { # 存放响应指令的具体数据内容
    "result": "success"  // “result” 用于存放请求指令处理是否成功，它的值为：“success 或 fail_xxx”
  }
}

• 消息推送：它是机器人主动向客户端发送信息的过程。这些信息可以包括机器人的序列号、当前运行状态、执行的操作等数据。通过及时地向客户端发送这些信息，机器人可以帮助客户端更好地理解它的工作状态，从而更好地使用它提供的服务。它的数据格式包含以下字段：
  • accid：机器人序列号，注意修为您机器人的序列号；
  • title：指令名称，以“notify_”为前缀；
  • timestamp：消息发出时间戳，单位为毫秒；
  • guid：消息的 guid 值，唯一标识这条消息；
  • data：存放消息数据内容。可以根据具体需求包含多个子字段，以存放请求指令所需的数据内容；
  • 示例如下：

{
  "accid": "WF_TRON2A_001",   // 机器人序列号，注意修为您机器人的序列号
  "title": "notify_xxx",  // 消息名称，以“notify_”为前缀
  "timestamp": 1672373633989, // 消息发出时间戳，单位为毫秒
  "guid": "746d937cd8094f6a98c9577aaf213d98", // 消息的guid值，唯一标识这条消息
  "data": { } // 存放消息数据内容
}

3.3 查看软件序列号(ACCID)

• 连接机器人无线网络

  • 机器人开机完成后，使用个人电脑连接机器人 Wi-Fi，名称格式通常为「WF_TRON2A_xxx」

  • 输入 Wi-Fi 密码：12345678

• 在浏览器中输入 http://10.192.1.2:8080 可以进入“机器人信息页”，并查看机器人信息。如下图所示，页面中显示的 SN (序列号) 为 SF_TRON2A_127，其中 SF_TRON2A_127 便是此机器人的软件序列号。

3.4 通信测试方法

Postman 是一个流行的 API 测试软件，可以用于测试 WebSocket 接口。使用 Postman 测试 WebSocket 接口，请按照以下步骤操作：

• 安装postman，下载地址：https://www.postman.com/downloads/?utm_source=postman-home；
  • 打开Postman，并创建一个WebSocket的请求；
  • 连接机器人无线网络
    • 机器人开机完成后，使用个人电脑连接机器人Wi-Fi，名称格式通常为「TRON2A_xxx」
    • 输入Wi-Fi密码：12345678
  • 在请求的URL中输入WebSocket接口的地址，例如，“ws://10.192.1.2:5000”;
  • 在“Message”中，输入要发送的指令请求；
  • 单击“Send”按钮，发送请求指令；
  • 发送指令后，可以从服务器接收响应消息。使用Postman的响应窗口查看服务器返回的数据，并检查是否符合预期结果。

3.5 通用协议接口定义

该机器人接口设计遵循与遥控器操控一致的流程和状态流转，确保调用顺序、响应时序及状态过渡与遥控器控制逻辑严格对齐。用户通过接口调用可获得如同使用遥控器的直观体验，同时支持遥控器与接口间的无缝切换，实现统一、稳定的机器人操控效果。

3.5.1 全局消息

3.5.1.1 机器人基本信息

机器人基本信息每秒上报一次，包含以下内容：

• accid：机器人序列号
  • title：notify_robot_info
  • timestamp：消息发出时间戳，单位为毫秒
  • guid：消息的guid值，唯一标识这条消息
  • data：存放消息内容，示例如下：

示例：

{
  "accid": "WF_TRON2A_001", 
  "title": "notify_robot_info", 
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
    "accid": "WF_TRON2A_001",
    "sw_version": "robot-tron2-2.0.10.20241111103012",
    "imu": "OK",    // 机器人IMU诊断信息
    "camera": "OK", // 机器人相机诊断信息
    "motor": "OK",  // 机器人电机诊断信息
    "battery": 95,  // 机器人电量
    "status": "WALK" // 机器人运行模式
  }
}

3.5.1.2 非法指令消息

当机器人收到非法格式的请求指令时，发送此消息，包含以下内容：

• accid：机器人序列号
  • title：notify_invalid_request
  • timestamp：消息发出时间戳，单位为毫秒
  • guid：消息的guid值，唯一标识这条消息
  • data：存放消息内容
  • 示例如下：

{
  "accid": "WF_TRON2A_001", 
  "title": "notify_invalid_request", 
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": "返回原请求指令内容，便于客户端排查问题"
}

3.5.2 连接Wifi热点

3.5.2.1 请求：request_connect_wifi

本协议用于向机器人路由器发起请求，指令路由器连接到指定 SSID 的 WiFi 热点并返回连接结果。

{
  "accid": "WF_TRON2A_001",
  "title": "request_connect_wifi",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": { 
      "wifi_band": 0,  // WiFi频段：0=5GHz，1=2.4GHz
      "wifi_ssid": "Limx-Guests",  // 目标WiFi的SSID（WiFi名称），区分大小写，需与实际热点一致
      "wifi_password": "LimX2024",  // 目标WiFi的密码，WPA2-PSK加密方式的密码
      "router_admin_password": "12345678"  // 机器人路由器的管理员密码
  }
}

3.5.2.2 响应：response_connect_wifi

{
  "accid": "WF_TRON2A_001",
  "title": "response_connect_wifi",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
      "result": "success"  // success: 成功
                           // fail_no_wifi_band: 没有指定频段
                           // fail_no_wifi_ssid: 没有指定ssid
                           // fail_no_wifi_password: 没有指定密码
                           // fail_no_router_admin_password: 没有指定密码
  }
}

3.5.2.3 消息推送：无

3.5.3 查询 Wifi 连接状态

3.5.3.1 请求：request_wifi_connection_status

本协议用于客户端向机器人路由器发起 WiFi 连接状态查询请求，路由器接收请求后反馈当前已连接 WiFi 的核心状态信息，包括关联 SSID、信号强度及连接结果，支撑客户端实时感知设备网络连接状态。客户端发起 WiFi 连接状态查询，需携带机器人路由器管理员密码完成身份校验。

{
  "accid": "WF_TRON2A_001",
  "title": "request_wifi_connection_status",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
      "router_admin_password": "12345678"  // 机器人路由器的管理员密码
  }
}

3.5.3.2 响应：response_wifi_connection_status

机器人路由器接收查询请求后，返回当前 WiFi 实际连接状态，供客户端解析展示或后续业务处理。

{
  "accid": "WF_TRON2A_001",
  "title": "response_wifi_connection_status",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
      "ssid": "Limx-Guests",
      "signal": -56,        // 单位dBm
      "result": "success"   // success: 成功
                            // fail_disconnected
  }
}

3.5.3.3 消息推送：无

3.5.4 设置灯效

3.5.4.1 请求：request_light_effect

{
  "accid": "WF_TRON2A_001",
  "title": "request_light_effect",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
    "effect": 1
  }
}

请求参数说明：

3.5.4.2 响应：response_light_effect

{
  "accid": "DACH_TRON2A_001",
  "title": "response_light_effect",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
    "result": "success"  // success: 成功, fail_light_effect: 失败
  }
}

3.5.4.3 消息推送：无

3.5.5 紧急停止

提示： 需要在空闲模式下调用，运动过程中无法响应

3.5.5.1 请求：request_emgy_stop

{
  "accid": "DACH_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号；
  "title": "request_emgy_stop",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}

3.5.5.2 响应：response_emgy_stop

{
  "accid": "DACH_TRON2A_001",
  "title": "response_emgy_stop",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
    "result": "success"  // success: 成功, fail_imu: IMU 错误, fail_motor: 电机错误
  }
}

3.5.5.3 消息推送：无