Add function for pairing a Plus-device

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## Ongoing updates
 
-- PR [405](https://github.com/plugwise/python-plugwise-usb/pull/405): Fix recent Ruff errors
+- PR [409](https://github.com/plugwise/python-plugwise-usb/pull/409): Fix recent Ruff errors
+- PR [405](https://github.com/plugwise/python-plugwise-usb/pull/405): Try adding plus-device pairing (untested!!)
 
 ## v0.47.2 - 2026-01-29
 

plugwise_usb/__init__.py

@@ -266,6 +266,10 @@ async def connect(self, port: str | None = None) -> None:
             self._port,
         )
 
+    async def plus_pair_request(self, mac: str) -> bool:
+        """Send a pair request to a Plus device."""
+        return await self._controller.pair_plus_device(mac)
+
     @raise_not_connected
     async def initialize(self, create_root_cache_folder: bool = False) -> None:
         """Initialize connection to USB-Stick."""

plugwise_usb/connection/__init__.py

@@ -8,19 +8,22 @@
 
 from ..api import StickEvent
 from ..constants import UTF8
-from ..exceptions import NodeError, StickError
-from ..helpers.util import version_to_model
+from ..exceptions import MessageError, NodeError, StickError
+from ..helpers.util import validate_mac, version_to_model
 from ..messages.requests import (
+    CirclePlusConnectRequest,
     NodeInfoRequest,
     NodePingRequest,
     PlugwiseRequest,
     StickInitRequest,
+    StickNetworkInfoRequest,
 )
 from ..messages.responses import (
     NodeInfoResponse,
     NodePingResponse,
     PlugwiseResponse,
     StickInitResponse,
+    StickInitShortResponse,
 )
 from .manager import StickConnectionManager
 from .queue import StickQueue
@@ -170,7 +173,9 @@ async def initialize_stick(self) -> None:
 
         try:
             request = StickInitRequest(self.send)
-            init_response: StickInitResponse | None = await request.send()
+            init_response: (
+                StickInitResponse | StickInitShortResponse | None
+            ) = await request.send()
         except StickError as err:
             raise StickError(
                 "No response from USB-Stick to initialization request."
@@ -186,10 +191,11 @@ async def initialize_stick(self) -> None:
         self._mac_stick = init_response.mac_decoded
         self.stick_name = f"Stick {self._mac_stick[-5:]}"
         self._network_online = init_response.network_online
+        if self._network_online:
+            # Replace first 2 characters by 00 for mac of circle+ node
+            self._mac_nc = init_response.mac_network_controller
+            self._network_id = init_response.network_id
 
-        # Replace first 2 characters by 00 for mac of circle+ node
-        self._mac_nc = init_response.mac_network_controller
-        self._network_id = init_response.network_id
         self._is_initialized = True
 
         # Add Stick NodeInfoRequest
@@ -199,8 +205,58 @@ async def initialize_stick(self) -> None:
             hardware, _ = version_to_model(node_info.hardware)
             self._hw_stick = hardware
 
-        if not self._network_online:
-            raise StickError("Zigbee network connection to Circle+ is down.")
+    async def pair_plus_device(self, mac: str) -> bool:
+        """Pair Plus-device to Plugwise Stick.
+
+        According to https://roheve.wordpress.com/author/roheve/page/2/
+        The pairing process should look like:
+        0001 - 0002 (- 0003): StickNetworkInfoRequest - StickNetworkInfoResponse - (PlugwiseQueryCirclePlusEndResponse - @SevenW),
+        000A - 0011: StickInitRequest - StickInitResponse,
+        0004 - 0005: CirclePlusConnectRequest - CirclePlusConnectResponse,
+        the Plus-device will then send a NodeRejoinResponse (0061).
+
+        Todo(?): Does this need repeating until pairing is successful?
+        """
+        _LOGGER.debug("Pair Plus-device with mac: %s", mac)
+        if not validate_mac(mac):
+            raise NodeError(f"Pairing failed: MAC {mac} invalid")
+
+        # Collect network info
+        try:
+            request = StickNetworkInfoRequest(self.send, None)
+            info_response = await request.send()
+        except MessageError as exc:
+            raise NodeError(f"Pairing failed: {exc}") from exc
+        if info_response is None:
+            raise NodeError(
+                "Pairing failed, StickNetworkInfoResponse is None"
+            ) from None
+        _LOGGER.debug("HOI NetworkInfoRequest done")
+
+        # Init Stick
+        try:
+            await self.initialize_stick()
+        except StickError as exc:
+            raise NodeError(
+                f"Pairing failed, failed to initialize Stick: {exc}"
+            ) from exc
+        _LOGGER.debug("HOI Init done")
+
+        try:
+            request = CirclePlusConnectRequest(self.send, bytes(mac, UTF8))
+            response = await request.send()
+        except MessageError as exc:
+            raise NodeError(f"Pairing failed: {exc}") from exc
+        if response is None:
+            raise NodeError(
+                "Pairing failed, CirclePlusConnectResponse is None"
+            ) from None
+        if response.allowed.value != 1:
+            raise NodeError("Pairing failed, not allowed")
+
+        _LOGGER.debug("HOI PlusConnectRequest done")
+
+        return True
 
     async def get_node_details(
         self, mac: str, ping_first: bool

plugwise_usb/messages/requests.py

@@ -38,6 +38,7 @@
     NodeSpecificResponse,
     PlugwiseResponse,
     StickInitResponse,
+    StickInitShortResponse,
     StickNetworkInfoResponse,
     StickResponse,
     StickResponseType,
@@ -514,7 +515,7 @@ class StickInitRequest(PlugwiseRequest):
     """Initialize USB-Stick.
 
     Supported protocols : 1.0, 2.0
-    Response message    : StickInitResponse
+    Response message    : StickInitResponse or StickInitShortResponse
     """
 
     _identifier = b"000A"
@@ -528,17 +529,17 @@ def __init__(
         super().__init__(send_fn, None)
         self._max_retries = 1
 
-    async def send(self) -> StickInitResponse | None:
+    async def send(self) -> StickInitResponse | StickInitShortResponse | None:
         """Send request."""
         if self._send_fn is None:
             raise MessageError("Send function missing")
         result = await self._send_request()
-        if isinstance(result, StickInitResponse):
+        if isinstance(result, (StickInitResponse, StickInitShortResponse)):
             return result
         if result is None:
             return None
         raise MessageError(
-            f"Invalid response message. Received {result.__class__.__name__}, expected StickInitResponse"
+            f"Invalid response message. Received {result.__class__.__name__}, expected StickInitResponse/StickInitShortResponse"
         )
 
 

plugwise_usb/messages/responses.py

@@ -409,8 +409,45 @@ def __init__(self, timestamp: datetime | None = None) -> None:
         self._params += [self.image_timestamp]
 
 
-class StickInitResponse(PlugwiseResponse):
-    """Returns the configuration and status of the USB-Stick.
+class StickInitShortResponse(PlugwiseResponse):
+    """Returns the configuration and status of the USB-Stick - no network.
+
+    Supported protocols : 1.0, 2.0
+    Response to request : StickInitRequest
+    """
+
+    def __init__(self) -> None:
+        """Initialize StickInitShortResponse message object."""
+        super().__init__(b"0011")
+        self._unknown1 = Int(0, length=2)
+        self._network_online = Int(0, length=2)
+        self._params += [
+            self._unknown1,
+            self._network_online,
+        ]
+
+    @property
+    def mac_network_controller(self) -> str | None:
+        """Return the mac of the network controller (Circle+)."""
+        return None
+
+    @property
+    def network_id(self) -> int | None:
+        """Return network ID."""
+        return None
+
+    @property
+    def network_online(self) -> bool:
+        """Return state of network."""
+        return self._network_online.value == 1
+
+    def __repr__(self) -> str:
+        """Convert request into writable str."""
+        return f"{super().__repr__()[:-1]}, network_controller={self.mac_network_controller}, network_online={self.network_online})"
+
+
+class StickInitResponse(StickInitShortResponse):
+    """Returns the configuration and status of the USB-Stick - network online.
 
     Optional:
     - circle_plus_mac
@@ -423,15 +460,11 @@ class StickInitResponse(PlugwiseResponse):
 
     def __init__(self) -> None:
         """Initialize StickInitResponse message object."""
-        super().__init__(b"0011")
-        self._unknown1 = Int(0, length=2)
-        self._network_online = Int(0, length=2)
+        super().__init__()
         self._mac_nc = String(None, length=16)
         self._network_id = Int(0, 4, False)
         self._unknown2 = Int(0, length=2)
         self._params += [
-            self._unknown1,
-            self._network_online,
             self._mac_nc,
             self._network_id,
             self._unknown2,
@@ -448,15 +481,6 @@ def network_id(self) -> int:
         """Return network ID."""
         return self._network_id.value
 
-    @property
-    def network_online(self) -> bool:
-        """Return state of network."""
-        return self._network_online.value == 1
-
-    def __repr__(self) -> str:
-        """Convert request into writable str."""
-        return f"{super().__repr__()[:-1]}, network_controller={self.mac_network_controller}, network_online={self.network_online})"
-
 
 class CirclePowerUsageResponse(PlugwiseResponse):
     """Returns power usage as impulse counters for several different time frames.
@@ -992,8 +1016,15 @@ def get_message_object(  # noqa: C901 PLR0911 PLR0912
         return NodePingResponse()
     if identifier == b"0010":
         return NodeImageValidationResponse()
+
+    # 0011 has two formats
     if identifier == b"0011":
-        return StickInitResponse()
+        if length == 36:
+            return StickInitShortResponse()
+        if length == 58:
+            return StickInitResponse()
+        return None
+
     if identifier == b"0013":
         return CirclePowerUsageResponse()
     if identifier == b"0015":

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "plugwise_usb"
-version         = "0.47.2"
+version         = "0.48.0a2"
 license         = "MIT"
 keywords        = ["home", "automation", "plugwise", "module", "usb"]
 classifiers     = [

tests/stick_pair_data.py

@@ -0,0 +1,57 @@
+"""Plus-device pairing test data."""
+
+RESPONSE_MESSAGES = {
+    b"\x05\x05\x03\x030001CAAB\r\n": (
+        "Stick network info request",
+        b"000000C1",  # Success ack
+        b"0002"  # response msg_id
+        + b"0123456789012345"  # stick-mac
+        + b"0F"  # channel
+        + b"FFFFFFFFFFFFFFFF"
+        + b"0698765432101234"  # 06 + plus-device mac
+        + b"FFFFFFFFFFFFFFFF"
+        + b"0698765432101234"  # 06 + plus-device mac
+        + b"1606"  # pan_id
+        + b"01",  # index
+    ),
+    b"\x05\x05\x03\x03000AB43C\r\n": (
+        "STICK INIT",
+        b"000000C1",  # Success ack
+        b"0011"  # msg_id
+        + b"0123456789012345"  # stick mac
+        + b"00"  # unknown1
+        + b"00",  # network_is_offline
+    ),
+    b"\x05\x05\x03\x0300040000000000000000000098765432101234\r\n": (
+        "Pair request of plus-device 0098765432101234",
+        b"000000C1",  # Success ack
+        b"0005"  # response msg_id
+        + b"00"  # existing
+        + b"01",  # allowed
+    ),
+    b"\x05\x05\x03\x0300230123456789012345A0EC\r\n": (
+        "Node Info of stick 0123456789012345",
+        b"000000C1",  # Success ack
+        b"0024"  # msg_id
+        + b"0123456789012345"  # mac
+        + b"00000000"  # datetime
+        + b"00000000"  # log address 0
+        + b"00"  # relay
+        + b"80"  # hz
+        + b"653907008512"  # hw_ver
+        + b"4E0843A9"  # fw_ver
+        + b"00",  # node_type (Stick)
+    ),
+}
+
+SECOND_RESPONSE_MESSAGES = {
+    b"\x05\x05\x03\x03000D55555555555555555E46\r\n": (
+        "ping reply for 5555555555555555",
+        b"000000C1",  # Success ack
+        b"000E"
+        + b"5555555555555555"  # mac
+        + b"44"  # rssi in
+        + b"33"  # rssi out
+        + b"0055",  # roundtrip
+    )
+}