enviroplussensorstomqtt 0.1.0__py3-none-any.whl

enviroplussensorstomqtt/__init__.py

@@ -0,0 +1,5 @@
+"""Enviroplus sensors to MQTT."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

enviroplussensorstomqtt/args.py

@@ -0,0 +1,160 @@
+"""Args handler module."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Any
+
+from .config import parse_config, validate_config
+
+
+def args_handler(
+    argv: list[str] | None = None,
+    *,
+    config_file: str | None = None,
+    validate: bool = False,
+) -> dict[str, Any]:
+    """
+    Function for reading arguments and config file.
+
+    Args:
+        argv (list[str], optional): Arguments list to parse. Defaults to sys.argv[1:].
+        config_file (str, optional): Default config file to use if not overridden by CLI.
+        validate (bool, optional): Whether to validate config immediately against AppConfig schema.
+
+    Returns:
+        dict: Parsed and merged configuration dictionary.
+    """
+    parser = argparse.ArgumentParser(description="Publish Enviro+ sensor data to MQTT")
+    parser.add_argument("--username", type=str, required=False, help="MQTT username")
+    parser.add_argument("--password", type=str, required=False, help="MQTT password")
+    parser.add_argument("--host", type=str, required=False, help="MQTT broker host")
+    parser.add_argument("--port", type=int, required=False, help="MQTT broker port")
+    parser.add_argument("--topics", type=str, required=False, help="Comma-separated MQTT topics")
+    parser.add_argument("--config_file", type=str, required=False, help="Path to YAML configuration file")
+    parser.add_argument("--log_file", type=str, required=False, help="Path to log file")
+    parser.add_argument("--interval", type=float, required=False, help="Interval in seconds between cycles")
+    parser.add_argument("--measurements", type=int, required=False, help="Number of samples to average per cycle")
+    parser.add_argument(
+        "--temperature_offset",
+        type=float,
+        required=False,
+        help="Temperature offset in °C to subtract/compensate for self-heating",
+    )
+    parser.add_argument("--client_id", type=str, required=False, help="MQTT client ID")
+    parser.add_argument("--tls", action=argparse.BooleanOptionalAction, default=None, help="Enable TLS")
+    parser.add_argument("--tls_ca_certs", type=str, required=False, help="Path to CA certificate")
+    parser.add_argument("--tls_certfile", type=str, required=False, help="Path to client certificate")
+    parser.add_argument("--tls_keyfile", type=str, required=False, help="Path to client key")
+    parser.add_argument("--tls_insecure", action=argparse.BooleanOptionalAction, default=None, help="Skip TLS verify")
+    parser.add_argument(
+        "--per_metric_topics", action=argparse.BooleanOptionalAction, default=None, help="Publish per-metric"
+    )
+    parser.add_argument(
+        "--ha_discovery", action=argparse.BooleanOptionalAction, default=None, help="Enable HA discovery"
+    )
+    parser.add_argument("--ha_discovery_prefix", type=str, required=False, help="HA discovery prefix")
+    parser.add_argument("--device_id", type=str, required=False, help="Device ID for HA discovery")
+    parser.add_argument(
+        "--disable-ltr559",
+        action="store_true",
+        help="Disable LTR559 light and proximity sensor",
+    )
+    parser.add_argument("-D", "--debug", action="store_true", help="Enable debug logging")
+    args = parser.parse_args(argv)
+
+    if args.config_file:
+        config = parse_config(config_file=args.config_file)
+    elif config_file:
+        config = parse_config(config_file=config_file)
+    elif os.path.isfile("/etc/enviroplussensorstomqtt.yaml"):
+        config = parse_config(config_file="/etc/enviroplussensorstomqtt.yaml")
+    elif os.path.isfile("config.yaml"):
+        config = parse_config(config_file="config.yaml")
+    else:
+        config = parse_config()
+
+    if args.username is not None:
+        config["username"] = args.username
+
+    if args.password is not None:
+        config["password"] = args.password
+
+    if args.host is not None:
+        config["host"] = args.host
+
+    if args.port is not None:
+        config["port"] = args.port
+
+    if args.debug:
+        config["debug"] = True
+
+    if args.disable_ltr559:
+        config["enable_ltr559"] = False
+
+    if args.log_file is not None:
+        config["log_file"] = args.log_file
+
+    if args.interval is not None:
+        config["interval"] = args.interval
+
+    if args.measurements is not None:
+        config["measurements"] = args.measurements
+
+    if args.temperature_offset is not None:
+        config["temperature_offset"] = args.temperature_offset
+
+    if args.topics is not None:
+        config["topics"] = [item.strip() for item in args.topics.split(",") if item.strip()]
+
+    if args.client_id is not None:
+        config["client_id"] = args.client_id
+
+    if args.tls is not None:
+        config["tls"] = args.tls
+
+    if args.tls_ca_certs is not None:
+        config["tls_ca_certs"] = args.tls_ca_certs
+
+    if args.tls_certfile is not None:
+        config["tls_certfile"] = args.tls_certfile
+
+    if args.tls_keyfile is not None:
+        config["tls_keyfile"] = args.tls_keyfile
+
+    if args.tls_insecure is not None:
+        config["tls_insecure"] = args.tls_insecure
+
+    if args.per_metric_topics is not None:
+        config["per_metric_topics"] = args.per_metric_topics
+
+    if args.ha_discovery is not None:
+        config["ha_discovery"] = args.ha_discovery
+
+    if args.ha_discovery_prefix is not None:
+        config["ha_discovery_prefix"] = args.ha_discovery_prefix
+
+    if args.device_id is not None:
+        config["device_id"] = args.device_id
+
+    # Environment variable fallbacks for secrets and broker config
+    if not config.get("password") and "MQTT_PASSWORD" in os.environ:
+        config["password"] = os.environ["MQTT_PASSWORD"]
+
+    if not config.get("username") and "MQTT_USERNAME" in os.environ:
+        config["username"] = os.environ["MQTT_USERNAME"]
+
+    if not config.get("host") and "MQTT_HOST" in os.environ:
+        config["host"] = os.environ["MQTT_HOST"]
+
+    # Validate configuration if requested
+    if validate:
+        app_config = validate_config(config)
+        config = app_config.to_dict()
+
+    if config.get("debug"):
+        debug_config = {k: ("***" if k == "password" and v else v) for k, v in config.items()}
+        print(f"config: {debug_config}")
+
+    return config

