app/docs/code/connectors.md

Writing a connector

A walkthrough from an empty directory to a node on the canvas. The normative surface is in the connector contract; this is how to use it.

Start from the skeleton

A working connector, kept as small as a correct one can be, lives at skeleton/ in the connectors repository. Copy it:

git clone https://git.stroblme.de/Fluksio/connectors.git
cp -r connectors/skeleton fluksio-connector-mydevice
cd fluksio-connector-mydevice

Rename the package (src/fluksio_connector_skeleton/ and the [project] name in pyproject.toml), then point the entry point at your class:

[project.entry-points."fluksio.node_types"]
my_device = "fluksio_connector_mydevice:MyDevice"

Install it into the engine

Connectors are found through installed package metadata, so the engine has to have yours installed. During development, install it as an editable path dependency of the backend:

cd app/backend
uv add --editable ../../fluksio-connector-mydevice

Editing your connector's code then takes effect on the next engine restart, with no reinstall. Changing its metadata — the entry point, the version, the package name — needs uv sync to regenerate the installed metadata before a restart picks it up.

Two things to know about this:

• uv add writes the path dependency into backend/pyproject.toml and uv.lock. That path does not exist inside the backend's Docker image, so revert both files before committing; the dependency belongs on your machine, not in the repo. Distribution is a later milestone.

• For the same reason, develop against the standalone backend rather than the Docker stack:

  cd app && make dev-backend    # FastAPI on :8000
  make dev-frontend             # Vite on :5173
  

Restart the backend and your node type appears in the add-node palette (⌘P), labelled with the package it came from.

Write the node

from typing import Any

from pydantic import Field
from fluksio.flow.connector import CONTRACT_VERSION, ConnectorNode


class MyDevice(ConnectorNode):
    contract = CONTRACT_VERSION
    title = "My device"
    description = "Reads temperature and humidity over the device's HTTP API."

    class Params(ConnectorNode.Params):
        host: str = "192.168.1.50"
        api_key: str | None = Field(
            default=None, json_schema_extra={"x-secret": True}
        )

    async def poll(self) -> dict[str, Any] | None:
        reading = await self._read()
        return {"temperature": reading.temp, "humidity": reading.humidity}

Then, on the canvas: place the node, set poll_interval to how often the device should be read, pick the API key from the secrets store, and add output ports named temperature and humidity. The port names are the wiring — any node consuming those messages is downstream of this one.

If the device is told rather than asked

A connector that commands something implements write() instead of, or alongside, poll(). Input ports carry the values in:

    def write(self, **ports: Any) -> None:
        self._device.set(ports["level"])

Place the node with input ports named level, and whatever publishes that message drives the device. Set idempotent = False on the class: a write is a command, and a redelivery after a crash should not undo a newer one.

Keep the first version off the wire. A boolean setting the code checks before it sends — artnet's transmit is the example — lets a flow be built and watched in the logs before anything physically moves.

If the reading is bytes

A camera or a microphone publishes a reference rather than the bytes:

    async def poll(self):
        jpeg = await asyncio.to_thread(self._grab)
        return {"frame": self.save_artifact(jpeg, "f.jpg", media_type="image/jpeg")}

Place the node with an image-typed output port and a Media widget draws each frame as it lands. fluksio-connector-test-media publishes test frames and tones this way, so the whole path can be wired up with no camera in the room — copy it if yours is a media device.

Try it without a device

Give poll something predictable first and confirm the values reach the canvas before pointing it at hardware:

async def poll(self):
    return {"temperature": 21.5}

Press Run, or wait for the poll interval, and the value appears on the edge. Anything the connector prints shows up in the logs panel in the dock, and a raised exception shows there with its traceback and marks the node down.

Checklist before sharing it

• contract = CONTRACT_VERSION declared on the class itself.
• Credentials marked x-secret, never read from the environment.
• stop() is safe to call twice, and after a failed start().
• Blocking I/O wrapped in asyncio.to_thread.
• poll() returns None rather than raising when there is simply nothing new.
• write() returns quickly; the thread it runs on is the scheduler's.
• Health reported when the connection comes and goes.