Implement TasmotaPower driver

docs/source/reference/package-apis/drivers/index.md

@@ -22,6 +22,7 @@ Drivers that control the power state and basic operation of devices:
 * **[DUT Link](dutlink.md)** (`jumpstarter-driver-dutlink`) - [DUT Link
   Board](https://github.com/jumpstarter-dev/dutlink-board) hardware control
 * **[Energenie PDU](energenie.md)** (`jumpstarter-driver-energenie`) - Energenie PDUs
+* **[Tasmota](tasmota.md)** (`jumpstarter-driver-tasmota`) - Tasmota hardware control
 
 ### Communication Drivers
 
@@ -93,6 +94,7 @@ raspberrypi.md
 sdwire.md
 shell.md
 snmp.md
+tasmota.md
 tftp.md
 uboot.md
 ustreamer.md

docs/source/reference/package-apis/drivers/tasmota.md

@@ -0,0 +1 @@
+../../../../../packages/jumpstarter-driver-tasmota/README.md

packages/jumpstarter-driver-tasmota/README.md

@@ -0,0 +1,44 @@
+# Tasmota driver
+
+`jumpstarter-driver-tasmota` provides functionality for interacting with tasmota compatible devices.
+
+## Installation
+
+```shell
+pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-driver-tasmota
+```
+
+## Configuration
+
+Example configuration:
+
+```yaml
+export:
+  power:
+    type: jumpstarter_driver_tasmota.driver.TasmotaPower
+```
+
+### Config parameters
+
+| Parameter    | Description                                                     | Default  |
+|--------------|-----------------------------------------------------------------|----------|
+| `host`       | MQTT broker hostname or IP address                              | Required |
+| `port`       | MQTT broker port                                                | 1883     |
+| `tls`        | MQTT broker TLS enabled                                         | True     |
+| `client_id`  | Client identifier for MQTT connection                           |          |
+| `transport`  | Transport protocol, one of "tcp", "websockets", "unix"          | "tcp"    |
+| `timeout`    | Timeout in seconds for operations                               |          |
+| `username`   | Username for MQTT authentication                                |          |
+| `password`   | Password for MQTT authentication                                |          |
+| `cmnd_topic` | MQTT topic for sending commands to the Tasmota device           | Required |
+| `stat_topic` | MQTT topic for receiving status updates from the Tasmota device | Required |
+
+## API Reference
+
+The tasmota power driver provides a `PowerClient` with the following API:
+
+```{eval-rst}
+.. autoclass:: jumpstarter_driver_power.client.PowerClient()
+    :no-index:
+    :members: on, off
+```

packages/jumpstarter-driver-tasmota/jumpstarter_driver_tasmota/driver.py

@@ -0,0 +1,85 @@
+from dataclasses import dataclass, field
+from threading import Condition
+from typing import Literal
+
+import paho.mqtt.client as paho
+from jumpstarter_driver_power.driver import PowerInterface
+from paho.mqtt.enums import CallbackAPIVersion
+
+from jumpstarter.driver import Driver, export
+
+
+@dataclass(kw_only=True)
+class TasmotaPower(PowerInterface, Driver):
+    """driver for tasmota compatible power switches"""
+
+    client_id: str | None = None
+    transport: Literal["tcp", "websockets", "unix"] = "tcp"
+    timeout: float | None = None
+
+    host: str
+    port: int = 1883
+    tls: bool = True
+
+    username: str | None = None
+    password: str | None = None
+
+    cmnd_topic: str
+    stat_topic: str
+
+    mq: paho.Client = field(init=False)
+    state: str | None = field(init=False, default=None)
+    cond: Condition = field(init=False, default_factory=Condition)
+
+    def __post_init__(self):
+        if hasattr(super(), "__post_init__"):
+            super().__post_init__()
+
+        self.mq = paho.Client(
+            callback_api_version=CallbackAPIVersion.VERSION2,
+            client_id=self.client_id,
+            transport=self.transport,
+        )
+
+        def on_message(client, userdata, msg):
+            if msg.topic == self.stat_topic:
+                self.state = msg.payload.decode()
+                with self.cond:
+                    self.cond.notify_all()
+
+        self.mq.on_message = on_message
+
+        if self.tls:
+            self.mq.tls_set()
+
+        self.mq.username_pw_set(self.username, self.password)
+        self.mq.connect(self.host, self.port)
+        self.mq.loop_start()
+
+        self.mq.subscribe(self.stat_topic)
+
+    def publish(self, state):
+        self.mq.publish(
+            self.cmnd_topic,
+            payload=state,
+            qos=1,
+        ).wait_for_publish(
+            timeout=self.timeout,
+        )
+        with self.cond:
+            self.cond.wait_for(
+                lambda: self.state == state,
+                timeout=self.timeout,
+            )
+
+    @export
+    def on(self):
+        self.publish("ON")
+
+    @export
+    def off(self):
+        self.publish("OFF")
+
+    @export
+    def read(self):
+        pass

packages/jumpstarter-driver-tasmota/jumpstarter_driver_tasmota/driver_test.py

@@ -0,0 +1,29 @@
+import pytest
+from pytest_mqtt.model import MqttMessage
+
+from .driver import TasmotaPower
+from jumpstarter.common.utils import serve
+
+
+@pytest.mark.skip("requires docker")
+def test_tasmota_power(mosquitto, capmqtt):
+    cmnd_topic = "cmnd/tasmota_6990F2/POWER"
+    stat_topic = "stat/tasmota_6990F2/POWER"
+
+    with serve(
+        TasmotaPower(
+            host=mosquitto[0],
+            port=int(mosquitto[1]),
+            tls=False,
+            transport="tcp",
+            cmnd_topic=cmnd_topic,
+            stat_topic=stat_topic,
+        )
+    ) as client:
+        capmqtt.publish(topic=stat_topic, payload="ON")
+        client.on()
+        assert MqttMessage(topic=cmnd_topic, payload=b"ON", userdata=None) in capmqtt.messages
+
+        capmqtt.publish(topic=stat_topic, payload="OFF")
+        client.off()
+        assert MqttMessage(topic=cmnd_topic, payload=b"OFF", userdata=None) in capmqtt.messages

packages/jumpstarter-driver-tasmota/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "jumpstarter-driver-tasmota"
+dynamic = ["version", "urls"]
+description = "Jumpstarter driver for controlling Tasmota-compatible devices via MQTT"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Nick Cao", email = "nickcao@nichi.co" }]
+requires-python = ">=3.11"
+dependencies = [
+    "anyio>=4.6.2.post1",
+    "jumpstarter_driver_power",
+    "jumpstarter",
+    "paho-mqtt>=2.1.0",
+]
+
+[project.entry-points."jumpstarter.drivers"]
+TasmotaPower = "jumpstarter_driver_tasmota.driver:TasmotaPower"
+
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { 'root' = '../../' }
+
+[tool.hatch.metadata.hooks.vcs.urls]
+Homepage = "https://jumpstarter.dev"
+source_archive = "https://github.com/jumpstarter-dev/repo/archive/{commit_hash}.zip"
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=html --cov-report=xml"
+log_cli = true
+log_cli_level = "INFO"
+testpaths = ["jumpstarter_driver_tasmota"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs", "hatch-pin-jumpstarter"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.hooks.pin_jumpstarter]
+name = "pin_jumpstarter"
+
+[dependency-groups]
+dev = [
+    "pytest-cov>=6.0.0",
+    "pytest>=8.3.3",
+    "pytest-mqtt>=0.5.0",
+]

pyproject.toml

@@ -22,6 +22,7 @@ jumpstarter-driver-probe-rs = { workspace = true }
 jumpstarter-driver-pyserial = { workspace = true }
 jumpstarter-driver-qemu = { workspace = true }
 jumpstarter-driver-sdwire = { workspace = true }
+jumpstarter-driver-tasmota = { workspace = true }
 jumpstarter-driver-tftp = { workspace = true }
 jumpstarter-driver-snmp = { workspace = true }
 jumpstarter-driver-shell = { workspace = true }
@@ -75,6 +76,7 @@ locale = "en-us"
 [tool.typos.default.extend-words]
 ser = "ser"
 Pn = "Pn"
+mosquitto = "mosquitto"
 
 [tool.coverage.run]
 omit = ["conftest.py", "test_*.py", "*_test.py", "*_pb2.py", "*_pb2_grpc.py"]