ble/lwp3: add AdvertisementData

This adds data structures for parsing manufacturer-specific advertising
data according the the LWP3 protocol.

Author: dlech

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added ``ble.lpw3.AdvertisementData`` class.
+- Added ``ble.lpw3.BootloaderAdvertisementData`` class.
+
 ## [1.0.0-alpha.21] - 2022-01-12
 
 ### Changed

pybricksdev/ble/lwp3/__init__.py

@@ -1,12 +1,14 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021 The Pybricks Authors
+# Copyright (c) 2021-2022 The Pybricks Authors
 
 """This module and its submodules are used for Bluetooth Low Energy
 communications with devices that provide the LEGO Wireless Protocol v3.
 """
 
 from enum import IntEnum
 
+from .bytecodes import Capabilities, HubKind, LastNetwork, Status, Version
+
 # LEGO Wireless Protocol v3 is defined at:
 # https://lego.github.io/lego-ble-wireless-protocol-docs/
 
@@ -105,3 +107,91 @@ class BootloaderError(IntEnum):
 
     UNKNOWN_COMMAND = 0x05
     """The command was not recognized."""
+
+
+class BootloaderAdvertisementData:
+    """
+    The 6-byte manufacturer-specific advertisement data sent when a hub in
+    bootloader mode is advertising.
+    """
+
+    def __init__(self, data: bytes) -> None:
+        if len(data) != 6:
+            raise ValueError("expecting 6 bytes of data")
+
+        self._data = data
+
+    def __bytes__(self) -> bytes:
+        return self._data
+
+    @property
+    def version(self) -> Version:
+        """
+        Gets the bootloader software version.
+        """
+        return Version(int.from_bytes(self._data[:4], "little"))
+
+    @property
+    def hub_kind(self) -> HubKind:
+        """
+        Gets the hub type identifier.
+        """
+        return HubKind(self._data[4])
+
+    @property
+    def hub_capabilities(self) -> Capabilities:
+        """
+        Gets the hub capability flags.
+        """
+        return Capabilities(self._data[5])
+
+
+class AdvertisementData:
+    """
+    The 6-byte manufacturer-specific advertisement data sent when a hub running
+    official LEGO firmware is advertising.
+    """
+
+    def __init__(self, data: bytes) -> None:
+        if len(data) != 6:
+            raise ValueError("expecting 6 bytes of data")
+
+        self._data = data
+
+    def __bytes__(self) -> bytes:
+        return self._data
+
+    @property
+    def is_button_pressed(self) -> bool:
+        """
+        Gets the state of the button on the hub.
+        """
+        return bool(self._data[0])
+
+    @property
+    def hub_kind(self) -> HubKind:
+        """
+        Gets the hub type identifier.
+        """
+        return HubKind(self._data[1])
+
+    @property
+    def hub_capabilities(self) -> Capabilities:
+        """
+        Gets the hub capability flags.
+        """
+        return Capabilities(self._data[2])
+
+    @property
+    def last_network(self) -> LastNetwork:
+        """
+        Gets the ID of the last network the hub was connected to.
+        """
+        return LastNetwork(self._data[3])
+
+    @property
+    def status(self) -> Status:
+        """
+        Gets the status of the advertising hub.
+        """
+        return Status(self._data[4])

tests/ble/test_lwp3.py

@@ -3,7 +3,10 @@
     LWP3_BOOTLOADER_SERVICE_UUID,
     LWP3_HUB_CHARACTERISTIC_UUID,
     LWP3_HUB_SERVICE_UUID,
+    AdvertisementData,
+    BootloaderAdvertisementData,
 )
+from pybricksdev.ble.lwp3.bytecodes import Capabilities, HubKind, LastNetwork, Status
 
 
 def test_lwp3_hub_service_uuid():
@@ -20,3 +23,19 @@ def test_lwp3_bootloader_service_uuid():
 
 def test_lwp3_bootloader_characteristic_uuid():
     assert LWP3_BOOTLOADER_CHARACTERISTIC_UUID == "00001626-1212-efde-1623-785feabcd123"
+
+
+def test_bootloader_advertisement_data():
+    adv = BootloaderAdvertisementData(b"\x78\x56\x34\x12\x40\x02")
+    assert adv.version == 0x12345678
+    assert adv.hub_kind == HubKind.BOOST
+    assert adv.hub_capabilities == Capabilities.PERIPHERAL
+
+
+def test_advertisement_data():
+    adv = AdvertisementData(b"\x01\x40\x02\x05\x03\x00")
+    assert adv.is_button_pressed
+    assert adv.hub_kind == HubKind.BOOST
+    assert adv.hub_capabilities == Capabilities.PERIPHERAL
+    assert adv.last_network == LastNetwork(5)
+    assert adv.status == Status.PERIPHERAL | Status.CENTRAL