Connections

Connections to the Pebble are represented by the PebbleConnection, connecting via a transport.

Event loops

Having connected to a Pebble, the event loop must be run for anything interesting to occur. There are three ways to do this:

Fire and forget

PebbleConnection.run_async() will spawn a new thread (called PebbleConnection) and run the event loop on that thread. It handles expected exceptions and will emit log messages at the WARNING level. It will also call PebbleConnection.fetch_watch_info() on your behalf before returning. This is the easiest option, and often what you want.

pebble.connect()
pebble.run_async()

Blocking forever

PebbleConnection.run_sync() will run the event loop in place. It will handle exceptions for you and emit logs at the WARNING level. It will not return until the watch disconnects or an error occurs.

pebble.connect()
pebble.run_sync()

Do it manually

Calling PebbleConnection.pump_reader() will (synchronously) cause exactly one message to be read from the transport, which may or may not be a message from the Pebble. It will fire all of the events for that message, and then return. It doesn’t return anything.

pebble.connect()
while pebble.connected:
    pebble.pump_reader()

Note

pump_reader may throw exceptions on receiving malformed messages; these should probably be handled.

API

class libpebble2.communication.FirmwareVersion(major, minor, patch, suffix)

Represents a firmware version, in the format major.minor.patch-suffix.

major

Alias for field number 0

minor

Alias for field number 1

patch

Alias for field number 2

suffix

Alias for field number 3

class libpebble2.communication.PebbleConnection(transport, log_protocol_level=None, log_packet_level=None)

PebbleConnection represents the connection to a pebble; all interaction with a pebble goes through it.

Parameters:
  • transport (BaseTransport) – The underlying transport layer to communicate with the Pebble.
  • log_packet_level (int) – If not None, the log level at which to log decoded messages sent and received.
  • log_protocol_level (int) – int If not None, the log level at which to log raw messages sent and received.
connect()

Synchronously initialises a connection to the Pebble. Once it returns, a valid connection will be open.

connected
Returns:True if currently connected to a Pebble; otherwise False.
fetch_watch_info()

This method should be called before accessing watch_info, firmware_version or watch_platform. Blocks until it has fetched the required information.

firmware_version

Provides information on the connected Pebble, including its firmware version, language, capabilities, etc.

Return type:WatchVersionResponse
get_endpoint_queue(endpoint)

Returns a BaseEventQueue from which messages to the given endpoint can be read.

This is useful if you need to make sure that you receive all messages to an endpoint, without risking dropping some due to time in between read_from_endpoint() calls.

Parameters:endpoint (PacketType) – The endpoint to read from
Returns:
pump_reader()

Synchronously reads one message from the watch, blocking until a message is available. All events caused by the message read will be processed before this method returns.

Note

You usually don’t need to invoke this method manually; instead, see run_sync() and run_async().

read_from_endpoint(endpoint, timeout=10)

Blocking read from an endpoint. Will block until a message is received, or it times out. Also see get_endpoint_queue() if you are considering calling this in a loop.

Warning

Avoid calling this method from an endpoint callback; doing so is likely to lead to deadlock.

Note

If you’re reading a response to a message you just sent, send_and_read() might be more appropriate.

Parameters:
  • endpoint (PacketType) – The endpoint to read from.
  • timeout – The maximum time to wait before raising TimeoutError.
Returns:

The message read from the endpoint; of the same type as passed to endpoint.

read_transport_message(origin, message_type, timeout=10)

Blocking read of a transport message that does not indicate a message from the Pebble. Will block until a message is received, or it times out.

Warning

Avoid calling this method from an endpoint callback; doing so is likely to lead to deadlock.

Parameters:
  • origin – The type of MessageTarget that triggers the message.
  • message_type – The class of the message to read from the transport.
  • timeout – The maximum time to wait before raising TimeoutError.
Returns:

The object read from the transport; of the same type as passed to message_type.

register_endpoint(endpoint, handler)

Register a handler for a message received from the Pebble.

Parameters:
  • endpoint (PacketType) – The type of PebblePacket that is being listened for.
  • handler (callable) – A callback to be called when a message is received.
Returns:

A handle that can be passed to unregister_endpoint() to remove the handler.

register_raw_inbound_handler(handler)

Register a handler for all outgoing messages received from the Pebble. Transport framing is not included. In most cases you should not need to use this; consider using register_endpoint() instead.

Parameters:handler (callable) – A callback to be called when any message is received.
Returns:A handle that can be passed to unregister_endpoint() to remove the handler.
register_raw_outbound_handler(handler)

Register a handler for all outgoing messages to be sent to the Pebble. Transport framing is not included.

Parameters:handler (callable) – A callback to be called when any message is received.
Returns:A handle that can be passed to unregister_endpoint() to remove the handler.
register_transport_endpoint(origin, message_type, handler)

Register a handler for a message received from a transport that does not indicate a message from the connected Pebble.

Parameters:
  • origin – The type of MessageTarget that triggers the message
  • message_type – The class of the message that is expected.
  • handler (callable) – A callback to be called when a message is received.
Returns:

A handle that can be passed to unregister_endpoint() to remove the handler.

run_async()

Spawns a new thread that runs the message loop until the Pebble disconnects. run_async will call fetch_watch_info() on your behalf, and block until it receives a response.

run_sync()

Runs the message loop until the Pebble disconnects. This method will block until the watch disconnects or a fatal error occurs.

For alternatives that don’t block forever, see pump_reader() and run_async().

send_and_read(packet, endpoint, timeout=10)

Sends a packet, then returns the next response received from that endpoint. This method sets up a listener before it actually sends the message, avoiding a potential race.

Warning

Avoid calling this method from an endpoint callback; doing so is likely to lead to deadlock.

Parameters:
  • packet (PebblePacket) – The message to send.
  • endpoint (PacketType) – The endpoint to read from
  • timeout – The maximum time to wait before raising TimeoutError.
Returns:

The message read from the endpoint; of the same type as passed to endpoint.

send_packet(packet)

Sends a message to the Pebble.

Parameters:packet (PebblePacket) – The message to send.
send_raw(message)

Sends a raw binary message to the Pebble. No processing will be applied, but any transport framing should be omitted.

Parameters:message (bytes) – The message to send to the pebble.
unregister_endpoint(handle)

Removes a handler registered by register_transport_endpoint(), register_endpoint(), register_raw_outbound_handler() or register_raw_inbound_handler().

Parameters:handle – A handle returned by the register call to be undone.
watch_info

Returns information on the connected Pebble, including its firmware version, language, capabilities, etc.

Return type:WatchVersionResponse
watch_model
Returns:The model of the watch.
Return type:Model
watch_platform

A string naming the platform of the watch (‘aplite’, ‘basalt’, ‘chalk’, or ‘unknown’).

Return type:str