Pebble Pairing Service

GATT service through which the phone app checks the connection and triggers pairing. More...

Data Structures
struct	pbl_bt_pps_connectivity_status
	Connectivity Status value, with respect to the device reading it. More...
struct	pbl_bt_pps_trigger_request
	Value written to the Trigger Pairing characteristic. More...
struct	pbl_bt_pps_conn_param_set
	A connection parameter set, in the Connection Parameters characteristic format. More...
struct	pbl_bt_pps_conn_params_read_notif
	Connection Parameters read or notified value, for the reading device's connection. More...
struct	pbl_bt_pps_remote_param_mgmt_settings
	Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_PARAM_MGMT_SETTINGS. More...
struct	pbl_bt_pps_remote_desired_state
	Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_DESIRED_STATE. More...
struct	pbl_bt_pps_packet_length_extension
	Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_ENABLE_PACKET_LENGTH_EXTENSION. More...
struct	pbl_bt_pps_inhibit_ble_sleep
	Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_INHIBIT_BLE_SLEEP. More...
struct	pbl_bt_pps_conn_params_write
	Value written to the Connection Parameters characteristic. More...
union	pbl_bt_pps_connectivity_status.__unnamed1__
struct	pbl_bt_pps_connectivity_status.__unnamed1__.__unnamed3__
union	pbl_bt_pps_conn_params_write.__unnamed5__
	Command payload, selected by cmd. More...

Macros
#define	PBL_BT_PPS_CONNECTION_STATUS_UUID   PBL_BT_PEBBLE_UUID_EXPAND(1)
	UUID of the Connectivity Status characteristic, as an initializer list.
#define	PBL_BT_PPS_TRIGGER_PAIRING_UUID   PBL_BT_PEBBLE_UUID_EXPAND(2)
	UUID of the Trigger Pairing characteristic, as an initializer list.
#define	PBL_BT_PPS_CONNECTION_PARAMETERS_UUID   PBL_BT_PEBBLE_UUID_EXPAND(5)
	UUID of the Connection Parameters characteristic, as an initializer list.
#define	PBL_BT_PPS_REMOTE_PARAM_MGMT_SETTINGS_SIZE_WITH_PARAM_SETS
	Size of struct pbl_bt_pps_remote_param_mgmt_settings with all parameter sets.
#define	PBL_BT_PPS_CONN_PARAMS_WRITE_SIZE_WITH_PARAM_SETS
	Size of a parameter management settings write with all parameter sets.

Typedefs
typedef struct GAPLEConnection	GAPLEConnection
	LE connection state kept by the firmware (see comm/ble/gap_le_connection.h).

Enumerations
enum	pbl_bt_pps_gatt_error {   PBL_BT_PPS_GATT_ERROR_UNKNOWN_COMMAND_ID = PBL_BT_GATT_ERROR_APPLICATION_SPECIFIC_ERROR_START , PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_INVALID_REMOTE_DESIRED_STATE , PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_MIN_SLOTS_TOO_SMALL , PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_MIN_SLOTS_TOO_LARGE ,   PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_MAX_SLOTS_TOO_LARGE , PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_SUPERVISION_TIMEOUT_TOO_SMALL , PBL_BT_PPS_GATT_ERROR_DEVICE_DOES_NOT_SUPPORT_PLE }
	Application specific ATT errors returned by the service. More...
enum	pbl_bt_pps_conn_params_write_cmd {   PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_PARAM_MGMT_SETTINGS = 0x00 , PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_DESIRED_STATE = 0x01 , PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_ENABLE_PACKET_LENGTH_EXTENSION = 0x02 , PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_INHIBIT_BLE_SLEEP = 0x03 ,   PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_NUM }
	Commands written to the Connection Parameters characteristic. More...

Functions
void	pbl_bt_pps_handle_status_change (const GAPLEConnection *connection)
	Signal a change of the connection status (pairing, encryption, ...).
void	pbl_bt_cb_pps_handle_ios_app_termination_detected (void)
	Called when the Connectivity Status characteristic is unsubscribed from.
