In a serialized application, serialization codecs are a mechanism for encoding and decoding the commands and events between the application chip and the connectivity chip.
Packet encoding format
The following figure presents the general format of serialized packets:
Commands and responses
The following figure presents the flow of command and response packets in a serialized application:
| Packet type | Description |
|---|---|
| 0x00 BLE command 0x06 ANT command | The packet is sent from the application chip to the connectivity chip, where it is decoded and the corresponding function in the SoftDevice is executed. |
| 0x01 BLE command response 0x07 ANT command response | After a function in the SoftDevice is called, the response is encoded in the connectivity chip and a response packet is sent to the application chip. |
| 0x03 DTM command | The packet is sent from the application chip to the connectivity chip, where it is decoded and the chip enters DTM mode. |
| 0x04 DTM command response | Before the connectivity chip enters DTM mode, it sends a response packet to the application chip. |
| 0x05 System reset command | The application chip sends a system reset command to the connectivity chip. |
- Note
- If the length field is invalid for the specific command, the call returns the error code NRF_ERROR_INVALID_LENGTH from the codec in the application chip.
Events
The following figure presents the flow of event packets in a serialized application:
| Packet Type | Description |
|---|---|
| 0x02 BLE event 0x08 ANT event | If an event is triggered in the SoftDevice, an event packet is sent from the connectivity chip to the application chip. |
General rules for encoding data
Certain rules apply when encoding each type of data in a serialized application. See the following sections for details.
Encoding primitive arguments
Function arguments are encoded in the same order as in the function declaration. When arguments are passed by value, they are encoded as is (regarding their size and ordering), assuming that the receiver has knowledge about the order and type of elements. The function return value is also encoded as is into the packet and sent in response.
Example:
Encoding arguments passed by a pointer
If an argument of a function is a pointer, its encoding depends on the nature of the argument.
If the data passed by the pointer is an input argument, then it is encoded only in the request packet and is not present in the response packet. An argument provided by a pointer is preceeded in the packet with a 1-byte flag that indicates if the pointer is NULL or not. Data is present only if the pointer is not NULL.
Example:
If the argument is an output argument, then the request packet contains only a presence flag and does not contain the content of the argument. The response packet contains both the presence flag and the content.
Example:
If the argument is described as input/output, then its content is present both in the request and the response packet.
Encoding structures
Structures are encoded in the same way as arguments in a function. Elements keep the defined order unless it is necessary to change the order. Such a change is required if the structure contains a pointer to data and length fields and the length field is defined after the data pointer. In such a case, it is important to send the length field before the actual data. If the structure contains nested structures, they are unrolled and encoded in order of definition.
Example:
If the structure contains pointers, then the same unrolling rule applies, for example:
Encoding variable length data
Encoding variable length data consists of encoding length and the buffer. Because the buffer is a pointer, a presence flag is put before the buffer and it is encoded only if this pointer is not NULL. The length field is encoded before the data, regardless of function arguments ordering or ordering of elements in the structure.
Example:
In certain cases, the SoftDevice API has variable length data where the length field is not provided. There are other ways to determine the size of a variable length buffer (for example, a custom type flag). In such cases, serialization parses such data to determine the data length.
Encoding bit fields
The order of bit fields encoding is controlled by serialization, so that it does not rely on the compiler or architecture ordering.