ramses-rf 0.52.4__py3-none-any.whl → 0.53.0__py3-none-any.whl

ramses_rf-0.53.0.dist-info/RECORD

@@ -0,0 +1,56 @@
+ramses_cli/__init__.py,sha256=uvGzWqOf4avvgzxJNSLFWEelIWqSZ-AeLAZzg5x58bc,397
+ramses_cli/client.py,sha256=OpsVfrdwChrBKia_yfAlI60ERMg7KAk3BWRpQyY3AWA,24762
+ramses_cli/debug.py,sha256=PLcz-3PjUiMVqtD_p6VqTA92eHUM58lOBFXh_qgQ_wA,576
+ramses_cli/discovery.py,sha256=MWoahBnAAVzfK2S7EDLsY2WYqN_ZK9L-lktrj8_4cb0,12978
+ramses_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ramses_cli/utils/cat_slow.py,sha256=AhUpM5gnegCitNKU-JGHn-DrRzSi-49ZR1Qw6lxe_t8,607
+ramses_cli/utils/convert.py,sha256=N3LxGe3_0pclijtmYW-ChqCuPTzbkoJA4XNAnoSnBk0,1806
+ramses_rf/__init__.py,sha256=AXsCK1Eh9FWeAI9D_zY_2KB0dqrTb9a5TNY1NvyQaDM,1271
+ramses_rf/binding_fsm.py,sha256=fuqvcc9YW-wr8SPH8zadpPqrHAvzl_eeWF-IBtlLppY,26632
+ramses_rf/const.py,sha256=L3z31CZ-xqno6oZp_h-67CB_5tDDqTwSWXsqRtsjMcs,5460
+ramses_rf/database.py,sha256=9nY1Wt2hjkBoDvDqopzPP3mPSH5-Q5XHPQuJnM2GHOw,21362
+ramses_rf/dispatcher.py,sha256=YjEU-QrBLo9IfoEhJo2ikg_FxOaMYoWvzelr9Vi-JZ8,11398
+ramses_rf/entity_base.py,sha256=6jsHQD_5buaV56rF6nTgzPKOLsXFGVly9EHAeigqeRg,59039
+ramses_rf/exceptions.py,sha256=mt_T7irqHSDKir6KLaf6oDglUIdrw0S40JbOrWJk5jc,3657
+ramses_rf/gateway.py,sha256=KWE7ZkHGPcZFp9eaKN9zXchkykMJLEx_k5Le99or5lQ,30064
+ramses_rf/helpers.py,sha256=TNk_QkpIOB3alOp1sqnA9LOzi4fuDCeapNlW3zTzNas,4250
+ramses_rf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ramses_rf/schemas.py,sha256=X1GAK3kttuLMiSCUDY2s-85fgBxPeU8xiDa6gJ1I5mY,13543
+ramses_rf/version.py,sha256=FlL_C6hC_miMOJxgK12zDE2CvaAfRA3KoLOL1_U-7QE,125
+ramses_rf/device/__init__.py,sha256=sUbH5dhbYFXSoM_TPFRutpRutBRpup7_cQ9smPtDTy8,4858
+ramses_rf/device/base.py,sha256=Tu5I8Lj7KplfRsIBQAYjilS6YPgTyjpU8qgKugMR2Jk,18281
+ramses_rf/device/heat.py,sha256=T-ENFzH1AEOd0m4-TgV-Qk0TnLNir_pYmyKlJtxy6NI,54538
+ramses_rf/device/hvac.py,sha256=vdgiPiLtCAGr7CVsGhQl6XuAFkyYdQSE_2AEdCmRl2I,48502
+ramses_rf/system/__init__.py,sha256=uZLKio3gLlBzePa2aDQ1nxkcp1YXOGrn6iHTG8LiNIw,711
+ramses_rf/system/faultlog.py,sha256=GdGmVGT3137KsTlV_nhccgIFEmYu6DFsLTn4S-8JSok,12799
+ramses_rf/system/heat.py,sha256=qQmzgmyHy2x87gHAstn0ee7ZVVOq-GJIfDxCrC-6gFU,39254
+ramses_rf/system/schedule.py,sha256=Ts6tdZPTQLV5NkgwA73tPa5QUsnZNIIuYoKC-8VsXDk,18808
+ramses_rf/system/zones.py,sha256=qMv7CuvZUKBNLpPRXgFA70NFRStgVJcw062h5mc3Y8Q,37034
+ramses_tx/__init__.py,sha256=sqnjM7pUGJDmec6igTtKViSB8FLX49B5gwhAmcY9ERY,3596
+ramses_tx/address.py,sha256=IuwUwZxykn3fP1UCRcv4D-zbTICBe2FJjDAFX5X6VoI,9108
+ramses_tx/command.py,sha256=drxmpdM4YgyPg4h0QIr1ouxK9QjfeLVgnFpDRox0CCY,125652
+ramses_tx/const.py,sha256=gmRQ59V5AJx2TlACL3tDSBy5VpvEOVbQfG0z7WjFCKE,32941
+ramses_tx/exceptions.py,sha256=FJSU9YkvpKjs3yeTqUJX1o3TPFSe_B01gRGIh9b3PNc,2632
+ramses_tx/fingerprints.py,sha256=nfftA1E62HQnb-eLt2EqjEi_la0DAoT0wt-PtTMie0s,11974
+ramses_tx/frame.py,sha256=GzNsXr15YLeidJYGtk_xPqsZQh4ehDDlUCtT6rTDhT8,22046
+ramses_tx/gateway.py,sha256=Fl6EqAUU2DnLOiA2_87sS7VPBEyxA1a_ICCmg55WMMA,11494
+ramses_tx/helpers.py,sha256=VIPSw0lrDrE3S92YchzeRo7G2AlQ_vE8OuYUF-rlpQw,33616
+ramses_tx/logger.py,sha256=1iKRHKUaqHqGd76CkE_6mCVR0sYODtxshRRwfY61fTk,10426
+ramses_tx/message.py,sha256=HUSNiBgGlnWEBeBqb4K28GcU5oB7RbS9a0JC2p9SGe4,13676
+ramses_tx/opentherm.py,sha256=58PXz9l5x8Ou6Fm3y-R_UnGHCYahoi2RKIDdYStUMzk,42378
+ramses_tx/packet.py,sha256=_nzuInS_WhdOI26SYvgsdDqIaDvVNguc2YDwdPOVCbU,7661
+ramses_tx/parsers.py,sha256=qQz8VOKaH26MUvo9AfUwhrnbH7VwXLxFc2gKJYvjXvY,148571
+ramses_tx/protocol.py,sha256=nBPKCD1tcGp_FiX0qhsY0XoGO_h87w5cYywBjSpum4w,33048
+ramses_tx/protocol_fsm.py,sha256=o9vLvlXor3LkPgsY1zii5P1R01GzYLf_PECDdoxtC24,27520
+ramses_tx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ramses_tx/ramses.py,sha256=vp748Tf_a-56OMM8CWDA2ZktRfTuj0QVyPRcnsOstSM,53983
+ramses_tx/schemas.py,sha256=Hrmf_q9bAZtkKJzGu6GtUO0QV_-K9i4L99EzGWR13eE,13408
+ramses_tx/transport.py,sha256=Tk2CPAu9W0T4HCe6Q2VUYex2bFNZlyYsluP7iLf0rdQ,76277
+ramses_tx/typed_dicts.py,sha256=w-0V5t2Q3GiNUOrRAWiW9GtSwbta_7luME6GfIb1zhI,10869
+ramses_tx/typing.py,sha256=eF2SlPWhNhEFQj6WX2AhTXiyRQVXYnFutiepllYl2rI,5042
+ramses_tx/version.py,sha256=DToXw6Td-r5_4JxS4fbBBGkajaXoEj8xCJOh7vaNcQI,123
+ramses_rf-0.53.0.dist-info/METADATA,sha256=YkSNqr4RWgOsSi-z8SO5H4LEbzOI87IVYurjHWpUgRc,4179
+ramses_rf-0.53.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ramses_rf-0.53.0.dist-info/entry_points.txt,sha256=NnyK29baOCNg8DinPYiZ368h7MTH7bgTW26z2A1NeIE,50
+ramses_rf-0.53.0.dist-info/licenses/LICENSE,sha256=ptVutrtSMr7X-ek6LduiD8Cce4JsNn_8sR8MYlm-fvo,1086
+ramses_rf-0.53.0.dist-info/RECORD,,

