foresttm23-iot 0.1.3.5__tar.gz

foresttm23_iot-0.1.3.5/.gitignore

@@ -0,0 +1,14 @@
+.venv
+.idea
+.env
+
+__pycache__/
+*.pyc
+
+*.coverage
+
+*logs
+
+*.pypirc
+
+dist

foresttm23_iot-0.1.3.5/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.13-slim
+
+WORKDIR /iot_framework
+
+RUN pip install uv
+
+COPY pyproject.toml .
+
+RUN uv pip install --system --no-cache -r pyproject.toml
+
+COPY . .
+
+CMD ["python", "main.py"]

foresttm23_iot-0.1.3.5/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: foresttm23-iot
+Version: 0.1.3.5
+Summary: Implementation of the IoT system. For usage you have to run a mqtt broker.
+Project-URL: Homepage, https://github.com/Foresttm23/mqtt-iot-framework
+Project-URL: Repository, https://github.com/Foresttm23/mqtt-iot-framework
+Project-URL: Issues, https://github.com/Foresttm23/mqtt-iot-framework/issues
+Author-email: Foresttm23 <max.gogulia@gmail.com>
+Keywords: devices,home-automation,iot,mqtt,sensors,smart-home
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: paho-mqtt>=2.1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.3.0; extra == 'dev'
+Requires-Dist: hatchling>=1.28.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: testcontainers[mqtt]>=4.13.3; extra == 'dev'
+Requires-Dist: twine>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Extensible MQTT IoT Communication Framework
+
+A lightweight **Python framework** for building **MQTT-based IoT systems**. It provides reusable base classes for hubs, devices, sensors, and MQTT clients, making it easier to implement custom IoT workflows with a consistent architecture.
+
+- **PyPI:** [foresttm23-iot](https://pypi.org/project/foresttm23-iot/)
+- **Requires:** Python 3.13+
+
+## Overview
+
+This framework is designed for object-oriented IoT development and is centered around reusable base abstractions for:
+
+- `BaseMqttClient` — base class for MQTT clients
+- `BaseIot` — shared base class for sensors and devices
+- `BaseDevice` — base class for IoT devices
+- `BaseSensor` — base class for IoT sensors
+- `BaseHub` — base class for IoT hubs
+
+It also includes a registry system that allows IoT classes to be dynamically discovered and instantiated by their `sub_type`.
+
+## Key Features
+
+- MQTT-based IoT architecture
+- Reusable base classes for hubs, devices, and sensors
+- Class registry for dynamic IoT type lookup
+- Support for custom and extended IoT implementations
+- Built-in logging and helper utilities
+- Designed to work with an MQTT broker
+
+## Core Concepts
+
+### Registry System
+
+Use the `@register_iot` decorator to register your IoT classes:
+
+```python
+from iot_framework import BaseDevice, register_iot
+
+
+@register_iot
+class LampDevice(BaseDevice):
+    sub_type = "lamp"
+```
+
+This registers the class in the framework’s internal registry so it can be instantiated dynamically with `get_iot_class()`.
+
+### Base Classes
+
+- **`BaseMqttClient`**: Provides the shared MQTT client behavior.
+- **`BaseIot`**: Adds shared IoT functionality for sensors and devices.
+- **`BaseDevice` / `BaseSensor`**: Specialized implementations for device and sensor behavior.
+- **`BaseHub`**: Coordinates devices and sensors, handles discovery, and manages device interactions.
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install foresttm23-iot
+```
+
+Or install dependencies for local development using the project’s environment setup.
+
+## Usage
+
+### Run the framework entry point
+
+```bash
+python main.py <hub_sub_type> <device_sub_type> <sensor_sub_type>
+```
+
+Example:
+
+```bash
+python main.py hub lamp motion
+```
+
+This launches the requested IoT processes and connects them to the configured MQTT broker.
+
+### Example Device
+
+```python
+import json
+import time
+
+from iot_framework import BaseDevice, logger, register_iot
+
+
+@register_iot
+class LampDevice(BaseDevice):
+    sub_type = "lamp"
+
+    def __init__(self, client, device_id: str):
+        super().__init__(client, device_id, self.sub_type)
+
+    def on_message(self, client, userdata, msg) -> None:
+        payload = json.loads(msg.payload.decode())
+        command = payload.get("command").lower()
+        transaction_id = payload.get("transaction_id")
+
+        logger.info(f"📩 [{self.id}] Received command: {command}")
+        self.set_state(command)
+
+        lamp_payload = json.dumps(
+            {
+                "state": self.state,
+                "transaction_id": transaction_id,
+                "timestamp": time.time(),
+            }
+        )
+        self.client.publish(self.state_topic, lamp_payload, retain=True)
+```
+
+## Requirements
+
+- Python 3.13+
+- MQTT broker
+- `loguru`
+- `paho-mqtt`
+
+## Project Structure
+
+- `iot_framework/` — framework package
+- `main.py` — launcher for IoT processes
+- `docker-compose.yml` — container setup
+- `Dockerfile` — image definition
+- `load_test.jmx` — performance/load testing
+- `mosquitto.conf` — MQTT broker configuration
+
+## License
+
+No license has been specified for this project.

foresttm23_iot-0.1.3.5/README.md

@@ -0,0 +1,131 @@
+# Extensible MQTT IoT Communication Framework
+
+A lightweight **Python framework** for building **MQTT-based IoT systems**. It provides reusable base classes for hubs, devices, sensors, and MQTT clients, making it easier to implement custom IoT workflows with a consistent architecture.
+
+- **PyPI:** [foresttm23-iot](https://pypi.org/project/foresttm23-iot/)
+- **Requires:** Python 3.13+
+
+## Overview
+
+This framework is designed for object-oriented IoT development and is centered around reusable base abstractions for:
+
+- `BaseMqttClient` — base class for MQTT clients
+- `BaseIot` — shared base class for sensors and devices
+- `BaseDevice` — base class for IoT devices
+- `BaseSensor` — base class for IoT sensors
+- `BaseHub` — base class for IoT hubs
+
+It also includes a registry system that allows IoT classes to be dynamically discovered and instantiated by their `sub_type`.
+
+## Key Features
+
+- MQTT-based IoT architecture
+- Reusable base classes for hubs, devices, and sensors
+- Class registry for dynamic IoT type lookup
+- Support for custom and extended IoT implementations
+- Built-in logging and helper utilities
+- Designed to work with an MQTT broker
+
+## Core Concepts
+
+### Registry System
+
+Use the `@register_iot` decorator to register your IoT classes:
+
+```python
+from iot_framework import BaseDevice, register_iot
+
+
+@register_iot
+class LampDevice(BaseDevice):
+    sub_type = "lamp"
+```
+
+This registers the class in the framework’s internal registry so it can be instantiated dynamically with `get_iot_class()`.
+
+### Base Classes
+
+- **`BaseMqttClient`**: Provides the shared MQTT client behavior.
+- **`BaseIot`**: Adds shared IoT functionality for sensors and devices.
+- **`BaseDevice` / `BaseSensor`**: Specialized implementations for device and sensor behavior.
+- **`BaseHub`**: Coordinates devices and sensors, handles discovery, and manages device interactions.
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install foresttm23-iot
+```
+
+Or install dependencies for local development using the project’s environment setup.
+
+## Usage
+
+### Run the framework entry point
+
+```bash
+python main.py <hub_sub_type> <device_sub_type> <sensor_sub_type>
+```
+
+Example:
+
+```bash
+python main.py hub lamp motion
+```
+
+This launches the requested IoT processes and connects them to the configured MQTT broker.
+
+### Example Device
+
+```python
+import json
+import time
+
+from iot_framework import BaseDevice, logger, register_iot
+
+
+@register_iot
+class LampDevice(BaseDevice):
+    sub_type = "lamp"
+
+    def __init__(self, client, device_id: str):
+        super().__init__(client, device_id, self.sub_type)
+
+    def on_message(self, client, userdata, msg) -> None:
+        payload = json.loads(msg.payload.decode())
+        command = payload.get("command").lower()
+        transaction_id = payload.get("transaction_id")
+
+        logger.info(f"📩 [{self.id}] Received command: {command}")
+        self.set_state(command)
+
+        lamp_payload = json.dumps(
+            {
+                "state": self.state,
+                "transaction_id": transaction_id,
+                "timestamp": time.time(),
+            }
+        )
+        self.client.publish(self.state_topic, lamp_payload, retain=True)
+```
+
+## Requirements
+
+- Python 3.13+
+- MQTT broker
+- `loguru`
+- `paho-mqtt`
+
+## Project Structure
+
+- `iot_framework/` — framework package
+- `main.py` — launcher for IoT processes
+- `docker-compose.yml` — container setup
+- `Dockerfile` — image definition
+- `load_test.jmx` — performance/load testing
+- `mosquitto.conf` — MQTT broker configuration
+
+## License
+
+No license has been specified for this project.

foresttm23_iot-0.1.3.5/docker-compose.yml

@@ -0,0 +1,31 @@
+services:
+  mqtt:
+    image: eclipse-mosquitto:2
+    container_name: mqtt-broker
+    ports:
+      - "1883:1883"
+    volumes:
+      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
+
+  smart-hub:
+    build: .
+    command: python main.py hub  # Запускаємо тільки Хаб
+    depends_on:
+      - mqtt
+    environment:
+      - MQTT_BROKER=mqtt
+      - MQTT_PORT=1883
+    volumes:
+      - .:/iot_framework
+
+  devices-sim:
+    build: .
+    command: python main.py lamp lamp motion motion
+    depends_on:
+      - mqtt
+      - smart-hub
+    environment:
+      - MQTT_BROKER=mqtt
+      - MQTT_PORT=1883
+    volumes:
+      - .:/iot_framework

foresttm23_iot-0.1.3.5/iot_framework/__init__.py

@@ -0,0 +1,44 @@
+"""
+IoT Framework - A library for building MQTT-based IoT systems.
+"""
+
+from importlib.metadata import version
+
+# Base
+from iot_framework.base.base_device import BaseDevice
+from iot_framework.base.base_hub import BaseHub
+from iot_framework.base.base_iot import BaseIot
+from iot_framework.base.base_mqtt_client import BaseMqttClient
+from iot_framework.base.base_sensor import BaseSensor
+# Enums
+from iot_framework.config.enums import STATE, STATUS
+# Logger
+from iot_framework.config.logger import logger
+# Registry
+from iot_framework.config.registry import register_iot, DEVICE_CLASSES, SENSOR_CLASSES, HUB_CLASSES
+# Utils
+from iot_framework.utils.utils import get_iot_class, start_process
+
+__version__ = version("foresttm23-iot")
+
+__all__ = [
+    # Base classes
+    "BaseMqttClient",
+    "BaseIot",
+    "BaseDevice",
+    "BaseSensor",
+    "BaseHub",
+    # Enums
+    "STATE",
+    "STATUS",
+    # Logger
+    "logger",
+    # Registry
+    "register_iot",
+    "DEVICE_CLASSES",
+    "SENSOR_CLASSES",
+    "HUB_CLASSES",
+    # Utils
+    "get_iot_class",
+    "start_process"
+]

foresttm23_iot-0.1.3.5/iot_framework/base/base_device.py

@@ -0,0 +1,43 @@
+import json
+from abc import abstractmethod
+
+import paho.mqtt.client as mqtt
+
+from iot_framework.base.base_iot import BaseIot
+
+
+class BaseDevice(BaseIot):
+    """
+    Base class for all devices.
+
+    See Also:
+        - LampDevice in iot_framework.devices.lamp_device for a full implementation
+    """
+
+    iot_type = "device"
+
+    def __init__(self, client: mqtt.Client, device_id: str, sub_type: str):
+        prefix = "devices"
+        super().__init__(client=client, iot_id=device_id, sub_type=sub_type, prefix=prefix)
+        self.state_topic = f"{self.base_topic}/state"
+
+    def get_birth_payload(self) -> str:
+        device_info = {
+            "id": self.id,
+            "iot_type": self.iot_type,
+            "sub_type": self.sub_type,
+            "state_topic": self.state_topic,
+            "status_topic": self.status_topic,
+            "control_topic": self.control_topic,
+
+            "status": self.status
+        }
+        return json.dumps(device_info)
+
+    @abstractmethod
+    def on_message(self, client, userdata, msg) -> None:  # pragma: no cover
+        pass
+
+    @abstractmethod
+    def run(self):  # pragma: no cover
+        pass

foresttm23_iot-0.1.3.5/iot_framework/base/base_hub.py

@@ -0,0 +1,237 @@
+import json
+import threading
+import time
+from uuid import uuid4
+
+import paho.mqtt.client as mqtt
+
+from iot_framework.base.base_mqtt_client import BaseMqttClient
+from iot_framework.config.enums import STATUS
+from iot_framework.config.logger import logger
+
+
+class BaseHub(BaseMqttClient):
+    """
+    Base class for all hubs.
+
+    See Also:
+        - SmartHub in iot_framework.hubs.hub for a full implementation
+    """
+
+    iot_type = "hub"
+
+    def __init__(self, client: mqtt.Client, hub_id: str):
+        super().__init__(client, hub_id)
+        self.devices = {}
+        self.sensors = {}
+
+        # Saves transaction_id: {"iot_id": id, "timestamp", time.time(), "expected_state": new_state}
+        # We can later add handling for the time. So if time is elapsed, we delete the transaction or stop the device.
+        self.pending_transactions = {}
+
+        self.device_timers = {}
+
+        self.status_topic = f"hub/{self.id}/status"
+
+    def on_connect(self, client, userdata, flags, rc, properties) -> None:
+        if rc == 0:
+            logger.info(f"✅ [HUB] Connected with ID {self.id}")
+
+            self.status = STATUS.ONLINE.value
+            client.publish(self.status_topic, json.dumps({"status": self.status}), retain=True)
+
+            client.subscribe("discovery/+")
+            client.subscribe("sensors/+/+/data")
+            client.subscribe("devices/+/+/state")
+            client.subscribe("+/+/+/status")
+        else:
+            logger.warning(f"❌ [HUB] Connection failed: {rc}")
+
+    def on_message(self, client, userdata, msg) -> None:
+        """Handles basic functionality for discovery, state and status messages."""
+        try:
+            if "discovery/" in msg.topic:
+                self.handle_discovery(msg)
+
+            # State can only be in devices
+            if "/state" in msg.topic:
+                self.handle_device_state(msg)
+
+            # Status is used for both
+            if "/status" in msg.topic:
+                self.handle_status(msg)
+
+        except Exception as e:
+            logger.info(f"⚠️ [HUB] Error: {e}")
+
+    @staticmethod
+    def _get_payload(msg):
+        try:
+            payload = json.loads(msg.payload.decode())
+            return payload
+        except json.JSONDecodeError:
+            logger.warning(f"❌ Failed to decode JSON from {msg.topic}")
+            return None
+
+    @staticmethod
+    def _get_field_from_payload(payload, field_name: str, default_value=None):
+        field_value = payload.get(field_name, default_value)
+        if field_value is None:
+            raise ValueError(f"Missing required field: {field_name}")
+
+        return field_value
+
+    def _register_iot(self, iot_id: str, iot_type: str, payload: dict, base_iot_device: dict) -> None:
+        if iot_type == "device":
+            state_topic = self._get_field_from_payload(payload, "state_topic")
+            self.devices[iot_id] = {"state_topic": state_topic, **base_iot_device}
+            logger.info(f"📝 [HUB] Registered device: {self.devices[iot_id]}")
+
+        elif iot_type == "sensor":
+            data_topic = self._get_field_from_payload(payload, "data_topic")
+            self.sensors[iot_id] = {"data_topic": data_topic, **base_iot_device}
+            logger.info(f"📝 [HUB] Registered sensor: {self.sensors[iot_id]}")
+        else:
+            logger.info(f"⚠️ Unknown iot_type: {iot_type}")
+
+    def handle_discovery(self, msg):
+        payload = self._get_payload(msg)
+        if payload is None:
+            return
+
+        try:
+            iot_id = self._get_field_from_payload(payload, "id")
+            iot_type = self._get_field_from_payload(payload, "iot_type")
+            sub_type = self._get_field_from_payload(payload, "sub_type")
+            status_topic = self._get_field_from_payload(payload, "status_topic")
+            control_topic = self._get_field_from_payload(payload, "control_topic")
+
+            status = self._get_field_from_payload(payload, "status")
+            # We dont register offline devices.
+            if status == STATUS.OFFLINE.value:
+                return
+
+            base_iot_device = {"iot_type": iot_type,
+                               "sub_type": sub_type,
+                               "status_topic": status_topic,
+                               "control_topic": control_topic,
+
+                               "status": status}
+
+            self._register_iot(iot_id, iot_type, payload, base_iot_device)
+
+        except ValueError as e:
+            logger.warning(f"❌ Discovery Error for topic {msg.topic}: {e}")
+
+    def _publish_to_device(self, topic: str, command: str, device_id: str) -> None:
+        transaction_id = str(uuid4())
+        payload = json.dumps({"command": command, "transaction_id": transaction_id, "timestamp": time.time()})
+        self.client.publish(topic, payload)
+        self.pending_transactions[transaction_id] = {"iot_id": device_id, "timestamp": time.time(),
+                                                     "expected_state": command}
+        logger.info(f"⚡ [HUB] Sent {command} to {device_id}")
+
+    def _publish_to_device_with_timer(self, topic: str, command: str, device_id: str, duration: int):
+        if device_id in self.device_timers:
+            logger.info(f"🔄 [HUB] Motion detected again! Resetting timer for {device_id}")
+            self.device_timers[device_id].cancel()
+
+        timer = threading.Timer(duration, self._publish_to_device, args=(topic, command, device_id))
+        self.device_timers[device_id] = timer
+        timer.start()
+
+        logger.info(f"🕒 [HUB] Scheduled Auto-OFF for {device_id} in {duration}s")
+
+    def handle_device_state(self, msg):
+        """
+        Handles state messages from devices.
+        For custom behavior overwrite _is_admin_transaction(), _validate_transaction(), _validate_timestamp() methods.
+        """
+        if msg.retain:
+            return
+
+        payload = self._get_payload(msg)
+        if payload is None:
+            return
+
+        new_state = self._get_field_from_payload(payload, "state")
+        timestamp = self._get_field_from_payload(payload, "timestamp")
+        transaction_id = self._get_field_from_payload(payload, "transaction_id")
+
+        if self._is_admin_transaction(transaction_id):
+            return
+        if not self._validate_transaction(transaction_id, new_state):
+            return
+        if not self._validate_timestamp(timestamp):
+            return
+
+        topic_parts = msg.topic.split("/")
+        device_id = topic_parts[2]
+
+        if device_id not in self.devices:
+            logger.warning(f"❓ [HUB] Received state from unknown iot device: {device_id}")
+            return
+
+        del self.pending_transactions[transaction_id]
+        logger.info(f"transaction_id: {transaction_id}")
+
+    @staticmethod
+    def _validate_timestamp(timestamp: float) -> bool:
+        """Validate timestamp is not too old."""
+        return time.time() - timestamp < 10
+
+    def _validate_transaction(self, transaction_id: str, new_state: str) -> bool:
+        """Validate transaction exists and state matches expected."""
+        if transaction_id not in self.pending_transactions:
+            logger.warning(f"❌ Unknown transaction_id: {transaction_id}")
+            return False
+
+        expected_state = self.pending_transactions[transaction_id]["expected_state"]
+        if expected_state != new_state:
+            logger.error(f"❌ State mismatch for {transaction_id}: expected {expected_state}, got {new_state}")
+            return False
+
+        return True
+
+    @staticmethod
+    def _is_admin_transaction(transaction_id: str) -> bool:
+        if transaction_id.startswith("admin-"):
+            logger.info(f"ℹ️ [HUB] Acknowledging admin-initiated command:  {transaction_id}")
+            return True
+        return False
+
+    def handle_status(self, msg):
+        """Updates internal status of a device or sensor from external status messages."""
+        payload = self._get_payload(msg)
+        if payload is None:
+            return
+
+        status = self._get_field_from_payload(payload, "status")
+
+        topic_parts = msg.topic.split("/")
+        iot_id = topic_parts[2]
+
+        self._update_iot_status(iot_id, status)
+
+    def _update_iot_status(self, iot_id: str, status: STATUS) -> None:
+        if iot_id in self.devices:
+            self.devices[iot_id]["status"] = status
+            logger.info(f"ℹ️ [HUB] Iot device {iot_id} is now {status}")
+
+        elif iot_id in self.sensors:
+            self.sensors[iot_id]["status"] = status
+            logger.info(f"ℹ️ [HUB] Iot device {iot_id} is now {status}")
+
+    def cancel_all_timers(self):
+        """
+        Cancel all timers for devices.
+        Can be used for tests.
+        """
+        for device_id, timer in self.device_timers.items():
+            timer.cancel()
+        self.device_timers.clear()
+
+    def run(self):
+        logger.info(f"🧠 [HUB] Running...")
+        while True:
+            time.sleep(10)