Persistent BLE bondings, CCCDs and local Bluetooth settings. More...

Typedefs
typedef void(*	BtPersistBondingChangeHandler) (pbl_bt_bonding_id_t affected_bonding, BtPersistBondingOp operation)
	Handler of bonding database changes.

typedef void(*	BtPersistBondingDBEachBLE) (struct pbl_bt_device_internal device, struct pbl_bt_sm_key irk, const char name, pbl_bt_bonding_id_t id, void *context)
	Callback for bt_persistent_storage_for_each_ble_pairing().

Enumerations
enum	BtPersistBondingOp { BtPersistBondingOpInvalid = -1 , BtPersistBondingOpDidAdd , BtPersistBondingOpDidChange , BtPersistBondingOpWillDelete }
	Change made to a bonding. More...

enum	BtPersistBondingType { BtPersistBondingTypeBTClassic , BtPersistBondingTypeBLE , BtPersistBondingNumTypes }
	Transport of a bonding. More...

Functions
bool	bt_persistent_storage_has_pinned_ble_pairings (void)
	Check whether any BLE bonding requires address pinning.

bool	bt_persistent_storage_set_ble_pinned_address (const struct pbl_bt_addr *address)
	Store the pinned local BLE address.

bool	bt_persistent_storage_get_ble_pinned_address (struct pbl_bt_addr *address_out)
	Get the pinned local BLE address.

pbl_bt_bonding_id_t	bt_persistent_storage_store_ble_pairing (const struct pbl_bt_sm_pairing_info pairing_info, bool is_gateway, const char device_name, bool requires_address_pinning, uint8_t flags)
	Add or update a BLE bonding.

bool	bt_persistent_storage_update_ble_device_name (pbl_bt_bonding_id_t bonding, const char *device_name)
	Update the name of a BLE bonding.

void	bt_persistent_storage_delete_ble_pairing_by_id (pbl_bt_bonding_id_t)
	Delete the BLE bonding with the given ID, with its CCCDs.

void	bt_persistent_storage_delete_ble_pairing_by_addr (const struct pbl_bt_device_internal *device)
	Delete the BLE bonding with an identity address, with its CCCDs.

bool	bt_persistent_storage_get_ble_pairing_by_id (pbl_bt_bonding_id_t bonding, struct pbl_bt_sm_key IRK_out, struct pbl_bt_device_internal device_out, char *name_out)
	Look up a BLE bonding by ID.

bool	bt_persistent_storage_get_ble_pairing_by_addr (const struct pbl_bt_device_internal device, struct pbl_bt_sm_key IRK_out, char name_out[PBL_BT_DEVICE_NAME_BUFFER_SIZE])
	Look up a BLE bonding by identity address.

pbl_bt_bonding_id_t	bt_persistent_storage_get_ble_ancs_bonding (void)
	Get the first BLE bonding that supports ANCS.

bool	bt_persistent_storage_is_ble_ancs_bonding (pbl_bt_bonding_id_t bonding)
	Check whether a bonding is a BLE bonding that supports ANCS.

bool	bt_persistent_storage_has_ble_ancs_bonding (void)
	Check whether any BLE bonding supports ANCS.

bool	bt_persistent_storage_has_active_ble_gateway_bonding (void)
	Check whether the active gateway is a BLE bonding.

void	bt_persistent_storage_for_each_ble_pairing (BtPersistBondingDBEachBLE cb, void *context)
	Call a function for each BLE bonding.

void	bt_persistent_storage_register_existing_ble_bondings (void)
	Register all stored BLE bondings and CCCDs with the Bluetooth driver.

pbl_bt_cccd_id_t	bt_persistent_storage_store_cccd (const struct pbl_bt_cccd *cccd)
	Store a CCCD, replacing the one for the same peer and characteristic.

bool	bt_persistent_storage_delete_cccd (const struct pbl_bt_device_internal *peer, uint16_t chr_val_handle)
	Delete a stored CCCD.

void	bt_persistent_storage_set_active_gateway (pbl_bt_bonding_id_t bonding)
	Set the active gateway, the bonding that implements Pebble Protocol.

