rosbridge v2.0 协议规范

本文来源：

https://github.com/RobotWebTools/rosbridge_suite/blob/groovy-devel/ROSBRIDGE_PROTOCOL.md#344-subscribe

这篇文档概述了rosbridge v2.0 协议规范。V2.0协议包含了自 rosbridge v1.0发布以来出现的许多需求，并进行了少量修改，以便于更大的可扩展性。在其核心，协议仍然包含相同的操作，其语义与以前的版本相同。主要的变化在于消息的结构，从消息信息中分离出控制信息；主要新增的是碎片、压缩和日志记录。

本文档概述了协议规范，但也涉及rosbridge服务器实现的预期方向。rosbridge 2.0服务器实现的架构是为了便于添加和修改协议操作。此外，rosbridge v2.0服务器将JSON处理与websockets服务器解耦，允许用户任意更改他们正在使用的特定websockets服务器实现。

rosbridge 传递的消息是JSON对象。唯一需要的字段是“OP”字段，它指定该消息的操作，每个“OP”然后指定它自己的消息语义。

rosbridge 协议是一组“OP”代码，它定义了多个操作，以及每个操作的语义。

rosbridge 服务器是一个接受Websockets连接并实现rosbridge 协议的服务器。

rosbridge 的全部源代码位于rosbridge_suite 包中。该包链接：https://github.com/robotwebtools/rosbridge_suite，在文档的第4.5节详细介绍了rosbridge_suite 包的各个部分。

1. The rosbridge transport

在基本情况下，一个rosbridge消息是一个带有一个称为“OP”的字符串字段的JSON对象。例如：{ "op": "Example" }
——》OP字段表示的是消息的类型。OP有不同值的消息表示不同的处理。只要JSON对象的消息带有OP字段，那么就是一个有效的 rosbridge 消息。

当然，消息还可以提供任意字符串或整型ID：
       { "op": "Example",
       "id": "fred"
       }

如果一个带有ID的消息被发送给服务器，那么相关的响应消息通常也包含该ID。此操作引起的日志消息也将包含ID。

在语义上，ID不是它所在的特定消息的标识符，而是用于交互的标识符，它包括来回消息中的许多操作，因此，ID可以用于同一事件的多个消息中。

2. The rosbridge protocol

rosbridge协议定义了许多不同的操作。它们如下：

（１）Message compression / transformation:
       fragment - a part of a fragmented message
       png - a part of a PNG compressed fragmented message
（２）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 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

通常，客户端采取的操作（例如发布和订阅）具有操作码，这些操作码是动作（subscribe、call_service、unadvertise等）。
而来自服务器的响应消息是客户端返回的东西，因此它们是名词（片段、状态、service_response等）。
（此命名约定唯一的例外例外是发布publish）

3. Details of the rosbridge protocol

下面是rosbridge协议中的操作规范，由rosbridge服务器支持。任何标记为[experimental]的操作规范在检验后可能会被修改。

3.1 Data Encoding and Transformation（Message compression / transformation）
rosbridge协议提供了分段消息和压缩消息（fragment messages and to compress messages.）。
3.1.1 Fragmentation ( fragment ) [experimental]
如果消息信息特别大那么消息可能会被碎片化，或者client端要求消息碎片。碎片化的消息有如下格式：

{ "op": "fragment",
  "id": <string>,
  "data": <string>,
  "num": <int>,
  "total": <int>
}

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-encoded的字节来传输。PNG操作码复制了FRG操作码的分段逻辑（并且只有一个片段是可能和合理的），除了数据字段由ASCII编码的PNG字节组成。

{ "op": "png",
  (optional) "id": <string>,
  "data": <string>,
  (optional) "num": <int>,
  (optional) "total": <int>
}

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和总字段设置为分段中的适当值。否则，这些字段可以被省略。

3.2 Status messages（Rosbridge status messages）
rosbridge发送状态消息到客户端，包含命令执行是否 successes or failures 。有四个status级别：info, warning, error, none.默认，rosbridge使用error status。
3.2.1 Set Status Level ( status_level ) [experimental]

{ "op": "set_level",
  (optional) "id": <string>,
  "level": <string>
}

level – one of 'info', 'warning', 'error', or 'none'

将状态级别设置为指定的级别。如果指定了坏字符串，则将删除该消息。

3.2.2 Status message ( status ) [experimental]

{ "op": "status",
  (optional) "id": <string>,
  "level": <string>,
  "msg": <string>
}

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（Authentication）

认证信息可以通过robbridge协议来验证客户端连接。此信息应该来自一些受信任的第三方认证器。

认证是基于MAC（消息认证码）的。使用MAC的关键在于它不将用户绑定到一个“用户数据库”，它只需要某些可信的第三方提供hash-keys。

