ramses-rf 0.52.1__py3-none-any.whl → 0.52.3__py3-none-any.whl

ramses_tx/parsers.py

@@ -3,9 +3,11 @@
 
 NOTES: aspirations on a consistent Schema, going forward:
 
-  :mode/state: | :bool:  | :mutex (infinitive. vs -ing):      | :flags:
-mode (config.) | enabled | disabled, heat, cool, heat_cool... | ch_enabled, dhw_enabled
-state (action) | active  | idle, heating, cooling...          | is_heating, is_cooling
+==============  ========  ===================================  ========================
+  :mode/state:   :bool:    :mutex (infinitive. vs -ing):        :flags:
+mode (config.)   enabled   disabled, heat, cool, heat_cool...   ch_enabled, dhw_enabled
+state (action)   active    idle, heating, cooling...            is_heating, is_cooling
+==============  ========  ===================================  ========================
 
 - prefer: enabled: True over xx_enabled: True (if only ever 1 flag)
 - prefer:  active: True over is_heating: True (if only ever 1 flag)
@@ -362,8 +364,9 @@ def parser_0009(payload: str, msg: Message) -> dict | list[dict]:  # TODO: only
 
     The failsafe mode defines the relay behaviour if the RF communication is lost (e.g.
     when a room thermostat stops communicating due to discharged batteries):
-        False (disabled) - if RF comms are lost, relay will be held in OFF position
-        True  (enabled)  - if RF comms are lost, relay will cycle at 20% ON, 80% OFF
+
+    - False (disabled) - if RF comms are lost, relay will be held in OFF position
+    - True  (enabled)  - if RF comms are lost, relay will cycle at 20% ON, 80% OFF
 
     This setting may need to be enabled to ensure frost protect mode.
     """
@@ -2289,45 +2292,46 @@ def parser_31da(payload: str, msg: Message) -> PayDictT._31DA:
 def parser_31e0(payload: str, msg: Message) -> dict | list[dict]:  # TODO: only dict
     """Notes are.
 
-    van means “of”.
+    "van" means "of".
     - 0 = min. van min. potm would be:
     - 0 = minimum of minimum potentiometer
 
     See: https://www.industrialcontrolsonline.com/honeywell-t991a
     - modulates air temperatures in ducts
-
-    case 0x31E0:  ' 12768:
-    {
-        string str4;
-        unchecked
-        {
-            result.Fan = Conversions.ToString((double)(int)data[checked(start + 1)] / 2.0);
-            str4 = "";
-        }
-        str4 = (data[start + 2] & 0xF) switch
-        {
-            0 => str4 + "0 = min. potm. ",
-            1 => str4 + "0 = min. van min. potm ",
-            2 => str4 + "0 = min. fan ",
-            _ => "",
-        };
-        switch (data[start + 2] & 0xF0)
-        {
-        case 16:
-            str4 += "100 = max. potm";
-            break;
-        case 32:
-            str4 += "100 = max. van max. potm ";
-            break;
-        case 48:
-            str4 += "100 = max. fan ";
-            break;
-        }
-        result.Data = str4;
-        break;
-    }
     """
 
+    # coding note:
+    # case 0x31E0:  ' 12768:
+    # {
+    #     string str4;
+    #     unchecked
+    #     {
+    #         result.Fan = Conversions.ToString((double)(int)data[checked(start + 1)] / 2.0);
+    #         str4 = "";
+    #     }
+    #     str4 = (data[start + 2] & 0xF) switch
+    #     {
+    #         0 => str4 + "0 = min. potm. ",
+    #         1 => str4 + "0 = min. van min. potm ",
+    #         2 => str4 + "0 = min. fan ",
+    #         _ => "",
+    #     };
+    #     switch (data[start + 2] & 0xF0)
+    #     {
+    #     case 16:
+    #         str4 += "100 = max. potm";
+    #         break;
+    #     case 32:
+    #         str4 += "100 = max. van max. potm ";
+    #         break;
+    #     case 48:
+    #         str4 += "100 = max. fan ";
+    #         break;
+    #     }
+    #     result.Data = str4;
+    #     break;
+    # }
+
     # .I --- 37:005302 32:132403 --:------ 31E0 008 00-0000-00 01-0064-00  # RF15 CO2 to Orcon HRC400 series SmartComfort Valve
 
     # .I --- 29:146052 32:023459 --:------ 31E0 003 00-0000

ramses_tx/schemas.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """RAMSES RF - a RAMSES-II protocol decoder & analyser.
 