bool	bt_persistent_storage_get_active_gateway (pbl_bt_bonding_id_t bonding_out, BtPersistBondingType type_out)
	Get the active gateway.

bool	bt_persistent_storage_is_unfaithful (void)
	Check whether the watch is unfaithful.

void	bt_persistent_storage_set_unfaithful (bool is_unfaithful)
	Set whether the watch is unfaithful.

bool	bt_persistent_storage_get_root_key (enum pbl_bt_sm_root_key_type key_type, struct pbl_bt_sm_key *key_out)
	Get a BLE root key.

void	bt_persistent_storage_set_root_keys (struct pbl_bt_sm_key *keys_in)
	Store the BLE root keys.

bool	bt_persistent_storage_get_local_device_name (char *local_device_name_out, size_t max_size)
	Get the stored local device name.

void	bt_persistent_storage_set_local_device_name (char *local_device_name, size_t max_size)
	Store the local device name.

bool	bt_persistent_storage_get_airplane_mode_enabled (void)
	Get the stored airplane mode setting.

void	bt_persistent_storage_set_airplane_mode_enabled (bool enable)
	Store the airplane mode setting.

void	bt_persistent_storage_get_cached_system_capabilities (PebbleProtocolCapabilities *capabilities_out)
	Get the cached capabilities of the last system session.

void	bt_persistent_storage_set_cached_system_capabilities (const PebbleProtocolCapabilities *capabilities)
	Cache the capabilities of the system session.

void	bt_persistent_storage_init (void)
	Initialize the database, before the Bluetooth stack starts.

void	bt_persistent_storage_delete_all_pairings (void)
	Delete all bondings, keeping the local device settings.

int	bt_persistent_storage_get_raw_data (const void key, size_t key_len, void data_out, size_t buf_len)
	Read a raw database record, for unit tests.

Detailed Description

Persistent BLE bondings, CCCDs and local Bluetooth settings.

Normal firmware keeps them in a settings file and mirrors the gateway pairing, root keys, device name and pinned address to shared PRF storage. Recovery firmware uses shared PRF storage directly, with a single bonding slot. Only one BLE bonding is kept: storing a new one replaces the others.

Bonding changes are announced on KernelMain to the address, connection and client modules.

Typedef Documentation

◆ BtPersistBondingChangeHandler

typedef void(* BtPersistBondingChangeHandler) (pbl_bt_bonding_id_t affected_bonding, BtPersistBondingOp operation)

Handler of bonding database changes.

Parameters

affected_bonding	Bonding that changed.
operation	Change made.

◆ BtPersistBondingDBEachBLE

typedef void(* BtPersistBondingDBEachBLE) (struct pbl_bt_device_internal *device, struct pbl_bt_sm_key *irk, const char *name, pbl_bt_bonding_id_t *id, void *context)

Callback for bt_persistent_storage_for_each_ble_pairing().

Parameters

device	Remote identity address.
irk	Remote identity resolving key.
name	Remote device name.
id	Bonding ID.
context	User context.

Enumeration Type Documentation

◆ BtPersistBondingOp

enum BtPersistBondingOp

Change made to a bonding.

Enumerator
BtPersistBondingOpInvalid	No change.
BtPersistBondingOpDidAdd	Bonding was added.
BtPersistBondingOpDidChange	Existing bonding was updated.
BtPersistBondingOpWillDelete	Bonding is about to be deleted.

◆ BtPersistBondingType

enum BtPersistBondingType

Transport of a bonding.

Enumerator
BtPersistBondingTypeBTClassic	Bluetooth Classic (legacy, no longer stored).
BtPersistBondingTypeBLE	Bluetooth Low Energy.
BtPersistBondingNumTypes	Number of bonding types.

Function Documentation

◆ bt_persistent_storage_delete_all_pairings()

void bt_persistent_storage_delete_all_pairings ( void )

Delete all bondings, keeping the local device settings.

◆ bt_persistent_storage_delete_ble_pairing_by_addr()

void bt_persistent_storage_delete_ble_pairing_by_addr ( const struct pbl_bt_device_internal * device )

Delete the BLE bonding with an identity address, with its CCCDs.