void	pbl_bt_cb_pps_handle_connection_parameter_write (const struct pbl_bt_device_internal *device, const struct pbl_bt_pps_conn_params_write *conn_params, size_t conn_params_length)
	Called when the Connection Parameters characteristic was written.

Detailed Description

GATT service through which the phone app checks the connection and triggers pairing.

The service (PBL_BT_PPS_UUID_16BIT) has a Connectivity Status characteristic (read, notify) and a Trigger Pairing characteristic (read, write). The NimBLE backend does not implement the Connection Parameters characteristic. The wire formats below must fit the minimum ATT MTU.

---

Data Structure Documentation

pbl_bt_pps_connectivity_status

struct pbl_bt_pps_connectivity_status

Connectivity Status value, with respect to the device reading it.

Data Fields
union pbl_bt_pps_connectivity_status.__unnamed1__	__unnamed__

pbl_bt_pps_trigger_request

struct pbl_bt_pps_trigger_request

Value written to the Trigger Pairing characteristic.

Data Fields
bool	is_reversed_ppogatt_enabled: 1	Reverse the PPoGATT server and client roles for this phone. For older Android phones with a broken GATT server API: the watch then hosts a "reversed" PPoGATT service the phone app connects to as a client. It only works if this bit is set before pairing, which keeps unpaired devices and non-Pebble apps on a phone that supports normal PPoGATT away from the reversed service.
bool	no_slave_security_request: 1	Don't send a security request. Mutually exclusive with should_force_slave_security_request.
bool	should_auto_accept_re_pairing: 1	Accept re-pairing with this device automatically (matching IRK or identity address). Note A work-around for an Android 4.4.x bug. It opens a security hole: a phone could impersonate the trusted phone and pair without the user knowing.
bool	should_force_slave_security_request: 1	Send a security request even if the link is already encrypted. Mutually exclusive with no_slave_security_request.
bool	should_pin_address: 1	Pin the local address for this device.

pbl_bt_pps_conn_param_set

struct pbl_bt_pps_conn_param_set

A connection parameter set, in the Connection Parameters characteristic format.

