libpebble2 0.0.29__py3-none-any.whl

libpebble2/__init__.py

@@ -0,0 +1,8 @@
+__author__ = 'katharine'
+from .version import __version__, __version_info__
+
+import logging
+
+from .exceptions import *
+
+logging.getLogger('libpebble2').addHandler(logging.NullHandler())

libpebble2/communication/__init__.py

@@ -0,0 +1,389 @@
+from __future__ import absolute_import
+
+__author__ = 'katharine'
+
+from binascii import hexlify
+from collections import namedtuple
+from enum import Enum
+import logging
+import struct
+import threading
+
+from .transports import BaseTransport, MessageTargetWatch
+from libpebble2.events.threaded import ThreadedEventHandler
+from libpebble2.exceptions import PacketDecodeError, ConnectionError, IncompleteMessage
+from libpebble2.protocol.base import PebblePacket, PacketType
+from libpebble2.protocol.system import (PhoneAppVersion, AppVersionResponse, WatchVersion, WatchVersionRequest,
+                                        WatchVersionResponse, WatchModel, ModelRequest, Model)
+from libpebble2.util.hardware import PebbleHardware
+
+logger = logging.getLogger("libpebble2.communication")
+
+_EventType = Enum('_EventType', ('Watch', 'Transport'))
+
+FirmwareVersion = namedtuple('FirmwareVersion', ('major', 'minor', 'patch', 'suffix'))
+"""
+Represents a firmware version, in the format ``major.minor.patch-suffix``.
+"""
+
+
+class PebbleConnection(object):
+    """
+    PebbleConnection represents the connection to a pebble; all interaction with a pebble goes through it.
+
+    :param transport: The underlying transport layer to communicate with the Pebble.
+    :type transport: BaseTransport
+    :param log_packet_level: If not None, the log level at which to log decoded messages sent and received.
+    :type log_packet_level: int
+    :param log_protocol_level: int If not None, the log level at which to log raw messages sent and received.
+    :type log_protocol_level: int
+    """
+    def __init__(self, transport, log_protocol_level=None, log_packet_level=None):
+        assert isinstance(transport, BaseTransport)
+        self.transport = transport
+        self.pending_bytes = b''
+        self.event_handler = ThreadedEventHandler()
+        self._register_internal_handlers()
+        self._watch_info = None
+        self._watch_model = None
+        self.log_protocol_level = log_protocol_level
+        self.log_packet_level = log_packet_level
+
+    def connect(self):
+        """
+        Synchronously initialises a connection to the Pebble. Once it returns, a valid connection will be open.
+        """
+        self.transport.connect()
+
+    @property
+    def connected(self):
+        """
+        :return: ``True`` if currently connected to a Pebble; otherwise ``False``.
+        """
+        return self.transport.connected
+
+    def pump_reader(self):
+        """
+        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 :meth:`run_sync` and :meth:`run_async`.
+        """
+        origin, message = self.transport.read_packet()
+        if isinstance(origin, MessageTargetWatch):
+            self._handle_watch_message(message)
+        else:
+            self._broadcast_transport_message(origin, message)
+
+    def run_sync(self):
+        """
+        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 :meth:`pump_reader` and :meth:`run_async`.
+        """
+        while self.connected:
+            try:
+                self.pump_reader()
+            except PacketDecodeError as e:
+                logger.warning("Packet decode failed: %s", e)
+            except ConnectionError:
+                break
+
+    def run_async(self):
+        """
+        Spawns a new thread that runs the message loop until the Pebble disconnects.
+        ``run_async`` will call :meth:`fetch_watch_info` on your behalf, and block until it receives a response.
+        """
+        thread = threading.Thread(target=self.run_sync)
+        thread.daemon = True
+        thread.name = "PebbleConnection"
+        thread.start()
+        self.fetch_watch_info()
+
+    def _handle_watch_message(self, message):
+        """
+        Processes a binary message received from the watch and broadcasts the relevant events.
+
+        :param message: A raw message from the watch, without any transport framing.
+        :type message: bytes
+        """
+        if self.log_protocol_level is not None:
+            logger.log(self.log_protocol_level, "<- %s", hexlify(message).decode())
+        message = self.pending_bytes + message
+
+        while len(message) >= 4:
+            try:
+                packet, length = PebblePacket.parse_message(message)
+            except IncompleteMessage:
+                self.pending_bytes = message
+                break
+            except:
+                # At this point we've failed to deconstruct the message via normal means, but we don't want to end
+                # up permanently desynced (because we wiped a partial message), nor do we want to get stuck (because
+                # we didn't wipe anything). We therefore parse the packet length manually and skip ahead that far.
+                # If the expected length is 0, we wipe everything to ensure forward motion (but we are quite probably
+                # screwed).
+                expected_length, = struct.unpack('!H', message[:2])
+                if expected_length == 0:
+                    self.pending_bytes = b''
+                else:
+                    self.pending_bytes = message[expected_length + 4:]
+                raise
+
+            self.event_handler.broadcast_event("raw_inbound", message[:length])
+            if self.log_packet_level is not None:
+                logger.log(self.log_packet_level, "<- %s", packet)
+            message = message[length:]
+            self.event_handler.broadcast_event((_EventType.Watch, type(packet)), packet)
+            if length == 0:
+                break
+        self.pending_bytes = message
+
+    def _broadcast_transport_message(self, origin, message):
+        """
+        Broadcasts an event originating from a transport that does not represent a message from the Pebble.
+
+        :param origin: The type of transport responsible for the message.
+        :type origin: .MessageTarget
+        :param message: The message from the transport
+        """
+        self.event_handler.broadcast_event((_EventType.Transport, type(origin), type(message)), message)
+
+    def register_transport_endpoint(self, origin, message_type, handler):
+        """
+        Register a handler for a message received from a transport that does not indicate a message from the connected
+        Pebble.
+
+        :param origin: The type of :class:`.MessageTarget` that triggers the message
+        :param message_type: The class of the message that is expected.
+        :param handler: A callback to be called when a message is received.
+        :type handler: callable
+        :return: A handle that can be passed to :meth:`unregister_endpoint` to remove the handler.
+        """
+        return self.event_handler.register_handler((_EventType.Transport, origin, message_type), handler)
+
+    def register_endpoint(self, endpoint, handler):
+        """
+        Register a handler for a message received from the Pebble.
+
+        :param endpoint: The type of :class:`.PebblePacket` that is being listened for.
+        :type endpoint: .PacketType
+        :param handler: A callback to be called when a message is received.
+        :type handler: callable
+        :return: A handle that can be passed to :meth:`unregister_endpoint` to remove the handler.
+        """
+        return self.event_handler.register_handler((_EventType.Watch, endpoint), handler)
+
+    def register_raw_outbound_handler(self, handler):
+        """
+        Register a handler for all outgoing messages to be sent to the Pebble. Transport framing is not included.
+
+        :param handler: A callback to be called when any message is received.
+        :type handler: callable
+        :return: A handle that can be passed to :meth:`unregister_endpoint` to remove the handler.
+        """
+        return self.event_handler.register_handler("raw_outbound", handler)
+
+    def register_raw_inbound_handler(self, 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 :meth:`register_endpoint` instead.
+
+        :param handler: A callback to be called when any message is received.
+        :type handler: callable
+        :return: A handle that can be passed to :meth:`unregister_endpoint` to remove the handler.
+        """
+        return self.event_handler.register_handler("raw_inbound", handler)
+
+    def unregister_endpoint(self, handle):
+        """
+        Removes a handler registered by :meth:`register_transport_endpoint`, :meth:`register_endpoint`,
+        :meth:`register_raw_outbound_handler` or :meth:`register_raw_inbound_handler`.
+
+        :param handle: A handle returned by the register call to be undone.
+        """
+        return self.event_handler.unregister_handler(handle)
+
+    def read_from_endpoint(self, endpoint, timeout=15):
+        """
+        Blocking read from an endpoint. Will block until a message is received, or it times out. Also see
+        :meth:`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, :meth:`send_and_read` might be more appropriate.
+
+        :param endpoint: The endpoint to read from.
+        :type endpoint: .PacketType
+        :param timeout: The maximum time to wait before raising :exc:`.TimeoutError`.
+        :return: The message read from the endpoint; of the same type as passed to ``endpoint``.
+        """
+        return self.event_handler.wait_for_event((_EventType.Watch, endpoint), timeout=timeout)
+
+    def get_endpoint_queue(self, endpoint):
+        """
+        Returns a :class:`.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 :meth:`read_from_endpoint` calls.
+
+        :param endpoint: The endpoint to read from
+        :type endpoint: .PacketType
+        :return:
+        """
+        return self.event_handler.queue_events((_EventType.Watch, endpoint))
+
+    def read_transport_message(self, origin, message_type, timeout=15):
+        """
+        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.
+
+        :param origin: The type of :class:`.MessageTarget` that triggers the message.
+        :param message_type: The class of the message to read from the transport.
+        :param timeout: The maximum time to wait before raising :exc:`.TimeoutError`.
+        :return: The object read from the transport; of the same type as passed to ``message_type``.
+        """
+        return self.event_handler.wait_for_event((_EventType.Transport, origin, message_type), timeout=timeout)
+
+    def send_packet(self, packet):
+        """
+        Sends a message to the Pebble.
+
+        :param packet: The message to send.
+        :type packet: .PebblePacket
+        """
+        if self.log_packet_level:
+            logger.log(self.log_packet_level, "-> %s", packet)
+        serialised = packet.serialise_packet()
+        self.event_handler.broadcast_event("raw_outbound", serialised)
+        self.send_raw(serialised)
+
+    def send_and_read(self, packet, endpoint, timeout=15):
+        """
+        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.
+
+        :param packet: The message to send.
+        :type packet: .PebblePacket
+        :param endpoint: The endpoint to read from
+        :type endpoint: .PacketType
+        :param timeout: The maximum time to wait before raising :exc:`.TimeoutError`.
+        :return: The message read from the endpoint; of the same type as passed to ``endpoint``.
+        """
+        queue = self.get_endpoint_queue(endpoint)
+        self.send_packet(packet)
+        try:
+            return queue.get(timeout=timeout)
+        finally:
+            queue.close()
+
+    def send_raw(self, message):
+        """
+        Sends a raw binary message to the Pebble. No processing will be applied, but any transport framing should be
+        omitted.
+
+        :param message: The message to send to the pebble.
+        :type message: bytes
+        """
+        if self.log_protocol_level:
+            logger.log(self.log_protocol_level, "-> %s", hexlify(message).decode())
+        self.transport.send_packet(message)
+
+    def _register_internal_handlers(self):
+        if self.transport.must_initialise:
+            self.register_endpoint(PhoneAppVersion, self._app_version_response)
+
+    def _app_version_response(self, packet):
+        packet = PhoneAppVersion(message=AppVersionResponse(
+            protocol_version=0xFFFFFFFF,
+            session_caps=0x80000000,
+            platform_flags=50,
+            response_version=2,
+            major_version=3,
+            minor_version=0,
+            bugfix_version=0,
+            protocol_caps=0xFFFFFFFFFFFFFFFF
+        ))
+        self.send_packet(packet)
+
+    def fetch_watch_info(self):
+        """
+        This method should be called before accessing :attr:`watch_info`, :attr:`firmware_version`
+        or :attr:`watch_platform`. Blocks until it has fetched the required information.
+        """
+        self._watch_info = self.send_and_read(WatchVersion(data=WatchVersionRequest()), WatchVersion).data
+
+    @property
+    def watch_info(self):
+        """
+        Returns information on the connected Pebble, including its firmware version, language, capabilities, etc.
+
+        .. note:
+           This is a blocking call if :meth:`fetch_watch_info` has not yet been called, which could lead to deadlock
+           if called in an endpoint callback.
+
+        :rtype: .WatchVersionResponse
+        """
+        if self._watch_info is None:
+            self.fetch_watch_info()
+        return self._watch_info
+
+    @property
+    def firmware_version(self):
+        """
+        Provides information on the connected Pebble, including its firmware version, language, capabilities, etc.
+
+        .. note:
+           This is a blocking call if :meth:`fetch_watch_info` has not yet been called, which could lead to deadlock
+           if called in an endpoint callback.
+
+        :rtype: .WatchVersionResponse
+        """
+        version = self.watch_info.running.version_tag[1:]
+        parts = version.split('-', 1)
+        points = [int(x) for x in parts[0].split('.')]
+        while len(points) < 3:
+            points.append(0)
+        if len(parts) == 2:
+            suffix = parts[1]
+        else:
+            suffix = ''
+        return FirmwareVersion(*(points + [suffix]))
+
+    @property
+    def watch_model(self):
+        """
+
+        :return: The model of the watch.
+        :rtype: ~libpebble2.protocol.system.Model
+        """
+        if self._watch_model is None:
+            info_bytes = self.send_and_read(WatchModel(data=ModelRequest()), WatchModel).data.data
+            if len(info_bytes) == 4:
+                self._watch_model, = struct.unpack('>I', info_bytes)
+            else:
+                self._watch_model = Model.Unknown
+        return self._watch_model
+
+    @property
+    def watch_platform(self):
+        """
+        A string naming the platform of the watch ('aplite', 'basalt', 'chalk', or 'unknown').
+
+        .. note:
+           This is a blocking call if :meth:`fetch_watch_info` has not yet been called, which could lead to deadlock
+           if called in an endpoint callback.
+
+        :rtype: str
+        """
+        return PebbleHardware.hardware_platform(self.watch_info.running.hardware_platform)

libpebble2/communication/transports/__init__.py

@@ -0,0 +1,64 @@
+__author__ = 'katharine'
+
+from six import with_metaclass
+
+from abc import ABCMeta, abstractmethod, abstractproperty
+
+
+class MessageTarget(object):
+    def __repr__(self):
+        return type(self).__name__ + "()"
+
+
+class MessageTargetWatch(MessageTarget):
+    pass
+
+
+class BaseTransport(with_metaclass(ABCMeta)):
+    @abstractproperty
+    def must_initialise(self):
+        """
+        :return: ``True`` if libpebble2 is responsible for negotiating the connection; otherwise ``False``.
+        """
+        pass
+
+    @abstractproperty
+    def connected(self):
+        """
+        :return: ``True`` if the transport is currently connected; otherwise ``False``.
+        """
+        pass
+
+    @abstractmethod
+    def connect(self):
+        """
+        Synchronously connect to the Pebble. Once this method returns, libpebble2 should be able to safely send
+        messages to the connected Pebble.
+
+        Ordinarily, this method should only be called by :class:`.PebbleConnection`.
+        """
+        pass
+
+    @abstractmethod
+    def read_packet(self):
+        """
+        Synchronously read a message. This message could be from the Pebble(in which case it will be a
+        :class:`PebblePacket`), or it could be from the transport, in which case the result is transport-defined.
+        The origin of the result is indicated by the returned :class:`MessageTarget`.
+
+        :return: (:class:`MessageTarget`, :class:`libpebble2.protocol.base.PebblePacket`)
+        """
+        pass
+
+    @abstractmethod
+    def send_packet(self, message, target=MessageTargetWatch()):
+        """
+        Send a message. This message could be to the Pebble (in which case it must be a :class:`PebblePacket`), or
+        to the transport (in which case the message type is transport-defined).
+
+        :param message: Message to send.
+        :type message: PebblePacket
+        :param target: Target for the message
+        :type target: MessageTarget
+        """
+        pass

libpebble2/communication/transports/pulse.py

@@ -0,0 +1,108 @@
+from __future__ import absolute_import
+__author__ = 'Liam McLoughlin'
+
+import time
+import struct
+
+try:
+    from pebble import pulse2
+except ImportError:
+    pass
+
+from . import BaseTransport, MessageTargetWatch
+from libpebble2.exceptions import ConnectionError, PebbleError
+
+
+class PULSETransport(BaseTransport):
+    """
+    Represents a direct connection to a physical/virtual Pebble uses the PULSEv2 interface.
+    This transport expects to be given a PULSE2 Link object.
+
+    :param connection: A PULSE2 Link object to tunnel Pebble Protocol over.
+    :type link: pulse2.link.Link
+    """
+    must_initialise = True
+
+    PPOPULSE_PORT = 0x3e22
+
+    OPCODE_PROTOCOL_DATA = 0x1
+    OPCODE_PROTOCOL_OPEN = 0x2
+    OPCODE_PROTOCOL_CLOSE = 0x3
+
+    def __init__(self, link):
+        self.link = link
+        self.connection = None
+        self.buffer = b''
+
+    @staticmethod
+    def _chunks(list_items, chunk_length):
+        for i in range(0, len(list_items), chunk_length):
+            yield list_items[i:i+chunk_length]
+
+    def connect(self):
+        self.connection = self.link.open_socket('reliable', self.PPOPULSE_PORT)
+        if not self.connection:
+            raise ConnectionError('Failed to open PPoPULSE socket')
+
+        self._send_with_opcode(self.OPCODE_PROTOCOL_OPEN)
+        start_time = time.time()
+        while time.time() < start_time + 10.0:
+            opcode, _ = self._recv_with_opcode()
+            if opcode == self.OPCODE_PROTOCOL_OPEN:
+                break
+        else:
+            raise ConnectionError('Timeout waiting for PPoPULSE open ACK')
+
+    def disconnect(self):
+        if self.connected:
+            try:
+                self._send_with_opcode(self.OPCODE_PROTOCOL_CLOSE)
+            except pulse2.exceptions.SocketClosed:
+                pass
+            self.connection.close()
+            self.connection = None
+
+    @property
+    def connected(self):
+        return self.connection is not None
+
+    def read_packet(self):
+        while self.connected:
+            if len(self.buffer) >= 2:
+                length, = struct.unpack('!H', self.buffer[:2])
+                length += 4
+
+                if len(self.buffer) >= length:
+                    msg_data = self.buffer[:length]
+                    self.buffer = self.buffer[length:]
+
+                    return MessageTargetWatch(), msg_data
+
+            opcode, data = self._recv_with_opcode()
+            if opcode == self.OPCODE_PROTOCOL_DATA:
+                self.buffer += data
+
+    def send_packet(self, message, target=MessageTargetWatch()):
+        assert isinstance(target, MessageTargetWatch)
+        for chunk in self._chunks(message, self.connection.mtu - 1):
+            self._send_with_opcode(self.OPCODE_PROTOCOL_DATA, chunk)
+
+    def _recv_with_opcode(self):
+        try:
+            packet = self.connection.receive(block=True)
+        except (AttributeError, pulse2.exceptions.SocketClosed):
+            self.connection = None
+            raise ConnectionError('PULSE transport closed')
+
+        assert len(packet) >= 1
+        opcode = packet[0]
+        data = packet[1:]
+        return opcode, data
+
+    def _send_with_opcode(self, opcode, body=None):
+        assert self.connected
+
+        data = bytes([opcode])
+        if body:
+            data += body
+        self.connection.send(data)

libpebble2/communication/transports/qemu/__init__.py

@@ -0,0 +1,113 @@
+from __future__ import absolute_import
+__author__ = 'katharine'
+
+import socket
+
+from .. import BaseTransport, MessageTarget, MessageTargetWatch
+from .protocol import QemuPacket, QemuInboundPacket, QemuSPP, QemuRawPacket, HEADER_SIGNATURE, FOOTER_SIGNATURE
+from libpebble2.exceptions import ConnectionError
+from libpebble2.protocol.base.types import PacketDecodeError
+
+
+class MessageTargetQemu(MessageTarget):
+    """
+    Indicates that a message is directed at QEMU, rather than the firmware running on it. If ``raw`` is ``True``,
+    the message should be a binary message (without framing), with QEMU protocol indicated by ``protocol``.
+    Otherwise, the message should be a :class:`.PebblePacket` from :mod:`.protocol`.
+
+    :param protocol: The protocol to send to, if sending a ``raw`` message
+    :type protocol: :any:`int`
+    :param raw: If ``True``, the message is pre-serialised and will be sent as-is after adding framing.
+    :type raw: :any:`bool`
+    """
+    def __init__(self, protocol=None, raw=False):
+        self.protocol = protocol
+        self.raw = raw
+
+
+class QemuTransport(BaseTransport):
+    """
+    Represents a connection to a `Pebble QEMU <https://github.com/pebble/qemu>`_ instance.
+
+    :param host: The host on which the QEMU instance is running.
+    :type host: str
+    :param port: The port on which the QEMU instance has exposed its Pebble QEMU Protocol port.
+    :type port: int
+    """
+    #: Number of bytes read from the socket at a time.
+    BUFFER_SIZE = 2048
+    must_initialise = True
+
+    def __init__(self, host='127.0.0.1', port=12344, socket = None):
+        self.host = host
+        self.port = port
+        self.socket = socket
+        self.assembled_data = b''
+        self._connected = socket is not None
+
+    def connect(self):
+        try:
+            self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.socket.connect((self.host, self.port))
+        except socket.error as e:
+            raise ConnectionError(str(e))
+        self._connected = True
+
+    @property
+    def connected(self):
+        return self.socket is not None and self._connected
+
+    def read_packet(self):
+        while True:
+            if len(self.assembled_data) > 0:
+                try:
+                    packet, length = QemuInboundPacket.parse(self.assembled_data)
+                except PacketDecodeError:
+                    pass
+                else:
+                    self.assembled_data = self.assembled_data[length:]
+                    if packet.signature == HEADER_SIGNATURE and packet.footer == FOOTER_SIGNATURE:
+                        if isinstance(packet.data, QemuSPP):
+                            return MessageTargetWatch(), packet.data.payload
+                        else:
+                            return MessageTargetQemu(packet.protocol), packet.data
+                    else:
+                        raise PacketDecodeError("QemuTransport: signature mismatch ({:x} = {:x}, {:x} = {:x})".format(
+                            packet.signature,
+                            HEADER_SIGNATURE,
+                            packet.footer,
+                            FOOTER_SIGNATURE,
+                        ))
+            try:
+                received = self.socket.recv(self.BUFFER_SIZE)
+                if len(received) == 0:
+                    self._connected = False
+                    raise ConnectionError("Disconnected.")
+                self.assembled_data += received
+            except socket.error:
+                self._connected = False
+                raise ConnectionError("Disconnected.")
+
+    def send_packet(self, message, target=MessageTargetWatch()):
+        try:
+            if isinstance(target, MessageTargetWatch):
+                start_idx = 0
+                bytes_left = len(message)
+                while bytes_left:
+                    bytes_to_send = bytes_left
+                    if bytes_to_send > self.BUFFER_SIZE:
+                        bytes_to_send = self.BUFFER_SIZE
+                    chunk = message[start_idx:start_idx+bytes_to_send]
+                    self.socket.send(QemuPacket(data=QemuSPP(payload=chunk)).serialise())
+                    bytes_left -= bytes_to_send
+                    start_idx += bytes_to_send
+            elif isinstance(target, MessageTargetQemu):
+                if not target.raw:
+                    self.socket.send(QemuPacket(data=message).serialise())
+                else:
+                    self.socket.send(QemuRawPacket(protocol=target.protocol, data=message).serialise())
+            else:
+                assert False
+        except socket.error as e:
+            self._connected = False
+            raise ConnectionError(str(e))