Bluetooth

Bluetooth Low Energy stack interface (pbl/bluetooth). More...

Modules
	Advertising
	LE advertising.
	Battery Service
	GATT Battery Service.
	Bonding synchronization
	Keep the stack's bondings and CCCD states in sync with persistent storage.
	Comm session scheduling
	Pick the task that sends a comm session's pending data.
	Connection event statistics
	Controller statistics of connection events in the peripheral role.
	Device Information Service
	Values served by the GATT Device Information Service.
	LE connections
	LE connection events and disconnection.
	Peer device names
	Read the GAP Device Name of connected peers.
	Scanning
	LE scanning.
	GATT
	GATT client operations, GATT events and the Service Changed characteristic.
	GATT service discovery
	Discover the GATT database of a connected peer.
	GATT service description
	Compact description of a discovered remote GATT service.
	HCI types
	HCI status codes.
	Heart Rate Service
	GATT Heart Rate Service, sharing the watch's heart rate with connected devices.
	Local identity
	Local device name and addresses.
	Identity address source
	Where the watch's identity address comes from.
	ATT MTU
	ATT MTU limits.
	Pairability
	Whether new LE pairings are accepted.
	Pairing confirmation
	Ask the user to confirm a pairing request.
	Pebble identifiers
	Pebble-specific Bluetooth identifiers: service and characteristic UUIDs.
	Pebble Pairing Service
	GATT service through which the phone app checks the connection and triggers pairing.
	Reversed PPoGATT
	Reversed PPoGATT service: the watch hosts the service and the phone is the GATT client.
	Responsiveness
	Connection response time requests and connection parameter updates.
	Security Manager types
	Keys and pairing information.
	Types
	Error codes, addresses, devices and advertising data shared by the Bluetooth API.

Data Structures
struct	pbl_bt_config
	Stack configuration passed to pbl_bt_start(). More...

Functions
void	pbl_bt_init (void)
	One-time initialization of the Bluetooth stack.
bool	pbl_bt_start (struct pbl_bt_config *config)
	Start the Bluetooth stack.
void	pbl_bt_stop (void)
	Stop the Bluetooth stack.
void	pbl_bt_power_down_controller_on_boot (void)
	Power down the controller at boot if Bluetooth is not going to be started.
void	pbl_bt_handle_host_resynced (void)
	Called each time the host (re-)synchronizes with the controller.

Detailed Description

Bluetooth Low Energy stack interface (pbl/bluetooth).

The firmware's Bluetooth code (fw/comm/ble and fw/services/bluetooth) talks to the stack only through the pbl_bt_* API declared in these headers. It is implemented in subsys/bluetooth on top of the NimBLE host, which runs in its own task.

The API has two directions:

• Calls into the stack, such as pbl_bt_start(), pbl_bt_advert_advertising_enable() or pbl_bt_gatt_read().
• Callbacks, declared extern and named pbl_bt_handle_* or pbl_bt_cb_*, that the firmware implements and the stack invokes to report events. Unless stated otherwise they run on the NimBLE host task without bt_lock() held.

The NimBLE host reaches its controller through the HCI transport selected with the BT_HCI_* Kconfig choice: the in-image NimBLE link layer (BT_HCI_NRF52), the SiFli LCPU over IPC (BT_HCI_SF32LB52), H4 over UART (BT_HCI_UART) or a fake controller (BT_HCI_FAKE). The fake controller, used on QEMU, accepts every HCI command and never raises an event: the host synchronizes and the GATT server runs, but no link is ever established.

The watch is a peripheral only. Typical bring-up:

pbl_bt_init(); // once, at boot
 
struct pbl_bt_config *config = kernel_zalloc_check(sizeof(*config));
dis_get_info(&config->dis_info);
// Bondings registered before starting are restored by the host.
bt_persistent_storage_register_existing_ble_bondings();
bool running = pbl_bt_start(config);
kernel_free(config);
 
// ...
 
pbl_bt_stop();

---

Data Structure Documentation

pbl_bt_config

struct pbl_bt_config

Stack configuration passed to pbl_bt_start().

Data Fields
struct pbl_bt_dis_info	dis_info	Values served by the Device Information Service.
struct pbl_bt_addr	identity_addr	Identity address. Not used by the NimBLE backend, see pbl_bt_id_addr_get().
bool	is_hrm_supported_and_enabled	Whether the heart rate service may be exposed. Not used by the NimBLE backend.
struct pbl_bt_sm_key	root_keys[PBL_BT_SM_ROOT_KEY_TYPE_NUM]	Root keys, indexed by enum pbl_bt_sm_root_key_type. Not used by the NimBLE backend, which reads and generates the root keys through the persistent storage service.

Function Documentation

pbl_bt_handle_host_resynced()

void pbl_bt_handle_host_resynced ( void  )

extern

Called each time the host (re-)synchronizes with the controller.

Implemented by the firmware. The controller state is lost on a host reset, so this is where advertising data and parameters must be pushed again. Invoked on the NimBLE host task.

pbl_bt_init()

void pbl_bt_init

(

void

)

One-time initialization of the Bluetooth stack.

Creates the NimBLE host task (and the link layer task when the controller runs in the same image) and installs the bonding store. Call once at boot, before any other function of this API.

pbl_bt_power_down_controller_on_boot()

void pbl_bt_power_down_controller_on_boot

(

void

)

Power down the controller at boot if Bluetooth is not going to be started.

Does nothing in the NimBLE backend.

pbl_bt_start()

bool pbl_bt_start

(

struct pbl_bt_config *

config

)

Start the Bluetooth stack.

Registers the GATT services, starts the host and waits for it to synchronize with the controller, then sets up the identity address. Does nothing if the stack is already running.

Parameters

config

Stack configuration. Only read during the call.

Returns

true if the stack is running, false if it failed to start.

pbl_bt_stop()

void pbl_bt_stop

(

void

)

Stop the Bluetooth stack.

Blocks until the host has stopped, then resets the GATT server and drops the in-memory bonding store. No bonding removal callbacks are issued.