Metadata-Version: 2.1
Name: local_tuya_domoticz_tools
Version: 1.1.2
Summary: Tools to create a Domoticz plugin for local-tuya devices.
Home-page: https://github.com/gpajot/local-tuya-domoticz-tools
License: MIT
Author: Gabriel Pajot
Author-email: gab@les-cactus.co
Requires-Python: >=3.8
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: concurrent-tasks (>=1.4,<2)
Requires-Dist: local-tuya (>=2.4,<3)
Requires-Dist: xmltodict (>=0.13,<0.14)
Project-URL: Repository, https://github.com/gpajot/local-tuya-domoticz-tools
Description-Content-Type: text/markdown

# local-tuya-domoticz-tools

[![tests](https://github.com/gpajot/local-tuya-domoticz-tools/actions/workflows/test.yml/badge.svg?branch=main&event=push)](https://github.com/gpajot/local-tuya-domoticz-tools/actions/workflows/test.yml?query=branch%3Amain+event%3Apush)
[![version](https://img.shields.io/pypi/v/local_tuya_domoticz_tools?label=stable)](https://pypi.org/project/local_tuya_domoticz_tools/)
[![python](https://img.shields.io/pypi/pyversions/local_tuya_domoticz_tools)](https://pypi.org/project/local_tuya_domoticz_tools/)

Tools to create a Domoticz plugin for local-tuya devices.
> 💡 The Domoticz version should be `2022.1` or higher.

## Creating the plugin
To create a plugin, you will need to create 2 things.

### Plugin metadata
This is the XML header that is used to populate the plugin creation page in Domoticz.
You can create it using `local_tuya_domoticz_tools.PluginMetadata`.

### Starting the device.
To start the plugin, you need to create the device and register the units.

Check `local_tuya_domoticz_tools.plugin.plugin.OnStart` for the function signature.

Units should be created using `manager.register(...)`.

For a switch unit, it would look like:
```python
from typing import Dict

from local_tuya import DeviceConfig, ProtocolConfig
from local_tuya_domoticz_tools import UnitManager, switch_unit

from my_device import SwitchState, SwitchDevice


def on_start(
    protocol_config: ProtocolConfig,
    _: Dict[str, str],
    manager: UnitManager[SwitchState],
) -> SwitchDevice:
    device = SwitchDevice(config=DeviceConfig(protocol=protocol_config))
    manager.register(
        switch_unit(
            id_=1,
            name="power",
            image=9,
            command_func=device.switch,
        ),
        lambda s: s.power,
    )
    return device
```

### Units
Units represent a Domoticz device and is associated to a Domoticz hardware.

#### Manager
The role of the manager is to
- create/remove units: `register` method
- dispatch the commands from units: `on_command` method
- update units state: `update` method

#### Unit types
- [switch](./units/switch.py)
- [selector switch](./units/selector_switch.py)
- [temperature](./units/temperature.py) (accepts values preprocessor)
- [set point](./units/set_point.py)

For common units parameters, see the [base](./units/base.py).

## Installing the plugin
You should provide a script that will be used to install the plugin.
It would look like:
```python
from local_tuya_domoticz_tools import install_plugin, PluginMetadata

def on_start(...):
    ...


if __name__ == "__main__":
    install_plugin(
        metadata=PluginMetadata(...),
        on_start=on_start,
        import_path="my_device.domoticz",
    )
```

> 💡 Domoticz path defaults to `~/domoticz` a `-p` option can be passed to change that.

### Filtering units
You can automatically add an option to the plugin to filter created units.

To enable it, you need to implement `local_tuya_domoticz_tools.UnitId` and add all unit IDs, then simply pass it to the `install` function. `UnitManager.register` will handle device deletion.
