Bluetooth Manager (BLEM)

Owned by Shibshankar Talukder
Mar 27, 2024
8 min read

General

Bluetooth Low Energy (BLE) advertisement packet

BLE Advertising Physical Channel Protocol Data Unit (APC PDU)

The advertising physical channel PDU has a 16-bit header and a variable size payload, with the format shown in the following diagram:

 

Advertising_Physical_Channel_PDU.drawio.png

 

APC PDU Payload structure depends on the PDU Type value. 3 out of 9 possible advertising modes (PDU Type values) are used, selected using OSP BLE API methods:

  • ADV_NONCONN_IND: Non-connectable, non-scannable undirected advertising – BLE Broadcaster mode.
    Used when connectable mode is disabled using osp_ble_set_connectable(false) and Scan Response is disabled using osp_ble_set_advertising_params(sr_enabled=false).

  • ADV_SCAN_IND: Non-connectable, scannable undirected advertising – BLE Broadcaster mode.
    Used when connectable mode is disabled using osp_ble_set_connectable(false) and Scan Response is enabled using osp_ble_set_advertising_params(sr_enabled=true).

  • ADV_IND: Connectable and scannable undirected advertising – BLE Peripheral mode.
    Used when connectable mode is enabled using osp_ble_set_connectable(true), irrespective of whether Scan Response is enabled or not.

In all 3 modes above, the structure of the APC PDU Payload is the same:

 

BLE_APC_PDU_Payload.drawio.png

 

AdvData contains a sequence of Advertising Data (AD) structures. Each AD structure has a Length field of one octet, which contains the Length value, and a Data field of Length octets. The first octet of the Data field contains the AD Type field. The content of the remaining Length-1 octets in the Data field depends on the value of the AD Type field and is called the AD Data. All possible AD type data formats and meanings are defined in Bluetooth Core Specification Supplement, Part A, Section 1; all possible AD type identifier values are defined in Bluetooth Assigned Numbers document.

BLE Advertising Data packet structure

BLEM uses the following AD structures:

 

 

The 28 octets of AdvData is set directly using osp_ble_set_advertising_data(), except for the AD structure of type Flags, which is usually added automatically by the on-chip Bluetooth stack. If this is not the case, OSP BLE layer should ensure that the Flags AD structure is the first structure in AdvData.

In all cases, length, structure and content of SerialNumber, MsgType and Msg fields in the Manufacturer Specific Data is identical. Version information can be used to distinguish between obsolete advertising packet v0004 (advData[4+4] == 0x00 && advData[4+5] == 0x04) and new advertising packet v05 (advData[3+4+4] == 0x05).

SerialNumber

Field SerialNumber represents ASCII-encoded node serial number, which is used as the main identifier for the source of the received BLE advertising packet.

As an example, a node with serial number 4C12345678 would have the value of this field set to 344331323334353637380000.

MsgType

Field MsgType specifies the type of the payload currently present in the Msg field:

  • 0x00: Onboarding
    Used for broadcasting pod connectivity.

  • 0x01: Diagnostic
    Not used.

  • 0x02: Locate
    Used for pod locating and naming.

Msg

The 6-byte field Msg is currently only used when the MsgType value is set to 0x00 – Onboarding.

The first octet represents the connectivity status as reported by the Connection Manager (CM):

Bit

Bitmask value

Description

Bit

Bitmask value

Description

0

0x01

Ethernet physical link

1

0x02

Wi-Fi physical link

2

0x04

Backhaul over Ethernet

3

0x08

Backhaul over Wi-Fi

4

0x10

Connected to Router

5

0x20

Connected to Internet

6

0x40

Connected to Controller

If the specific bit is present (set to 1), then the described property is present (Up, Connected, Yes), otherwise absent (Down, Disconnected, No).

Advertising as non-connectable

Other 5 octets (index 1-5) are not used when advertising in non-connectable mode.

Advertising as connectable

When advertising as connectable, the last 4 octets (index 2-5) of the Msg are used for the random token used in the process of generating passkey for BLE pairing.

