Communication sessions

Pebble Protocol sessions with the phone. More...

Modules
	App session capability cache
	Per-app cache of app session capabilities, persisted in a settings file.
	Default kernel sender
	Kernel-heap send buffers behind the session send buffer API.
	Meta endpoint
	Protocol error responses sent on the meta endpoint (ID 0).
	Pebble Protocol framing
	Pebble Protocol message header and size limits.
	Session analytics
	Connectivity analytics hooks for session open and close.
	Session internals
	Session state, for the session module and its transports.
	Receive router
	Inbound message parsing and dispatch to endpoint handlers.
	Remote OS
	Phone operating system reported in the platform bitfield.
	Remote version
	Phone version and capabilities exchange.
	Send buffers
	Build an outbound message piecemeal in a kernel-heap buffer.
	Send queue
	Per-session queue of outbound jobs, each holding complete messages.
	Transport interface
	Interface between sessions and the transports that carry them.

Macros
#define	COMM_SESSION_DEFAULT_TIMEOUT   (4000)
	Default send timeout in milliseconds.

Enumerations
enum	CommSessionType { CommSessionTypeInvalid = -1 , CommSessionTypeSystem = 0 , CommSessionTypeApp = 1 , NumCommSessions }
	Kind of session. More...
enum	CommSessionCapability {   CommSessionRunState = 1 << 0 , CommSessionInfiniteLogDumping = 1 << 1 , CommSessionExtendedMusicService = 1 << 2 , CommSessionExtendedNotificationService = 1 << 3 ,   CommSessionLanguagePackSupport = 1 << 4 , CommSessionAppMessage8kSupport = 1 << 5 , CommSessionActivityInsightsSupport = 1 << 6 , CommSessionVoiceApiSupport = 1 << 7 ,   CommSessionSendTextSupport = 1 << 8 , CommSessionNotificationFilteringSupport = 1 << 9 , CommSessionUnreadCoredumpSupport = 1 << 10 , CommSessionWeatherAppSupport = 1 << 11 ,   CommSessionRemindersAppSupport = 1 << 12 , CommSessionWorkoutAppSupport = 1 << 13 , CommSessionSmoothFwInstallProgressSupport = 1 << 14 , CommSessionImagingSupport = 1 << 17 ,   CommSessionSettingsSyncSupport = 1 << 23 , CommSessionNotificationWindowStateSupport = 1 << 26 , CommSessionOutOfRange }
	Protocol capabilities announced by the phone. More...

Functions
bool	comm_session_has_capability (CommSession *session, CommSessionCapability capability)
	Check whether a session supports a capability.
CommSessionCapability	comm_session_get_capabilities (CommSession *session)
	Get the capabilities of a session.
CommSession *	comm_session_get_system_session (void)
	Get the system (Pebble mobile app) session.
CommSession *	comm_session_get_current_app_session (void)
	Get the session serving the currently running watch app.
void	comm_session_sanitize_app_session (CommSession **session_in_out)
	Restrict a session to the one the current app is permitted to use.
CommSessionType	comm_session_get_type (const CommSession *session)
	Get the kind of a session.
CommSession *	comm_session_get_by_type (CommSessionType type)
	Get a session by kind.
const Uuid *	comm_session_get_uuid (const CommSession *session)
	Get the UUID of the app a session is connected to.
bool	comm_session_is_system (CommSession *session)
	Check whether a session is the system session.
void	comm_session_reset (CommSession *session)
	Reset a session by asking its transport to close and reopen it.
bool	comm_session_send_data (CommSession *session, uint16_t endpoint_id, const uint8_t *data, size_t length, uint32_t timeout_ms)
	Send a complete Pebble Protocol message.
void	comm_session_set_responsiveness (CommSession *session, enum pbl_bt_consumer consumer, enum pbl_bt_response_time_state state, uint16_t max_period_secs)
	Request a connection response time for a session.
void	comm_session_set_responsiveness_ext (CommSession *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_handler)
	Request a connection response time for a session, with a granted callback.
void	comm_session_init (void)
	Initialize the session module.

Detailed Description

Pebble Protocol sessions with the phone.

A session carries Pebble Protocol messages over a transport (iAP for iOS, plain SPP for Android, PPoGATT over BLE, QEMU, PULSE) and hides the differences between them.

There are two kinds of sessions:

• The system session talks to the Pebble mobile app. Only one exists at a time; when another transport opens a system session, the previous one is closed. On Android it uses a hybrid transport that also carries PebbleKit app traffic.
• An app session connects directly to a third party phone app. PPoGATT can carry several app sessions at once, iAP only one.

Sessions may disconnect at any time: a CommSession pointer is only a handle, validated by every call. Outbound messages are queued per session and drained by the transport.

CommSession *session = comm_session_get_system_session();
const uint8_t msg[] = {0x01, 0x02};
 
if (!comm_session_send_data(session, endpoint_id, msg, sizeof(msg),
                            COMM_SESSION_DEFAULT_TIMEOUT)) {
  // Not connected, or no room in the send buffer before the timeout.
}

Macro Definition Documentation

COMM_SESSION_DEFAULT_TIMEOUT

#define COMM_SESSION_DEFAULT_TIMEOUT   (4000)

Default send timeout in milliseconds.

Enumeration Type Documentation

CommSessionCapability

enum CommSessionCapability

Protocol capabilities announced by the phone.

Bit positions match the fields of PebbleProtocolCapabilities.

