安卓与ROS通信开发——3、rosbridge v2.0协议规范

安卓与ROS通信开发——3、rosbridge v2.0协议规范

https://github.com/RobotWebTools/rosbridge_suite/blob/groovy-devel/ROSBRIDGE_PROTOCOL.md
更新于2019年3月28日
本文档概述了rosbridge v2.0协议。v2.0协议包含了自rosbridge的第一个版本发布以来出现的许多需求，并进行了少量的修改，以提高协议的可扩展性。在其核心，该协议仍然包含与先前版本rosbridge相同的语义的操作。
主要的变化是消息的结构，将控制信息和消息信息分开。新增加的主要内容是碎片、压缩和日志记录。
本文概述了协议规范，但也涉及到rosbridge服务器实现的预期方向。rosbridgev2.0服务器实现的体系结构使添加和修改协议操作变得更加容易。此外，rosbridgev2.0服务器将JSON处理与websockets服务器分离，允许用户任意更改他们正在使用的特定websockets服务器实现。
rosbridge的消息传输是JSON对象。唯一必需的字段是“op”字段，它指定该消息的操作。然后每个“op”指定自己的消息语义。
rosbridge协议是一组“op”代码，它们定义了许多操作，以及每个操作的语义。
rosbridge服务器是一个接受websockets连接并实现rosbridge协议的服务器。
rosbridge的完整源代码位于rosbridge_suite包中。https://github.com/robotwebtools/rosbridge_suite

1. 前言 The rosbridge transport

在基本情况下，rosbridge消息是一个JSON对象，带有一个名为“op”的字符串字段。例如：
{
“op”：“Example”
}
op字段指示这是什么类型的消息。具有不同op值的消息可能会以不同的方式处理。
只要消息是带有op字段的JSON对象，它就是有效的rosbridge消息。
或者，消息还可以提供任意字符串或整数ID：
{
“op”：“Example”，
“id”：“fred”
}
如果向服务器提供了一个ID，那么相关的响应消息通常也包含该ID。此操作导致的日志消息也将包含ID。
从语义上讲，ID不是它所在的特定消息的标识符，而是一个交互的标识符，该交互可能由往返消息中的多个操作组 成。因此，该ID可由引用同一事务的多个消息使用。

2. 目录 The rosbridge protocol

rosbridge协议定义了许多不同的操作。
通常，客户端执行的操作或操作（例如发布和订阅）的操作码是动词（subscribe、call_service、unadvertise等）。
来自服务器的响应消息是客户端返回的内容，因此它们是名词（片段、状态、服务响应等）
具体如下：

信息压缩/转化** Message compression / transformation:**

• fragment - a part of a fragmented message
• png - a part of a PNG compressed fragmented message

Rosbridge状态消息** Rosbridge status messages:**

• set_status_level - a request to set the reporting level for rosbridge status messages
• status - a status message

身份验证** Authentication:**

• auth - a set of authentication credentials to authenticate a client connection

ROS操作** ROS operations:**

• advertise – advertise that you are publishing a topic
• unadvertise – stop advertising that you are publishing topic
• publish - a published ROS-message
• subscribe - a request to subscribe to a topic
• unsubscribe - a request to unsubscribe from a topic
• call_service - a service call
• service_response - a service response

3. 协议细节 Details of the rosbridge protocol

3.1 数据编码及转换 Data Encoding and Transformation

该协议能够分割消息与压缩消息
The rosbridge protocol provides the ability to fragment messages and to compress messages.

3.1.1 消息分割 Fragmentation ( fragment ) [experimental]

如果消息特别大，或者客户端请求碎片化，那么消息可能是碎片化的。碎片化的消息的格式如下：
{ **
"op": “fragment”,
** “id”: ,
** “data”: ,**
** “num”: ,**
** “total”: **
}

• id - an id is required for fragmented messages, in order to identify corresponding fragments for the fragmented message:
• data - a fragment of data that, when combined with other fragments of data, makes up another message
• num - the index of the fragment in the message
• total - the total number of fragments

为了对消息进行分段，将获取其JSON字符串并将其拆分为多个子字符串。对于每个子字符串，构造一个片段消息，子字符串填充片段的数据字段。
为了重建原始消息，片段的数据字段被连接起来，从而得到原始消息的JSON字符串。
**

