Tendrl

Docs / Contact / sdks/overview

SDKs & Clients

Tendrl provides official SDKs and clients to connect your devices, services, and applications to the Contact platform. Each SDK handles authentication, message batching, offline resilience, and reconnection so you can focus on your application logic.

Choose Your SDK#

SDK Language Best For Protocol
Python SDK Python 3.9+ Servers, Raspberry Pi, data pipelines HTTPS
Go SDK Go 1.25+ High-performance services, edge gateways HTTPS
JavaScript SDK JavaScript/Node.js 16+ Web apps, Node.js services, React dashboards HTTPS
MicroPython Client MicroPython ESP32, Pico W, embedded microcontrollers MQTT
Nano Agent Any (Unix socket) Language-agnostic local gateway, high-throughput HTTPS

Quick Comparison#

Feature Matrix#

Feature Python Go JavaScript MicroPython Nano Agent
Message publishing Yes Yes Yes Yes Yes
File transfer² No Yes No Yes No
Inbound routing Callback only Yes (client.On()) Callback only Yes (@client.on()) Callback only
Inbound state No Yes (client.OnState(), poll) No Yes (@client.on_state(), MQTT push) No
Dynamic batching Yes Yes Yes Yes Yes
Offline storage SQLite BoltDB⁴ IndexedDB BTree BoltDB
Automatic heartbeats No Yes⁴ No Yes Yes
Manual heartbeat method No Yes Yes No Yes
State table (write) REST¹ REST¹ REST¹ Yes Yes
State table (read) REST¹ REST¹ REST¹ REST¹ Yes
Tether decorator Yes Yes No Yes No
Video streaming No No No Yes No
On-device vision No No No Yes (OpenMV) No
Remote deployment (OTA)³ No No No Yes (add-on) No
React hooks No No Yes No No
Headless mode Yes Yes No No No

¹ REST = no SDK wrapper; call the /entities/status-table REST endpoints directly (GET to read, PATCH to merge, PUT to replace). The MicroPython client can _write_ state over MQTT (update_state/replace_state) but has no on-device read, so read it back over REST.

² File transfer = send_file / check_files / download_file on MicroPython; SendFile / CheckFiles / DownloadFile on Go. The Python and JavaScript SDKs have no file-transfer methods — call the /entities/files REST endpoints directly. Files are scanned by Surface before delivery and are deleted on download. See File Transfer.

³ Remote deployment (OTA) = pushing application code to a device from the dashboard with automatic rollback, via the updater add-on. Selected at provision time (on by default for Full). See Remote Deployments.

⁴ Go managed features are gated on a config file. Offline storage, offline retry, connectivity monitoring, and automatic heartbeats are all off unless a config file at ~/.tendrl/config.json (or /etc/tendrl/config.json) sets "managed": true along with the individual keys. Passing true to NewClient alone does not turn them on. See Go configuration.

Heartbeats: "Automatic" means the client sends heartbeats on its own once started (no code needed). A "manual heartbeat method" lets you push a heartbeat with your own system metrics on demand. The JavaScript SDK has no system-metrics source, so it exposes only the manual sendHeartbeat method and does not send heartbeats automatically. The Python SDK has no heartbeat support at all: neither an automatic loop nor a manual method.

Operating Modes#

Most SDKs support two modes:

The Nano Agent is a standalone binary that provides managed-mode features to any language via a local Unix socket. Use it when your language doesn't have an SDK or when you want a single process handling all Tendrl communication.

Common Concepts#

All SDKs share the same core patterns:

Authentication#

Every SDK authenticates with an API key tied to a Contact entity. You can pass it directly or set the TENDRL_KEY environment variable.

Publishing Messages#

code

client.publish(data, tags)

Messages are JSON objects sent to Contact. Tags control how messages are routed to flows and connectors. All SDKs accept any JSON-serializable data.

Receiving Messages#

Pass a callback when constructing the client. Two clients add tag-based routing on top of that: @client.on() on MicroPython and client.On() on Go. The Python and JavaScript SDKs have no routing decorators or methods — a single callback receives every inbound message, and you branch on tags yourself. The SDK delivers incoming messages automatically; see each SDK's Getting Started page.

State Table#

Each entity has a persistent key-value state table:

Not every client wraps all three. The Nano Agent exposes read/update/replace directly; MicroPython exposes update/replace only (read it back over REST); Go can _read_ the table by polling (client.OnState() / client.CheckState()) but has no write wrapper; Python and JavaScript have no state-table methods at all. In every case you can manage state over the /entities/status-table REST endpoints (GET / PATCH / PUT). See the feature matrix above.

Offline Resilience#

When the network is unavailable, messages can be stored locally and retried when connectivity returns. Each SDK uses a storage engine appropriate for its platform. Offline storage is opt-in on Python (offline_storage=True) and JavaScript (offlineStorage: true), and on Go it requires a config file (see footnote 4). Without it, a message that cannot be delivered is dropped.

Testing against a local stack#

The Python, Go, and JavaScript SDKs and the Nano Agent all read TENDRL_APP_URL to pick the server they talk to, so the same code runs against production, staging, or a stack on your laptop. (The MicroPython client uses the app_url field in its on-device config instead.) See Testing against a local or staging stack.

Next Steps#

Pick the SDK that fits your stack and follow the Getting Started guide:

Once a client is publishing, Testing against a local or staging stack shows how to point it somewhere other than production.

← Back to Contact docs