enviroplussensorstomqtt/config.py

@@ -0,0 +1,218 @@
+"""Config module."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class AppConfig:
+    """Validated application configuration."""
+
+    host: str
+    topics: list[str]
+    port: int = 1883
+    username: str | None = None
+    password: str | None = None
+    client_id: str | None = None
+    qos: int = 1
+    retain: bool = True
+    debug: bool = False
+    log_file: str | None = None
+    interval: float = 60.0
+    measurements: int = 3
+    temperature_offset: float = 0.0
+    enable_ltr559: bool = True
+    tls: bool = False
+    tls_ca_certs: str | None = None
+    tls_certfile: str | None = None
+    tls_keyfile: str | None = None
+    tls_insecure: bool = False
+    per_metric_topics: bool = False
+    ha_discovery: bool = False
+    ha_discovery_prefix: str = "homeassistant"
+    device_id: str = "enviroplus"
+
+    def __post_init__(self) -> None:
+        self.validate()
+
+    def validate(self) -> None:
+        """Validate configuration values and raise ValueError on error."""
+        if not self.host or not isinstance(self.host, str) or not self.host.strip():
+            raise ValueError("Configuration error: 'host' must be a non-empty string.")
+
+        if not self.topics:
+            raise ValueError("Configuration error: 'topics' must be a non-empty list of topic strings.")
+
+        if isinstance(self.topics, str):
+            raise ValueError("Configuration error: 'topics' must be a list of strings, not a single string.")
+
+        if not all(isinstance(t, str) and t.strip() for t in self.topics):
+            raise ValueError("Configuration error: all items in 'topics' must be non-empty strings.")
+
+        try:
+            port_num = int(self.port)
+        except (ValueError, TypeError):
+            raise ValueError(f"Configuration error: 'port' must be an integer, got {self.port!r}.") from None
+
+        if not (1 <= port_num <= 65535):
+            raise ValueError(f"Configuration error: 'port' must be between 1 and 65535, got {port_num}.")
+        self.port = port_num
+
+        try:
+            qos_num = int(self.qos)
+        except (ValueError, TypeError):
+            raise ValueError(f"Configuration error: 'qos' must be an integer, got {self.qos!r}.") from None
+
+        if qos_num not in (0, 1, 2):
+            raise ValueError(f"Configuration error: 'qos' must be 0, 1, or 2, got {qos_num}.")
+        self.qos = qos_num
+
+        try:
+            self.interval = float(self.interval)
+            if self.interval <= 0:
+                raise ValueError
+        except (ValueError, TypeError):
+            msg = f"Configuration error: 'interval' must be a positive number, got {self.interval!r}."
+            raise ValueError(msg) from None
+
+        try:
+            self.measurements = int(self.measurements)
+            if self.measurements <= 0:
+                raise ValueError
+        except (ValueError, TypeError):
+            raise ValueError(
+                f"Configuration error: 'measurements' must be a positive integer, got {self.measurements!r}."
+            ) from None
+
+        try:
+            self.temperature_offset = float(self.temperature_offset)
+        except (ValueError, TypeError):
+            raise ValueError(
+                f"Configuration error: 'temperature_offset' must be a float, got {self.temperature_offset!r}."
+            ) from None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert config to dictionary format for backward compatibility."""
+        return {
+            "host": self.host,
+            "topics": self.topics,
+            "port": self.port,
+            "username": self.username,
+            "password": self.password,
+            "client_id": self.client_id,
+            "qos": self.qos,
+            "retain": self.retain,
+            "debug": self.debug,
+            "log_file": self.log_file,
+            "interval": self.interval,
+            "measurements": self.measurements,
+            "temperature_offset": self.temperature_offset,
+            "enable_ltr559": self.enable_ltr559,
+            "tls": self.tls,
+            "tls_ca_certs": self.tls_ca_certs,
+            "tls_certfile": self.tls_certfile,
+            "tls_keyfile": self.tls_keyfile,
+            "tls_insecure": self.tls_insecure,
+            "per_metric_topics": self.per_metric_topics,
+            "ha_discovery": self.ha_discovery,
+            "ha_discovery_prefix": self.ha_discovery_prefix,
+            "device_id": self.device_id,
+        }
+
+
+def get_default_config() -> dict[str, Any]:
+    """Return default configuration options."""
+    return {
+        "debug": False,
+        "port": 1883,
+        "client_id": None,
+        "qos": 1,
+        "retain": True,
+        "log_file": None,
+        "interval": 60.0,
+        "measurements": 3,
+        "temperature_offset": 0.0,
+        "enable_ltr559": True,
+        "tls": False,
+        "tls_ca_certs": None,
+        "tls_certfile": None,
+        "tls_keyfile": None,
+        "tls_insecure": False,
+        "per_metric_topics": False,
+        "ha_discovery": False,
+        "ha_discovery_prefix": "homeassistant",
+        "device_id": "enviroplus",
+    }
+
+
+def parse_config(config_file: str | None = None) -> dict[str, Any]:
+    """
+    Parse configuration file in YAML format.
+
+    Args:
+        config_file (str, optional): Path to configuration file. If None, returns default config.
+
+    Returns:
+        dict: A dictionary containing parsed configuration values merged with defaults.
+
+    Raises:
+        FileNotFoundError: If the specified config file is not found.
+    """
+    config = get_default_config()
+
+    if config_file is not None:
+        if not os.path.isfile(config_file):
+            raise FileNotFoundError(f"Configuration file '{config_file}' not found.")
+
+        with open(config_file, encoding="utf-8") as stream:
+            loaded = yaml.safe_load(stream)
+            if loaded and isinstance(loaded, dict):
+                config.update(loaded)
+
+    for k, v in get_default_config().items():
+        config.setdefault(k, v)
+
+    # Normalize topics if given as comma-separated string in YAML
+    if isinstance(config.get("topics"), str):
+        config["topics"] = [t.strip() for t in config["topics"].split(",") if t.strip()]
+
+    return config
+
+
+def validate_config(config: dict[str, Any]) -> AppConfig:
+    """Validate a raw configuration dict and return an AppConfig instance."""
+    # Normalize topics if still string
+    topics = config.get("topics")
+    if isinstance(topics, str):
+        topics = [t.strip() for t in topics.split(",") if t.strip()]
+
+    return AppConfig(
+        host=config.get("host", ""),
+        topics=topics if isinstance(topics, list) else [],
+        port=config.get("port", 1883),
+        username=config.get("username"),
+        password=config.get("password"),
+        client_id=config.get("client_id"),
+        qos=int(config.get("qos", 1)),
+        retain=bool(config.get("retain", True)),
+        debug=bool(config.get("debug", False)),
+        log_file=config.get("log_file"),
+        interval=config.get("interval", 60.0),
+        measurements=config.get("measurements", 3),
+        temperature_offset=config.get("temperature_offset", 0.0),
+        enable_ltr559=bool(config.get("enable_ltr559", True)),
+        tls=bool(config.get("tls", False)),
+        tls_ca_certs=config.get("tls_ca_certs"),
+        tls_certfile=config.get("tls_certfile"),
+        tls_keyfile=config.get("tls_keyfile"),
+        tls_insecure=bool(config.get("tls_insecure", False)),
+        per_metric_topics=bool(config.get("per_metric_topics", False)),
+        ha_discovery=bool(config.get("ha_discovery", False)),
+        ha_discovery_prefix=str(config.get("ha_discovery_prefix", "homeassistant")),
+        device_id=str(config.get("device_id", "enviroplus")),
+    )

