Skip to main content

OpenIoE user guide

🟩 Setup · 🟨 Configuration · 🟪 Device operations · 🟦 Reference

Use OpenIoE to read and write device data over HTTP and publish or receive MQTT messages. All device operations select an entry from your configuration by idx. Python 3.10 or newer is required.

For complete configuration details, architecture, module extensions, testing, and releases, see ReadmeDev.md.

Table of contents

Installation

🟩 Setup

Run from the repository root:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .
python3 examples/quickstart.py

For MQTT support, install the optional dependency:

python3 -m pip install -e '.[mqtt]'

HTTP methods use Python's standard library. MQTT uses optional Paho MQTT 2.x; HTTP operations and configuration loading work without it.

Load your configuration

🟨 Configuration

Copy examples/config.example.json to config.json and replace the placeholder IDs and credentials with your project settings.

from openioe import Config
from openioe.devices import Devices

config = Config("config.json")
devices = Devices(config=config)

You may also use Config(config_file="config.json"), Config.from_json("config.json"), or Devices(config_file="config.json"). Relative paths resolve against the current working directory.

A minimal HTTP configuration is:

{
  "base_url": "https://api.openioe.in",
  "api_key": "your-account-api-key",
  "api_version": "v1",
  "timeout": 30,
  "devices": [{
    "idx": 1,
    "device_id": "your-device-id",
    "read_apikey": "your-read-api-key",
    "write_apikey": "your-write-api-key",
    "communication_protocol": "http"
  }]
}

idx is the integer stored on the device entry, not its list position. Exactly one entry must match. The library automatically selects read_apikey for reads and write_apikey for writes. Keep actual credentials out of version control.

Provide configuration in Python

Labeled constructor input:

config = Config(
    base_url="https://api.openioe.in",
    api_key="your-account-api-key",
    devices=[{
        "idx": 1,
        "device_id": "your-device-id",
        "read_apikey": "your-read-api-key",
        "write_apikey": "your-write-api-key",
        "communication_protocol": "http",
    }],
)
devices = Devices(config=config)

Ordered input uses base_url, api_key, api_version, timeout; resource lists remain keyword arguments:

config = Config("https://api.openioe.in", "your-account-api-key", "v1", 30,
                devices=[{"idx": 1, "device_id": "your-device-id",
                          "read_apikey": "your-read-api-key",
                          "write_apikey": "your-write-api-key"}])

api_version defaults to "v1" and timeout to 30 seconds. Do not mix file input with direct settings. All module constructors accept a shared Config instance.

Read device data

🟪 HTTP read

response = devices.readdata(idx=1)
print(response["data"])

This POSTs to /v1/readdata using the selected device's device_id and read_apikey. Omitted is_bulk defaults to False; omitted timestamps or None are sent as empty strings. Supply a time range when needed:

response = devices.readdata(
    idx=1,
    is_bulk=False,
    from_timestamp="2026-06-02 00:10:04.629315+00",
    to_timestamp="2026-06-02 00:10:04.629315+00",
)

The full response dictionary is returned, for example:

{"data": {}, "message": "success"}

Write device data

🟪 HTTP write

response = devices.writedata(idx=1, data={"voltage": 230})
print(response)

This POSTs to /v1/writedata. The request's device_api_key is automatically set to the configured device's write_apikey. data must be a JSON-serializable dictionary. data_type defaults to "http" and can be supplied explicitly:

response = devices.writedata(idx=1, data={"voltage": 230}, data_type="http")

The full response dictionary is returned. HTTP endpoints use your configured base_url and api_version.

MQTT publish and subscribe

🟪 MQTT messaging

Install MQTT support with python3 -m pip install -e '.[mqtt]'. Use a device with communication_protocol: "mqtt", MQTT_CLIENT, MQTT_USERNAME, MQTT_PASSWORD, and a nonempty MQTT_TOPIC list. Set the project's MQTT_BROKER and, if needed, MQTT_PORT. See the full example configuration.

result = devices.publish(idx=1, data={"voltage": 230}, topic="data/monitor", qos=1)
print(result)

messages = devices.subscribe(idx=1, topic="data/control", num_messages=1)
for message in messages:
    print(message["topic"], message["payload"].decode("utf-8"))