Parameters

device Remote identity address.

◆ bt_persistent_storage_delete_ble_pairing_by_id()

void bt_persistent_storage_delete_ble_pairing_by_id ( pbl_bt_bonding_id_t )

Delete the BLE bonding with the given ID, with its CCCDs.

◆ bt_persistent_storage_delete_cccd()

bool bt_persistent_storage_delete_cccd	(	const struct pbl_bt_device_internal *	peer,
		uint16_t	chr_val_handle
	)

Delete a stored CCCD.

Parameters

peer	Peer identity address.
chr_val_handle	Characteristic value handle.

Returns: True if found and deleted.

◆ bt_persistent_storage_for_each_ble_pairing()

void bt_persistent_storage_for_each_ble_pairing	(	BtPersistBondingDBEachBLE	cb,
		void *	context
	)

Call a function for each BLE bonding.

cb must not take bt_lock(), or it may deadlock.

Parameters

cb	Callback.
context	User context passed to `cb`.

◆ bt_persistent_storage_get_active_gateway()

bool bt_persistent_storage_get_active_gateway	(	pbl_bt_bonding_id_t *	bonding_out,
		BtPersistBondingType *	type_out
	)

Get the active gateway.

Parameters

[out]	bonding_out	Bonding ID, may be NULL.
[out]	type_out	Bonding type, may be NULL.

Returns: True if an active gateway exists; outputs are only written then.

◆ bt_persistent_storage_get_airplane_mode_enabled()

bool bt_persistent_storage_get_airplane_mode_enabled ( void )

Get the stored airplane mode setting.

Returns: True if airplane mode is on; false by default.

◆ bt_persistent_storage_get_ble_ancs_bonding()

pbl_bt_bonding_id_t bt_persistent_storage_get_ble_ancs_bonding ( void )

Get the first BLE bonding that supports ANCS.

Returns: Bonding ID, or PBL_BT_BONDING_ID_INVALID if none.

◆ bt_persistent_storage_get_ble_pairing_by_addr()

bool bt_persistent_storage_get_ble_pairing_by_addr	(	const struct pbl_bt_device_internal *	device,
		struct pbl_bt_sm_key *	IRK_out,
		char	name_out[PBL_BT_DEVICE_NAME_BUFFER_SIZE]
	)

Look up a BLE bonding by identity address.

Parameters

	device	Remote identity address.
[out]	IRK_out	Remote identity resolving key, may be NULL.
[out]	name_out	Remote name, may be NULL.

Returns: True if found.

◆ bt_persistent_storage_get_ble_pairing_by_id()

bool bt_persistent_storage_get_ble_pairing_by_id	(	pbl_bt_bonding_id_t	bonding,
		struct pbl_bt_sm_key *	IRK_out,
		struct pbl_bt_device_internal *	device_out,
		char *	name_out
	)

Look up a BLE bonding by ID.

Parameters

	bonding	Bonding ID.
[out]	IRK_out	Remote identity resolving key, may be NULL.
[out]	device_out	Remote identity address, may be NULL.
[out]	name_out	Remote name, `PBL_BT_DEVICE_NAME_BUFFER_SIZE` bytes, may be NULL.

Returns: True if found.

◆ bt_persistent_storage_get_ble_pinned_address()

bool bt_persistent_storage_get_ble_pinned_address ( struct pbl_bt_addr * address_out )

Get the pinned local BLE address.

Parameters

[out] address_out Pinned address, may be NULL.

Returns: True if a pinned address is stored.

◆ bt_persistent_storage_get_cached_system_capabilities()

void bt_persistent_storage_get_cached_system_capabilities ( PebbleProtocolCapabilities * capabilities_out )

Get the cached capabilities of the last system session.

Prefer comm_session_get_capabilities() when connected.

Parameters

[out] capabilities_out Capabilities, zero if none cached. Ignored if NULL.

◆ bt_persistent_storage_get_local_device_name()

bool bt_persistent_storage_get_local_device_name	(	char *	local_device_name_out,
		size_t	max_size
	)

Get the stored local device name.

Parameters

[out]	local_device_name_out	Destination buffer.
	max_size	Size of `local_device_name_out` in bytes.

