mqttcommander 0.0.1__py3-none-any.whl

mqttcommander/Helper.py

@@ -0,0 +1,37 @@
+import json
+from datetime import datetime, date, timedelta
+from typing import Any
+from uuid import UUID
+
+
+def print_pretty_dict_json(data: Any, indent: int = 4) -> None:
+    print(json.dumps(data, indent=indent, sort_keys=True, cls=ComplexEncoder, default=str))
+
+
+def get_pretty_dict_json(data: Any, indent: int = 4) -> str:
+    return json.dumps(data, indent=indent, sort_keys=True, cls=ComplexEncoder, default=str)
+
+
+def get_pretty_dict_json_no_sort(data: Any, indent: int = 4) -> str:
+    return json.dumps(data, indent=indent, sort_keys=False, cls=ComplexEncoder, default=str)
+
+
+class ComplexEncoder(json.JSONEncoder):
+    def default(self, obj: Any) -> Any:
+        if hasattr(obj, "repr_json"):
+            return obj.repr_json()
+        elif hasattr(obj, "as_string"):
+            return obj.as_string()
+        elif isinstance(obj, UUID):
+            return str(obj)
+        elif isinstance(obj, datetime):
+            return obj.isoformat()  # strftime("%Y-%m-%d %H:%M:%S %Z")
+        elif isinstance(obj, date):
+            return obj.strftime("%Y-%m-%d")
+        elif isinstance(obj, timedelta):
+            return str(obj)
+        elif isinstance(obj, dict) or isinstance(obj, list):
+            robj: str = get_pretty_dict_json_no_sort(obj)
+            return robj
+        else:
+            return json.JSONEncoder.default(self, obj)

mqttcommander/__init__.py

@@ -0,0 +1,88 @@
+__version__ = "0.0.1"
+
+import os
+import sys
+from typing import Callable, Dict, Any
+
+from loguru import logger as glogger
+
+glogger.disable(__name__)
+
+
+def _loguru_skiplog_filter(record: dict) -> bool:
+    """Filter function to hide records with ``extra['skiplog']`` set.
+
+    Intended for use with ``loguru``'s ``filter=`` parameter so that callers can
+    temporarily suppress verbose logs for specific operations by binding
+    ``skiplog=True`` on the logger.
+
+    Args:
+        record (dict): Loguru record dictionary.
+
+    Returns:
+        bool: ``True`` to keep the record, ``False`` to skip it.
+    """
+    # {
+    #     "elapsed": timedelta,      # Zeit seit Programmstart
+    #     "exception": tuple,         # Exception-Info (type, value, traceback) oder None
+    #     "extra": dict,             # Benutzerdefinierte Extra-Felder
+    #     "file": RecordFile,        # Datei-Info (name, path)
+    #     "function": str,           # Name der Funktion
+    #     "level": RecordLevel,      # Level-Info (name, no, icon)
+    #     "line": int,               # Zeilennummer
+    #     "message": str,            # Formatierte Nachricht
+    #     "module": str,             # Modulname
+    #     "name": str,               # Logger-Name
+    #     "process": RecordProcess,  # Process-Info (id, name)
+    #     "thread": RecordThread,    # Thread-Info (id, name)
+    #     "time": datetime           # Zeitstempel des Log-Eintrags
+    # }
+    return not record.get("extra", {}).get("skiplog", False)
+
+
+def configure_loguru_default_with_skiplog_filter(
+    loguru_filter: Callable[[Dict[str, Any]], bool] = _loguru_skiplog_filter,
+) -> None:
+    """Configure a default ``loguru`` sink with a convenient format and filter.
+
+    This sets a colored formatter, applies the given filter (by default
+    :func:`_loguru_skiplog_filter`), and ensures a reasonable default log level
+    via the ``LOGURU_LEVEL`` environment variable.
+
+    Args:
+        loguru_filter: A callable taking a record dict and returning ``True``
+            if the record should be emitted. Defaults to
+            :func:`_loguru_skiplog_filter`.
+    """
+    glogger.info("configure_loguru_default_with_skiplog_filter")
+
+    os.environ["LOGURU_LEVEL"] = os.getenv("LOGURU_LEVEL", "DEBUG")  # standard is DEBUG
+    glogger.remove()  # remove default-handler
+    logger_fmt: str = (
+        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{module}</cyan>::<cyan>{extra[classname]}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>"
+    )
+    # logger_fmt: str = "<g>{time:HH:mm:ssZZ}</> | <lvl>{level}</> | <c>{module}::{extra[classname]}:{function}:{line}</> - {message}"
+
+    glogger.add(sys.stderr, level=os.getenv("LOGURU_LEVEL"), format=logger_fmt, filter=loguru_filter)  # type: ignore # TRACE | DEBUG | INFO | WARN | ERROR |  FATAL
+    glogger.configure(extra={"classname": "None", "skiplog": False})
+
+
+from .tasmotacommander import (
+    MqttCommander,
+    read_tasmotas_from_latest_file,
+    write_tasmota_devices_file,
+    TASMOTA_DEFAULT_TOPICS,
+    TASMOTA_DISCOVERY_TOPIC_BEGIN,
+    TASMOTA_LWT_TOPIC_BEGIN,
+    TASMOTA_LWT_TOPIC_END,
+)
+
+from .models import (
+    TasmotaDevice,
+    TasmotaDeviceConfig,
+    TasmotaDeviceSensors,
+    TasmotaTimerConfig,
+    TasmotaTimezoneConfig,
+    TasmotaRule,
+    TasmotaTimeZoneDSTSTD,
+)