Data Fields
uint8_t	interval_max_delta_1_25ms	Maximum minus minimum connection interval in 1.25 ms units. A one-byte delta, not the spec's uint16_t, to fit the minimum MTU.
uint16_t	interval_min_1_25ms	Minimum connection interval in 1.25 ms units, 7.5 ms to 4 s.
uint8_t	slave_latency_events	Peripheral latency in connection events. One byte, not the spec's uint16_t, to fit the minimum MTU.
uint8_t	supervision_timeout_30ms	Supervision timeout in 30 ms units (not the spec's 10 ms, to fit one byte), 100 ms to 32 s.

pbl_bt_pps_conn_params_read_notif

struct pbl_bt_pps_conn_params_read_notif

Connection Parameters read or notified value, for the reading device's connection.

Data Fields
uint16_t	current_interval_1_25ms	Current connection interval in 1.25 ms units, 7.5 ms to 4 s.
uint16_t	current_slave_latency_events	Current peripheral latency in connection events, at most 0x01F3.
uint16_t	current_supervision_timeout_10ms	Current supervision timeout in 10 ms units, 100 ms to 32 s.
uint8_t	packet_length_extension_supported: 1	True if Packet Length Extension is supported.
uint8_t	rsvd: 7	Reserved.

pbl_bt_pps_remote_param_mgmt_settings

struct pbl_bt_pps_remote_param_mgmt_settings

Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_PARAM_MGMT_SETTINGS.

Data Fields
struct pbl_bt_pps_conn_param_set	connection_parameter_sets[]	Optional parameter sets for the watch's connection parameter manager.
bool	is_remote_device_managing_connection_parameters: 1	True if the remote device manages the connection parameters. The watch then never requests a connection parameter change.
uint8_t	rsvd: 7	Reserved.

pbl_bt_pps_remote_desired_state

struct pbl_bt_pps_remote_desired_state

Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_DESIRED_STATE.

Data Fields
uint8_t	rsvd: 6	Reserved.
uint8_t	state: 2	Response time desired by the remote device, an enum pbl_bt_response_time_state. The remote can ask for PBL_BT_RESPONSE_TIME_MIN before a bulk transfer the watch cannot anticipate, and is responsible for setting PBL_BT_RESPONSE_TIME_MAX when done. The watch falls back to PBL_BT_RESPONSE_TIME_MAX after 5 minutes; write again before then to keep the state.

pbl_bt_pps_packet_length_extension

struct pbl_bt_pps_packet_length_extension

Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_ENABLE_PACKET_LENGTH_EXTENSION.

Data Fields
uint8_t	rsvd: 7	Reserved.
uint8_t	trigger_ll_length_req: 1	Trigger an LL length request.

pbl_bt_pps_inhibit_ble_sleep

struct pbl_bt_pps_inhibit_ble_sleep

Payload of PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_INHIBIT_BLE_SLEEP.

Data Fields
uint8_t	rsvd	Reserved.

pbl_bt_pps_conn_params_write

struct pbl_bt_pps_conn_params_write

Value written to the Connection Parameters characteristic.

Data Fields
union pbl_bt_pps_conn_params_write.__unnamed5__	__unnamed__	Command payload, selected by cmd.
enum pbl_bt_pps_conn_params_write_cmd	cmd: 8	The command, selects the payload.

pbl_bt_pps_connectivity_status.__unnamed1__

union pbl_bt_pps_connectivity_status.__unnamed1__

Data Fields
struct pbl_bt_pps_connectivity_status.__unnamed1__.__unnamed3__	__unnamed__
uint8_t	bytes[4]	Raw value.

pbl_bt_pps_connectivity_status.__unnamed1__.__unnamed3__

struct pbl_bt_pps_connectivity_status.__unnamed1__.__unnamed3__

Data Fields
bool	ble_is_bonded: 1	True if the reading device is bonded.
bool	ble_is_connected: 1	True if the reading device is connected (always true).
bool	ble_is_encrypted: 1	True if the current LE link is encrypted.
bool	has_bonded_gateway: 1	True if the watch has a bonding to an LE gateway.
bool	is_reversed_ppogatt_enabled: 1	True if reversed PPoGATT was enabled at the time of bonding.
uint8_t	last_pairing_result	Error of the last pairing, or zero if no pairing completed or it succeeded. See Bluetooth Core Specification v4.2, Vol 3, Part H, 3.5.5 Pairing Failed.
uint32_t	rsvd: 18	Reserved, zero.
bool	supports_pinning_without_security_request: 1	True if the watch supports the pbl_bt_pps_trigger_request::no_slave_security_request bit.

pbl_bt_pps_conn_params_write.__unnamed5__

union pbl_bt_pps_conn_params_write.__unnamed5__

Command payload, selected by cmd.

Data Fields
struct pbl_bt_pps_inhibit_ble_sleep	ble_sleep	Valid iff cmd is PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_INHIBIT_BLE_SLEEP.
struct pbl_bt_pps_packet_length_extension	ple_req	Valid iff cmd is PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_ENABLE_PACKET_LENGTH_EXTENSION.
struct pbl_bt_pps_remote_desired_state	remote_desired_state	Valid iff cmd is PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_DESIRED_STATE.
struct pbl_bt_pps_remote_param_mgmt_settings	remote_param_mgmt_settings	Valid iff cmd is PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_PARAM_MGMT_SETTINGS.

Macro Definition Documentation

PBL_BT_PPS_CONN_PARAMS_WRITE_SIZE_WITH_PARAM_SETS

#define PBL_BT_PPS_CONN_PARAMS_WRITE_SIZE_WITH_PARAM_SETS

Value:

  (offsetof(struct pbl_bt_pps_conn_params_write, remote_param_mgmt_settings) + \
   PBL_BT_PPS_REMOTE_PARAM_MGMT_SETTINGS_SIZE_WITH_PARAM_SETS)

Size of a parameter management settings write with all parameter sets.

PBL_BT_PPS_CONNECTION_PARAMETERS_UUID

#define PBL_BT_PPS_CONNECTION_PARAMETERS_UUID   PBL_BT_PEBBLE_UUID_EXPAND(5)

UUID of the Connection Parameters characteristic, as an initializer list.

UUID 4 was used by a pre-release Android app for an earlier version of it and must not be reused.

PBL_BT_PPS_CONNECTION_STATUS_UUID

#define PBL_BT_PPS_CONNECTION_STATUS_UUID   PBL_BT_PEBBLE_UUID_EXPAND(1)

UUID of the Connectivity Status characteristic, as an initializer list.

PBL_BT_PPS_REMOTE_PARAM_MGMT_SETTINGS_SIZE_WITH_PARAM_SETS

#define PBL_BT_PPS_REMOTE_PARAM_MGMT_SETTINGS_SIZE_WITH_PARAM_SETS

Value:

  (sizeof(struct pbl_bt_pps_remote_param_mgmt_settings) +          \
   (sizeof(struct pbl_bt_pps_conn_param_set) * PBL_BT_RESPONSE_TIME_NUM))

Size of struct pbl_bt_pps_remote_param_mgmt_settings with all parameter sets.

PBL_BT_PPS_TRIGGER_PAIRING_UUID

#define PBL_BT_PPS_TRIGGER_PAIRING_UUID   PBL_BT_PEBBLE_UUID_EXPAND(2)

UUID of the Trigger Pairing characteristic, as an initializer list.

Typedef Documentation

GAPLEConnection

typedef struct GAPLEConnection GAPLEConnection

LE connection state kept by the firmware (see comm/ble/gap_le_connection.h).

Enumeration Type Documentation

pbl_bt_pps_conn_params_write_cmd

enum pbl_bt_pps_conn_params_write_cmd

Commands written to the Connection Parameters characteristic.

Enumerator
PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_PARAM_MGMT_SETTINGS	Change the connection parameter sets and take over parameter management.
PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_SET_REMOTE_DESIRED_STATE	Request a connection parameter change if the watch is not in the desired state.
PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_ENABLE_PACKET_LENGTH_EXTENSION	Control the LE Packet Length Extension feature.
PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_INHIBIT_BLE_SLEEP	Disable the controller sleep mode, a safeguard for a Dialog controller issue.
PBL_BT_PPS_CONN_PARAMS_WRITE_CMD_NUM	Number of commands.

pbl_bt_pps_gatt_error

enum pbl_bt_pps_gatt_error

Application specific ATT errors returned by the service.

Enumerator
PBL_BT_PPS_GATT_ERROR_UNKNOWN_COMMAND_ID	Unknown command.
PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_INVALID_REMOTE_DESIRED_STATE	The requested remote desired state is invalid.
PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_MIN_SLOTS_TOO_SMALL	The minimum connection interval is too small.
PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_MIN_SLOTS_TOO_LARGE	The minimum connection interval is too large.
PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_MAX_SLOTS_TOO_LARGE	The maximum connection interval is too large.
PBL_BT_PPS_GATT_ERROR_CONN_PARAMS_SUPERVISION_TIMEOUT_TOO_SMALL	The supervision timeout is too small.
PBL_BT_PPS_GATT_ERROR_DEVICE_DOES_NOT_SUPPORT_PLE	The device does not support Packet Length Extension.

Function Documentation

pbl_bt_cb_pps_handle_connection_parameter_write()

void pbl_bt_cb_pps_handle_connection_parameter_write ( const struct pbl_bt_device_internal *  device, const struct pbl_bt_pps_conn_params_write *  conn_params, size_t  conn_params_length  )

extern

Called when the Connection Parameters characteristic was written.

Not invoked by the NimBLE backend.

Parameters

device	The device that wrote the characteristic.
conn_params	The value written, validated by the stack.
conn_params_length	Length of conn_params in bytes.

pbl_bt_cb_pps_handle_ios_app_termination_detected()

void pbl_bt_cb_pps_handle_ios_app_termination_detected ( void  )

extern

Called when the Connectivity Status characteristic is unsubscribed from.

Used to detect that the Pebble iOS app was terminated. Not invoked by the NimBLE backend.

pbl_bt_pps_handle_status_change()

void pbl_bt_pps_handle_status_change

(

const GAPLEConnection *

connection

)

Signal a change of the connection status (pairing, encryption, ...).

Notifies the Connectivity Status to the subscribed device.

Parameters

connection

The connection whose status changed.