Returns: True if a name is stored.

◆ bt_persistent_storage_get_raw_data()

int bt_persistent_storage_get_raw_data	(	const void *	key,
		size_t	key_len,
		void *	data_out,
		size_t	buf_len
	)

Read a raw database record, for unit tests.

Parameters

	key	Record key.
	key_len	Length of `key` in bytes.
[out]	data_out	Destination buffer.
	buf_len	Size of `data_out` in bytes.

Returns: Number of bytes read, 0 if not found.

◆ bt_persistent_storage_get_root_key()

bool bt_persistent_storage_get_root_key	(	enum pbl_bt_sm_root_key_type	key_type,
		struct pbl_bt_sm_key *	key_out
	)

Get a BLE root key.

Parameters

	key_type	Encryption root (ER) or identity root (IR).
[out]	key_out	Key, may be NULL.

Returns: True if a non-zero key is stored.

◆ bt_persistent_storage_has_active_ble_gateway_bonding()

bool bt_persistent_storage_has_active_ble_gateway_bonding ( void )

Check whether the active gateway is a BLE bonding.

Returns: True if it is.

◆ bt_persistent_storage_has_ble_ancs_bonding()

bool bt_persistent_storage_has_ble_ancs_bonding ( void )

Check whether any BLE bonding supports ANCS.

Returns: True if one does.

◆ bt_persistent_storage_has_pinned_ble_pairings()

bool bt_persistent_storage_has_pinned_ble_pairings ( void )

Check whether any BLE bonding requires address pinning.

Returns: True if one does.

◆ bt_persistent_storage_init()

void bt_persistent_storage_init ( void )

Initialize the database, before the Bluetooth stack starts.

Merges data from shared PRF storage and loads the cached capabilities.

◆ bt_persistent_storage_is_ble_ancs_bonding()

bool bt_persistent_storage_is_ble_ancs_bonding ( pbl_bt_bonding_id_t bonding )

Check whether a bonding is a BLE bonding that supports ANCS.

Parameters

bonding Bonding ID.

Returns: True if it is.

◆ bt_persistent_storage_is_unfaithful()

bool bt_persistent_storage_is_unfaithful ( void )

Check whether the watch is unfaithful.

The watch becomes unfaithful when its gateway changes, until the next sync.

Returns: True if unfaithful; true by default.

◆ bt_persistent_storage_register_existing_ble_bondings()

void bt_persistent_storage_register_existing_ble_bondings ( void )

Register all stored BLE bondings and CCCDs with the Bluetooth driver.

◆ bt_persistent_storage_set_active_gateway()

void bt_persistent_storage_set_active_gateway ( pbl_bt_bonding_id_t bonding )

Set the active gateway, the bonding that implements Pebble Protocol.

On change, marks the watch unfaithful and clears the cached system capabilities.

Parameters

bonding Bonding ID.

◆ bt_persistent_storage_set_airplane_mode_enabled()

void bt_persistent_storage_set_airplane_mode_enabled ( bool enable )

Store the airplane mode setting.

Parameters

enable Airplane mode state.

◆ bt_persistent_storage_set_ble_pinned_address()

bool bt_persistent_storage_set_ble_pinned_address ( const struct pbl_bt_addr * address )

Store the pinned local BLE address.

Parameters

address Address to pin.

Returns: True on success.

◆ bt_persistent_storage_set_cached_system_capabilities()

void bt_persistent_storage_set_cached_system_capabilities ( const PebbleProtocolCapabilities * capabilities )

Cache the capabilities of the system session.

When they change, they are persisted and a capabilities changed event is emitted.

Parameters

capabilities Capabilities, or NULL to clear the cache.

◆ bt_persistent_storage_set_local_device_name()

void bt_persistent_storage_set_local_device_name	(	char *	local_device_name,
		size_t	max_size
	)

Store the local device name.

Parameters

local_device_name	Name to store. Ignored if NULL.
max_size	Number of bytes to store.

◆ bt_persistent_storage_set_root_keys()

void bt_persistent_storage_set_root_keys ( struct pbl_bt_sm_key * keys_in )