Enumerator
CommSessionRunState	App run state endpoint.
CommSessionInfiniteLogDumping	Infinite log dumping.
CommSessionExtendedMusicService	Extended music service.
CommSessionExtendedNotificationService	Extended notification service.
CommSessionLanguagePackSupport	Language pack installation.
CommSessionAppMessage8kSupport	8 KiB AppMessage buffers.
CommSessionActivityInsightsSupport	Activity insights.
CommSessionVoiceApiSupport	Voice API.
CommSessionSendTextSupport	Send text.
CommSessionNotificationFilteringSupport	Notification filtering.
CommSessionUnreadCoredumpSupport	Fetching unread coredumps.
CommSessionWeatherAppSupport	Weather app.
CommSessionRemindersAppSupport	Reminders app.
CommSessionWorkoutAppSupport	Workout app.
CommSessionSmoothFwInstallProgressSupport	Smooth firmware install progress.
CommSessionImagingSupport	Phone serves images through the imaging endpoint.
CommSessionSettingsSyncSupport	Phone syncs settings through BlobDB.
CommSessionNotificationWindowStateSupport	Phone tracks which notification the watch is displaying.
CommSessionOutOfRange	First value past the defined capabilities.

CommSessionType

enum CommSessionType

Kind of session.

Enumerator
CommSessionTypeInvalid	Not a valid (or no longer connected) session.
CommSessionTypeSystem	Session with the Pebble mobile app.
CommSessionTypeApp	Session with a third party phone app.
NumCommSessions	Number of valid session types.

Function Documentation

comm_session_get_by_type()

CommSession * comm_session_get_by_type

(

CommSessionType

type

)

Get a session by kind.

Parameters

type	Session type. CommSessionTypeApp returns the session of the currently running app.

Returns

The session, or NULL if it does not exist.

comm_session_get_capabilities()

CommSessionCapability comm_session_get_capabilities

(

CommSession *

session

)

Get the capabilities of a session.

Parameters

session

Session to query.

Returns

Capability bitset, 0 if session is not valid.

comm_session_get_current_app_session()

CommSession * comm_session_get_current_app_session

(

void

)

Get the session serving the currently running watch app.

For apps that use PebbleKit JS this is the system session. The session may disconnect at any time after this returns.

Returns

The app session, or NULL if not connected.

comm_session_get_system_session()

CommSession * comm_session_get_system_session

(

void

)

Get the system (Pebble mobile app) session.

The session may disconnect at any time after this returns.

Returns

The system session, or NULL if not connected.

comm_session_get_type()

CommSessionType comm_session_get_type

(

const CommSession *

session

)

Get the kind of a session.

Parameters

session

Session to query.

Returns

Session type, or CommSessionTypeInvalid if session is not valid.

comm_session_get_uuid()

const Uuid * comm_session_get_uuid

(

const CommSession *

session

)

Get the UUID of the app a session is connected to.

The caller must hold bt_lock() and stop using the pointer once it is released.

Parameters

session

Session to query.

Returns

App UUID, or NULL if not known.

comm_session_has_capability()

bool comm_session_has_capability	(	CommSession *	session,
		CommSessionCapability	capability
	)

Check whether a session supports a capability.

Parameters

session	Session to check.
capability	Capability to look for.

Returns

True if session is valid and supports capability.

comm_session_init()

void comm_session_init

(

void

)

Initialize the session module.

Called when Bluetooth is enabled; no session may exist yet.

comm_session_is_system()

bool comm_session_is_system

(

CommSession *

session

)

Check whether a session is the system session.

Parameters

session

Session to check.

Returns

True if session is a valid system session.

comm_session_reset()

void comm_session_reset

(

CommSession *

session

)

Reset a session by asking its transport to close and reopen it.

With iAP this closes every session on the transport, since a single iAP session cannot be closed on its own.

Parameters

session

Session to reset.

comm_session_sanitize_app_session()

void comm_session_sanitize_app_session

(

CommSession **

session_in_out

)

Restrict a session to the one the current app is permitted to use.

A NULL session selects the current app session. A non-NULL one is kept only if it is the current app session.

Parameters

[in,out]

session_in_out

Session to sanitize; set to NULL if not permitted or if no session is available.

comm_session_send_data()

bool comm_session_send_data	(	CommSession *	session,
		uint16_t	endpoint_id,
		const uint8_t *	data,
		size_t	length,
		uint32_t	timeout_ms
	)

Send a complete Pebble Protocol message.

Wraps comm_session_send_buffer_begin_write(), comm_session_send_buffer_write() and comm_session_send_buffer_end_write(), so the message is copied to the kernel heap. Use comm_session_send_queue_add_job() to avoid the copy, or the send buffer functions to build a message piecemeal. bt_lock() must not be held.

Parameters

session	Destination session.
endpoint_id	Pebble Protocol endpoint ID.
data	Message payload.
length	Length of data in bytes.
timeout_ms	Maximum time to block waiting for room in the send buffer.

Returns

True if the message was queued for sending.

comm_session_set_responsiveness()

void comm_session_set_responsiveness	(	CommSession *	session,
		enum pbl_bt_consumer	consumer,
		enum pbl_bt_response_time_state	state,
		uint16_t	max_period_secs
	)

Request a connection response time for a session.

Same as comm_session_set_responsiveness_ext() without a granted callback.

Parameters

session	Session whose connection to adjust; ignored if not valid.
consumer	Consumer making the request.
state	Requested response time state.
max_period_secs	Maximum time to stay in state before falling back to the slowest response time.

comm_session_set_responsiveness_ext()

void comm_session_set_responsiveness_ext	(	CommSession *	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_handler
	)

Request a connection response time for a session, with a granted callback.

Forwarded to the transport, which applies it through the Bluetooth connection manager.

Parameters

session	Session whose connection to adjust; ignored if not valid.
consumer	Consumer making the request.
state	Requested response time state.
max_period_secs	Maximum time to stay in state before falling back to the slowest response time.
granted_handler	Called on KernelMain once a state at least as responsive as state is entered. May be NULL.