# Universal Packet Format

## General Packet Format

Ping Protocol comprises a binary packet format. All packets have the same structure which is defined in the table below. 

| Byte index       | Data Type | Name            | Description                                                          |
| ---------------- | --------- | --------------- | -------------------------------------------------------------------- |
| 0                | u8        | 'B'             | decimal value 66, hex 0x42                                           |
| 1                | u8        | 'R'             | decimal value 82, hex 0x52                                           |
| 2-3              | u16       | N               | number of bytes in the payload                                       |
| 4-5              | u16       | packet\_id      | unique id for each packet type                                       |
| 6                | u8        | src\_device\_id | which device the packet is coming from                               |
| 7                | u8        | dst\_device\_id | which device the packet is going to                                  |
| 8 to (8+N-1)     | u8\[]     | payload         | payload specific to each packet\_id                                  |
| (8+N) to (8+N+1) | u16       | checksum        | sum of all the bytes in the packet from 0 to n, truncated to 16 bits |

Note that `src_device_id` and `dst_device_id` are usually 0. However, when SonarLink receives a packet from a device, it updates `src_device_id`. When it sends a packet to a device, it will respect `dst_device_id`. The special value 255 is reserved to mean "all devices".

### Payload Conventions

Individual fields within the payload are aligned on their appropriate boundaries. So 32 bit fields are aligned on 4 byte boundaries, 16 bit fields are aligned on 2 byte boundaries and 8 bit fields can be on any byte alignment. Note that the checksum field is not necessarily aligned on a 2 byte boundary however.

### Parsing Unknown Packet IDs

Note that a packet parser can easily skip over packets that it doesn't understand or need to handle by just advancing the stream beyond the payload and the checksum. It is to be expected that there could be unknown packet types in any live stream or replayed log file. 

### Future Proofing

It is allowed for future fields to be added to any particular packet payload. Therefore parsers should check to see that the packet length is sufficient for any fields that will be used, but should not be alarmed if the payload length is longer than expected.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ceruleansonar.com/c/cerulean-ping-protocol/universal-packet-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.