3.1.2 消息压缩 PNG compression ( png ) [experimental]

有些消息（如点云）可能非常大，出于效率考虑，我们可能希望将它们基于PNG编码的字节进行传输。PNG操作码复制了FRG操作码的碎片逻辑（只有一个片段是可能的，也是合理的），除了数据字段由ASCII编码的PNG字节组成。
{
"op": “png”,
** (optional) “id”: ,**
"data": ,
(optional) “num”: ,
(optional) “total”:
}

• id – only required if the message is fragmented. Identifies the fragments for the fragmented message.
• data – a fragment of a PNG-encoded message or an entire message.
• num – only required if the message is fragmented. The index of the fragment.
• total – only required if the message is fragmented. The total number of fragments.

要构造一个PNG压缩消息，请获取原始消息的JSON字符串并将该字符串的字节读入PNG图像。然后，ASCII对图像进行编码。此字符串现在用作数据字段。如果需要分段，则对数据进行分段，并将ID、num和total字段设置为片段中适当的值。否则这些字段可以省略。

3.2 状态消息Status messages

rosbridge向客户机发送有关rosbridge协议命令成功和失败的状态消息。有四个状态级别： info, warning, error, none.（信息、警告、错误、无）

• error – Whenever a user sends a message that is invalid or requests something that does not exist (ie. Sending an incorrect opcode or publishing to a topic that doesn’t exist)
• warning – error, plus, whenever a user does something that may succeed but the user has still done something incorrectly (ie. Providing a partially-complete published message)
• info – warning, plus messages indicating success of various operations

3.2.1 改变状态级别 Set Status Level ( status_level ) [experimental]

默认情况下，rosbridge使用error的状态级别。
{ **
"op": “set_level”,
** (optional) “id”: ,
** “level”: **
}

• level – one of ‘info’, ‘warning’, ‘error’, or 'none’

**

3.2.2 状态消息 Status message ( status ) [experimental]

{
** “op”: “status”,**
** (optional) "id": ,**
** "level": ,**
** "msg": **
}

• level – the level of this status message
• msg – the string message being logged
• id – if the status message was the result of some operation that had an id, then that id is included

3.3 身份验证 Authentication message

身份验证信息可以通过rosbridge协议传递来验证客户端连接。此信息应该来自可信的第三方身份验证程序。
认证基于MAC（消息认证码）方案。使用MAC的关键在于它不会将用户绑定到一个“用户数据库”，它只需要一些可信的第三方来提供hash-keys哈希密钥。

3.3.1 Authenticate ( auth )

To send authentication credentials, use the auth command.
{
"op": “auth”, **
** “mac”: , **
** “client”: , **
** “dest”: , **
** “rand”: , **
** “t”: , **
** “level”: , **
** “end”:
**}
**

• mac – MAC (hashed) string given by the client

• client – IP of the client

• dest – IP of the destination

• rand – random string given by the client

• t – time of the authorization request

• level – user level as a string given by the client

• end – end time of the client’s session

  • Any server that enabled authentication should wait for this request to come in first before accepting any otherop code from the client.
  • Once the request comes in, it would verify the information (in a ROS system, using rosauth; however, the verification method is not tied to ROS).
  • If the authentication is good, the connection would be kept and rosbridge would function as normal. If the authentication is bad, the connection would be severed.
  • In the case that authentication is not enabled on the server, this op code can be ignored.

3.4 与ROS交互的消息 ROS messages

3.4.1 建立新主题 Advertise ( advertise )

If you wish to advertise that you are or will be publishing a topic, then use the advertise command.
{ **
"op": “advertise”,
** (optional) "id": ,
** "topic": ,**
** “type”: **
}

• topic – the string name of the topic to advertise

• type – the string type to advertise for the topic

  • If the topic does not already exist, and the type specified is a valid type, then the topic will be established with this type.
  • If the topic already exists with a different type, an error status message is sent and this message is dropped.
  • If the topic already exists with the same type, a warning status message is sent and this message is dropped.
  • If the topic doesnt already exist but the type cannot be resolved, then an error status message is sent and this message is dropped.

3.4.2 撤销已存在主题 Unadvertise ( unadvertise )