enviroplussensorstomqtt/hardware.py

@@ -0,0 +1,173 @@
+"""Hardware interface and adapter for Enviro+ sensors."""
+
+from __future__ import annotations
+
+import logging
+from typing import NamedTuple, Protocol
+
+LOGGER = logging.getLogger(__name__)
+
+
+class GasReadings(NamedTuple):
+    oxidising: float
+    reducing: float
+    nh3: float
+
+
+class PMReadings(NamedTuple):
+    pm1: float
+    pm25: float
+    pm10: float
+
+
+class NoiseReadings(NamedTuple):
+    low: float
+    mid: float
+    high: float
+    amp: float
+
+
+class LightReadings(NamedTuple):
+    lux: float
+    proximity: int
+
+
+class HardwareInterface(Protocol):
+    """Protocol defining hardware operations for Enviro+ sensors."""
+
+    def read_temperature(self) -> float: ...
+    def read_humidity(self) -> float: ...
+    def read_pressure(self) -> float: ...
+    def read_noise(self) -> NoiseReadings: ...
+    def read_gas(self) -> GasReadings: ...
+    def read_pm(self) -> PMReadings: ...
+    def read_light(self) -> LightReadings: ...
+    def close(self) -> None: ...
+
+
+class EnviroPlusHardware:
+    """Hardware adapter for real Enviro+ hardware."""
+
+    def __init__(self, bus_id: int = 1) -> None:
+        self.bus_id = bus_id
+        self._bus = None
+        self._bme280 = None
+        self._noise = None
+        self._gas = None
+        self._pms5003 = None
+        self._ltr559 = None
+
+    def get_bme280(self):
+        """Lazily initialize BME280 sensor."""
+        if self._bme280 is None:
+            try:
+                from smbus2 import SMBus
+            except ImportError:
+                from smbus import SMBus  # type: ignore[import-not-found]
+            from bme280 import BME280
+
+            self._bus = SMBus(self.bus_id)
+            self._bme280 = BME280(i2c_dev=self._bus)
+        return self._bme280
+
+    def get_noise(self):
+        """Lazily initialize Noise sensor."""
+        if self._noise is None:
+            from enviroplus.noise import Noise
+
+            self._noise = Noise()
+        return self._noise
+
+    def get_gas(self):
+        """Lazily initialize Gas sensor."""
+        if self._gas is None:
+            from enviroplus import gas
+
+            self._gas = gas
+        return self._gas
+
+    def get_pms5003(self):
+        """Lazily initialize PMS5003 particle sensor."""
+        if self._pms5003 is None:
+            from pms5003 import PMS5003
+
+            self._pms5003 = PMS5003()
+        return self._pms5003
+
+    def get_ltr559(self):
+        """Lazily initialize LTR559 light and proximity sensor."""
+        if self._ltr559 is None:
+            try:
+                from ltr559 import LTR559
+
+                self._ltr559 = LTR559()
+            except Exception as exc:
+                LOGGER.debug("LTR559 sensor not available: %s", exc)
+                return None
+        return self._ltr559
+
+    def read_temperature(self) -> float:
+        """Read temperature in Celsius."""
+        return float(self.get_bme280().get_temperature())
+
+    def read_humidity(self) -> float:
+        """Read relative humidity in percent."""
+        return float(self.get_bme280().get_humidity())
+
+    def read_pressure(self) -> float:
+        """Read atmospheric pressure in mbar."""
+        return float(self.get_bme280().get_pressure())
+
+    def read_noise(self) -> NoiseReadings:
+        """Read noise frequency bands and amplitude."""
+        low, mid, high, amp = self.get_noise().get_noise_profile()
+        return NoiseReadings(low=float(low), mid=float(mid), high=float(high), amp=float(amp))
+
+    def read_gas(self) -> GasReadings:
+        """Read gas resistances in Ohms."""
+        readings = self.get_gas().read_all()
+        return GasReadings(
+            oxidising=float(readings.oxidising),
+            reducing=float(readings.reducing),
+            nh3=float(readings.nh3),
+        )
+
+    def read_pm(self) -> PMReadings:
+        """Read particulate matter (PM1, PM2.5, PM10)."""
+        from pms5003 import ReadTimeoutError
+
+        pms = self.get_pms5003()
+        try:
+            raw = pms.read()
+        except ReadTimeoutError:
+            pms.reset()
+            raw = pms.read()
+        return PMReadings(
+            pm1=float(raw.pm_ug_per_m3(1)),
+            pm25=float(raw.pm_ug_per_m3(2.5)),
+            pm10=float(raw.pm_ug_per_m3(10)),
+        )
+
+    def read_light(self) -> LightReadings:
+        """Read lux and proximity from LTR559."""
+        ltr = self.get_ltr559()
+        if ltr is None:
+            raise RuntimeError("LTR559 sensor not initialized")
+        ltr.update_sensor()
+        lux = float(ltr.get_lux())
+        proximity = int(ltr.get_proximity())
+        return LightReadings(lux=lux, proximity=proximity)
+
+    def close(self) -> None:
+        """Release hardware handles."""
+        if self._bus is not None and hasattr(self._bus, "close"):
+            try:
+                self._bus.close()
+            except Exception as exc:
+                LOGGER.debug("Error closing I2C bus: %s", exc)
+            self._bus = None
+        self._bme280 = None
+        self._noise = None
+        self._gas = None
+        self._pms5003 = None
+        self._ltr559 = None

enviroplussensorstomqtt/log_setup.py

@@ -0,0 +1,36 @@
+"""Logging setup module."""
+
+import logging
+import logging.handlers
+
+
+def setup_logger(
+    *,
+    debug: bool = False,
+    log_file: str | None = None,
+) -> logging.Logger:
+    """Configure root logger with console and optional rotating file handler."""
+    root = logging.getLogger()
+    formatter = logging.Formatter(
+        "%(asctime)s %(process)d %(processName)-10s %(name)-8s %(funcName)-8s %(levelname)-8s %(message)s"
+    )
+
+    # Always attach a console handler so stdout/stderr (and systemd journald) captures logs
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+    root.addHandler(console_handler)
+
+    if debug:
+        root.setLevel(logging.DEBUG)
+    else:
+        root.setLevel(logging.INFO)
+
+    if log_file:
+        try:
+            file_handler = logging.handlers.RotatingFileHandler(log_file, "a", maxBytes=3 * 10**6, backupCount=10)
+            file_handler.setFormatter(formatter)
+            root.addHandler(file_handler)
+        except OSError as exc:
+            root.warning("Failed to initialize log file '%s': %s. Continuing with console logging.", log_file, exc)
+
+    return root