Bluetooth Low Energy Domain

The Bluetooth Low Energy Domain service implements a series of procedures and messages allowing to interact with BLE devices and connections.

Bluetooth Low Energy procedures

Discovering access addresses

If the WHAD interface implements the SniffAccessAddressCmd command then it is able to discover access addresses.

sequenceDiagram participant Host participant Interface Host->>+Interface: SniffAccessAddressCmd Interface-->>-Host: CommandResult(result=SUCCESS) Host->>+Interface: StartCmd Interface-->>-Host: CommandResult(result=SUCCESS) loop Interface->>Host: AccessAddressDiscovered end Host->>+Interface: StopCmd Interface-->>-Host: CommandResult(result=SUCCESS)

The host sends a SniffAccessAddressCmd command to switch the WHAD interface into access address sniffing mode and then starts the WHAD interface with a StartCmd. Discovered access addresses are reported to the host by the WHAD interface through a series of AccessAddressDiscovered messages.

Scanning devices

The WHAD interface can be set into scanning mode in order to discover any available devices. This mode can be passive or active: in active mode the WHAD interface will send a BLE scan request (SCAN_REQ) PDU for each advertisement it receives in order to get more information from devices.

sequenceDiagram participant Host participant Interface Host->>+Interface: ScanModeCmd Interface-->>-Host: CommandResult(result=SUCCESS) Host->>+Interface: StartCmd Interface-->>-Host: CommandResult(result=SUCCESS) loop Interface->>Host: PduReceived end Host->>+Interface: StopCmd Interface-->>-Host: CommandResult(result=SUCCESS)

First, the host sends a ScanModeCmd message to the WHAD interface. If the active_scan field is set to true, the WHAD interface will send a scan request for each advertisement it receives. If set to false, only the received advertisement will be reported to the host.

Initiating a connection to a target device

sequenceDiagram participant Host participant Interface Host->>+Interface: CentralModeCmd Interface-->>-Host: CommandResult(result=SUCCESS) Host->>+Interface: ConnectToCmd Interface-->>-Host: CommandResult(result=SUCCESS) Host->>+Interface: StartCmd Interface-->>-Host: CommandResult(result=SUCCESS) Interface->>Host: Connected Note over Host,Interface: Connection is established

First, the host puts the WHAD interface in central mode by sending a CentralModeCmd message to the WHAD interface. If this command succeeds, then the host sends a ConnectToCmd message providing the WHAD interface with all the information required to initiate a connection to the target device. The bd_address and addr_type can be provided to initiate a normal connection on a device.

If the connection cannot be initiated, no Connected message is sent by the WHAD interface. The host needs to enforce a timeout to determine if the connection has failed.

Creating a BLE peripheral

sequenceDiagram participant Host participant Interface Host->>+Interface: PeripheralModeCmd(adv_data, scanrsp_data) Interface-->>-Host: CommandResult(result=SUCCESS) Host->>+Interface: StartCmd Interface-->>-Host: CommandResult(result=SUCCESS) Note over Host,Interface: Peripheral is advertising Interface->>Host: Connected Note over Host,Interface: Central device is connected Interface->>Host: Disconnected Note over Host,Interface: Central device has disconnected Host->>+Interface: StopCmd Interface-->>-Host: CommandResult(result=SUCCESS) Note over Host,Interface: Peripheral is stopped, no advertising

First, the host sends a PeripheralModeCmd to the WHAD interface in order to set it in BLE peripheral mode. This message provides the WHAD interface with the advertising data and optional scan response to send while advertising. At this point, the BLE peripheral is configured but not yet advertising.

The host must send a StartCmd message to make the WHAD interface advertising. Once started, the WHAD interface will wait for BLE connections initiated by other devices. If a connection is established, the host is notified with a Connected notification sent by the WHAD interface.

If a device disconnects, a Disconnected notification message is sent to the host.

The host can stop this BLE peripheral at any time by sending a StopCmd command.

Sending and receiving PDUs

Once a connection established (in central or peripheral mode), the host can provide the WHAD interface with a PDU to send. If the WHAD interface does have the NoRawData capability (see. Capability), the host must send SendPduCmd messages. If the WHAD interface can send raw PDU, it must send SendRawPduCmd messages.

A received PDU is notified by the WHAD interface to the host through a PduReceived message or RawPduReceived message depending on its capabilities.

