ramses-rf 0.53.1__tar.gz → 0.53.2__tar.gz

{ramses_rf-0.53.1 → ramses_rf-0.53.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ramses_rf
-Version: 0.53.1
+Version: 0.53.2
 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

{ramses_rf-0.53.1 → ramses_rf-0.53.2}/docs/source/binding_process.md

@@ -7,7 +7,8 @@ This diagram shows the binding finite state machine (FSM) for RAMSES RF devices,
 
 ```mermaid
 stateDiagram-v2
-    direction LR
+    direction TB
+    
     [*] --> DevIsNotBinding
     DevIsNotBinding --> InitiateBindingProcess : initiate_binding_process()
     InitiateBindingProcess --> SuppSendOfferWaitForAccept

ramses_rf-0.53.2/docs/source/modules.rst

@@ -0,0 +1,97 @@
+ramses_rf/src/
+==============
+
+.. mermaid::
+
+    classDiagram
+        direction RL
+
+        namespace ramses_rf-dispatcher{
+            class Dispatcher{
+                + create_device()
+                + ..
+                + process_msg()
+            }
+        }
+        namespace ramses_rf-database{
+            class Database {
+                - add(msg)
+                - ..
+                - qry(msg)
+                - ..
+                - rem(msg)
+            }
+        }
+        namespace ramses_rf-device{
+            class heat
+            class hvac
+        }
+        namespace ramses_rf-gateway{
+            class hgi
+        }
+        namespace ramses_tx-message{
+            class Message {
+                - parse_message()
+                - ..
+                - parse_payload()
+                - ..
+                - validate_msg()
+            }
+        }
+        namespace ramses_tx-command{
+            class Command{
+                - _from_attrs
+                - ..
+                - set_zone_config
+            }
+        }
+        namespace ramses_tx-gateway-engine{
+            class Engine {
+                - add_msg_handler()
+                - ..
+                - create_cmd()
+                - ..
+                - async_send_cmd()
+            }
+        }
+        namespace ramses_tx-transport{
+            class Transport {
+                - MqttTransport
+                - ..
+                - PortTransport
+            }
+        }
+        namespace ramses_ESP{
+            class RF:::esp
+            class Serial:::esp
+        }
+
+        Transport <|--|> Serial
+        Transport <|--|> RF
+        Transport <|--|> Engine
+        Engine <|--|> hgi
+        Database <|--|> hgi
+        Message <|--|> hgi
+        heat <|--|> hgi
+        hvac <|--|> hgi
+        Dispatcher <|--|> hvac
+        Dispatcher <|--|> heat
+        Dispatcher <|--|> Message
+
+        click Transport href "ramses_tx.html#module-ramses_tx.transport" "docs"
+        click Engine href "ramses_tx.html#module-ramses_tx.gateway" "docs"
+        click hgi href "ramses_rf.html#module-ramses_rf.gateway" "docs"
+        click Database href "ramses_rf.html#module-ramses_rf.database" "docs"
+        click Message href "ramses_tx.html#module-ramses_tx.message" "docs"
+        click heat href "ramses_rf.device.html#module-ramses_rf.device.heat" "docs"
+        click hvac href "ramses_rf.device.html#module-ramses_rf.device.hvac" "docs"
+        click Dispatcher href "ramses_rf.html#module-ramses_rf.dispatcher" "docs"
+        click Command href "ramses_tx.html#module-ramses_tx.command" "docs"
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   ramses_cli
+   ramses_rf
+   ramses_tx

{ramses_rf-0.53.1 → ramses_rf-0.53.2}/docs/source/ramses_rf.rst

@@ -32,6 +32,20 @@ ramses\_rf.const module
 ramses\_rf.database module
 --------------------------
 
+.. mermaid::
+    erDiagram
+        msg_db ||--o{ device : query
+
+        msg_db {
+            TEXT(26)* dtm
+            TEXT(2) verb
+            TEXT(9) src
+            TEXT(9) dst
+            TEXT(4) code
+            TEXT() ctx
+            TEXT() hdr
+        }
+
 .. automodule:: ramses_rf.database
    :members:
    :show-inheritance:

{ramses_rf-0.53.1 → ramses_rf-0.53.2}/ramses_rf/version.py

@@ -1,4 +1,4 @@
 """RAMSES RF - a RAMSES-II protocol decoder & analyser (application layer)."""
 
-__version__ = "0.53.1"
+__version__ = "0.53.2"
 VERSION = __version__

{ramses_rf-0.53.1 → ramses_rf-0.53.2}/ramses_tx/version.py

@@ -1,4 +1,4 @@
 """RAMSES RF - a RAMSES-II protocol decoder & analyser (transport layer)."""
 
-__version__ = "0.53.1"
+__version__ = "0.53.2"
 VERSION = __version__

{ramses_rf-0.53.1 → ramses_rf-0.53.2}/requirements/requirements_docs.txt

@@ -1,5 +1,5 @@
 # Requirements to build the code documentation from the source code
-# - last checked/updated: 2026-01-11 (c.f. HA 2026.1.0)
+# - last checked/updated: 2026-01-16 (c.f. HA 2026.1.0)
 
 # libraries required to build with sphinx
 # - pip list | grep -E 'sphinx'

ramses_rf-0.53.2/tests/tests_rf/test_virtual_rf.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""
+Combined Unit tests for the VirtualRf harness.
+
+Verifies PTY handling, I/O safety, and hardware gateway emulation.
+"""
+
+import asyncio
+from collections.abc import AsyncGenerator
+from typing import Final
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from .virtual_rf import virtual_rf as vrf_mod
+from .virtual_rf.const import SCHEMA_3, HgiFwTypes
+from .virtual_rf.virtual_rf import VirtualRf
+
+# Constants
+TEST_DATA: Final[bytes] = b"Hello World\r\n"
+
+
+@pytest.fixture
+async def virtual_rf() -> AsyncGenerator[VirtualRf, None]:
+    """
+    Fixture to provide a VirtualRf instance using the Async Context Manager.
+
+    :yield: An initialized VirtualRf instance.
+    """
+    # Using 'async with' ensures __aenter__ and __aexit__ are tested
+    async with VirtualRf(num_ports=3) as vrf:
+        yield vrf
+
+
+@pytest.mark.asyncio
+async def test_virtual_rf_lifecycle() -> None:
+    """
+    Test the start and stop lifecycle via the Async Context Manager.
+    """
+    # Test that __aenter__ and __aexit__ handle resources correctly
+    async with VirtualRf(num_ports=2) as vrf:
+        assert len(vrf.ports) == 2
+        assert len(vrf._master_to_port) == 2
+
+    # Verify cleanup occurred after context exit
+    assert len(vrf._master_to_port) == 0
+
+
+@pytest.mark.asyncio
+async def test_broadcast_data(virtual_rf: VirtualRf) -> None:
+    """
+    Test that data written to one PTY is broadcast to others.
+    """
+    port_0 = virtual_rf.ports[0]
+    port_1 = virtual_rf.ports[1]
+    fd_0_master = virtual_rf._port_to_master[port_0]
+
+    mock_file_io = MagicMock()
+    original_io = virtual_rf._port_to_object[port_1]
+    virtual_rf._port_to_object[port_1] = mock_file_io
+
+    try:
+        with patch.object(
+            virtual_rf._port_to_object[port_0], "read", return_value=TEST_DATA
+        ):
+            virtual_rf._handle_data_ready(fd_0_master)
+
+        # Note: Broadcaster adds RSSI '000 ' if not a control frame
+        mock_file_io.write.assert_called_with(b"000 " + TEST_DATA)
+
+    finally:
+        virtual_rf._port_to_object[port_1] = original_io
+
+
+@pytest.mark.asyncio
+async def test_blocking_io_handling(virtual_rf: VirtualRf) -> None:
+    """
+    Test handling of BlockingIOError during broadcast write.
+    """
+    port_0 = virtual_rf.ports[0]
+    port_1 = virtual_rf.ports[1]
+    fd_0_master = virtual_rf._port_to_master[port_0]
+
+    mock_file_io = MagicMock()
+    mock_file_io.write.side_effect = BlockingIOError
+    original_io = virtual_rf._port_to_object[port_1]
+    virtual_rf._port_to_object[port_1] = mock_file_io
+
+    with patch.object(vrf_mod._LOGGER, "warning") as mock_log:
+        with patch.object(
+            virtual_rf._port_to_object[port_0], "read", return_value=TEST_DATA
+        ):
+            virtual_rf._handle_data_ready(fd_0_master)
+
+        mock_log.assert_called_with(f"Buffer full writing to {port_1}, dropping packet")
+
+    virtual_rf._port_to_object[port_1] = original_io
+
+
+@pytest.mark.asyncio
+async def test_gateway_emulation(virtual_rf: VirtualRf) -> None:
+    """
+    Test hardware-specific emulation logic for different firmware types.
+    """
+    # Setup different gateway profiles
+    virtual_rf.set_gateway(virtual_rf.ports[0], "18:111111", HgiFwTypes.EVOFW3)
+    virtual_rf.set_gateway(virtual_rf.ports[1], "18:222222", HgiFwTypes.EVOFW3_FTDI)
+    virtual_rf.set_gateway(virtual_rf.ports[2], "18:333333", HgiFwTypes.HGI_80)
+
+    # Test !V (Version) response for EVOFW3
+    for i in range(2):
+        port = virtual_rf.ports[i]
+        response = virtual_rf._proc_after_rx(port, b"!V")
+        assert response == b"# evofw3 0.7.1\r\n"
+
+    # Test HGI80 correctly ignores !V
+    hgi_port = virtual_rf.ports[2]
+    assert virtual_rf._proc_after_rx(hgi_port, b"!V") is None
+
+
+@pytest.mark.asyncio
+async def test_schema_3_integration(virtual_rf: VirtualRf) -> None:
+    """
+    Verify that SCHEMA_3 (HVAC/Generic) initializes without errors.
+    """
+
+    # Test that the gateway from SCHEMA_3 can be attached
+    gwy_id = list(SCHEMA_3["known_list"].keys())[0]  # 18:333333
+
+    # This should not raise LookupError or TypeError
+    virtual_rf.set_gateway(virtual_rf.ports[0], gwy_id)
+
+    assert virtual_rf.gateways[gwy_id] == virtual_rf.ports[0]
+
+
+@pytest.mark.asyncio
+async def test_rapid_cycling_stress_test() -> None:
+    """
+    Stress test: Rapidly start and stop the VirtualRf environment.
+
+    This ensures that:
+    1. File descriptors are not leaking.
+    2. Event loop readers are cleanly removed (no 'File descriptor bad' errors).
+    3. No race conditions occur during fast teardown/setup cycles.
+    """
+    for _ in range(50):
+        async with VirtualRf(num_ports=2) as vrf:
+            # Verify ports allow basic IO immediately
+            assert len(vrf.ports) == 2
+            # Minimal sleep to let the loop turn once
+            await asyncio.sleep(0)
+        # Give the loop one final turn to settle the FDs from the context manager
+        await asyncio.sleep(0)

{ramses_rf-0.53.1 → ramses_rf-0.53.2}/tests/tests_rf/virtual_rf/__init__.py

@@ -6,10 +6,9 @@ from unittest.mock import patch
 
 from ramses_rf import Gateway
 from ramses_rf.const import DEV_TYPE_MAP, DevType
-from ramses_rf.database import MessageIndex
 from ramses_rf.schemas import SZ_CLASS, SZ_KNOWN_LIST
 
-from .const import HgiFwTypes
+from .const import MAX_NUM_PORTS, HgiFwTypes
 from .virtual_rf import VirtualRf
 
 __all__ = ["HgiFwTypes", "VirtualRf", "rf_factory"]
@@ -38,34 +37,55 @@ def _get_hgi_id_for_schema(
 
     Does not modify the schema.
 
-    If a Gateway (18:) device is present in the schema, it must have a defined class of
-    "HGI". Otherwise, the Gateway device_id is derived from the serial port ordinal
-    (port_idx, 0-5).
+    Checks that only one Gateway is defined and ensures all 18: type devices
+    have an explicit HGI class defined.
+
+    If a Gateway (18:) device is present in the schema, it must have a defined class
+    of "HGI". If it does, its device_id is returned, along with its FW type (if
+    specified, or EVOFW3 is assumed).
+
+    If no Gateway device is present, one is created (18:000000), and its
+    details returned.
+
+    :param schema: The configuration schema.
+    :param port_idx: Index used to construct a default ID if none found.
+    :raises TypeError: If multiple gateways exist or an HGI device lacks a class.
+    :return: A tuple of (device_id, firmware_type).
     """
 
     known_list: dict[str, Any] = schema.get(SZ_KNOWN_LIST, {})
 
-    hgi_ids = [k for k, v in known_list.items() if v.get(SZ_CLASS) == DevType.HGI]
+    # 1. Collect HGI IDs for validation
+    hgi_ids = [
+        device_id
+        for device_id, v in known_list.items()
+        if v.get(SZ_CLASS) == DevType.HGI
+    ]
 
+    # 2. Validation: Multiple Gateways
     if len(hgi_ids) > 1:
         raise TypeError("Multiple Gateways per schema are not supported")
 
-    elif len(hgi_ids) == 1:
-        hgi_id = hgi_ids[0]
-        fw_type = known_list[hgi_id].get("_type", "EVOFW3")
-
-    elif [
+    # 3. Validation: Orphaned 18: devices (Gateways without a class)
+    if any(
         k
         for k, v in known_list.items()
-        if k[:2] == DEV_TYPE_MAP.HGI and not v.get(SZ_CLASS)
-    ]:
-        raise TypeError("Any Gateway must have its class defined explicitly")
+        if k.startswith(DEV_TYPE_MAP[DevType.HGI]) and not v.get(SZ_CLASS)
+    ):
+        raise TypeError("Any Gateway (18:) must have its class defined explicitly")
 
-    else:
-        hgi_id = f"18:{str(port_idx) * 6}"
-        fw_type = "EVOFW3"
+    # 4. Logic: Return existing
+    if len(hgi_ids) == 1:
+        hgi_id = hgi_ids[0]
+        fw_type_name = known_list[hgi_id].get("fw_version", HgiFwTypes.EVOFW3.name)
+        return hgi_id, HgiFwTypes[fw_type_name]
 
-    return hgi_id, fw_type
+    # 5. Logic: Create default if none present (18:000000 for idx 0, 18:111111 for idx 1)
+    if port_idx == 0:
+        return GWY_ID_0, HgiFwTypes.EVOFW3
+    if port_idx == 1:
+        return GWY_ID_1, HgiFwTypes.EVOFW3
+    return f"18:{port_idx:06d}", HgiFwTypes.EVOFW3
 
 
 @patch("ramses_tx.transport.MIN_INTER_WRITE_GAP", MIN_INTER_WRITE_GAP)
@@ -79,10 +99,8 @@ async def rf_factory(
     virtual RF pool.
     """
 
-    MAX_PORTS = 6  # 18:666666 is not a valid device_id, but 18:000000 is OK
-
-    if len(schemas) > MAX_PORTS:
-        raise TypeError(f"Only a maximum of {MAX_PORTS} ports is supported")
+    if len(schemas) > MAX_NUM_PORTS:
+        raise TypeError(f"Only a maximum of {MAX_NUM_PORTS} ports is supported")
 
     gwys = []
 
@@ -96,16 +114,16 @@ async def rf_factory(
         hgi_id, fw_type = _get_hgi_id_for_schema(schema, idx)
 
         # rf._create_port(idx)  # REMOVED: Redundant and causes race condition
-        rf.set_gateway(rf.ports[idx], hgi_id, fw_type=HgiFwTypes.__members__[fw_type])
+        rf.set_gateway(rf.ports[idx], hgi_id, fw_type=fw_type)
 
         with patch("ramses_tx.transport.comports", rf.comports):
             gwy = Gateway(rf.ports[idx], **schema)
-        gwys.append(gwy)
+            # gwy._engine.ptcl.qos.disable_qos = False  # Hack for testing
 
-        if start_gwys:
-            await gwy.start()
-            gwy.msg_db = MessageIndex(maintain=False)
-            assert gwy._transport is not None  # mypy
-            gwy._transport._extra["virtual_rf"] = rf
+            if start_gwys:
+                await gwy.start()
+            gwy.get_device(hgi_id)
+
+        gwys.append(gwy)
 
     return rf, gwys

ramses_rf-0.53.2/tests/tests_rf/virtual_rf/const.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Constants and type definitions for the virtual RF network.
+"""
+
+from enum import Enum
+from typing import Any, Final, NamedTuple
+
+# Shared Constants
+MAX_NUM_PORTS: Final = 6
+
+
+class HardwareProfile(NamedTuple):
+    """
+    Metadata for a specific hardware gateway profile.
+
+    :param manufacturer: USB manufacturer name.
+    :param product: USB product name string.
+    :param vid: Vendor ID (e.g., 0x10AC).
+    :param pid: Product ID (e.g., 0x0102).
+    :param description: Human-readable device description.
+    :param serial_number: Unique hardware serial, if any.
+    :param interface: Specific interface name.
+    :param subsystem: The system subsystem (e.g., 'usb').
+    :param dev_path: Default system device path.
+    :param dev_by_id: The persistent 'by-id' system path.
+    """
+
+    manufacturer: str
+    product: str
+    vid: int
+    pid: int
+    #
+    description: str
+    serial_number: str | None
+    interface: str | None
+    #
+    subsystem: str
+    dev_path: str
+    dev_by_id: str
+
+
+class HgiFwTypes(Enum):
+    """
+    Supported firmware/hardware combinations for gateway emulation.
+    """
+
+    EVOFW3 = HardwareProfile(  # 8/16 MHz atmega32u4 (HW Uart)
+        manufacturer="SparkFun",
+        product="evofw3 atmega32u4",
+        vid=0x1B4F,  # aka SparkFun Electronics
+        pid=0x9206,
+        #
+        description="evofw3 atmega32u4",
+        serial_number=None,
+        interface=None,
+        #
+        subsystem="usb-serial",
+        dev_path="/dev/ttyACM0",  # is not a fixed value
+        dev_by_id="/dev/serial/by-id/usb-SparkFun_evofw3_atmega32u4-if00",
+    )
+    """Standard SparkFun hardware (Atmega32u4), values are from real devices."""
+
+    EVOFW3_FTDI = HardwareProfile(  # 16MHZ atmega328 (SW Uart)
+        manufacturer="FTDI",
+        product="FT232R USB UART",
+        vid=0x0403,  # aka Future Technology Devices International Ltd.
+        pid=0x6001,
+        description="FT232R USB UART - FT232R USB UART",
+        serial_number="A50285BI",
+        interface="FT232R USB UART",
+        subsystem="usb-serial",
+        dev_path="/dev/ttyUSB0",  # is not a fixed value
+        dev_by_id="/dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A50285BI-if00-port0",
+    )
+    """Alternative hardware using an FTDI chip (Atmega328P), values are from real devices."""
+
+    HGI_80 = HardwareProfile(  # Honeywell HGI80 (partially contrived)
+        manufacturer="Texas Instruments",
+        product="TUSB3410 Boot Device",
+        vid=0x10AC,  # aka Honeywell, Inc.
+        pid=0x0102,
+        description="TUSB3410 Boot Device",  # contrived
+        serial_number="TUSB3410",
+        interface=None,  # assumed
+        subsystem="usb",
+        dev_path="/dev/ttyUSB0",  # is not a fixed value
+        dev_by_id="/dev/serial/by-id/usb-Texas_Instruments_TUSB3410_Boot_Device_TUSB3410-if00-port0",
+    )
+    """Original Honeywell HGI80 hardware, partially contrived values."""
+
+
+# Schema constants for testing
+SCHEMA_1: Final[dict[str, Any]] = {
+    "orphans_hvac": ["41:111111"],
+    "known_list": {
+        "18:111111": {"class": "HGI", "fw_version": "EVOFW3"},
+        "41:111111": {"class": "REM"},
+    },
+}
+
+SCHEMA_2: Final[dict[str, Any]] = {
+    "orphans_hvac": ["42:222222"],
+    "known_list": {
+        "18:222222": {"class": "HGI", "fw_version": "HGI_80"},
+        "42:222222": {"class": "FAN"},
+    },
+}
+
+SCHEMA_3: Final[dict[str, Any]] = {
+    "orphans_hvac": ["42:333333"],
+    "known_list": {"18:333333": {"class": "HGI"}, "42:333333": {"class": "FAN"}},
+}
+"""Schema added for specific HVAC functionality testing."""