{ramses_rf-0.52.4.dist-info → ramses_rf-0.53.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

{ramses_rf-0.52.4.dist-info → ramses_rf-0.53.0.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2025 David Bonnes
+Copyright (c) 2021-2026 D. Bonnes and E. Broerse
 
 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/address.py

@@ -39,7 +39,12 @@ class Address:
     _SLUG = None
 
     def __init__(self, device_id: DeviceIdT) -> None:
-        """Create an address from a valid device id."""
+        """Create an address from a valid device ID.
+
+        :param device_id: The RAMSES II device ID (e.g., '01:123456')
+        :type device_id: DeviceIdT
+        :raises ValueError: If the device_id is not a valid format.
+        """
 
         # if device_id is None:
         #     device_id = NON_DEVICE_ID
@@ -91,7 +96,15 @@ class Address:
 
     @classmethod
     def convert_from_hex(cls, device_hex: str, friendly_id: bool = False) -> str:
-        """Convert (say) '06368E' to '01:145038' (or 'CTL:145038')."""
+        """Convert a 6-character hex string to a device ID.
+
+        :param device_hex: The hex string to convert (e.g., '06368E')
+        :type device_hex: str
+        :param friendly_id: If True, returns a named ID (e.g., 'CTL:145038'), defaults to False
+        :type friendly_id: bool
+        :return: The formatted device ID string
+        :rtype: str
+        """
 
         if device_hex == "FFFFFE":  # aka '63:262142'
             return ">null dev<" if friendly_id else ALL_DEVICE_ID
@@ -191,11 +204,13 @@ def is_valid_dev_id(value: str, dev_class: None | str = None) -> bool:
 
 @lru_cache(maxsize=256)  # there is definite benefit in caching this
 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
+    """Parse address fields from a 30-character address fragment.
 
-    Will raise an InvalidAddrSetError if the address fields are not valid.
+    :param addr_fragment: The 30-char fragment (e.g., '01:078710 --:------ 01:144246')
+    :type addr_fragment: str
+    :return: A tuple of (src_addr, dst_addr, addr_0, addr_1, addr_2)
+    :rtype: tuple[Address, Address, Address, Address, Address]
+    :raises PacketAddrSetInvalid: If the address fields are not valid.
     """
     # for debug: print(pkt_addrs.cache_info())
 

ramses_tx/command.py

@@ -1866,7 +1866,7 @@ class Command(Frame):
             The actual number of available zones depends on the controller configuration.
             Requesting a non-existent zone will typically result in no response.
         """
-        return cls.from_attrs(W_, ctl_id, Code._2309, _check_idx(zone_idx))
+        return cls.from_attrs(RQ, ctl_id, Code._2309, _check_idx(zone_idx))
 
     @classmethod  # constructor for W|2309
     def set_zone_setpoint(
@@ -2254,7 +2254,13 @@ class Command(Frame):
 
     @classmethod  # constructor for RQ|2E04
     def get_system_mode(cls, ctl_id: DeviceIdT | str) -> Command:
-        """Constructor to get the mode of a system (c.f. parser_2e04)."""
+        """Get the mode of a system (c.f. parser_2e04).
+
+        :param ctl_id: The device ID of the controller
+        :type ctl_id: DeviceIdT | str
+        :return: A Command object for the RQ|2E04 message
+        :rtype: Command
+        """
 
         return cls.from_attrs(RQ, ctl_id, Code._2E04, FF)
 
@@ -2453,7 +2459,17 @@ class Command(Frame):
         datetime: dt | str,
         is_dst: bool = False,
     ) -> Command:
-        """Constructor to set the datetime of a system (c.f. parser_313f)."""
+        """Set the datetime of a system (c.f. parser_313f).
+
+        :param ctl_id: The device ID of the controller
+        :type ctl_id: DeviceIdT | str
+        :param datetime: The target date and time
+        :type datetime: dt | str
+        :param is_dst: Whether Daylight Saving Time is active, defaults to False
+        :type is_dst: bool
+        :return: A Command object for the W|313F message
+        :rtype: Command
+        """
         # .W --- 30:185469 01:037519 --:------ 313F 009 0060003A0C1B0107E5
 
         dt_str = hex_from_dtm(datetime, is_dst=is_dst, incl_seconds=True)

ramses_tx/const.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
-"""RAMSES RF - a RAMSES-II protocol decoder & analyser."""
+"""RAMSES RF - a RAMSES-II protocol decoder & analyser.
+
+This module contains constants, enums, and helper classes used throughout the
+library to decode and encode RAMSES-II protocol packets.
+"""
 
 from __future__ import annotations
 
@@ -15,16 +19,23 @@ DEV_MODE = __dev_mode__
 DEFAULT_DISABLE_QOS: Final[bool | None] = None
 DEFAULT_WAIT_FOR_REPLY: Final[bool | None] = None
 
-DEFAULT_ECHO_TIMEOUT: Final[float] = 0.50  # waiting for echo pkt after cmd sent
-DEFAULT_RPLY_TIMEOUT: Final[float] = 0.50  # waiting for reply pkt after echo pkt rcvd
+#: Waiting for echo pkt after cmd sent (seconds)
+DEFAULT_ECHO_TIMEOUT: Final[float] = 0.50
+
+#: Waiting for reply pkt after echo pkt rcvd (seconds)
+DEFAULT_RPLY_TIMEOUT: Final[float] = 0.50
 DEFAULT_BUFFER_SIZE: Final[int] = 32
 
-DEFAULT_SEND_TIMEOUT: Final[float] = 20.0  # total waiting for successful send: FIXME
-MAX_SEND_TIMEOUT: Final[float] = 20.0  # for a command to be sent, incl. queuing time
+#: Total waiting for successful send (seconds)
+DEFAULT_SEND_TIMEOUT: Final[float] = 20.0
+#: For a command to be sent, incl. queuing time (seconds)
+MAX_SEND_TIMEOUT: Final[float] = 20.0
 
-MAX_RETRY_LIMIT: Final[int] = 3  # for a command to be re-sent (not incl. 1st send)
+#: For a command to be re-sent (not incl. 1st send)
+MAX_RETRY_LIMIT: Final[int] = 3
 
-MIN_INTER_WRITE_GAP: Final[float] = 0.05  # seconds
+#: Minimum gap between writes (seconds)
+MIN_INTER_WRITE_GAP: Final[float] = 0.05
 DEFAULT_GAP_DURATION: Final[float] = MIN_INTER_WRITE_GAP
 DEFAULT_MAX_RETRIES: Final[int] = 3
 DEFAULT_NUM_REPEATS: Final[int] = 0
@@ -139,6 +150,8 @@ SZ_OTC_ACTIVE: Final = "otc_active"
 
 @verify(EnumCheck.UNIQUE)
 class Priority(IntEnum):
+    """Priority levels for protocol messages."""
+
     LOWEST = 4
     LOW = 2
     DEFAULT = 0
@@ -147,31 +160,60 @@ class Priority(IntEnum):
 
 
 def slug(string: str) -> str:
-    """Convert a string to snake_case."""
+    """Convert a string to snake_case.
+
+    :param string: The input string to convert.
+    :return: The string converted to snake_case (lowercase, with non-alphanumerics replaced by underscores).
+    """
     return re.sub(r"[\W_]+", "_", string.lower())
 
 
 # TODO: FIXME: This is a mess - needs converting to StrEnum
 class AttrDict(dict):  # type: ignore[type-arg]
+    """A read-only dictionary that supports dot-access and two-way lookup.
+
+    This class is typically used to map hex codes (keys) to human-readable slugs (values),
+    while also allowing reverse lookup via dot notation (e.g., ``map.SLUG``).
+
+    .. warning::
+        This class is immutable. Attempting to modify it will raise a :exc:`TypeError`.
+    """
+
     _SZ_AKA_SLUG: Final = "_root_slug"
     _SZ_DEFAULT: Final = "_default"
     _SZ_SLUGS: Final = "SLUGS"
 
-    @classmethod
-    def __readonly(cls, *args: Any, **kwargs: Any) -> NoReturn:
-        raise TypeError(f"'{cls.__class__.__name__}' object is read only")
+    def _readonly(self, *args: Any, **kwargs: Any) -> NoReturn:
+        """Raise TypeError for read-only operations."""
+        raise TypeError(f"'{self.__class__.__name__}' object is read only")
+
+    def __setitem__(self, key: Any, value: Any) -> NoReturn:
+        self._readonly()
 
-    __delitem__ = __readonly
-    __setitem__ = __readonly
-    clear = __readonly
-    pop = __readonly
-    popitem = __readonly
-    setdefault = __readonly
-    update = __readonly
+    def __delitem__(self, key: Any) -> NoReturn:
+        self._readonly()
 
-    del __readonly
+    def clear(self) -> NoReturn:
+        self._readonly()
+
+    def pop(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._readonly()
+
+    def popitem(self) -> NoReturn:
+        self._readonly()
+
+    def setdefault(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._readonly()
+
+    def update(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._readonly()
 
     def __init__(self, main_table: dict[str, dict], attr_table: dict[str, Any]) -> None:  # type: ignore[type-arg]
+        """Initialize the AttrDict.
+
+        :param main_table: A dictionary mapping keys (usually hex codes) to property dictionaries.
+        :param attr_table: A dictionary of additional attributes to expose on the object.
+        """
         self._main_table = main_table
         self._attr_table = attr_table
         self._attr_table[self._SZ_SLUGS] = tuple(sorted(main_table.keys()))
@@ -237,7 +279,12 @@ class AttrDict(dict):  # type: ignore[type-arg]
         return self.__getattribute__(name)
 
     def _hex(self, key: str) -> str:
-        """Return the key/ID (2-byte hex string) of the two-way dict (e.g. '04')."""
+        """Return the key/ID (2-byte hex string) of the two-way dict (e.g. '04').
+
+        :param key: The lookup key (can be slug or code).
+        :raises KeyError: If the key is not found.
+        :return: The 2-byte hex string identifier.
+        """
         if key in self._main_table:
             return list(self._main_table[key].keys())[0]  # type: ignore[no-any-return]
         if key in self._reverse:
@@ -245,7 +292,12 @@ class AttrDict(dict):  # type: ignore[type-arg]
         raise KeyError(key)
 
     def _str(self, key: str) -> str:
-        """Return the value (string) of the two-way dict (e.g. 'radiator_valve')."""
+        """Return the value (string) of the two-way dict (e.g. 'radiator_valve').
+
+        :param key: The lookup key.
+        :raises KeyError: If the key is not found.
+        :return: The human-readable slug string.
+        """
         if key in self._main_table:
             return list(self._main_table[key].values())[0]  # type: ignore[no-any-return]
         if key in self:
@@ -256,14 +308,23 @@ class AttrDict(dict):  # type: ignore[type-arg]
     #     return {k: k for k in super().values()}.values()
 
     def slug(self, key: str) -> str:
-        """WIP: Return master slug for a hex key/ID (e.g. 00 -> 'TRV', not 'TR0')."""
+        """Return master slug for a hex key/ID.
+
+        Example: 00 -> 'TRV' (master), not 'TR0'.
+
+        :param key: The hex key to look up.
+        :return: The master slug.
+        """
         slug_ = self._slug_lookup[key]
         # if slug_ in self._attr_table["_TRANSFORMS"]:
         #     return self._attr_table["_TRANSFORMS"][slug_]
         return slug_  # type: ignore[no-any-return]
 
     def slugs(self) -> tuple[str]:
-        """Return the slugs from the main table."""
+        """Return the slugs from the main table.
+
+        :return: A tuple of all available slugs.
+        """
         return self._attr_table[self._SZ_SLUGS]  # type: ignore[no-any-return]
 
 
@@ -271,6 +332,12 @@ def attr_dict_factory(
     main_table: dict[str, dict],  # type: ignore[type-arg]
     attr_table: dict | None = None,  # type: ignore[type-arg]
 ) -> AttrDict:  # is: SlottedAttrDict
+    """Create a new AttrDict instance with a slotted subclass.
+
+    :param main_table: The primary mapping of codes to slugs.
+    :param attr_table: Optional additional attributes to attach to the instance.
+    :return: An instance of a dynamic AttrDict subclass.
+    """
     if attr_table is None:
         attr_table = {}
 
@@ -295,6 +362,8 @@ def attr_dict_factory(
 # slugs for device/zone entity klasses, used by 0005/000C
 @verify(EnumCheck.UNIQUE)
 class DevRole(StrEnum):
+    """Slugs for device/zone entity classes, used by commands 0005/000C."""
+
     #
     # Generic device/zone classes
     ACT = "ACT"  # Generic heating zone actuator group
@@ -345,6 +414,8 @@ DEV_ROLE_MAP = attr_dict_factory(
 # slugs for device entity types, used in device_ids
 @verify(EnumCheck.UNIQUE)
 class DevType(StrEnum):
+    """Slugs for device entity types, used in device_ids."""
+
     #
     # Promotable/Generic devices
     DEV = "DEV"  # xx: Promotable device
@@ -457,6 +528,8 @@ DEV_TYPE_MAP = attr_dict_factory(
 
 # slugs for zone entity klasses, used by 0005/000C
 class ZoneRole(StrEnum):
+    """Slugs for zone entity classes, used by commands 0005/000C."""
+
     #
     # Generic device/zone classes
     ACT = "ACT"  # Generic heating zone actuator group
@@ -645,6 +718,8 @@ MESSAGE_REGEX = re.compile(f"^{r} {v} {r} {d} {d} {d} {c} {l} {p}$")
 
 # Used by 0418/system_fault parser
 class FaultDeviceClass(StrEnum):
+    """Device classes for system faults."""
+
     CONTROLLER = "controller"
     SENSOR = "sensor"
     SETPOINT = "setpoint"
@@ -666,6 +741,8 @@ FAULT_DEVICE_CLASS: Final[dict[str, FaultDeviceClass]] = {
 
 
 class FaultState(StrEnum):
+    """States for system faults."""
+
     FAULT = "fault"
     RESTORE = "restore"
     UNKNOWN_C0 = "unknown_c0"
@@ -680,6 +757,8 @@ FAULT_STATE: Final[dict[str, FaultState]] = {  # a bitmap?
 
 
 class FaultType(StrEnum):
+    """Types of system faults."""
+
     SYSTEM_FAULT = "system_fault"
     MAINS_LOW = "mains_low"
     BATTERY_LOW = "battery_low"
@@ -703,6 +782,8 @@ FAULT_TYPE: Final[dict[str, FaultType]] = {
 
 
 class SystemType(StrEnum):
+    """System types (e.g. Evohome, Hometronics)."""
+
     CHRONOTHERM = "chronotherm"
     EVOHOME = "evohome"
     HOMETRONICS = "hometronics"
@@ -742,6 +823,8 @@ FAN_RATE: Final = "fan_rate"  # percentage, 0.0 - 1.0  # deprecated, use SZ_FAN_
 # Below, verbs & codes - can use Verb/Code/Index for mypy type checking
 @verify(EnumCheck.UNIQUE)
 class VerbT(StrEnum):
+    """Protocol verbs (message types)."""
+
     I_ = " I"
     RQ = "RQ"
     RP = "RP"
@@ -756,6 +839,8 @@ W_: Final = VerbT.W_
 
 @verify(EnumCheck.UNIQUE)
 class MsgId(StrEnum):
+    """Message identifiers."""
+
     _00 = "00"
     _03 = "03"
     _06 = "06"
@@ -791,6 +876,8 @@ class MsgId(StrEnum):
 # StrEnum is intended to include all known codes, see: test suite, code schema in ramses.py
 @verify(EnumCheck.UNIQUE)
 class Code(StrEnum):
+    """Protocol command codes."""
+
     _0001 = "0001"
     _0002 = "0002"
     _0004 = "0004"

ramses_tx/helpers.py

@@ -131,28 +131,36 @@ file_time = _FILE_TIME()
 def timestamp() -> float:
     """Return the number of seconds since the Unix epoch.
 
-    Return an accurate value, even for Windows-based systems.
+    This function attempts to return a high-precision value, using specific
+    system calls on Windows if available.
+    :return: The current timestamp in seconds.
+    :rtype: float
     """
 
     # see: https://www.python.org/dev/peps/pep-0564/
-    if sys.platform != "win32":  # since 1970-01-01T00:00:00Z, time.gmtime(0)
+    if sys.platform == "win32":
+        # Windows uses a different epoch (1601-01-01)
+        ctypes.windll.kernel32.GetSystemTimePreciseAsFileTime(ctypes.byref(file_time))
+        _time = (file_time.dwLowDateTime + (file_time.dwHighDateTime << 32)) / 1e7
+        return float(_time - 134774 * 24 * 60 * 60)
+    else:
+        # Linux/macOS uses the Unix epoch (1970-01-01)
         return time.time_ns() / 1e9
 
-    # otherwise, is since 1601-01-01T00:00:00Z
-    ctypes.windll.kernel32.GetSystemTimePreciseAsFileTime(ctypes.byref(file_time))  # type: ignore[unreachable]
-    _time = (file_time.dwLowDateTime + (file_time.dwHighDateTime << 32)) / 1e7
-    return _time - 134774 * 24 * 60 * 60
-
 
 def dt_now() -> dt:
     """Return the current datetime as a local/naive datetime object.
 
     This is slower, but potentially more accurate, than dt.now(), and is used mainly for
     packet timestamps.
+
+    :return: The current local datetime.
+    :rtype: dt
     """
     if sys.platform == "win32":
         return dt.fromtimestamp(timestamp())
-    return dt.now()
+    else:
+        return dt.now()
 
 
 def dt_str() -> str:
@@ -369,7 +377,14 @@ def hex_from_str(value: str) -> str:
 
 
 def hex_to_temp(value: HexStr4) -> bool | float | None:  # TODO: remove bool
-    """Convert a 2's complement 4-byte hex string to a float."""
+    """Convert a 4-byte 2's complement hex string to a float temperature ('C).
+
+    :param value: The 4-character hex string (e.g., '07D0')
+    :type value: HexStr4
+    :return: The temperature in Celsius, or None if N/A
+    :rtype: float | None
+    :raises ValueError: If input is not a 4-char hex string or temperature is invalid.
+    """
     if not isinstance(value, str) or len(value) != 4:
         raise ValueError(f"Invalid value: {value}, is not a 4-char hex string")
     if value == "31FF":  # means: N/A (== 127.99, 2s complement), signed?
@@ -488,13 +503,18 @@ AIR_QUALITY_BASIS: dict[str, str] = {
 
 # 31DA[2:6] and 12C8[2:6]
 def parse_air_quality(value: HexStr4) -> PayDictT.AIR_QUALITY:
-    """Return the air quality (%): poor (0.0) to excellent (1.0).
+    """Return the air quality percentage (0.0 to 1.0) and its basis.
 
     The basis of the air quality level should be one of: VOC, CO2 or relative humidity.
     If air_quality is EF, air_quality_basis should be 00.
 
     The sensor value is None if there is no sensor present (is not an error).
     The dict does not include the key if there is a sensor fault.
+
+    :param value: The 4-character hex string encoding quality and basis
+    :type value: HexStr4
+    :return: A dictionary containing the air quality and its basis (e.g., CO2, VOC)
+    :rtype: PayDictT.AIR_QUALITY
     """  # VOC: Volatile organic compounds
 
     # TODO: remove this as API used only internally...

ramses_tx/message.py

@@ -54,7 +54,9 @@ class MessageBase:
     def __init__(self, pkt: Packet) -> None:
         """Create a message from a valid packet.
 
-        :raises InvalidPacketError if message payload is invalid.
+        :param pkt: The packet to process into a message
+        :type pkt: Packet
+        :raises PacketInvalid: If the packet payload cannot be parsed.
         """
 
         self._pkt = pkt
@@ -359,10 +361,14 @@ def re_compile_re_match(regex: str, string: str) -> bool:  # Optional[Match[Any]
 
 
 def _check_msg_payload(msg: MessageBase, payload: str) -> None:
-    """Validate the packet's payload against its verb/code pair.
-
-    :raises InvalidPayloadError if the payload is seen as invalid. Such payloads may
-    actually be valid, in which case the rules (likely the regex) will need updating.
+    """Validate a packet's payload against its verb/code pair.
+
+    :param msg: The message object being validated
+    :type msg: MessageBase
+    :param payload: The raw hex payload string
+    :type payload: str
+    :raises PacketInvalid: If the code is unknown or verb/code pair is invalid.
+    :raises PacketPayloadInvalid: If the payload does not match the expected regex.
     """
 
     _ = repr(msg._pkt)  # HACK: ? raise InvalidPayloadError

ramses_tx/packet.py

@@ -48,9 +48,14 @@ class Packet(Frame):
     _rssi: str
 
     def __init__(self, dtm: dt, frame: str, **kwargs: Any) -> None:
-        """Create a packet from a string (actually from f"{RSSI} {frame}").
-
-        Will raise InvalidPacketError if it is invalid.
+        """Create a packet from a raw frame string.
+
+        :param dtm: The timestamp when the packet was received
+        :type dtm: dt
+        :param frame: The raw frame string, typically including RSSI
+        :type frame: str
+        :param kwargs: Metadata including 'comment', 'err_msg', or 'raw_frame'
+        :raises PacketInvalid: If the frame content is malformed.
         """
 
         super().__init__(frame[4:])  # remove RSSI
@@ -156,9 +161,12 @@ class Packet(Frame):
 
 # TODO: remove None as a possible return value
 def pkt_lifespan(pkt: Packet) -> td:  # import OtbGateway??
-    """Return the pkt lifespan, or dt.max() if the packet does not expire.
+    """Return the lifespan of a packet before it expires.
 
-    Some codes require a valid payload to best determine lifespan (e.g. 1F09).
+    :param pkt: The packet instance to evaluate
+    :type pkt: Packet
+    :return: The duration the packet's data remains valid
+    :rtype: td
     """
 
     if pkt.verb in (RQ, W_):