-Schema processor for protocol (lower) layer.
+:term:`Schema` processor for protocol (lower) layer.
 """
 
 from __future__ import annotations
@@ -73,13 +73,17 @@ class PktLogConfigT(TypedDict):
 def sch_packet_log_dict_factory(
     default_backups: int = 0,
 ) -> dict[vol.Required, vol.Any]:
-    """Return a packet log dict with a configurable default rotation policy.
+    """
+    :return: a packet log dict with a configurable default rotation policy.
 
-    usage:
+    Usage:
+
+    .. code-block::
+
+        SCH_PACKET_LOG_7 = vol.Schema(
+            packet_log_dict_factory(default_backups=7), extra=vol.PREVENT_EXTRA
+        )
 
-    SCH_PACKET_LOG_7 = vol.Schema(
-        packet_log_dict_factory(default_backups=7), extra=vol.PREVENT_EXTRA
-    )
     """
 
     SCH_PACKET_LOG_CONFIG = vol.Schema(
@@ -162,11 +166,13 @@ class PortConfigT(TypedDict):
 def sch_serial_port_dict_factory() -> dict[vol.Required, vol.Any]:
     """Return a serial port dict.
 
-    usage:
+    Usage:
 
-    SCH_SERIAL_PORT = vol.Schema(
-        sch_serial_port_dict_factory(), extra=vol.PREVENT_EXTRA
-    )
+    .. code-block::
+
+        SCH_SERIAL_PORT = vol.Schema(
+            sch_serial_port_dict_factory(), extra=vol.PREVENT_EXTRA
+        )
     """
 
     SCH_SERIAL_PORT_NAME = str
@@ -252,11 +258,13 @@ def sch_global_traits_dict_factory(
 ) -> tuple[dict[vol.Optional, vol.Any], vol.Any]:
     """Return a global traits dict with a configurable extra traits.
 
-    usage:
+    Usage:
 
-    SCH_GLOBAL_TRAITS = vol.Schema(
-        sch_global_traits_dict(heat=traits), extra=vol.PREVENT_EXTRA
-    )
+    .. code-block::
+
+        SCH_GLOBAL_TRAITS = vol.Schema(
+            sch_global_traits_dict(heat=traits), extra=vol.PREVENT_EXTRA
+        )
     """
 
     heat_traits = heat_traits or {}
@@ -348,7 +356,8 @@ def select_device_filter_mode(
     known_list: DeviceListT,
     block_list: DeviceListT,
 ) -> bool:
-    """Determine which device filter to use, if any.
+    """
+    Determine which device filter to use, if any.
 
     Either:
      - block if device_id in block_list (could be empty), otherwise
@@ -404,6 +413,7 @@ SZ_EVOFW_FLAG: Final = "evofw_flag"
 SZ_SQLITE_INDEX: Final = (
     "sqlite_index"  # temporary 0.52.x SQLite dev config option in ramses_cc
 )
+SZ_LOG_ALL_MQTT: Final = "log_all_mqtt"
 SZ_USE_REGEX: Final = "use_regex"
 
 SCH_ENGINE_DICT = {
@@ -418,6 +428,9 @@ SCH_ENGINE_DICT = {
     vol.Optional(
         SZ_SQLITE_INDEX, default=False
     ): bool,  # temporary 0.52.x dev config option
+    vol.Optional(
+        SZ_LOG_ALL_MQTT, default=False
+    ): bool,  # log all incoming MQTT traffic config option
     vol.Optional(SZ_USE_REGEX): dict,  # vol.All(ConvertNullToDict(), dict),
     vol.Optional(SZ_COMMS_PARAMS): SCH_COMMS_PARAMS,
 }

ramses_tx/transport.py

@@ -3,30 +3,38 @@
 
 Operates at the pkt layer of: app - msg - pkt - h/w
 
-For ser2net, use the following YAML with: ser2net -c misc/ser2net.yaml
-  connection: &con00
-  accepter: telnet(rfc2217),tcp,5001
-  timeout: 0
-  connector: serialdev,/dev/ttyUSB0,115200n81,local
-  options:
-    max-connections: 3
-
-For socat, see:
-  socat -dd pty,raw,echo=0 pty,raw,echo=0
-  python client.py monitor /dev/pts/0
-  cat packet.log | cut -d ' ' -f 2- | unix2dos > /dev/pts/1
+For ser2net, use the following YAML with: ``ser2net -c misc/ser2net.yaml``
+
+.. code-block::
+
+    connection: &con00
+    accepter: telnet(rfc2217),tcp,5001
+    timeout: 0
+    connector: serialdev,/dev/ttyUSB0,115200n81,local
+    options:
+        max-connections: 3
+
+For ``socat``, see:
+
+.. code-block::
+
+    socat -dd pty,raw,echo=0 pty,raw,echo=0
+    python client.py monitor /dev/pts/0
+    cat packet.log | cut -d ' ' -f 2- | unix2dos > /dev/pts/1
 
 For re-flashing evofw3 via Arduino IDE on *my* atmega328p (YMMV):
- - Board:      atmega328p (SW UART)
- - Bootloader: Old Bootloader
- - Processor:  atmega328p (5V, 16 MHz)
- - Host:       57600 (or 115200, YMMV)
- - Pinout:     Nano
+
+  - Board:      atmega328p (SW UART)
+  - Bootloader: Old Bootloader
+  - Processor:  atmega328p (5V, 16 MHz)
+  - Host:       57600 (or 115200, YMMV)
+  - Pinout:     Nano
 
 For re-flashing evofw3 via Arduino IDE on *my* atmega32u4 (YMMV):
- - Board:      atmega32u4 (HW UART)
- - Processor:  atmega32u4 (5V, 16 MHz)
- - Pinout:     Pro Micro
+
+  - Board:      atmega32u4 (HW UART)
+  - Processor:  atmega32u4 (5V, 16 MHz)
+  - Pinout:     Pro Micro
 """
 
 from __future__ import annotations
@@ -250,11 +258,12 @@ async def is_hgi80(serial_port: SerPortNameT) -> bool | None:
 
 
 def _normalise(pkt_line: str) -> str:
-    """Perform any (transparent) frame-level hacks, as required at (near-)RF layer.
+    """
+    Perform any (transparent) frame-level hacks, as required at (near-)RF layer.
 
     Goals:
     - ensure an evofw3 provides the same output as a HGI80 (none, presently)
-    - handle 'strange' packets (e.g. I|08:|0008)
+    - handle 'strange' packets (e.g. ``I|08:|0008``)
     """
 
     # TODO: deprecate as only for ramses_esp <0.4.0
@@ -1015,6 +1024,7 @@ class PortTransport(_RegHackMixin, _FullTransport, _PortTransportAbstractor):  #
 
 class MqttTransport(_FullTransport, _MqttTransportAbstractor):
     """Send/receive packets to/from ramses_esp via MQTT.
+    For full RX logging, turn on debug logging.
 
     See: https://github.com/IndaloTech/ramses_esp
     """
@@ -1057,6 +1067,9 @@ class MqttTransport(_FullTransport, _MqttTransportAbstractor):
         self._max_tokens: float = self._MAX_TOKENS * 2  # allow for the initial burst
         self._num_tokens: float = self._MAX_TOKENS * 2
 
+        # set log MQTT flag
+        self._log_all = kwargs.pop("log_all", False)
+
         # instantiate a paho mqtt client
         self.client = mqtt.Client(
             protocol=mqtt.MQTTv5, callback_api_version=CallbackAPIVersion.VERSION2
@@ -1274,8 +1287,9 @@ class MqttTransport(_FullTransport, _MqttTransportAbstractor):
 
         if _DBG_FORCE_FRAME_LOGGING:
             _LOGGER.warning("Rx: %s", msg.payload)
-        elif _LOGGER.getEffectiveLevel() == logging.INFO:  # log for INFO not DEBUG
-            _LOGGER.info("Rx: %s", msg.payload)
+        elif self._log_all and _LOGGER.getEffectiveLevel() == logging.INFO:
+            # log for INFO not DEBUG
+            _LOGGER.info("mq Rx: %s", msg.payload)  # TODO remove mq marker?
 
         if msg.topic[-3:] != "/rx":  # then, e.g. 'RAMSES/GATEWAY/18:017804'
             if msg.payload == b"offline":
@@ -1498,6 +1512,7 @@ async def transport_factory(
     disable_sending: bool | None = False,
     extra: dict[str, Any] | None = None,
     loop: asyncio.AbstractEventLoop | None = None,
+    log_all: bool = False,
     **kwargs: Any,  # HACK: odd/misc params
 ) -> RamsesTransportT:
     """Create and return a Ramses-specific async packet Transport."""
@@ -1549,19 +1564,24 @@ async def transport_factory(
             "Packet source must be exactly one of: packet_dict, packet_log, port_name"
         )
 
+    # File
     if (pkt_source := packet_log or packet_dict) is not None:
         return FileTransport(pkt_source, protocol, extra=extra, loop=loop, **kwargs)
 
     assert port_name is not None  # mypy check
     assert port_config is not None  # mypy check
 
+    # MQTT
     if port_name[:4] == "mqtt":  # TODO: handle disable_sending
-        transport = MqttTransport(port_name, protocol, extra=extra, loop=loop, **kwargs)
+        transport = MqttTransport(
+            port_name, protocol, extra=extra, loop=loop, log_all=log_all, **kwargs
+        )
 
         # TODO: remove this? better to invoke timeout after factory returns?
         await protocol.wait_for_connection_made(timeout=_DEFAULT_TIMEOUT_MQTT)
         return transport
 
+    # Serial
     ser_instance = get_serial_instance(port_name, port_config)
 
     if os.name == "nt" or ser_instance.portstr[:7] in ("rfc2217", "socket:"):

ramses_tx/version.py

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