[−][src]Module rubble::link

Link-Layer.

Note that a hardware BLE radio will already implement a few aspects of the link layer (such as CRC calculation, preamble generation, etc.). Consider this module to be a construction kit for BLE Link-Layers: Take whatever your hardware can do, supplement it with a few condiments from this module, and you get a (hopefully) working Link-Layer.

Refer to the official Link Layer Specification for details and more graphics and tables.

Packet Format

All following graphics are based on the Bluetooth specification. If a field is marked with -, it should be set to 0 when sending such a packet, and ignored when receiving it (the spec calls these "RFU" = Reserved for Future Use).

All values are transmitted in little-endian bit order unless otherwise noted. All fields in graphics are ordered starting with the field transmitted first (LSB).

The following graphic illustrates the raw in-air packet format. The packet transfers a PDU whose format depends on whether it is sent on an advertising channel or a data channel.

LSB                                                     MSB
+-----------+----------------+---------------+------------+
| Preamble  | Access Address |     PDU       |  CRC       |
| (1 octet) | (4 octets)     | (2-39 octets) | (3 octets) |
+-----------+----------------+---------------+------------+
                             \---------------/      ^
                                     |              |
                                     +--------------+
                                    CRC is calculated
                                      over the PDU

                             \----------------------------/
                                   Data Whitening is
                                applied to PDU and CRC

The 24-bit CRC value is transmitted MSb first. Length of the PDU depends on the kind of PDU (advertising or data channel).

Advertising Channel PDU

Each advertising channel PDU consists of a 16-bit header and a variably-sized payload, the length of which is stored in a header field.

LSB                                           MSB
+-------------+---------------------------------+
|  Header     |             Payload             |
|  (16 bits)  |    (length stored in header)    |
+-------------+---------------------------------+

The header looks like this:

LSB                                                                     MSB
+------------+------------+---------+---------+--------------+------------+
|  PDU Type  |     -      |  TxAdd  |  RxAdd  |    Length    |     -      |
|  (4 bits)  |  (2 bits)  | (1 bit) | (1 bit) |   (6 bits)   |  (2 bits)  |
+------------+------------+---------+---------+--------------+------------+

The TxAdd and RxAdd field are only used for some payloads, for all others, they should be set to 0.

Length may be in range 6 to 36 (inclusive).

The data in Payload depends on the PDU Type. Refer to the spec or advertising::PduType for details.

Data Channel PDU

A data channel PDU also contains a 16-bit header (but with a different layout) and a variably-sized payload.

If the connection is encrypted and the payload contains at least 1 octet, a Message Integrity Check (MIC) is appended at the end.

LSB                                          MSB
+-----------+----------------------+ - - - - - +
|  Header   |        Payload       |    MIC    |
| (16 bits) |    (0..=27 octets)   | (32 bits) |
+-----------+----------------------+ - - - - - +

Layout (in Bluetooth 4.2):

LSB                                                                MSB
+----------+---------+---------+---------+------------+--------------+
|   LLID   |  NESN   |   SN    |   MD    |     -      |    Length    |
| (2 bits) | (1 bit) | (1 bit) | (1 bit) |  (3 bits)  |   (8 bits)   |
+----------+---------+---------+---------+------------+--------------+

Payload format depends on the value of the 2-bit LLID field:

0b00: Reserved value.
0b01: LL Data PDU Continuation fragment or empty PDU.
0b10: LL Data PDU Start of L2CAP message (or complete message if no fragmentation necessary).
0b11: LL Control PDU.

The NESN field specifies the Next Expected Sequence Number. The SN field specifies the Sequence Number of this PDU.

The MD field specifies that the device sending the packet has more data to send during this connection event. When both slave and master send a packet with the MD bit set to 0, the connection event ends.

The Length field specifies the length of payload and MIC. For Bluetooth versions <4.2, its maximum value is 31, resulting in a 27 octet Payload (the maximum) and a 32-bit MIC. 4.2 added the possibility of larger packets.

Modules

ad_structure	Advertising Data / Extended Inquiry Response (EIR) data.
advertising	Advertising channel operations.
data	Data Channel structures.
filter	Link-Layer Device Filtering.
queue	An SPSC queue for data channel PDUs.

Structs

Cmd	Command returned by the Link-Layer to the user.
CompanyId	Company identifier for use in link layer Control PDUs.
DeviceAddress	A Bluetooth device address.
FeatureSet	A set of optional Link Layer features.
LinkLayer	Implementation of the real-time BLE Link-Layer logic.
RawTransmitter	A `Transmitter` that lowers Link-Layer packets to raw byte arrays that can be directly transmitted over the air, given a suitable radio.
Responder	Data channel packet processor.

Enums

AddressKind	Specifies whether a device address is randomly generated or a LAN MAC address.
NextUpdate	Specifies when the Link Layer's `update` method should be called the next time.
RadioCmd	Specifies if and how the radio should listen for transmissions.

Constants

CRC_POLY	The CRC polynomial to use for CRC24 generation.
MIN_PACKET_BUF	Min. size a buffer for Link-Layer packets must have to comply with the spec.
MIN_PAYLOAD_BUF	Min. size a PDU payload buffer must have (to cover both advertising and data channels).
MIN_PDU_BUF	Min. size a Link-Layer PDU buffer must have (to cover both advertising and data channels).

Traits

HardwareInterface	Defines types that provide platform-dependent functionality.
Transmitter	Trait for Link Layer packet transmission.