ramses-rf 0.22.40__py3-none-any.whl → 0.51.1__py3-none-any.whl

ramses_rf/version.py

@@ -1,10 +1,4 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-"""RAMSES RF - a RAMSES-II protocol decoder & analyser.
+"""RAMSES RF - a RAMSES-II protocol decoder & analyser (application layer)."""
 
-The RAMSES-II system (controllers, zones, devices).
-"""
-
-__version__ = "0.22.40"
+__version__ = "0.51.1"
 VERSION = __version__

ramses_rf-0.51.1.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: ramses_rf
+Version: 0.51.1
+Summary: A stateful RAMSES-II protocol decoder & analyser.
+Project-URL: Homepage, https://github.com/ramses-rf/ramses_rf
+Project-URL: Bug Tracker, https://github.com/ramses-rf/ramses_rf/issues
+Project-URL: Wiki, https://github.com/ramses-rf/ramses_rf/wiki
+Author-email: David Bonnes <zxdavb@bonnes.me>, Egbert Broerse <dcc2@ebroerse.nl>
+Maintainer-email: Egbert Broerse <dcc2@ebroerse.nl>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: airios,chronotherm,climarad,evohome,hometronics,honeywell,itho,nuaire,orcon,ramses,resideo,round thermostat,sundial,vasco
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Requires-Dist: colorlog>=6.9.0
+Requires-Dist: paho-mqtt>=2.1.0
+Requires-Dist: pyserial-asyncio-fast>=0.16
+Requires-Dist: voluptuous>=0.15.2
+Description-Content-Type: text/markdown
+
+![Linting](https://github.com/ramses-rf/ramses_rf/actions/workflows/check-lint.yml/badge.svg)
+![Typing](https://github.com/ramses-rf/ramses_rf/actions/workflows/check-type.yml/badge.svg)
+![Testing](https://github.com/ramses-rf/ramses_rf/actions/workflows/check-test.yml/badge.svg)
+
+## Overview
+
+**ramses_rf** is a Python client library/CLI utility used to interface with some Honeywell-compatible HVAC & CH/DHW systems that use 868MHz RF, such as:
+ - (Heat) **evohome**, **Sundial**, **Hometronic**, **Chronotherm**
+ - (HVAC) **Itho**, **Orcon**, **Nuaire**, **Vasco**, **ClimaRad**
+
+It requires a USB-to-RF device, either a Honeywell HGI80 (somewhat rare, expensive) or something running the [evofw3](https://github.com/ghoti57/evofw3) firmware, such as the one from [here](https://indalo-tech.onlineweb.shop/) or your own ESP32-S3-WROOM-1 N16R8 with a CC1100 transponder.
+
+It does four things:
+ - decodes RAMSES II-compatible packets and converts them into useful JSON
+ - builds a picture (schema, config & state) of evohome-compatible CH/DHW systems - either passively (by eavesdropping), or actively (probing)
+ - allows you to send commands to CH/DHW and HVAC systems, or monitor for state changes
+ - allows you to emulate some hardware devices
+
+> [!WARNING]
+> This library is not affiliated with Honeywell, Airios nor any final manufacturer. The developers take no responsibility for anything that may happen to your devices because of this library.
+
+For CH/DHW, the simplest way to know if it will work with your system is to identify the box connected to your boiler/HVAC appliance as one of:
+ - **R8810A**: OpenTherm Bridge
+ - **BDR91A**: Wireless Relay (also BDR91T)
+ - **HC60NG**: Wireless Relay (older hardware)
+
+Other systems may well work, such as some Itho Daalderop HVAC systems, use this protocol, YMMV.
+
+It includes a CLI and can be used as a standalone tool, but also is used as a client library by:
+ - [ramses_cc](https://github.com/ramses-rf/ramses_cc), a Home Assistant integration
+ - [evohome-Listener](https://github.com/smar000/evohome-Listener), an MQTT gateway
+
+## Installation
+
+To use the `ramses_cc` Integration in Home Assistant, just install `Ramses RF` from HACS. It will take care of installing this library. See the [`Ramses_cc wiki`](https://github.com/ramses-rf/ramses_cc/wiki/1.-Installation) for details.
+
+### Ramses_rf CLI
+
+To install the `ramses_rf` command line client:
+```
+git clone https://github.com/ramses-rf/ramses_rf
+cd ramses_rf
+pip install -r requirements.txt
+pip install -e .
+```
+
+The CLI is called ``client.py`` and is included in the code root.
+It has options to monitor and parse Ramses-II traffic to screen or a log file, and to parse a file containing Ramses-II messages to the screen.
+See the [client.py CLI wiki page](https://github.com/ramses-rf/ramses_rf/wiki/The-client.py-command-line) for instructions.
+
+For code development, some more setup is required. Please follow the steps in our [Developer's Resource](README-developers.md)

ramses_rf-0.51.1.dist-info/RECORD

@@ -0,0 +1,55 @@
+ramses_cli/__init__.py,sha256=uvGzWqOf4avvgzxJNSLFWEelIWqSZ-AeLAZzg5x58bc,397
+ramses_cli/client.py,sha256=QOmPKjCQHHOZwLBWEB438zabI9k38-ELRwisLvbvxSU,19782
+ramses_cli/debug.py,sha256=vgR0lOHoYjWarN948dI617WZZGNuqHbeq6Tc16Da7b4,608
+ramses_cli/discovery.py,sha256=81XbmpNiCpUHVZBwo2g1eRwyJG-wZhpSsc44G3hHlFA,12972
+ramses_cli/utils/cat_slow.py,sha256=AhUpM5gnegCitNKU-JGHn-DrRzSi-49ZR1Qw6lxe_t8,607
+ramses_cli/utils/convert.py,sha256=D_YiCyX5na9pgC-_NhBlW9N1dgRKUK-uLtLBfofjzZM,1804
+ramses_rf/__init__.py,sha256=zONFBiRdf07cPTSxzr2V3t-b3CGokZjT9SGit4JUKRA,1055
+ramses_rf/binding_fsm.py,sha256=uZAOl3i19KCXqqlaLJWkEqMMP7NJBhVPW3xTikQD1fY,25996
+ramses_rf/const.py,sha256=DSo4ROWDlOlcdXQdrpAF17vOsTLgmf2u0UppjYa5qJI,5390
+ramses_rf/database.py,sha256=6k5MLtK5Lplz8THfluQoQU-eniUkqSwEUMvVW7VyGhI,9880
+ramses_rf/dispatcher.py,sha256=b7Cg1vAP6FECC6GeZsJ0BZVqy-ZjJTXhZquzcwE87WI,11221
+ramses_rf/entity_base.py,sha256=BYHatdUuz_BSQsUlzsC52qPMLZw7h_M6UTb3A6PBPH4,39473
+ramses_rf/exceptions.py,sha256=rzVZDcYxFH7BjUAQ3U1fHWtgBpwk3BgjX1TO1L1iM8c,2538
+ramses_rf/gateway.py,sha256=vqoTEb6QXnwaIMa66oed_3LEVvlyQ3flsAAMliEEvVA,20921
+ramses_rf/helpers.py,sha256=LcrVLqnF2qJWqXrC7UXKOQE8khCT3OhoTpZ_ZVBjw3A,4249
+ramses_rf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ramses_rf/schemas.py,sha256=mYOUZOH5OIDNBxRM2vd8POzDWEEmLhxh5UtqjTpFNek,13287
+ramses_rf/version.py,sha256=F1An7mWrZUZVyxhkApeCPk3xFAau34Pc6hzHu6fqvk8,125
+ramses_rf/device/__init__.py,sha256=sUbH5dhbYFXSoM_TPFRutpRutBRpup7_cQ9smPtDTy8,4858
+ramses_rf/device/base.py,sha256=V2YzRhdxrTqfHYrCBq6pJsYdTgAx8gGzfdo8pkbeEo8,17450
+ramses_rf/device/heat.py,sha256=2sCsggySVcuTzyXDmgWy76QbhlU5MQWSejy3zgI5BDE,54242
+ramses_rf/device/hvac.py,sha256=5K0FsTTu506OByd_oMoNJ7FePvjfQaxlT4eehXUAEC8,23642
+ramses_rf/system/__init__.py,sha256=uZLKio3gLlBzePa2aDQ1nxkcp1YXOGrn6iHTG8LiNIw,711
+ramses_rf/system/faultlog.py,sha256=GdGmVGT3137KsTlV_nhccgIFEmYu6DFsLTn4S-8JSok,12799
+ramses_rf/system/heat.py,sha256=dARzcwL39JGwOBJkKJBi0_i7rr8IvY-qaNmWmgJLpdo,39223
+ramses_rf/system/schedule.py,sha256=Ts6tdZPTQLV5NkgwA73tPa5QUsnZNIIuYoKC-8VsXDk,18808
+ramses_rf/system/zones.py,sha256=QwRtSHY5c-Amcs6JD16uQcimOsEQTZcMm1dW-pqEFqM,36041
+ramses_tx/__init__.py,sha256=wJ7Ntx-0AyJwYwSG8OrFMpxDLXs6GbECbCcYhq98mSA,3162
+ramses_tx/address.py,sha256=2640K3sXzogZtd4-tSxwVjYEEXcFE1DgmtvZlTMM5mE,8444
+ramses_tx/command.py,sha256=g5PBf9JnuygveyaYrqIuV8wIn7grm0evuqKy9Cp1oaA,53844
+ramses_tx/const.py,sha256=B2db8Yxks-lMNsQAK1DoPkF1gvwNIacLmKwXuApUyLk,30221
+ramses_tx/exceptions.py,sha256=FJSU9YkvpKjs3yeTqUJX1o3TPFSe_B01gRGIh9b3PNc,2632
+ramses_tx/fingerprints.py,sha256=nfftA1E62HQnb-eLt2EqjEi_la0DAoT0wt-PtTMie0s,11974
+ramses_tx/frame.py,sha256=9lUVh8gAMXNRAolfFw2WuWANjn24AWkmscuM9Tm5imE,22036
+ramses_tx/gateway.py,sha256=FE5MWA1eIE9JATA2vRoBSQ8fAzqp7TqAm3Ds3k1KnKE,11267
+ramses_tx/helpers.py,sha256=WJ5JtAT9iyhkcW53AIPNPuvGEUWFwLumZc-mCG2kIOc,32236
+ramses_tx/logger.py,sha256=7vUpcfOFMW95juMWDx5dhUOqV8DTsindZ-Qz2aCmEoA,11073
+ramses_tx/message.py,sha256=J1wvVkLPJQr2ffKCUQYSWwLPzRTZBC0zUU5W9DkN3hU,13190
+ramses_tx/opentherm.py,sha256=58PXz9l5x8Ou6Fm3y-R_UnGHCYahoi2RKIDdYStUMzk,42378
+ramses_tx/packet.py,sha256=NGunaGCkEjhTp9t4mARK5e7kbqT-Z_JKCH7ibMYMJXU,7357
+ramses_tx/parsers.py,sha256=R-oFcRUe7HPsm9n4196hFUD1tULbFdKBAWo8HvzGyjw,109218
+ramses_tx/protocol.py,sha256=ifj3qwcQivjQDaQUwM94xp-U8Pmef6zwSH7mav8DLWA,28867
+ramses_tx/protocol_fsm.py,sha256=YhHkTqbl8w-myimsOjV50uIFgg9HiApwPU7xA_jg5nU,26827
+ramses_tx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ramses_tx/ramses.py,sha256=yPSdhxGRYQ9AuTWoKs9Cb3YQn5YnEKZVs7BYkQFmqCw,52037
+ramses_tx/schemas.py,sha256=h2AcArVROy1_C4n6F0Crj4e-2BxXxH74xogFlc6nKHI,12769
+ramses_tx/transport.py,sha256=28CtiqNltcJhLr4VIHCW9uCohWXrvxmx6ySUSIuRQ9c,52892
+ramses_tx/typed_dicts.py,sha256=4ZT50M-Cuwy2ljAIorwoxEJ9c737xUHrUxX9wTh79xE,10834
+ramses_tx/typing.py,sha256=eF2SlPWhNhEFQj6WX2AhTXiyRQVXYnFutiepllYl2rI,5042
+ramses_tx/version.py,sha256=PyOf332e4cHU33OjhzPo9s_NpQJZFU36TeBDdC0fF3M,123
+ramses_rf-0.51.1.dist-info/METADATA,sha256=cJUJq-2CnXserwY3AwjXZrRf_xUe-xRPLtAm069GCU8,3906
+ramses_rf-0.51.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ramses_rf-0.51.1.dist-info/entry_points.txt,sha256=NnyK29baOCNg8DinPYiZ368h7MTH7bgTW26z2A1NeIE,50
+ramses_rf-0.51.1.dist-info/licenses/LICENSE,sha256=-Kc35W7l1UkdiQ4314_yVWv7vDDrg7IrJfMLUiq6Nfs,1074
+ramses_rf-0.51.1.dist-info/RECORD,,

{ramses_rf-0.22.40.dist-info → ramses_rf-0.51.1.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.37.1)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

ramses_rf-0.51.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+client = ramses_cli.client:main

{ramses_rf-0.22.40.dist-info → ramses_rf-0.51.1.dist-info/licenses}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 David Bonnes
+Copyright (c) 2021-2025 David Bonnes
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

ramses_tx/__init__.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""RAMSES RF - a RAMSES-II protocol decoder & analyser."""
+
+from __future__ import annotations
+
+import asyncio
+from functools import partial
+from typing import TYPE_CHECKING, Any
+
+from .address import (
+    ALL_DEV_ADDR,
+    ALL_DEVICE_ID,
+    NON_DEV_ADDR,
+    NON_DEVICE_ID,
+    Address,
+    is_valid_dev_id,
+)
+from .command import CODE_API_MAP, Command
+from .const import (
+    DEV_ROLE_MAP,
+    DEV_TYPE_MAP,
+    F9,
+    FA,
+    FC,
+    FF,
+    SZ_ACTIVE_HGI,
+    SZ_DEVICE_ROLE,
+    SZ_DOMAIN_ID,
+    SZ_ZONE_CLASS,
+    SZ_ZONE_IDX,
+    SZ_ZONE_MASK,
+    SZ_ZONE_TYPE,
+    ZON_ROLE_MAP,
+    DevRole,
+    DevType,
+    IndexT,
+    Priority,
+    VerbT,
+    ZoneRole,
+)
+from .gateway import Engine
+from .logger import set_pkt_logging
+from .message import Message
+from .packet import PKT_LOGGER, Packet
+from .protocol import PortProtocol, ReadProtocol, protocol_factory
+from .ramses import CODES_BY_DEV_SLUG, CODES_SCHEMA
+from .schemas import SZ_SERIAL_PORT, DeviceIdT, DeviceListT
+from .transport import (
+    FileTransport,
+    PortTransport,
+    RamsesTransportT,
+    is_hgi80,
+    transport_factory,
+)
+from .typing import QosParams
+from .version import VERSION
+
+from .const import (  # isort: skip
+    I_,
+    RP,
+    RQ,
+    W_,
+    Code,
+)
+
+
+__all__ = [
+    "VERSION",
+    "Engine",
+    #
+    "SZ_ACTIVE_HGI",
+    "SZ_DEVICE_ROLE",
+    "SZ_DOMAIN_ID",
+    "SZ_SERIAL_PORT",
+    "SZ_ZONE_CLASS",
+    "SZ_ZONE_IDX",
+    "SZ_ZONE_MASK",
+    "SZ_ZONE_TYPE",
+    #
+    "ALL_DEV_ADDR",
+    "ALL_DEVICE_ID",
+    "NON_DEV_ADDR",
+    "NON_DEVICE_ID",
+    #
+    "CODE_API_MAP",
+    "CODES_BY_DEV_SLUG",  # shouldn't export this
+    "CODES_SCHEMA",
+    "DEV_ROLE_MAP",
+    "DEV_TYPE_MAP",
+    "ZON_ROLE_MAP",
+    #
+    "I_",
+    "RP",
+    "RQ",
+    "W_",
+    "F9",
+    "FA",
+    "FC",
+    "FF",
+    #
+    "DeviceIdT",
+    "DeviceListT",
+    "DevRole",
+    "DevType",
+    "IndexT",
+    "VerbT",
+    "ZoneRole",
+    #
+    "Address",
+    "Code",
+    "Command",
+    "Message",
+    "Packet",
+    "Priority",
+    "QosParams",
+    #
+    "PortProtocol",
+    "ReadProtocol",
+    "RamsesProtocolT",
+    "extract_known_hgi_id",
+    "protocol_factory",
+    #
+    "FileTransport",
+    "PortTransport",
+    "RamsesTransportT",
+    "is_hgi80",
+    "transport_factory",
+    #
+    "is_valid_dev_id",
+    "set_pkt_logging_config",
+]
+
+
+if TYPE_CHECKING:
+    from logging import Logger
+
+
+async def set_pkt_logging_config(**config: Any) -> Logger:
+    """
+    Set up ramses packet logging to a file or port.
+    Must runs async in executor to prevent HA blocking call opening packet log file (issue #200)
+
+    :param config: if file_name is included, opens packet_log file
+    :return: a logging.Logger
+    """
+    loop = asyncio.get_running_loop()
+    await loop.run_in_executor(None, partial(set_pkt_logging, PKT_LOGGER, **config))
+    return PKT_LOGGER
+
+
+def extract_known_hgi_id(
+    include_list: DeviceListT,
+    /,
+    *,
+    disable_warnings: bool = False,
+    strick_checking: bool = False,
+) -> DeviceIdT | None:
+    return PortProtocol._extract_known_hgi_id(
+        include_list, disable_warnings=disable_warnings, strick_checking=strick_checking
+    )

{ramses_rf/protocol → ramses_tx}/address.py

@@ -1,39 +1,44 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
 """RAMSES RF - a RAMSES-II protocol decoder & analyser."""
+
 from __future__ import annotations
 
 from functools import lru_cache
-from typing import Dict
+from typing import TYPE_CHECKING, Final
+
+from . import exceptions as exc
+from .const import DEV_TYPE_MAP as _DEV_TYPE_MAP, DEVICE_ID_REGEX, DevType
+from .schemas import DeviceIdT
 
-from .const import DEV_TYPE
-from .const import DEV_TYPE_MAP as _DEV_TYPE_MAP
-from .const import DEVICE_ID_REGEX, __dev_mode__
-from .exceptions import InvalidAddrSetError
-from .helpers import typechecked
+if TYPE_CHECKING:
+    from .schemas import DeviceIdT
 
-DEV_MODE = __dev_mode__ and False
-DEV_HVAC = True
 
-DEVICE_LOOKUP: Dict[str, str] = {
+DEVICE_LOOKUP: dict[str, str] = {
     k: _DEV_TYPE_MAP._hex(k)
     for k in _DEV_TYPE_MAP.SLUGS
-    if k not in (DEV_TYPE.JIM, DEV_TYPE.JST)
+    if k not in (DevType.JIM, DevType.JST)
 }
 DEVICE_LOOKUP |= {"NUL": "63", "---": "--"}
-DEV_TYPE_MAP: Dict[str, str] = {v: k for k, v in DEVICE_LOOKUP.items()}
+DEV_TYPE_MAP: dict[str, str] = {v: k for k, v in DEVICE_LOOKUP.items()}
 
 
-HGI_DEVICE_ID = "18:000730"  # default type and address of HGI, 18:013393
-NON_DEVICE_ID = "--:------"
-NUL_DEVICE_ID = "63:262142"  # FFFFFE - send here if not bound?
+HGI_DEVICE_ID: DeviceIdT = "18:000730"  # type: ignore[assignment]
+NON_DEVICE_ID: DeviceIdT = "--:------"  # type: ignore[assignment]
+ALL_DEVICE_ID: DeviceIdT = "63:262142"  # type: ignore[assignment]  # aka 'FFFFFE'
+
+#
+# NOTE: All debug flags should be False for deployment to end-users
+_DBG_DISABLE_STRICT_CHECKING: Final[bool] = False  # a convenience for the test suite
+_DBG_DISABLE_DEV_HVAC = False
 
 
 class Address:
     """The device Address class."""
 
-    def __init__(self, device_id) -> None:
+    _SLUG = None
+
+    def __init__(self, device_id: DeviceIdT) -> None:
         """Create an address from a valid device id."""
 
         # if device_id is None:
@@ -52,30 +57,29 @@ class Address:
     def __str__(self) -> str:
         return self._friendly(self.id).strip()
 
-    def __eq__(self, other) -> bool:
+    def __eq__(self, other: object) -> bool:
         if not hasattr(other, "id"):  # can compare Address with Device
             return NotImplemented
-        return self.id == other.id
+        return self.id == other.id  # type: ignore[no-any-return]
 
     @property
     def hex_id(self) -> str:
         if self._hex_id is not None:
             return self._hex_id
-        self._hex_id = self.convert_to_hex(self.id)
+        self._hex_id = self.convert_to_hex(self.id)  # type: ignore[unreachable]
         return self._hex_id
 
     @staticmethod
     def is_valid(value: str) -> bool:  # Union[str, Match[str], None]:
-
         # if value[:2] not in DEV_TYPE_MAP:
         #     return False
 
         return isinstance(value, str) and (
             value == NON_DEVICE_ID or DEVICE_ID_REGEX.ANY.match(value)
-        )  # type: ignore[return-value]
+        )
 
     @classmethod
-    def _friendly(cls, device_id: str) -> str:
+    def _friendly(cls, device_id: DeviceIdT) -> str:
         """Convert (say) '01:145038' to 'CTL:145038'."""
 
         if not cls.is_valid(device_id):
@@ -90,18 +94,18 @@ class Address:
         """Convert (say) '06368E' to '01:145038' (or 'CTL:145038')."""
 
         if device_hex == "FFFFFE":  # aka '63:262142'
-            return ">null dev<" if friendly_id else NUL_DEVICE_ID
+            return ">null dev<" if friendly_id else ALL_DEVICE_ID
 
         if not device_hex.strip():  # aka '--:------'
             return f"{'':10}" if friendly_id else NON_DEVICE_ID
 
         _tmp = int(device_hex, 16)
-        device_id = f"{(_tmp & 0xFC0000) >> 18:02d}:{_tmp & 0x03FFFF:06d}"
+        device_id: DeviceIdT = f"{(_tmp & 0xFC0000) >> 18:02d}:{_tmp & 0x03FFFF:06d}"  # type: ignore[assignment]
 
         return cls._friendly(device_id) if friendly_id else device_id
 
     @classmethod
-    def convert_to_hex(cls, device_id: str) -> str:
+    def convert_to_hex(cls, device_id: DeviceIdT) -> str:
         """Convert (say) '01:145038' (or 'CTL:145038') to '06368E'."""
 
         if not cls.is_valid(device_id):
@@ -116,25 +120,24 @@ class Address:
         return f"{(int(dev_type) << 18) + int(device_id[-6:]):0>6X}"  # no preceding 0x
 
     # @classmethod
-    # def from_hex(cls, hex_id: str):
+    # def from_hex(cls, hex_id: DeviceIdT):
     #     """Call as: d = Address.from_hex('06368E')."""
 
     #     return cls(cls.convert_from_hex(hex_id))
 
 
 @lru_cache(maxsize=256)
-def id_to_address(device_id) -> Address:
+def id_to_address(device_id: DeviceIdT) -> Address:
     """Factory method to cache & return device Address from device ID."""
     return Address(device_id=device_id)
 
 
-HGI_DEV_ADDR = Address(HGI_DEVICE_ID)
-NON_DEV_ADDR = Address(NON_DEVICE_ID)
-NUL_DEV_ADDR = Address(NUL_DEVICE_ID)
+HGI_DEV_ADDR = Address(HGI_DEVICE_ID)  # 18:000730
+NON_DEV_ADDR = Address(NON_DEVICE_ID)  # --:------
+ALL_DEV_ADDR = Address(ALL_DEVICE_ID)  # 63:262142
 
 
-@typechecked
-def dev_id_to_hex_id(device_id: str) -> str:
+def dev_id_to_hex_id(device_id: DeviceIdT) -> str:
     """Convert (say) '01:145038' (or 'CTL:145038') to '06368E'."""
 
     if len(device_id) == 9:  # e.g. '01:123456'
@@ -149,14 +152,13 @@ def dev_id_to_hex_id(device_id: str) -> str:
     return f"{(int(dev_type) << 18) + int(device_id[-6:]):0>6X}"
 
 
-@typechecked
-def hex_id_to_dev_id(device_hex: str, friendly_id: bool = False) -> str:
+def hex_id_to_dev_id(device_hex: str, friendly_id: bool = False) -> DeviceIdT:
     """Convert (say) '06368E' to '01:145038' (or 'CTL:145038')."""
     if device_hex == "FFFFFE":  # aka '63:262142'
-        return "NUL:262142" if friendly_id else NUL_DEVICE_ID
+        return "NUL:262142" if friendly_id else ALL_DEVICE_ID  # type: ignore[return-value]
 
     if not device_hex.strip():  # aka '--:------'
-        return f"{'':10}" if friendly_id else NON_DEVICE_ID
+        return f"{'':10}" if friendly_id else NON_DEVICE_ID  # type: ignore[return-value]
 
     _tmp = int(device_hex, 16)
     dev_type = f"{(_tmp & 0xFC0000) >> 18:02d}"
@@ -164,65 +166,69 @@ def hex_id_to_dev_id(device_hex: str, friendly_id: bool = False) -> str:
     if friendly_id:
         dev_type = DEV_TYPE_MAP.get(dev_type, f"{dev_type:<3}")
 
-    return f"{dev_type}:{_tmp & 0x03FFFF:06d}"
+    return f"{dev_type}:{_tmp & 0x03FFFF:06d}"  # type: ignore[return-value]
 
 
 @lru_cache(maxsize=128)
-@typechecked
-def is_valid_dev_id(value: str, dev_class: str = None) -> bool:
+def is_valid_dev_id(value: str, dev_class: None | str = None) -> bool:
     """Return True if a device_id is valid."""
 
     if not isinstance(value, str) or not DEVICE_ID_REGEX.ANY.match(value):
         return False
 
-    if not DEV_HVAC and value.split(":", 1)[0] not in DEV_TYPE_MAP:
-        return False
+    return not _DBG_DISABLE_DEV_HVAC or value.split(":", 1)[0] in DEV_TYPE_MAP
 
-    # TODO: specify device type (for HVAC)
-    # elif dev_type is not None and dev_type != value.split(":", maxsplit=1)[0]:
-    #     raise TypeError(f"The device type does not match '{dev_type}'")
+    # if _DBG_DISABLE_DEV_HVAC and value.split(":", 1)[0] not in DEV_TYPE_MAP:
+    #     return False
 
-    # assert value == hex_id_to_dev_id(dev_id_to_hex_id(value))
-    return True
+    # # TODO: specify device type (for HVAC)
+    # # elif dev_type is not None and dev_type != value.split(":", maxsplit=1)[0]:
+    # #     raise TypeError(f"The device type does not match '{dev_type}'")
+
+    # # assert value == hex_id_to_dev_id(dev_id_to_hex_id(value))
+    # return True
 
 
 @lru_cache(maxsize=256)  # there is definite benefit in caching this
-@typechecked
-def pkt_addrs(addr_fragment: str) -> tuple[Address, ...]:
+def pkt_addrs(addr_fragment: str) -> tuple[Address, Address, Address, Address, Address]:
     """Return the address fields from (e.g): '01:078710 --:------ 01:144246'.
 
+    returns: src_addr, dst_addr, addr_0, addr_1, addr_2
+
     Will raise an InvalidAddrSetError is the address fields are not valid.
     """
     # for debug: print(pkt_addrs.cache_info())
 
     try:
-        addrs = [id_to_address(addr_fragment[i : i + 9]) for i in range(0, 30, 10)]
-    except ValueError as exc:
-        raise InvalidAddrSetError(f"Invalid addr set: {addr_fragment}: {exc}")
+        addrs = tuple(id_to_address(addr_fragment[i : i + 9]) for i in range(0, 30, 10))
+    except ValueError as err:
+        raise exc.PacketAddrSetInvalid(
+            f"Invalid address set: {addr_fragment}: {err}"
+        ) from None
 
-    if (
+    if not _DBG_DISABLE_STRICT_CHECKING and (
         not (
             # .I --- 01:145038 --:------ 01:145038 1F09 003 FF073F # valid
             # .I --- 04:108173 --:------ 01:155341 2309 003 0001F4 # valid
-            addrs[0] not in (NON_DEV_ADDR, NUL_DEV_ADDR)
+            addrs[0] not in (NON_DEV_ADDR, ALL_DEV_ADDR)
             and addrs[1] == NON_DEV_ADDR
             and addrs[2] != NON_DEV_ADDR
         )
         and not (
-            # .I --- 32:206250 30:082155 --:------ 22F1 003 00020A # valid
+            # .I --- 32:206250 30:082155 --:------ 22F1 003 00020A         # valid
             # .I --- 29:151550 29:237552 --:------ 22F3 007 00023C03040000 # valid
-            addrs[0] not in (NON_DEV_ADDR, NUL_DEV_ADDR)
+            addrs[0] not in (NON_DEV_ADDR, ALL_DEV_ADDR)
             and addrs[1] not in (NON_DEV_ADDR, addrs[0])
             and addrs[2] == NON_DEV_ADDR
         )
         and not (
             # .I --- --:------ --:------ 10:105624 1FD4 003 00AAD4 # valid
-            addrs[2] not in (NON_DEV_ADDR, NUL_DEV_ADDR)
+            addrs[2] not in (NON_DEV_ADDR, ALL_DEV_ADDR)
             and addrs[0] == NON_DEV_ADDR
             and addrs[1] == NON_DEV_ADDR
         )
     ):
-        raise InvalidAddrSetError(f"Invalid addr set: {addr_fragment}")
+        raise exc.PacketAddrSetInvalid(f"Invalid address set: {addr_fragment}")
 
     device_addrs = list(filter(lambda a: a.type != "--", addrs))  # dex
     src_addr = device_addrs[0]
@@ -231,4 +237,4 @@ def pkt_addrs(addr_fragment: str) -> tuple[Address, ...]:
     if src_addr.id == dst_addr.id:  # incl. HGI_DEV_ADDR == HGI_DEV_ADDR
         src_addr = dst_addr
 
-    return src_addr, dst_addr, *addrs
+    return src_addr, dst_addr, addrs[0], addrs[1], addrs[2]