Metadata-Version: 2.5
Name: foresttm23-iot
Version: 0.1.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>
License: MIT
License-File: LICENSE
Keywords: devices,home-automation,iot,mqtt,sensors,smart-home
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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

This project is licensed under the terms of the [MIT License](https://github.com/Foresttm23/mqtt-iot-framework/blob/master/LICENSE).
