Pebble protocol

Messages exchanged with phone apps over any transport. More...

Modules
	Endpoints
	Handlers of inbound messages, one per endpoint ID.
	Wire protocol
	Pebble protocol message framing, endpoint IDs and capabilities.
	Sending
	Queueing outbound messages on a session.
	Transports
	Interface between sessions and the links that carry them.

Data Structures
struct	pbl_pp_session_listener
	Session listener. More...

Macros
#define	PBL_PP_SESSION_LISTENER_DEFINE(_name, _callback, _user_data)
	Define a listener of session events.

Enumerations
enum	pbl_pp_session_type : int8_t { PBL_PP_SESSION_INVALID = -1 , PBL_PP_SESSION_SYSTEM = 0 , PBL_PP_SESSION_APP = 1 }
	Kind of session. More...
enum	pbl_pp_session_event : uint8_t { PBL_PP_SESSION_OPENED , PBL_PP_SESSION_CLOSED , PBL_PP_SESSION_CAPABILITIES }
	Session life cycle events, see PBL_PP_SESSION_LISTENER_DEFINE(). More...

Functions
struct pbl_pp_session *	pbl_pp_session_get_system (void)
	Get the system session.
struct pbl_pp_session *	pbl_pp_session_get_app (const Uuid *app_uuid)
	Get the session serving a watch app.
enum pbl_pp_session_type	pbl_pp_session_get_type (const struct pbl_pp_session *session)
	Get the kind of a session.
bool	pbl_pp_session_is_system (const struct pbl_pp_session *session)
	Check whether a session is a system session.
uint32_t	pbl_pp_session_get_capabilities (const struct pbl_pp_session *session)
	Get the capabilities announced on a session.
bool	pbl_pp_session_has_capability (const struct pbl_pp_session *session, enum pbl_pp_capability capability)
	Check whether a session announced a capability.
void	pbl_pp_session_reset (struct pbl_pp_session *session)
	Ask the transport to reset a session.
void	pbl_pp_session_set_responsiveness (struct pbl_pp_session *session, enum pbl_bt_consumer consumer, enum pbl_bt_response_time_state state, uint16_t max_period_secs, pbl_bt_responsiveness_granted_cb_t granted)
	Request a connection response time for a session.

Detailed Description

Messages exchanged with phone apps over any transport.

A session carries Pebble protocol messages over a transport, such as PPoGATT over BLE, the serial console or the emulator, and hides the differences between them. Inbound messages are dispatched to endpoints; outbound ones are queued per session with the send API and drained by the transport.

There are two kinds of sessions:

• The system session talks to the Pebble mobile app. Opening one on a transport closes the previous one, unless one of them is on a transport that shares the role, like the console. A hybrid session also carries PebbleKit app traffic.
• An app session connects directly to a third party phone app.

Sessions may close at any time: a session pointer is only a handle, validated by every call.

Macro Definition Documentation

PBL_PP_SESSION_LISTENER_DEFINE

#define PBL_PP_SESSION_LISTENER_DEFINE	(		_name,
			_callback,
			_user_data
	)

Value:

  static const struct pbl_pp_session_listener pbl_pp_session_listener_##_name PBL_USED \
      PBL_ALIGNED(4) PBL_SECTION(".pbl_pp_session_listeners." #_name) = {              \
        .callback = (_callback),                                                       \
        .user_data = (_user_data),                                                     \
  }

Define a listener of session events.

Listeners are called in the context of the transport that caused the event, which may hold its own locks: they must not block, and should defer work to a task.

Parameters

_name	Name of the listener, unique across the firmware.
_callback	Function called for every event.
_user_data	Data passed to _callback.

Enumeration Type Documentation

pbl_pp_session_event

enum pbl_pp_session_event : uint8_t

Session life cycle events, see PBL_PP_SESSION_LISTENER_DEFINE().

Enumerator
PBL_PP_SESSION_OPENED	The session opened.
PBL_PP_SESSION_CLOSED	The session is closing; it is still valid during the callback.
PBL_PP_SESSION_CAPABILITIES	The phone announced the session's capabilities.

pbl_pp_session_type

enum pbl_pp_session_type : int8_t

Kind of session.

Enumerator
PBL_PP_SESSION_INVALID	Not a valid, or no longer open, session.
PBL_PP_SESSION_SYSTEM	Session with the Pebble mobile app.
PBL_PP_SESSION_APP	Session with a third party phone app.

Function Documentation

pbl_pp_session_get_app()

struct pbl_pp_session * pbl_pp_session_get_app

(

const Uuid *

app_uuid

)

Get the session serving a watch app.

Prefers an app session bound to app_uuid, then a hybrid session or an app session whose app is unknown.

Parameters

app_uuid

UUID of the watch app.

Returns

The session, or NULL if none can serve the app or app_uuid is a system UUID.

pbl_pp_session_get_capabilities()

uint32_t pbl_pp_session_get_capabilities

(

const struct pbl_pp_session *

session

)

Get the capabilities announced on a session.

Parameters

session

Session.

Returns

Capability bits, 0 if session is not open.

pbl_pp_session_get_system()

struct pbl_pp_session * pbl_pp_session_get_system

(

void

)

Get the system session.

When several system sessions are open, the one on the preferred transport is returned.

Returns

The system session, or NULL if none is open.

pbl_pp_session_get_type()

enum pbl_pp_session_type pbl_pp_session_get_type

(

const struct pbl_pp_session *

session

)

Get the kind of a session.

Parameters

session

Session.

Returns

Session type, or PBL_PP_SESSION_INVALID if session is not open.

pbl_pp_session_has_capability()

bool pbl_pp_session_has_capability	(	const struct pbl_pp_session *	session,
		enum pbl_pp_capability	capability
	)

Check whether a session announced a capability.

Parameters

session	Session.
capability	Capability.

Returns

true if session is open and announced capability.

pbl_pp_session_is_system()

bool pbl_pp_session_is_system

(

const struct pbl_pp_session *

session

)

Check whether a session is a system session.

Parameters

session

Session.

Returns

true if session is an open system session.

pbl_pp_session_reset()

void pbl_pp_session_reset

(

struct pbl_pp_session *

session

)

Ask the transport to reset a session.

The transport closes the session and may open a new one.

Parameters

session

Session.

pbl_pp_session_set_responsiveness()

void pbl_pp_session_set_responsiveness	(	struct pbl_pp_session *	session,
		enum pbl_bt_consumer	consumer,
		enum pbl_bt_response_time_state	state,
		uint16_t	max_period_secs,
		pbl_bt_responsiveness_granted_cb_t	granted
	)

Request a connection response time for a session.

Transports without a notion of response time grant every request at once.

Parameters

session	Session; ignored if not open.
consumer	Consumer making the request.
state	Requested response time state.
max_period_secs	Maximum time to stay in state.
granted	Called on KernelMain once state is in effect. May be NULL.