Draft
Conversation
There was a problem hiding this comment.
Pull request overview
This PR rewrites and reorganizes ROSBRIDGE_PROTOCOL.md to present a clearer, more structured rosbridge v2 protocol specification (envelope, operation summary, encoding/transformations, then per-operation specs).
Changes:
- Replaces the older narrative spec with a table-driven, sectioned specification (envelope, operations, encodings).
- Updates/clarifies encoding sections (base64 bytes, fragmentation, PNG, CBOR, CBOR-RAW).
- Adds per-op field tables and directionality notes for topics/services/actions.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Comment on lines
+26
to
+31
| - [4.2 Service operations](#42-service-operations) | ||
| - [4.2.1 advertise\_service (C → S)](#421-advertise_service-c--s) | ||
| - [4.2.2 unadvertise\_service (C → S)](#422-unadvertise_service-c--s) | ||
| - [4.2.3 call\_service (C ↔ S)](#423-call_service-c--s) | ||
| - [4.2.5 service\_response (C ↔ S)](#425-service_response-c--s) | ||
| - [4.3 Action operations](#43-action-operations) |
Comment on lines
+246
to
+248
| - If the topic does not exist, a warning status message is sent and this message is dropped. | ||
| - If the topic exists and there are still clients left advertising it, rosbridge will continue to advertise it until all of them have unadvertised. | ||
| - If the topic exists but rosbridge is not advertising it, a warning is logged and this message is dropped. |
Comment on lines
+256
to
+270
| | Field | Required | Type | Description | | ||
| |-------|----------|------|-------------| | ||
| | `op` | required | string | Must be `"publish"` | | ||
| | `id` | optional | string | An ID to associate with this operation. | | ||
| | `topic` | required | string | The name of the topic to publish on. | | ||
| | `msg` | required | object | The message being published on the topic. | | ||
|
|
||
| * **service** – the name of the service to unadvertise | ||
| **Client → Server** | ||
|
|
||
| #### 3.3.9 Service Response | ||
| The client sends a `publish` message to push a message onto a ROS topic. | ||
| The client must have previously advertised the topic using the `advertise` operation before publishing. | ||
|
|
||
| A response to a ROS service call. | ||
| - 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 is logged and this message is dropped. | ||
| - If the `msg` is a subset of the type of the topic, then a warning is logged and the unspecified fields are filled in with defaults. |
| | `id` | optional | string | An ID to associate with this service call. Will be included in the response. | | ||
| | `service` | required | string | The name of the service to call. | | ||
| | `args` | optional | object or list | The arguments to pass to the service. Can be an object with message fields or a list of field values in the order they appear in the service request definition. | | ||
| | `fragment_size` | optional | integer | (only C → S) The maximum size (in bytes) a message can reach before it is fragmented. | |
Comment on lines
+356
to
+362
| | Field | Required | Type | Description | | ||
| |-------|----------|------|-------------| | ||
| | `op` | required | string | Must be `"service_response"` | | ||
| | `id` | optional | string | An ID to associate with this service response. Will match the ID of the corresponding service call if it was provided. | | ||
| | `service` | required | string | The name of the service that was called. | | ||
| | `values` | required | object or string | The return values from the service or an error message if the service call failed. | | ||
| | `result` | required | boolean | The result of the service call. `true` indicates success, `false` indicates failure. | |
Comment on lines
+429
to
+431
| | `values` | required | object or string | The result values from the action or an error message if the action failed. | | ||
| | `status` | required | integer | The status of the action. This matches the enumeration in the [`action_msgs/msg/GoalStatus`](https://docs.ros2.org/latest/api/action_msgs/msg/GoalStatus.html) ROS message. | | ||
| | `result` | required | boolean | The result of the action. `true` indicates success, `false` indicates failure. | |
Comment on lines
+62
to
+63
| If an `id` is provided with a message to the server, then related response messages will typically contain that ID as well. | ||
| Log messages caused by this operation will also include the ID, so that clients can easily associate log messages with the operation that caused them. |
Comment on lines
+147
to
+156
| | Field | Required | Type | Description | | ||
| |-------|----------|------|-------------| | ||
| | `op` | required | string | Must be `"fragment"` | | ||
| | `id` | required | string | Identifies which fragments belong to the same original message. | | ||
| | `data` | required | string | A chunk of the original message payload. Concatenating all chunks in order reconstructs the original serialized message. | | ||
| | `num` | required | integer | Zero-based index of this fragment within the sequence. | | ||
| | `total` | required | integer | Total number of fragments that make up the original message. | | ||
|
|
||
| If you wish to advertise that you are or will be publishing a topic, then use the advertise command. | ||
| To fragment a message, its serialized payload is taken and split up into multiple substrings or byte arrays. | ||
| For each chunk, a fragment message is constructed, with the data field of the fragment populated by the chunk. |
| | `action_type` | required | string | The action type. | | ||
| | `args` | optional | object or list | The arguments to pass to the action goal. Can be an object with message fields or a list of field values in the order they appear in the action goal definition. | | ||
| | `feedback` | optional | boolean | Whether to send feedback messages for this goal. Defaults to `false`. | | ||
| | `fragment_size` | optional | integer | (only C → S) The maximum size (in bytes) a message can reach before it is fragmented. | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.