sequenceDiagram participant Host participant Interface Host->>+Interface: SendPduCmd Interface-->>-Host: CommandResult(result=SUCCESS) Note over Host,Interface: PDU send by host Interface->>Host: PduReceived Note over Host,Interface: Interface sends a received PDU

Enumerations

BleCommand

This enumeration contains the various BLE commands ID that are required to create the domain supported commands bitmap.

BleAdvType

This enumeration specifies the different advertisement types.

Type	Description
ADV_UNKNOWN	Unknown advertisement type (default)
ADV_IND	Indirected advertisement
ADV_DIRECT_IND	Directed advertisement
ADV_NONCONN_IND	Non-connectable indirected advertisement
ADV_SCAN_IND	Indirected scan advertisement
ADV_SCAN_RSP	Scan response

BleDirection

This enumeration specifies the direction of a PDU.

Direction	Description
UNKNOWN	Direction is unknown (default)
MASTER_TO_SLAVE	PDU is sent by the connection initiator
SLAVE_TO_MASTER	PDU is sent by the advertising device
INJECTION_TO_SLAVE	PDU has to be injected and target the advertising device
INJECTION_TO_MASTER	PDU has to be injected and target the initiator

BleAddrType

This enumeration specifies the Bluetooth Device address type.

Type	Description
PUBLIC	Device BD address is public
RANDOM	Device BD address is random

The address type information is part of the protocol, usually specified by the TxAdd``and ``RxAdd bits in the BLE header. It is critical to specify the correct address type for a device or a connection will fail.

Messages

AccessAddressDiscovered

This notification message is sent each time an access address has been discovered.

Field	Type	Description
access_address	uint32	Access address
rssi	int32, optional	Received signal strength indicator
timestamp	uint64, optional	When the access address has been discovered

AdvPduReceived

This notification message is sent whenever an advertising PDU has been received.

Field	Type	Description
adv_type	BleAdvType	BLE advertisement type
rssi	int32	Received signal strength indicator
bd_address	bytes	Advertiser BD address
adv_data	bytes	Advertising data
addr_type	BleAddrType	Advertiser BD address type

AdvModeCmd

This message sets the WHAD device in advertising mode.

Field	Type	Description
scan_data	bytes	Advertising data (31 bytes max)
scanrsp_data	bytes	Scan response data (31 bytes max)

scan_data sets the WHAD interface advertising data while scanrsp_data provides some extra advertising data that will be used to answer SCAN_REQ PDUs.

scan_data is mandatory while scanrsp_data is optional.

CentralModeCmd

This message sets the WHAD interface into Central mode.

Note

This message has no field.

Connected

This notification message is sent when a BLE connection is successfully established.

Field	Type	Description
initiator	bytes	Initiator BD address
advertiser	bytes	Advertiser BD address
access_address	uint32	Connection access address
conn_handle	uint32	Connection handle
adv_addr_type	BleAddrType	Advertiser BD address type
init_addr_type	BleAddrType	Initiator BD address type

ConnectToCmd

This message specifies a target device to connect to, or an existing connection to follow.