Store the BLE root keys.

Parameters

keys_in Array of PBL_BT_SM_ROOT_KEY_TYPE_NUM keys, indexed by key type. Ignored if NULL.

◆ bt_persistent_storage_set_unfaithful()

void bt_persistent_storage_set_unfaithful ( bool is_unfaithful )

Set whether the watch is unfaithful.

Parameters

is_unfaithful New state.

◆ bt_persistent_storage_store_ble_pairing()

pbl_bt_bonding_id_t bt_persistent_storage_store_ble_pairing	(	const struct pbl_bt_sm_pairing_info *	pairing_info,
		bool	is_gateway,
		const char *	device_name,
		bool	requires_address_pinning,
		uint8_t	flags
	)

Add or update a BLE bonding.

An existing bonding with the same identity is updated; otherwise a new one is added, the watch is marked unfaithful and any other BLE bonding is deleted.

Parameters

pairing_info	Pairing info; empty pairing info is rejected.
is_gateway	True if the device is the phone running the Pebble app.
device_name	Remote device name, may be NULL.
requires_address_pinning	True if the remote needs a stable local address.
flags	Bonding flags, passed back to the Bluetooth driver.

Returns: Bonding ID, or PBL_BT_BONDING_ID_INVALID on failure.

◆ bt_persistent_storage_store_cccd()

pbl_bt_cccd_id_t bt_persistent_storage_store_cccd ( const struct pbl_bt_cccd * cccd )

Store a CCCD, replacing the one for the same peer and characteristic.

Parameters

cccd	CCCD to store.

Returns: CCCD ID, or PBL_BT_CCCD_ID_INVALID on failure.

◆ bt_persistent_storage_update_ble_device_name()

bool bt_persistent_storage_update_ble_device_name	(	pbl_bt_bonding_id_t	bonding,
		const char *	device_name
	)

Update the name of a BLE bonding.

Parameters

bonding	Bonding ID.
device_name	New name.

Returns: True on success.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ BtPersistBondingChangeHandler

◆ BtPersistBondingDBEachBLE

Enumeration Type Documentation

◆ BtPersistBondingOp

◆ BtPersistBondingType

Function Documentation

◆ bt_persistent_storage_delete_all_pairings()

◆ bt_persistent_storage_delete_ble_pairing_by_addr()

◆ bt_persistent_storage_delete_ble_pairing_by_id()

◆ bt_persistent_storage_delete_cccd()

◆ bt_persistent_storage_for_each_ble_pairing()

◆ bt_persistent_storage_get_active_gateway()

◆ bt_persistent_storage_get_airplane_mode_enabled()

◆ bt_persistent_storage_get_ble_ancs_bonding()

◆ bt_persistent_storage_get_ble_pairing_by_addr()

◆ bt_persistent_storage_get_ble_pairing_by_id()

◆ bt_persistent_storage_get_ble_pinned_address()

◆ bt_persistent_storage_get_cached_system_capabilities()

◆ bt_persistent_storage_get_local_device_name()

◆ bt_persistent_storage_get_raw_data()

◆ bt_persistent_storage_get_root_key()

◆ bt_persistent_storage_has_active_ble_gateway_bonding()

◆ bt_persistent_storage_has_ble_ancs_bonding()

◆ bt_persistent_storage_has_pinned_ble_pairings()

◆ bt_persistent_storage_init()

◆ bt_persistent_storage_is_ble_ancs_bonding()

◆ bt_persistent_storage_is_unfaithful()

◆ bt_persistent_storage_register_existing_ble_bondings()

◆ bt_persistent_storage_set_active_gateway()

◆ bt_persistent_storage_set_airplane_mode_enabled()

◆ bt_persistent_storage_set_ble_pinned_address()

◆ bt_persistent_storage_set_cached_system_capabilities()

◆ bt_persistent_storage_set_local_device_name()

◆ bt_persistent_storage_set_root_keys()

◆ bt_persistent_storage_set_unfaithful()

◆ bt_persistent_storage_store_ble_pairing()

◆ bt_persistent_storage_store_cccd()

◆ bt_persistent_storage_update_ble_device_name()