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; otherwiseFalse
.
-
fetch_watch_info
()¶ This method should be called before accessing
watch_info
,firmware_version
orwatch_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 givenendpoint
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()
andrun_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
.- origin – The type of
-
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.- endpoint (PacketType) – The type of
-
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.- origin – The type of
-
run_async
()¶ Spawns a new thread that runs the message loop until the Pebble disconnects.
run_async
will callfetch_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()
andrun_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()
orregister_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