iobroker-python

Python SDK for ioBroker adapters. Speaks the Redis wire protocol of the states and objects databases directly — a Python process becomes a first-class adapter alongside any Node adapter, with no bridge in between.

Status: early draft. The wire layer is verified against a running installation (js-controller 7.2.3, jsonl databases). The API may still change.

Installation

pip install iobroker

An adapter in thirty lines

from iobroker import Adapter, State

class MyAdapter(Adapter):
    async def on_ready(self):
        await self.set_object_not_exists("temperature", {
            "type": "state",
            "common": {
                "name": "Temperature", "type": "number",
                "role": "value.temperature", "unit": "°C",
                "read": True, "write": False,
            },
        })
        await self.subscribe_states("*")
        await self.set_state("info.connection", True, ack=True)

    async def on_state_change(self, id: str, state: State | None):
        # ack=False means somebody wants something switched.
        if state and not state.ack:
            self.log.info(f"Command on {id}: {state.val}")

    async def on_message(self, msg):
        if msg.command == "ping":
            await self.reply(msg, {"pong": True})

MyAdapter("myadapter").run()

A runnable example lives in examples/minimal_adapter.py.

Connection settings

The adapter resolves them in this order:

1. Environment variables IOB_STATES_HOST/PORT/DB/PASS/TYPE and IOB_OBJECTS_* — this is how py-controller will pass them in later.
2. IOB_CONFIG holding the path to iobroker.json.
3. The usual installation paths.

Instance number and log level come from --instance / --loglevel or from IOB_INSTANCE / IOB_LOGLEVEL — the same arguments js-controller already passes to Node adapters today.

How the built-in server differs from Redis

In a default setup you are not talking to real Redis but to the Redis protocol server built into js-controller (ports 9000 and 9001). It deviates in several places. Every point below was measured on the wire against a running installation rather than inferred from documentation — tools/probe.py verifies them for your own installation.

One more property that is not a bug but matters: permission checks live in the JS client, not in the database server. Anything holding a Redis connection effectively has admin rights. That is equally true for Node adapters — the difference is that with Python, third-party code from PyPI shares the process.

Capability probe

python tools/probe.py

(from the repository, not shipped in the wheel)

Reports what both databases support in your installation, then performs a full round trip: create an object, write a state, receive the change. Cleans up again with --cleanup.

Lifecycle

alive, connected, uptime and memRss are written by the adapter itself through the states database — exactly like a Node adapter. Stopping goes through the sigKill state: when the controller sets it to -1, the adapter shuts down in an orderly fashion. That makes stopping work on Windows too, where there is no SIGTERM.

Development

python -m venv .venv && .venv/Scripts/activate   # Windows
pip install -e ".[dev]"
python examples/minimal_adapter.py --instance 0

The version number lives in src/iobroker/__init__.py only; pyproject.toml reads it from there through hatch, and the release workflow checks the git tag against it.

License

MIT