Octet

Description

Octet

Description

2

Pairing token byte 0

3

Pairing token byte 1

4

Pairing token byte 2

5

Pairing token byte 3 with 3 LSB bits masked.

The last 3 bits of this octet indicate the status of the currently advertised pairing token:

  • Msg[5] = 0bxxxxx101: Valid unstable token

  • Msg[5] = 0bxxxxx110: Valid stable token

  • Msg[5] = 0bxxxxxYYY: Any other YYY value shall be considered as unstable token.

Therefore, the random pairing token is {Msg[2], Msg[3], Msg[4], Msg[5] & 0xF8} and shall be used only when Msg[5] & 0x07 equals to 0x06.

Northbound API

AW_Bluetooth_Config

Name

Type

Description

Name

Type

Description

mode

enum

Bluetooth advertising state.

  • "off"
    BLE advertising is disabled, Bluetooth module might be powered off.

  • "on"
    BLE advertising is active in either Broadcasting or Connectable (Peripheral) mode, depending on connectable field.

connectable

bool [optional]

BLE advertising mode.

  • Not present or false
    BLEM advertises non-connectable BLE beacons (BLE Broadcaster mode).

  • true
    BLEM advertises connectable BLE beacons and is able to accept connection from BLE Central device (BLE Peripheral mode).

interval_millis

integer

BLE advertising interval in milliseconds, in the range of 20 ms to 10240 ms (usually 250 ms).

txpower

integer

Not used.

command

enum

Payload data type, representing the MsgType byte value in the BLE advertisement packet.

  • "on_boarding": 0x00

  • "diagnostic": 0x01

  • "locate": 0x02

payload

string

18-character string in the form of aa:bb:cc:dd:ee:ff, where each two characters represent a single octet in hexadecimal notation (00-ff) of the Msg filed value in the BLE advertising packet.

Handling of this value depends on the advertising mode:

  • If advertising as connectable (connectable == true), only the first 2 octets of this value (aa:bb) are copied to the Msg field.

  • If advertising as non-connectable (connectable != true), all 6 octets of this value are copied to the Msg field.

AW_Bluetooth_State

The schema of this read-only table is identical to AW_Bluetooth_Config and represents values actually applied to the Bluetooth chip using southbound API. The values in this table shall always match values in the AW_Bluetooth_Config (with a short delay) – if this is not the case, the logs shall be inspected for errors indicating why the desired property failed to be applied using southbound API.

Southbound API

BLEM uses OSP BLE API for platform-independent configuration of the Bluetooth peripheral. All API functions shall return true on success or false if desired operations could not be performed for any reason.

During BLEM startup, osp_ble_init is invoked, which shall take care of Bluetooth chip configuration. Optionally, additional configuration methods can be invoked to get the customized 16-bit service UUID (to overwrite the default 0xFE71) or to set the Bluetooth Device name (optionally used when advertising as connectable).

/** * Initialize the Bluetooth Low Energy subsystem * * Open and configure communication interface with the BT chip, download required * firmware, configure static parameters (e.g. Bluetooth Device Address), prepare * the Bluetooth module for advertising. * * @param[in] loop Optional event loop used to handle Bluetooth stack asynchronous events * and invoke the callbacks. If not provided, it is impossible to accept * BLE connections (therefore callbacks below will never be invoked), * but non-connectable advertising is still possible. * @param on_device_connected_cb Optional callback called when new BLE Central device initiates connection * to this device (before pairing process is initiated). * @param on_device_disconnected_cb Optional callback called when previously connected BLE Central device * disconnects for any reason. * @param on_pairing_status_cb Optional callback called when pairing with newly connected device succeeds * or fails (in that case the device will be disconnected soon after). * @param on_gatt_json_cb Optional callback called when connected device writes new data to the * local-config JSON GATT characteristic. * * @return true on success */ bool osp_ble_init(struct ev_loop *loop, osp_ble_on_device_connected_cb_t on_device_connected_cb, osp_ble_on_device_disconnected_cb_t on_device_disconnected_cb, osp_ble_on_pairing_status_cb_t on_pairing_status_cb, osp_ble_on_gatt_json_cb_t on_gatt_json_cb); /** * Get the value advertised as Complete List of 16-bit Service UUIDs * * @param[in,out] uuid Pointer to the value advertised as Complete List of 16-bit Service UUIDs. * The default value defined by BLEM_GATT_SERVICE_UUID (passed to this function) * can be changed by writing to this address. * * @return true if the default value passed to this function was modified */ bool osp_ble_get_service_uuid(uint16_t *uuid); /** * Set Device Name characteristic of Generic Access GATT Service, if supported * * @param[in] device_name Device Name to set as null-delimited UTF-8 string (null-delimiter will not be copied). * * @return true on success */ bool osp_ble_set_device_name(const char *device_name);