Setting Behavior
Topic Must match a configured MQTT_TOPIC. Omit for publish only if one topic exists; omit for subscribe to receive from all configured topics.
Payload Publish accepts dict/list (JSON encoded), string, bytes, or bytearray. Subscribe returns raw payload bytes.
QoS qos=0 by default; accepts 0, 1, or 2. QoS 0 does not confirm broker delivery.
Retain Publish defaults to retain=False.
Message count Subscribe defaults to num_messages=1, then disconnects.
Client IDs Publish uses {MQTT_CLIENT}_python_pub; subscribe uses {MQTT_CLIENT}_python_sub.
Timeout Uses config.timeout; subscribe raises TimeoutError if the requested batch does not arrive.
TLS Set tls=True; uses PEM Server_CA if provided, otherwise system trust.

Both methods connect for the operation and disconnect afterward. Subscribe blocks until its message count is reached or it times out. Publish returns topic, mid, qos, and retain; each received message contains topic, payload, qos, and retain. MQTT authenticates with its username/password rather than HTTP API keys. Avoid simultaneous publishers for the same device or simultaneous subscribers for the same device, since each role shares a client ID. Publish and subscribe use different IDs and can run together.

TLS does not turn on automatically when Server_CA exists. The configured port is always respected; if omitted, the default is 1883 or 8883 with TLS. The example certificate placeholder must be replaced before use with TLS, or omitted to use system trust.

Example programs

🟩 Run examples

Run from the repository root after installing the library:

Program Usage
quickstart.py python3 examples/quickstart.py — constructs clients without network calls
devices1.py Loads the script-local account export named in the example; constructs the device client
deviceread.py Loads the account export relative to the working directory and reads configured idx=9; edit the file/path and idx for your project
devicewrite.py python3 examples/devices/devicewrite.py /path/to/config.json --idx 1
devicepublish.py python3 examples/devices/devicepublish.py /path/to/config.json --idx 1 --topic data/monitor
devicesubscribe.py python3 examples/devices/devicesubscribe.py /path/to/config.json --idx 1 --topic data/control --count 1

Device read/write and MQTT examples make live network calls. MQTT examples accept --tls; subscribe accepts --count and an optional --topic.

Modules

🟦 Available modules

Module Class Current availability
openioe.auth Auth Configuration entry point for authentication integration
openioe.devices Devices HTTP read/write and MQTT publish/subscribe
openioe.dataset Dataset Configuration entry point for datasets
openioe.ai AI Configuration entry point for AI workflows
openioe.boards Boards Configuration entry point for boards
openioe.edge Edge Configuration entry point for edge nodes
openioe.digitaltwins DigitalTwins Configuration entry point for digital twins
openioe.usermanagement UserManagement Configuration entry point for users and roles
from openioe.edge import Edge
from openioe.edge.ota import OTA

edge = Edge(config=config)
ota = OTA(config=config)

OTA is a nested package entry point; firmware transfer is not implemented. Indexed AI model and edge firmware objects are preserved in the configuration. See the developer reference for the complete format and module examples.

Handling errors

🟨 Troubleshooting

Invalid inputs, missing devices, duplicate indices, or missing device keys raise ValueError. Missing files raise filesystem exceptions. HTTP errors, connection errors, timeouts, and malformed JSON responses propagate to callers. MQTT subscription denial raises PermissionError; missing Paho raises ImportError with installation instructions. TLS verification failures raise SSL exceptions.

Check that your idx, API keys, MQTT credentials, topics, and broker port match your exported project configuration. An MQTT subscription timeout can mean no matching messages arrived before config.timeout. Partial batches are not returned. Network requests are not automatically retried.

For detailed request bodies, exceptions, validation rules, testing, and release information, use ReadmeDev.md.

Metadata

Release files for openioe 1.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openioe 1.1.2
File Size Uploaded Provenance Actions
openioe-1.1.2.tar.gz 18.8 kB Without provenance Details for openioe-1.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openioe 1.1.2
File Interpreter ABI Platform Actions
openioe-1.1.2-py3-none-any.whl Python 3 none any Details for openioe-1.1.2-py3-none-any.whl

Total release size: 33.1 kB

Release files / openioe-1.1.2.tar.gz

Download URL openioe-1.1.2.tar.gz
Size 18.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e74b61a2106c4f7676428c8c7b578f86396938ecfda4e3f47bffc72976b7de9c
BLAKE2b-256 checksum
How to use checksums
82128e6fb35642263546108e708f3b4f7575548591b424579514e805450664dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / openioe-1.1.2-py3-none-any.whl

Download URL openioe-1.1.2-py3-none-any.whl
Size 14.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
897c1125e13430fabd0892f44e649cf7043f6d965b277be0b73b1a18c19e5b33
BLAKE2b-256 checksum
How to use checksums
93e07c9c2ec5f11b91977198a5da1bce3d9ea27e9813cb92ac636c51ccc68f3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for openioe 1.1.2

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page