otensor-sdk
Python SDK that runs on your device — publishes telemetry and receives commands from the Otensor IoT platform. Built for makers on Raspberry Pi and other Linux hardware.
PT-BR — SDK Python que roda no dispositivo: publica telemetria e recebe comandos da plataforma Otensor. Feito para makers com Raspberry Pi e outro hardware Linux. A documentação abaixo está em inglês.
from otensor_sdk import OtensorSDK
device = OtensorSDK().connect() # reads OTENSOR_API_BASE_URL/OTENSOR_API_KEY/OTENSOR_DEVICE_ID
sensor = device.slot("main")
sensor.publish_property("temperature", 24.5)
@sensor.on_action("set_pixels")
def light_up(payload: dict) -> None:
print("platform asked for:", payload)
Which package do I need?
Otensor ships two Python packages with different jobs:
otensor-sdk (this one) |
otensor |
|
|---|---|---|
| Runs | On the hardware (Raspberry Pi, Linux board) | Anywhere (laptop, server) |
| Job | Publish telemetry, execute commands | React to events, write automations |
| Talks to | MQTT broker + REST API | REST API |
Use both if you want a device that reports data and logic that reacts to it. They are independent — neither requires the other.
Requirements
- Python 3.11+
- An Otensor instance (self-hosted or managed)
- An API key (
sk-…) and a device registered in the dashboard
Install
pip install otensor-sdk
Hardware wrappers (otensor_sdk.sensehat, otensor_sdk.gpio) rely on
sense-hat and gpiozero, which ship with Raspberry Pi OS. They are not
pip dependencies of this package, so installing here never drags in hardware
libraries you don't need.
Configuration
OtensorSDK() reads its config from environment variables (loaded from a
.env file automatically, or from whatever's already exported) — no need to
pass them as arguments every time:
OTENSOR_API_BASE_URL=https://api.your-otensor.example # or http://localhost:8000
OTENSOR_API_KEY=sk-...
OTENSOR_DEVICE_ID=...
Pass any of api_base_url / api_key / device_id explicitly to
OtensorSDK(...) to override the corresponding env var — useful for
multi-device scripts or tests. If a value is missing from both the
constructor and the environment, OtensorSDK raises OtensorConfigError
right away (no silent fallback to the wrong host).
Quick start
from otensor_sdk import OtensorSDK
sdk = OtensorSDK() # OTENSOR_API_BASE_URL / OTENSOR_API_KEY / OTENSOR_DEVICE_ID from .env
device = sdk.connect() # fetches MQTT credentials and connects
main = device.slot("main") # a slot is one capability of the device
# Register handlers BEFORE publishing, so a command arriving right after
# connect() is not missed.
@main.on_action("set_pixels")
def handle_set_pixels(payload: dict) -> None:
print("light up:", payload)
main.publish_property("temperature", 24.5)
Slots
A device declares capabilities, each bound to a named slot — a board can
carry a sensor unit on main, a relay on relay1 and a motion sensor on
pir1 at the same time. Properties and actions are always scoped to a slot,
so the platform validates each reading against the right schema.
device.slot("main").publish_property("humidity", 61.2)
device.slot("relay1").publish_property("state", True)
Publishing on a schedule
TelemetryPublisher groups every source into one message per tick, instead
of one message per property:
from otensor_sdk import TelemetryPublisher
publisher = TelemetryPublisher(device, interval=5.0)
publisher.set_source("main", "temperature", read_temperature)
publisher.set_source("main", "humidity", read_humidity)
publisher.run_forever() # blocks until Ctrl-C
# publisher.publish_once() # or drive the loop yourself
Complete example — no hardware required
Runs anywhere with simulated sensors, so you can see the full loop before touching a Raspberry Pi:
import random
from otensor_sdk import OtensorSDK, TelemetryPublisher
sdk = OtensorSDK()
device = sdk.connect()
main = device.slot("main")
@main.on_action("set_pixels")
def set_pixels(payload: dict) -> None:
print("LED matrix ->", payload.get("pixels"))
@main.on_action("clear_display")
def clear_display(payload: dict) -> None:
print("LED matrix cleared")
publisher = TelemetryPublisher(device, interval=5.0)
publisher.set_source("main", "temperature", lambda: round(random.uniform(18, 32), 1))
publisher.set_source("main", "humidity", lambda: round(random.uniform(40, 80), 1))
try:
publisher.run_forever()
except KeyboardInterrupt:
device.disconnect()
Raspberry Pi hardware
from otensor_sdk.sensehat import SenseHatUnit, LedMatrixSwitch
from otensor_sdk.gpio import DigitalInput, DigitalOutput
unit = SenseHatUnit()
unit.bind("main", device, publisher) # sensors + set_pixels/clear_display, wired in one call
LedMatrixSwitch(sense_hat=unit._sense).bind("led", device) # same LED matrix as an on/off switch
DigitalOutput(pin=17).bind("relay1", device) # actions: turn_on / turn_off / toggle
DigitalInput(pin=4).bind("pir1", device) # publishes motion_detected on edge
LedMatrixSwitch exposes the LED matrix as a plain switch (turn_on/turn_off/toggle,
state property) — fills the matrix with a solid color to turn on, clears it to turn off.
Same contract as DigitalOutput, no set_pixels payload needed for simple on/off control.
bind() registers the action handlers and the telemetry sources for that
slot, so you don't wire each property by hand.
Reliability
Built for devices that stay online for weeks on flaky networks:
- Reconnect-safe commands — the
cmdtopic is re-subscribed on every connect, including automatic reconnects. Without this, telemetry keeps flowing while commands go silently mute after the first network blip. - State republish —
device.on_reconnect(fn)fires on first connect and every reconnect. Hardware wrappers use it to re-publish current state, which the dashboard would otherwise show as stale until the next physical change. - Last Will — the broker marks the device offline if it drops without a clean disconnect.
- Local ack —
device.on_ack(fn)fires in-process the moment this device confirms a command, with{commandId, slot, action, success, error?}. Lets local code know its own command finished without a REST round-trip.
API reference
| Symbol | Purpose |
|---|---|
OtensorSDK(api_base_url=None, api_key=None, device_id=None) |
Entry point; each param falls back to OTENSOR_API_BASE_URL/OTENSOR_API_KEY/OTENSOR_DEVICE_ID |
.connect() -> Device |
Fetches MQTT session and connects |
Device.slot(name) -> SlotHandle |
Handle scoped to one capability |
Device.publish_telemetry(nested) |
Publish {slot: {property: value}} directly |
Device.on_reconnect(fn) / .on_ack(fn) |
Lifecycle callbacks |
Device.disconnect() |
Stop the MQTT loop |
SlotHandle.publish_property(name, value) |
One reading for this slot |
SlotHandle.on_action(name) |
Decorator registering a command handler |
TelemetryPublisher(device, interval) |
Batched periodic publishing |
.set_source(slot, property, fn) |
Register a value producer |
.run_forever() / .publish_once() |
Drive the publish loop |
Exceptions: OtensorError (base), OtensorAuthError, OtensorSessionError,
OtensorHardwareError.
Versioning
Semantic versioning. While on 0.x, a minor bump may carry breaking
changes — pin the minor version in production:
otensor-sdk~=0.2.0
License
MIT
Metadata
Release files for otensor-sdk 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| otensor_sdk-0.6.0.tar.gz | 87.3 kB | With provenance | Details for otensor_sdk-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| otensor_sdk-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for otensor_sdk-0.6.0-py3-none-any.whl |
Total release size: 105.4 kB
Release files / otensor_sdk-0.6.0.tar.gz
| Download URL | otensor_sdk-0.6.0.tar.gz |
|---|---|
| Size | 87.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
85a9c6589069e6c5ecd300743c90a2db86a51b07ade1db9ea29f87af5c9a73c5
|
|
BLAKE2b-256 checksum How to use checksums |
c1608e447f3922efd15c0bef0add64d41a95f2448c16ba079eada1b4c4348370
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 9, 2026.
Transparency logRelease files / otensor_sdk-0.6.0-py3-none-any.whl
| Download URL | otensor_sdk-0.6.0-py3-none-any.whl |
|---|---|
| Size | 18.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ee2ea72ebf0681694dca9ab3f4ec83b5e0e3e9bfd8432ea27a172be1db7cfe68
|
|
BLAKE2b-256 checksum How to use checksums |
6938e4b560d8e60765bfd1f9eb8811c7280f6fc7d9efa9401c1140e7f673973c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 9, 2026.
Transparency logSecurity for otensor-sdk 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for otensor_sdk-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.