本文來源：

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、根據協議傳送命令或接收訊息；