mqttcommander/cli.py

@@ -0,0 +1,112 @@
+from typing import Optional, List, cast, Union
+
+from loguru import logger
+
+import mqttcommander
+from mqttcommander import (
+    MqttCommander,
+    TASMOTA_DEFAULT_TOPICS,
+    read_tasmotas_from_latest_file,
+    TasmotaDevice,
+)
+
+
+def _run(
+    host: str,
+    port: int,
+    username: str,
+    password: str,
+    action: str,
+    command: Optional[str] = None,
+    values: Optional[List[str]] = None,
+) -> None:
+    mqttcommander.configure_loguru_default_with_skiplog_filter()
+    logger.enable("mqttcommander")
+
+    comm: MqttCommander = MqttCommander(
+        topics=TASMOTA_DEFAULT_TOPICS,
+        host=host,
+        port=port,
+        username=username,
+        password=password,
+    )
+
+    match action:
+        case "readfromfile":
+            tasmotas = read_tasmotas_from_latest_file(noisy=True)
+            count = len(tasmotas) if tasmotas else 0
+            print(f"Loaded {count} tasmota devices from latest file")
+        case "list-retained":
+            msgs = comm.get_all_retained(noisy=False)
+            cnt = 0 if msgs is None else len(msgs)
+            print(f"Retained messages matching topics {comm.topics}: {cnt}")
+            if msgs:
+                for m in msgs[:10]:
+                    print(f"- {m.topic}")
+        case "list-tasmotas":
+            all_devs = comm.get_all_tasmota_devices_from_retained(noisy=False)
+            print(f"Found {len(all_devs)} tasmota devices from retained data")
+            for d in all_devs:
+                tc = d.tasmota_config
+                name = None
+                if tc is not None:
+                    name = tc.device_name or tc.friendly_name or tc.topic
+                print(f"- {name}")
+        case "list-online":
+            all_devs = comm.get_all_tasmota_devices_from_retained(noisy=False)
+            online = comm.filter_online_tasmotas_from_retained(all_devs)
+            print(f"Online devices: {len(online)} / {len(all_devs)}")
+            for d in online:
+                tc = d.tasmota_config
+                name = None
+                if tc is not None:
+                    name = tc.device_name or tc.friendly_name or tc.topic
+                print(f"- {name} online={d.lwt_current_value}")
+        case "send-cmd":
+            if not command:
+                raise SystemExit("--command is required for action send-cmd")
+            all_devs = comm.get_all_tasmota_devices_from_retained(noisy=False)
+            online = comm.filter_online_tasmotas_from_retained(all_devs)
+            vals_typed = cast(List[List[Union[str, float, dict, int]] | None] | None, [values] if values is not None else None)
+            comm.send_cmds_to_online_tasmotas(online, to_be_used_commands=[command], values_to_send=vals_typed)
+        case _:
+            raise SystemExit(f"Unknown action: {action}")
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="mqttcommander CLI")
+
+    # Common connection options
+    parser.add_argument("--host", type=str, required=True, help="MQTT broker host")
+    parser.add_argument("--port", type=int, required=True, help="MQTT broker port")
+    parser.add_argument("--username", type=str, required=True, help="MQTT username")
+    parser.add_argument("--password", type=str, required=True, help="MQTT password")
+
+    sub = parser.add_subparsers(dest="action", required=True)
+
+    sub.add_parser("readfromfile", help="Read latest saved tasmota devices file and show count")
+    sub.add_parser("list-retained", help="List count of retained messages for default topics")
+    sub.add_parser("list-tasmotas", help="Build device list from retained discovery and print devices")
+    sub.add_parser("list-online", help="Filter online devices and print them")
+
+    p_send = sub.add_parser("send-cmd", help="Send a command to all online devices")
+    p_send.add_argument("--command", required=True, help="Command, e.g. Power")
+    p_send.add_argument("--values", nargs="*", help="Values to send, e.g. Toggle or 1 0 ...")
+
+    args = parser.parse_args(argv)  # argv wird hier verwendet
+
+    _run(
+        host=args.host,
+        port=args.port,
+        username=args.username,
+        password=args.password,
+        action=args.action,
+        command=getattr(args, "command", None),
+        values=getattr(args, "values", None),
+    )
+
+
+if __name__ == "__main__":
+    main()

