In a serialized application, serialization codecs are a mechanism for encoding and decoding the commands and events between the Bluetooth Application Chip and the BLE Connectivity Chip.
The following figure presents the general format of serialized packets.
For an architectural overview of a serialized Bluetooth Application, see the figure Architectural overview of Serialized Bluetooth Application.
The following figure presents the flow of command and response packets in a serialized application.
Packet Type | Description |
---|---|
0x00 Command | The packet is sent from the application chip to the BLE Connectivity Chip, where it is decoded and the corresponding function in the SoftDevice is executed. |
0x01 Command Response | After a function in the SoftDevice is received, the response is encoded in the BLE 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 BLE Connectivity Chip, where it is decoded and the chip enters the DTM mode. |
0x04 DTM Command Response | Before the BLE Connectivity Chip enters the DTM mode, it sends a response packet to the application chip. |
Note: If the length field is invalid for the specific command, the call will return error code NRF_ERROR_INVALID_LENGTH from the codec in the application chip.
The following figure presents the flow of event packets in a serialized application.
Packet Type | Description |
---|---|
0x02 Event | If an event is triggered in the SoftDevice, an event packet is sent from the BLE Connectivity Chip to the application chip. |
Certain rules apply when encoding each type of data in a serialized application. See the sections below for details.
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:
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 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.
Structures are encoded the same way as arguments in a function. Elements keep the defined order unless it is necessary to change it. 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 case, it is important to send the length field before 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 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 (e.g. a custom type flag). In such cases, serialization parses such data to determine data length.
The order of bit fields encoding is controlled by serialization so it does not rely on the compiler or architecture ordering.