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 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.
pip install simpleiot
Requires Python 3.10 or newer. The client is built on
nats-py and uses asyncio.
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="...")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.
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=...), thenodes.<parent>.<id>requestsearch(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, assiot importwould, and waits until it hassubscribe_node(id),subscribe_tree(id),subscribe(subject): async iterators ofPointsMessageclose()
A server error raises SiotError; a missing node raises NotFoundError.
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
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.