Skip to content

Latest commit

 

History

History

python

Folders and files

README.md

simpleiot

A Python client for Simple IoT. Read and write nodes and points, and watch for changes, over the NATS API.

The client connects with the instance's shared token (SIOT_AUTH_TOKEN), which reaches the whole tree. It suits scripts and services running alongside an instance you operate.

a Python process on an edge device talks to the local SIOT over NATS; the local SIOT syncs with the cloud, and people use the web UI on either instance

A typical setup runs the Python process next to SIOT on an edge device. What it writes reaches the cloud through sync, and a person sees it in the web UI on site or remotely.

Install

pip install simpleiot

Requires Python 3.10 or newer. The client is built on nats-py and uses asyncio.

Usage

import asyncio
import simpleiot
from simpleiot import Point


async def main():
    async with await simpleiot.connect() as c:
        root = await c.get_root()
        print("root:", root.description)

        id = await c.create_node(root.id, "variable", description="tank level")
        await c.send_point(id, "value", 42.5)

        async with await c.subscribe_node(id) as sub:
            async for m in sub:
                for p in m.points:
                    print(p.type, p.value)


asyncio.run(main())

connect() reads SIOT_NATS_SERVER (default nats://localhost:4222) and SIOT_AUTH_TOKEN from the environment, or takes them as arguments:

c = await simpleiot.connect("nats://10.0.0.5:4222", token="...")

Nodes and points

Data in Simple IoT is a tree of nodes, each holding points. A point has a type, a key ("0" unless a node holds several of a type), a value, and a time. The edge from a node to its parent carries its own points, such as tombstone for a deleted node. See the data reference.

Point.value sets the encoding when sending:

Value Sent as
float, int, bool a float point
str a string point
dict, list a JSON point
None a point with no value

Pass data_type=DataType.INT to send an integer as an int point. A received point's value is a float, int, or str by its data type; number and text read it as a number or string either way.

API

All methods are coroutines on Client.

  • get_root(), get_node(id, parent="all"), get_children(parent, type=...)
  • get_nodes(parent, id="all", type=..., include_deleted=..., depth=...), the nodes.<parent>.<id> request
  • search(below, query, limit=..., type=...)
  • send_points(id, points), send_point(id, type, value, key="0")
  • send_edge_points(id, parent, points)
  • create_node(parent, type, points, id=..., description=..., primary=...)
  • delete_node(id, parent), move_node(id, old_parent, new_parent)
  • provision(name, yaml) uploads a node file for the server to apply, as siot import would, and waits until it has
  • subscribe_node(id), subscribe_tree(id), subscribe(subject): async iterators of PointsMessage
  • close()

A server error raises SiotError; a missing node raises NotFoundError.

Examples

Each example is a short script in its own directory with a README:

  • tree prints the node tree
  • send_points creates a node and writes a value to it once a second
  • watch prints every point change below a node
  • mirror_temperature reacts to one point by writing another
  • rover drives a simulated autonomous rover from a dashboard, with a live map, status, and commands

Run them against a local instance:

SIOT_AUTH_TOKEN=... python examples/tree/tree.py

With uv, run them from the python directory, and uv installs the package and its dependencies:

SIOT_AUTH_TOKEN=... uv run examples/tree/tree.py

To run an example against the published package instead of the source tree:

SIOT_AUTH_TOKEN=... uv run --isolated --no-project --with simpleiot examples/tree/tree.py

Development

The client lives in the Simple IoT repository under python/, so it changes together with the server.

cd python
uv sync
uv run pytest

The tests need uv. The codec tests check the encoder against the fixtures data/point_fixture_test.go writes, the same ones the JavaScript client is checked against. The integration tests start a scratch siot when SIOT_BIN names one; siot_test_python in envsetup.sh builds it and runs them.

To publish a release, set the version in python/src/simpleiot/__init__.py, add a python/CHANGELOG.md entry, and push a py-v<version> tag. The Python release workflow builds the package and publishes it to PyPI.