Field	Type	Description
bd_address	bytes	Target device BD address (6 bytes)
addr_type	BleAddrType	Target device address type
access_address	uint32, optional	Target connection access address
channel_map	bytes, optional	Target connection channel map
hop_increment	uint32, optional	Target connection hop increment (CSA #1)
hop_interval	uint32, optional	Target connection hop interval (CSA #1)
crc_init	uint32, optional	Target connection CRCInit value

Note

Only BLE v4 connections synchronization are supported for now, since CSA #2 is not implemented yet (and requires extra parameters)

DeleteSequenceCmd

This message deletes a previously registered prepared sequence.

Field	Type	Description
id	uint32	Prepared sequence ID

Desynchronized

This notification message is sent when the WHAD interface is desynchronized from an active connection.

Field	Type	Description
access_address	uint32	Connection access address

DisconnectCmd

This message terminates an existing connection.

Field	Type	Description
conn_handle	uint32	Connection handle

Disconnected

This notification message is sent when a connection has terminated.

Field	Type	Description
reason	uint32	Termination reason
conn_handle	uint32	Connection handle

HijackBothCmd

This message sets the WHAD interface into hijacking mode, targeting both the initiating device and the advertising device.

Field	Type	Description
access_address	uint32	Target connection access address

Hijacked

This notification message is sent by the WHAD interface to notify the result of a connection hijacking.

Field	Type	Description
success	bool	`true` if hijacking has succeeded
access_address	uint32	Target connection access address

HijackMasterCmd

This message sets the WHAD interface into hijacking mode, targeting the device that initiated the target connection.

Field	Type	Description
access_address	uint32	Target connection access address

HijackSlaveCmd

This message sets the WHAD interface into hijacking mode, targeting the advertising device.

Field	Type	Description
access_address	uint32	Target connection access address

Injected

This notification message is sent by the WHAD interface to notify the result of a packet injection.

Field	Type	Description
success	bool	`true` if hijacking has succeeded
access_address	uint32	Target connection access address
injection_attempts	uint32	Number of injection attempts

JamAdvCmd

This message sets the WHAD interface in BLE advertisements jamming mode. In this mode, the interface jams all BLE advertising channels.

Note

This message has no field.

JamAdvOnChannelCmd

This message sets the WHAD interface in single-channel BLE advertisements jamming mode.

Field	Type	Description
channel	uint32	Target channel to jam

Note

Looks like a duplicate with JamAdvCmd, may be interesting to use this command with an optional channel value instead.

JamConnCmd

This message sets the WHAD interface into connection jamming.

Field	Type	Description
access_address	uint32	Target access address

access address specifies the Access Address of the connection to jam.

PduReceived

This notification message is sent by the WHAD interface to report a raw PDU received to the host.

Field	Type	Description
direction	BleDirection	Direction
pdu	bytes	PDU
conn_handle	uint32	Connection handle
processed	bool	`true` if already processed by firmware
decrypted	bool	`true` if already decrypted by firmware

PeripheralModeCmd

This message sets the WHAD interface in peripheral mode. In this mode, the interface will send advertisements and accept incoming connections.

Field	Type	Description
scan_data	bytes	Advertising data (31 bytes max)
scanrsp_data	bytes	Scan response data (31 bytes max)

PrepareSequenceCmd

This message tells the WHAD interface to prepare a sequence of packets for transmission. This transmission will be triggered by a specific condition.

Field	Type	Description
trigger	Trigger	Reception trigger
id	uint32	Sequence unique ID
direction	BleDirection	Direction
sequence	PendingPacket	Sequence of prepared packets

trigger must be one of the following available triggers:

ReceptionTrigger
ConnectionEventTrigger
ManualTrigger

RawPduReceived

This notification message is sent by the WHAD interface to report a raw PDU received to the host.

Field	Type	Description
direction	BleDirection	Direction
channel	uint32	BLE channel on which the PDU was received
rssi	int32, optional	Received signal strength indicator
timestamp	uint64. optional	When the PDU has been received
relative_timestmap	uint64, optional	Relative timestamp
crc_validity	bool, optional	`true` if CRC is valid, ``false``otherwise
access_address	uint32	Connection access address
pdu	bytes	PDU
crc	uint32	PDU CRC
conn_handle	uint32	Connection handle
processed	bool	`true` if already processed by firmware
decrypted	bool	`true` if already decrypted by firmware

ReceptionTrigger

The reception trigger is basically a pattern-based trigger with offset and mask:

Field	Type	Description
pattern	bytes	Pattern to match
mask	bytes	Bitmask for pattern
offset	uint32	Pattern offset

ConnectionEventTrigger

Field	Type	Description
connection_event	uint32	Connection event to match

ManualTrigger

This trigger specifies that the sequence will be triggered manually with a specific message (TriggerSequenceCmd).

Note

This message have no specific field.

PendingPacket

This message defines a pending packet.

Field	Type	Description
packet	bytes	Packet bytes (PDU)

ReactiveJamCmd

This message sets the WHAD interface into reactive jamming mode.

Field	Type	Description
channel	uint32	Target channel
pattern	bytes	Pattern to trigger jamming
position	uint32	Pattern position in payload

ScanModeCmd

This message sets the WHAD interface into scanning mode.

Field	Type	Description
active_scan	bool	Enable active mode

If active_scan is set to True, the WHAD device sends a SCAN_REQ for each advertisement received. If set to False, only advertisements (ADV_IND, …) will be reported to host.

SendPduCmd

This message specifies a BLE PDU to send. There is no control over its header nor CRC.

Field	Type	Description
direction	BleDirection	PDU direction
conn_handle	uint32	Connection handle
pdu	bytes	Raw pdu to send
encrypt	bool	Let hardware encrypt PDU if `true`

SendRawPduCmd

This message specifies a raw BLE PDU to send. Raw PDU gives control over the BLE PDU header and its CRC.

Field	Type	Description
direction	BleDirection	PDU direction
conn_handle	uint32	Connection handle
access_address	uint32	Connection access address
pdu	bytes	Raw pdu to send
crc	uint32	PDU CRC
encrypt	bool	Let hardware encrypt PDU if `true`

Warning

Only devices without the NoRawData capability can send this message.

SetAdvDataCmd

This message sets the advertising data and scan response data.

Field	Type	Description
scan_data	bytes	Advertising data (31 bytes max)
scanrsp_data	bytes	Scan response data (31 bytes max)

scan_data` is mandatory while scanrsp_data is optional.

SetBdAddressCmd

This message sets the WHAD interface Bluetooth Device (BD) address.

Field	Type	Description
bd_address	bytes	Bluetooth Device address (6 bytes)
addr_type	BleAddrType	Address type

SetEncryptionCmd

This message sets the WHAD interface cryptographic material for a specific connection.

Field	Type	Description
conn_handle	uint32	Connection handle
enabled	bool	Enable encryption if set to `true`
ll_key	bytes	Link-layer encryption key
ll_iv	bytes	Link-layer initialization vector
key	bytes	Encryption key
rand	bytes	Random value
ediv	bytes	Diversifier value

SniffAccessAddressCmd

This message sets the WHAD interface into Access Address sniffing mode.

Field	Type	Description
monitored_channels	bytes	Channel map

The monitored_channels field specifies a BLE channel map which each bit represent a channel (from 0 to 39). This channel map is stored in a 5-byte buffer. Usually, advertising channels (37, 38 and 39) are excluded as they are not used by BLE connections for data exchange.

SniffActiveConnCmd

This message sets the WHAD interface into active connection sniffing mode.

Field	Type	Description
access_address	uint32	Target access address
crc_init	uint32	CRC initial seed
channel_map	bytes	Connection channel map
hop_interval	uint32	Hop interval (CSA #1)
hop_increment	uint32	Hop increment (CSA #1)
monitored_channels	bytes	Channel map used for sniffing

SniffAdvCmd

This message sets the WHAD interface into BLE advertising sniffing mode. The target channel can be specified, as well as a target BD address.

Field	Type	Description
use_extended_adv	bool	Enable Extended advertisements sniffing
channel	uint32	Target channel to sniff
bd_address	bytes	Target BD address

channel specifies the channel to sniff on, usually one of the default BLE advertising channels (37, 38 or 39).

bd_address specifies a specific BD address used to filter BLE advertisements and only keep those matching this address, except when set to FF:FF:FF:FF:FF:FF (a buffer of 6 bytes with value 0xFF).

The use_extended_adv option can be used with BLE5 compatible WHAD interfaces to follow extended advertisements that occur on data channels.

SniffConnReqCmd

This message sets the WHAD interface into BLE connection request sniffing mode.

Field	Type	Description
show_empty_packets	bool	Report BLE empty PDUs (size = 0)
show_advertisements	bool	Report the target device advertisement
channel	uint32	Target channel to sniff
bd_address	bytes	Target BD address

Setting show_empty_packets to true makes the WHAD interface report all PDUs, even the empty ones. Setting show_advertisements will report any advertisement seen on the specified channel before a connection is initiated.

channel specifies the advertising channel the WHAD interface will listen on to capture a CONN_REQ PDU used to initiate a BLE connection.

If bd_address is set, it will be used a filter to target a connection to the corresponding BD address. If set to FF:FF:FF:FF:FF:FF (6 0xFF bytes) then the WHAD interface will not filter connection initiation requests.

StartCmd

This message starts the WHAD interface in the currently selected mode.

Note

This message has no specific field.

StopCmd

This message stops the WHAD interface that then goes idle.

Note

This message has no specific field.

Synchronized

This notification message is sent when the WHAD interface is successfully synchronized with an active connection.

Field	Type	Description
access_address	uint32	Connection access address
crc_init	uint32	Connection CRCInit value
hop_interval	uint32	Hop interval (CSA #1)
hop_increment	uint32	Hop increment (CSA #1)
channel_map	bytes	Connection channel map

Triggered

This notification message is sent by the WHAD interface when a prepared sequence has been triggered.

Field	Type	Description
id	uint32	Prepared sequence ID

TriggerSequenceCmd

This message manually triggers a prepared sequence identified by its id.

Field	Type	Description
id	uint32	Prepared sequence ID