This stops advertising that you are publishing a topic.
{ **
"op": “unadvertise”,
** (optional) “id”: ,
** “topic”: **
}

• topic – the string name of the topic being unadvertised
  • If the topic does not exist, a warning status message is sent and this message is dropped
  • If the topic exists but rosbridge is not advertising it, a warning status message is sent and this message is dropped

3.4.3 发布消息 Publish ( publish )

The publish message is used to send data on a topic.
{
** "op": "publish",**
** (optional) "id": ,**
** "topic": ,**
** "msg": **
}
The publish command publishes a message on a topic.

• topic - the string name of the topic to publish to

• msg - the message to publish on the topic

  • If the topic does not exist, then an error status message is sent and this message is dropped
  • If the msg does not conform to the type of the topic, then an error status message is sent and this message is dropped
  • If the msg is a subset of the type of the topic, then a warning status message is sent and the unspecified fields are filled in with defaults

Special case: if the type being published has a ‘header’ field, then the client can optionally omit the header from the msg. If this happens, rosbridge will automatically populate the header with a frame id of “” and the timestamp as the current time. Alternatively, just the timestamp field can be omitted, and then the current time will be automatically inserted.

3.4.4 订阅主题 Subscribe

{ **
"op": “subscribe”,
** (optional) “id”: ,
** “topic”: ,**
** (optional) “type”: ,**
** (optional) “throttle_rate”: ,**
** (optional) “queue_length”: ,**
** (optional) “fragment_size”: ,**
** (optional) “compression”: **
}
This command subscribes the client to the specified topic. It is recommended that if the client has multiple components subscribing to the same topic, that each component makes its own subscription request providing an ID. That way, each can individually unsubscribe and rosbridge can select the correct rate at which to send messages.

• type – the (expected) type of the topic to subscribe to. If left off, type will be inferred, and if the topic doesn’t exist then the command to subscribe will fail
• topic – the name of the topic to subscribe to
• throttle_rate – the minimum amount of time (in ms) that must elapse between messages being sent. Defaults to 0
• queue_length – the size of the queue to buffer messages. Messages are buffered as a result of the throttle_rate. Defaults to 1.
• id – if specified, then this specific subscription can be unsubscribed by referencing the ID.
• fragment_size – the maximum size that a message can take before it is to be fragmented.
• compression – an optional string to specify the compression scheme to be used on messages. Valid values are “none” and “png”

If queue_length is specified, then messages are placed into the queue before being sent. Messages are sent from the head of the queue. If the queue gets full, the oldest message is removed and replaced by the newest message.
If a client has multiple subscriptions to the same topic, then messages are sent at the lowest throttle_rate, with the lowest fragmentation size, and highest queue_length. It is recommended that the client provides IDs for its subscriptions, to enable rosbridge to effectively choose the appropriate fragmentation size and publishing rate.

3.4.5 取消订阅主题Unsubscribe

{
** “op”: “unsubscribe”,**
** (optional) "id": ,**
** “topic”: **
}

• topic – the name of the topic to unsubscribe from
• id – an id of the subscription to unsubscribe

If an id is provided, then only the corresponding subscription is unsubscribed. If no ID is provided, then all subscriptions are unsubscribed.

3.4.6 呼叫服务 Call Service

{
"op": “call_service”,
** (optional) “id”: ,**
** “service”: ,**
** (optional) “args”: <list>,**
** (optional) “fragment_size”: ,**
** (optional) “compression”: **
}
Calls a ROS service

• service – the name of the service to call
• args – if the service has no args, then args does not have to be provided, though an empty list is equally acceptable. Args should be a list of json objects representing the arguments to the service
• id – an optional id to distinguish this service call
• fragment_size – the maximum size that the response message can take before it is fragmented
• compression – an optional string to specify the compression scheme to be used on messages. Valid values are “none” and “png”

3.4.7 服务响应 Service Response

{ **
"op": “service_response”,
** (optional) "id": ,
** "service": ,**
** (optional) “values”: <list>**
}
A response to a ROS service call

• service – the name of the service that was called
• values – the return values. If the service had no return values, then this field can be omitted (and will be by the rosbridge server)
• id – if an ID was provided to the service request, then the service response will contain the ID