Afterward, methods for setting the advertising mode and data can be called multiple times during normal BLEM operation.

/** * Set advertising packet payload * * 3 bytes of Flags data type is expected to be prepended by the Bluetooth Stack code, usually: * uint8_t len_flags = 2 * uint8_t ad_type_flags = 0x01 * uint8_t flags = (1 << 1)|(1 << 2) = LE General Discoverable Mode | BR/EDR Not Supported * That is why this payload is always maximum 28 instead of 31 bytes long. * * @param[in] payload Advertising packet payload, max. 28 bytes. * @param len Length of the payload in range [0, 28]. * * @return true on success */ bool osp_ble_set_advertising_data(const uint8_t payload[28], uint8_t len); /** * Set scan response packet payload * * @param[in] payload Scan Response packet payload, max. 31 bytes. * @param len Length of the payload in range [0, 31]. * * @return true on success */ bool osp_ble_set_scan_response_data(const uint8_t payload[31], uint8_t len); /** * Set advertising parameters * * @param enabled Whether to enable advertising. * @param sr_enabled Whether to enable scan responses. * @param interval_ms Advertising interval in ms (20 ms to 10.485 s, resolution 0.625 ms). * * @return true on success */ bool osp_ble_set_advertising_params(bool enabled, bool sr_enabled, uint16_t interval_ms); /** * Set connectable mode * * @param enabled Enable advertising as connectable and reception of connection requests. * * @return true on success */ bool osp_ble_set_connectable(bool enabled);

When advertising as connectable, methods for calculating and setting the pairing passkey are used, together with a method for setting the JSON configuration value after BLE Central device connects and completed the BLE Passkey Entry pairing process.

/** * Calculate 6-digit passkey for Passkey Entry BLE pairing method * * This passkey is later set applied to the BLE stack using @ref osp_ble_set_pairing_passkey. * * @param[in] random_token Random token from advertisement data (4 bytes). * This token always has stable bits cleared (neutral). * @param[out] passkey Pointer to a variable to which the generated passkey shall be stored. * Simple passkeys with 3 or more same or consecutive digits will be * rejected and this function will be called again with the new * `random_token`, until it produces valid passkey or returns false. * Some examples of rejected passkeys: * - 0 (000000), 111111, ..., 999999 * - 012345, 123456, ..., 456789 * - 987654, 876543, ..., 543210 * * @return true on success (passkey was calculated and written to `passkey`) */ bool osp_ble_calculate_pairing_passkey(const uint8_t token[4], uint32_t *passkey); /** * Set passkey for Passkey Entry Pairing * * @param passkey 6-digit (1-999999) passkey - value 0 rejects pairing. * * @return true on success */ bool osp_ble_set_pairing_passkey(uint32_t passkey); /** * Set GATT service - Local-config JSON GATT characteristic value * * @param value Value to set (shall be valid JSON), not required to be NULL terminated. * @param len Length of the value (including null termination, if present). * * @return true on success */ bool osp_ble_set_gatt_json(const char *value, uint16_t len);

If BLEM closes gracefully, osp_ble_close will be invoked to disable any BLE operations and cleanup resources.

Requirements

No additional requirements for this feature