3.3.1 Authenticate ( auth )

{ "op": "auth", 
  "mac": <string>, 
  "client": <string>, 
  "dest": <string>, 
  "rand": <string>, 
  "t": <int>, 
  "level": <string>, 
  "end": <int>
}

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

——》任何服务器，启用认证应该等待这个请求来先接受来自客户端的任何其他操作码。

——》一旦请求进入，它将验证信息（在ROS系统中，使用rosauth；然而，验证方法不与ROS绑定）。

——》如果认证良好，将保持连接，并且罗桥将正常工作。如果验证不正确，连接将被切断。

——》在服务器上没有启用身份验证的情况下，可以忽略此OP代码。

3.4 ROS messages（ROS operations）

这些rosbridge消息与ROS交互。

3.4.1 Advertise ( advertise )

{ "op": "advertise",
  (optional) "id": <string>,
  "topic": <string>,
  "type": <string>
}

topic – the string name of the topic to advertise
type – the string type to advertise for the topic

——》如果主题不存在，并且指定的类型是有效类型，则将使用此类型建立主题。

——》如果主题已存在不同的类型，则发送错误状态消息，并删除该消息。

——》如果主题已经存在于同一类型，则发送警告状态消息，并删除该消息。

——》如果主题已不存在，但无法解析类型，则发送错误状态消息，并删除该消息。

3.4.2 Unadvertise ( unadvertise )

{ "op": "unadvertise",
  (optional) "id": <string>,
  "topic": <string>
}

topic – the string name of the topic being unadvertised

——》如果主题不存在，则发送警告状态消息，并删除该消息。

——》如果主题存在但RoSbice不发布广告，则发送警告状态消息，并删除该消息。

3.4.3 Publish ( publish )

发布消息用于在主题上发送数据。

{ "op": "publish",
  (optional) "id": <string>,
  "topic": <string>,
  "msg": <json>
}

发布命令在主题上发布消息。

topic - the string name of the topic to publish to
msg - the message to publish on the topic

——》如果主题不存在，则发送错误状态消息，并删除该消息。

——》如果MSG不符合主题的类型，则发送错误状态消息，并删除该消息。

——》如果味精是对题目类型的一个子集，然后警告状态消息发送和未指定的字段填充默认值

特殊情况：如果所发布的类型有一个“页眉”字段，那么客户端可以随意地从MSG中省略头。如果发生这种情况，罗斯布里奇将自动以“ID”和时间戳作为当前时间填充报头。或者，可以省略时间戳字段，然后自动插入当前时间。

3.4.4 Subscribe

{ "op": "subscribe",
  (optional) "id": <string>,
  "topic": <string>,
  (optional) "type": <string>,
  (optional) "throttle_rate": <int>,
  (optional) "queue_length": <int>,
  (optional) "fragment_size": <int>,
  (optional) "compression": <string>
}

此命令将客户端订阅到指定的主题。如果客户机有多个组件订阅同一主题，建议每个组件发出自己的订阅请求，提供ID。这样，每个组件可以单独取消订阅，并且rosbridge可以选择发送消息的正确速率。

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"

如果指定了QuealeSL长度，则在发送之前将消息放入队列中。消息是从队列的头发送的。如果队列已满，则删除最旧的消息并用最新消息替换。如果客户机对同一主题有多个订阅，则以最低的throttle_rate、最低的分段大小和最高的queue_.发送消息。建议客户机为其订阅提供ID，以使rosbridge能够有效地选择适当的片段大小和发布速率。

3.4.5 Unsubscribe

{ "op": "unsubscribe",
  (optional) "id": <string>,
  "topic": <string>
}

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

如果提供ID，则只订阅相应的订阅。如果没有提供ID，则所有订阅都被取消订阅。

3.4.6 Call Service

{ "op": "call_service",
  (optional) "id": <string>,
  "service": <string>,
  (optional) "args": <list<json>>,
  (optional) "fragment_size": <int>,
  (optional) "compression": <string>
}

调用ROS服务

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": <string>,
  "service": <string>,
  (optional) "values": <list<json>>
}

对ROS服务调用的响应

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

4、使用rosbridge协议需要：

1、安装功能包：sudo apt-get install ros-kinect-rosbridge-suite

2、启动rosbridge_sever,如 roslaunch rosbridge_server rosbridge_tcp.launch 或

roslaunch rosbridge_server rosbridge_websocket.launch

3、client端连接sever端；

4、根据协议发送命令或接收消息；

rosbridge v2.0 协议规范

id – if an ID was provided to the service request, then the service response will contain the ID

4、使用rosbridge协议需要：

猜你喜欢