mqttcommander/models.py

@@ -0,0 +1,201 @@
+from datetime import datetime
+from io import StringIO
+from typing import Optional, Annotated, List, Literal, Any, Self
+
+from pydantic import BaseModel, Field, AliasPath, field_validator, AliasChoices
+from pydantic.networks import IPv4Address
+from pydantic_extra_types.mac_address import MacAddress
+
+
+class TasmotaTimerConfig(BaseModel):
+    # Enable	0 = disarm or disable timer
+    # 1 = arm or enable timer
+    enable: Optional[Annotated[int, Field(ge=0, le=1)]] = Field(None, validation_alias=AliasChoices("Enable", "enable"))
+
+    # Mode	0 = use clock time
+    # 1 = Use local sunrise time using Longitude, Latitude and Time offset
+    # 2 = use local sunset time using Longitude, Latitude and Time offset
+    mode: Optional[Annotated[int, Field(ge=0, le=2)]] = Field(None, validation_alias=AliasChoices("Mode", "mode"))
+
+    # Time	When Mode 0 is active
+    # > hh:mm = set time in hours 0 .. 23 and minutes 0 .. 59
+    # When Mode 1 or Mode 2 is active
+    # > +hh:mm or -hh:mm = set offset in hours 0 .. 11 and minutes 0 .. 59 from the time defined by sunrise/sunset.
+    time: Optional[str] = Field(None, validation_alias=AliasChoices("Time", "time"))
+
+    # Window	0..15 = add or subtract a random number of minutes to Time
+    window: Optional[Annotated[int, Field(ge=0, le=15)]] = Field(
+        None, validation_alias=AliasChoices("Window", "window")
+    )
+
+    # Days	SMTWTFS = set day of weeks mask where 0 or - = OFF and any different character = ON
+    days: Optional[Annotated[str, Field(pattern="[1|0|-]{7}")]] = Field(
+        None, validation_alias=AliasChoices("Days", "days")
+    )
+
+    # Repeat	0 = allow timer only once
+    # 1 = repeat timer execution
+    repeat: Optional[Annotated[int, Field(ge=0, le=1)]] = Field(None, validation_alias=AliasChoices("Repeat", "repeat"))
+
+    # Output	1..16 = select an output to be used if no rule is enabled
+    output: Optional[Annotated[int, Field(ge=1, le=16)]] = Field(
+        None, validation_alias=AliasChoices("Output", "output")
+    )
+
+    # Action	0 = turn output OFF
+    # 1 = turn output ON
+    # 2 = TOGGLE output
+    # 3 = RULE/BLINK
+    # If the Tasmota Rules feature has been activated by compiling the code (activated by default in all pre-compiled Tasmota binaries), a rule with Clock#Timer=<timer> will be triggered if written and turned on by the user.
+    # If Rules are not compiled, BLINK output using BlinkCount parameters.
+    action: Optional[Annotated[int, Field(ge=1, le=16)]] = Field(
+        None, validation_alias=AliasChoices("Action", "action")
+    )
+
+    # {"Timer1":{"Enable":1,"Mode":0,"Time":"22:00","Window":0,"Days":"1111111","Repeat":1,"Output":1,"Action":0}}
+
+
+class TasmotaTimeZoneDSTSTD(BaseModel):
+    hemisphere: Optional[int] = Field(None, validation_alias=AliasChoices("Hemisphere", "hemisphere"))
+    week: Optional[int] = Field(None, validation_alias=AliasChoices("Week", "week"))
+    month: Optional[int] = Field(None, validation_alias=AliasChoices("Month", "month"))
+    day: Optional[int] = Field(None, validation_alias=AliasChoices("Day", "day"))
+    hour: Optional[int] = Field(None, validation_alias=AliasChoices("Hour", "hour"))
+    offset: Optional[int] = Field(None, validation_alias=AliasChoices("Offset", "offset"))
+
+    def to_tasmota_command_string(self) -> str:
+        return str([self.hemisphere,self.week,self.month,self.day,self.hour,self.offset]).replace(" ", "")
+
+    @classmethod
+    def from_tasmota_command_string(cls, values_comma_separated: str) -> TasmotaTimeZoneDSTSTD:
+        data: List[str] = values_comma_separated.split(",")
+
+        assert len(data) == 6
+
+        return TasmotaTimeZoneDSTSTD(
+            hemisphere=int(data[0]),
+            week=int(data[1]),
+            month=int(data[2]),
+            day=int(data[3]),
+            hour=int(data[4]),
+            offset=int(data[5])
+        )
+
+class TasmotaTimezoneConfig(BaseModel):
+    latitude: Optional[float] = Field(None, validation_alias=AliasChoices("Latitude", "latitude"))
+    longitude: Optional[float] = Field(None, validation_alias=AliasChoices("Longitude", "longitude"))
+    timedst: Optional[TasmotaTimeZoneDSTSTD] = Field(None, validation_alias=AliasChoices("TimeDst", "timedst"))
+    timestd: Optional[TasmotaTimeZoneDSTSTD] = Field(None, validation_alias=AliasChoices("TimeStd", "timestd"))
+    timezone: Optional[int | str] = Field(None, validation_alias=AliasChoices("Timezone", "timezone"))  # 99 | +01:00
+
+    def as_tasmota_command_list(self) -> List[str | float | dict[Any, Any] | int] | None:
+        assert self.latitude is not None and \
+            self.longitude is not None and \
+            self.timedst is not None and \
+            self.timestd is not None and \
+            self.timezone is not None
+
+        return [
+                self.latitude,
+                self.longitude,
+                self.timedst.to_tasmota_command_string(),  # that is correct!
+                self.timestd.to_tasmota_command_string(),  # that is correct!
+                self.timezone
+            ]
+
+    def to_tasmota_command_string(self) -> str:
+        return str(self.as_tasmota_command_list()).replace(" ", "")
+
+
+class TasmotaDeviceConfig(BaseModel):
+    friendly_name: Optional[str] = Field(
+        None, validation_alias=AliasChoices("friendly_name", AliasPath("fn", 0))
+    )  # friendly name -> first element of list of strings?
+    device_name: Optional[str] = Field(None, validation_alias=AliasChoices("dn", "device_name"))
+    hostname: Optional[str] = Field(None, validation_alias=AliasChoices("hn", "hostname"))  # host name
+    manufacturer_description: Optional[str] = Field(
+        None, validation_alias=AliasChoices("md", "manufacturer_description")
+    )  # manufacturer description ?!
+    ip: Optional[IPv4Address] = None
+    mac: Optional[MacAddress] = None
+    offline_msg: Optional[str] = Field(None, validation_alias=AliasChoices("ofln", "offline_msg"))
+    online_msg: Optional[str] = Field(None, validation_alias=AliasChoices("onln", "online_msg"))
+    state: Optional[List[str]] = None
+    # t: str = Field(alias="topic", validation_alias='t')
+    topic: Optional[str] = Field(None, validation_alias=AliasChoices("t", "topic"))
+    tp: Optional[List[str]] = Field(None)
+    software_version: Optional[str] = Field(None, validation_alias=AliasChoices("sw", "software_version"))
+    timezoneconfig: Optional[TasmotaTimezoneConfig] = None
+    teleperiod: Optional[int] = Field(None, validation_alias=AliasChoices("TelePeriod", "teleperiod"))
+    powerdelta1: Optional[int] = Field(None, validation_alias=AliasChoices("PowerDelta1", "powerdelta1"))
+    setoption4: Optional[Literal["ON", "OFF"]] = Field(None, validation_alias=AliasChoices("SetOption4", "setoption4"))
+    timer1: Optional[TasmotaTimerConfig] = Field(None, validation_alias=AliasChoices("Timer1", "timer1"))
+    timer2: Optional[TasmotaTimerConfig] = Field(None, validation_alias=AliasChoices("Timer2", "timer2"))
+    timer3: Optional[TasmotaTimerConfig] = Field(None, validation_alias=AliasChoices("Timer2", "timer3"))
+    timer4: Optional[TasmotaTimerConfig] = Field(None, validation_alias=AliasChoices("Timer4", "timer4"))
+
+    # SSID1
+    # SSID2
+    # powerdelta
+    # ampres
+    # voltres
+    # setoption4
+    # SetOption53 1; SetOption56 0; SetOption57 0;
+
+    @field_validator("mac", mode="before")
+    @classmethod
+    def validate_mac(cls, v: Any) -> Optional[str]:
+        # logger.debug(f"VALIDATE MAC: {v}")
+        if not v:
+            return None
+
+        return cls.mac_no_colon_to_colon(v)
+
+    @staticmethod
+    def mac_no_colon_to_colon(mac: str) -> str:
+        if mac.find(":") == 2:
+            return mac
+
+        ret: StringIO = StringIO()
+        for ch2i in range(0, len(mac), 2):
+            if ret.tell() > 0:
+                ret.write(":")
+            ret.write(mac[ch2i : ch2i + 2])
+
+        return ret.getvalue()
+
+
+class TasmotaRule(BaseModel):
+    state: Optional[Literal["ON", "OFF"]] = Field(None, validation_alias=AliasChoices("State", "state"))
+    once: Optional[Literal["ON", "OFF"]] = Field(None, validation_alias=AliasChoices("Once", "once"))
+    stoponerror: Optional[Literal["ON", "OFF"]] = Field(
+        None, validation_alias=AliasChoices("StopOnError", "stoponerror")
+    )
+    length: Optional[int] = Field(None, validation_alias=AliasChoices("Length", "length"))
+    rules: Optional[str] = Field(None, validation_alias=AliasChoices("Rules", "rules"))
+
+
+class TasmotaDeviceSensors(BaseModel):
+    # tasmota/discovery/x/sensors
+    # sn: dict
+    time: datetime = Field(..., validation_alias=AliasChoices("time", "Time", AliasPath("sn", "Time")))
+
+    # {"sn": {"Time": "2024-07-04T13:09:25", "ANALOG": {"A0": 169},
+    #        "SHT3X": {"Temperature": 26.1, "Humidity": 44.5, "DewPoint": 13.1}, "TempUnit": "C"}, "ver": 1}
+
+
+class TasmotaDevice(BaseModel):
+    # tasmota/discovery/x/config
+    tasmota_config: Optional[TasmotaDeviceConfig] = None
+    tasmota_sensors: Optional[TasmotaDeviceSensors] = None
+    tasmota_rule1: Optional[TasmotaRule] = None
+    tasmota_rule2: Optional[TasmotaRule] = None
+    tasmota_rule3: Optional[TasmotaRule] = None
+
+    lwt_current_value: Optional[Literal["Online", "Offline"]] = None
+
+    def is_online(self, lwt_online_default_value: str = "Online") -> bool:
+        if self.tasmota_config and self.tasmota_config.online_msg:
+            return self.lwt_current_value == self.tasmota_config.online_msg
+
+        return self.lwt_current_value == lwt_online_default_value