Skip to content

Latest commit

 

History

History
156 lines (123 loc) · 5.46 KB

api.md

File metadata and controls

156 lines (123 loc) · 5.46 KB

UDP 服务器端 API 文档

1. 概述

该接口文档描述了控制端和机器人端与服务器进行通信时使用的消息类型。消息通过 UDP 协议传输，并使用 JSON 格式进行序列化。

2. 接口概览

  • 传输协议：UDP
  • 消息格式：JSON
  • 端口：8080 (可配置)
  • 消息类型：包含注册、控制指令、图像数据、图像分片、心跳等。

3. 消息类型

3.1 注册消息（Register）

请求

  • 请求类型：Register
  • 内容字段：
    • client_type (string)：客户端类型，值为 "control" 或 "robot"，表示控制端或机器人端。
    • client_id (string)：客户端唯一标识符，用于区分不同的控制端或机器人端。

示例：

{
  "type": "register",
  "data": {
    "client_type": "control",
    "client_id": "control_1"
  }
}

说明：

  • 该请求用于注册控制端或机器人端，服务器接收到后会记录客户端信息。
  • 注册成功后，服务器将为该客户端分配一个地址，并可以向其发送控制指令或图像数据。

3.2 控制指令消息（ControlCommand）

请求

  • 请求类型：ControlCommand
  • 内容字段：
    • command (string)：控制命令，值为 "forward"、"backward"、"left" 或 "right"，分别对应前进、后退、左转和右转。
    • timestamp (integer)：时间戳，表示此指令的发送时间（UNIX 时间戳）。

示例：

{
  "type": "control_command",
  "data": {
    "command": "forward",
    "timestamp": 1632739200
  }
}

说明：

  • 该请求用于控制机器人执行相应的动作，服务器会将该指令转发给所有已注册的机器人端。

3.3 图像数据消息（ImageData）

请求

  • 请求类型：ImageData
  • 内容字段：
    • image (string)：Base64 编码的图像数据，表示从机器人端拍摄到的实时图像。
    • timestamp (integer)：时间戳，表示图像数据的生成时间（UNIX 时间戳）。

示例：

{
  "type": "image_data",
  "data": {
    "image": "iVBORw0KGgoAAAANSUhEUgAAA...",
    "timestamp": 1632739200
  }
}

说明：

  • 该请求用于发送从机器人端拍摄的图像数据。图像数据经过 Base64 编码后传输，服务器会将图像转发给所有已注册的控制端。

3.4 图像分片数据消息（ImageFragment）

请求

  • 请求类型：ImageFragment
  • 内容字段：
    • sequence (integer)：当前分片编号，从 1 开始。
    • total (integer)：总分片数，表示该图像被分割为多少个部分。
    • image (string)：Base64 编码的图像分片数据。
    • timestamp (integer)：时间戳，表示此图像分片的生成时间（UNIX 时间戳）。

示例：

{
  "type": "image_fragment",
  "data": {
    "sequence": 1,
    "total": 3,
    "image": "iVBORw0KGgoAAAANSUhEUgAAA...",
    "timestamp": 1632739200
  }
}

说明：

  • 当图像过大时，机器人端会将图像分片发送。每个分片都带有 sequence 和 total 字段，以便服务器和控制端进行正确的分片重组。

3.5 心跳消息（Heartbeat）

请求

  • 请求类型：Heartbeat
  • 内容字段：
    • client_type (string)：客户端类型，值为 "control" 或 "robot"，表示控制端或机器人端。
    • client_id (string)：客户端唯一标识符，用于区分不同的控制端或机器人端。
    • timestamp (integer)：时间戳，表示心跳消息的发送时间（UNIX 时间戳）。

示例：

{
  "type": "heartbeat",
  "data": {
    "client_type": "control",
    "client_id": "control_1",
    "timestamp": 1632739200
  }
}

说明：

  • 心跳消息用于检测客户端是否仍然在线。控制端和机器人端都需要定期发送心跳消息，服务器将记录心跳时间，并定期清理超时的客户端。

4. 服务器响应

服务器并不会主动返回响应消息，所有响应都为 ACK（确认）。如果消息格式正确且处理成功，服务器会继续处理并将消息转发给其他相关端（如控制端、机器人端等）。若处理失败，服务器会记录错误并可能会丢弃该消息。

5. 服务器行为

5.1 注册行为

  • 控制端和机器人端在首次连接时需要发送注册消息。
  • 服务器接收到注册消息后，会将客户端地址存储在内存中，并根据客户端类型（control 或 robot）分配不同的处理逻辑。

5.2 消息转发行为

  • 控制指令：服务器将控制指令消息转发给所有已注册的机器人端。
  • 图像数据：服务器将图像数据转发给所有已注册的控制端。
  • 图像分片数据：服务器将图像分片转发给所有已注册的控制端。
  • 心跳消息：服务器会更新该客户端的心跳时间戳，并清理超时的客户端。

5.3 心跳检查

  • 服务器会定期检查所有客户端的心跳，若超过一定时间未收到心跳消息，服务器将移除该客户端，并不会再转发消息。

6. 错误处理

  • 无效消息格式：服务器会丢弃不符合 JSON 格式的消息，且不会发送任何确认消息。
  • 未知消息类型：如果接收到未知的消息类型，服务器会丢弃该消息并输出错误日志。
  • 客户端超时：如果超过设定的时间没有接收到心跳消息，服务器会认为该客户端已经失效，并将其从客户端列表中移除。