[−][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 |
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 |
RadioCmd | Specifies if and how the radio should listen for transmissions. |
Constants
CRC_POLY | The CRC polynomial to use for CRC24 generation. |
MAX_PACKET_SIZE | Max. total Link-Layer packet size in octets. |
MAX_PAYLOAD_SIZE | Max. PDU payload size in Bytes (for both advertising and data channels). |
MAX_PDU_SIZE | Max. PDU size in octets (header + payload). |
Traits
HardwareInterface | Defines types that provide platform-dependent functionality. |
Transmitter | Trait for Link Layer packet transmission. |