Docs / Contact / sdks/micropython/configuration

MicroPython Client Configuration

The MicroPython client is configured through a combination of the config.json file on the device and constructor parameters.

Config File

Create /config.json on the board's filesystem:

{
    "api_key": "your_entity_api_key",
    "wifi_ssid": "YourNetwork",
    "wifi_pw": "YourPassword",
    "app_url": "https://app.tendrl.com",
    "mqtt_ssl": true
}

The SDK also checks /lib/tendrl/config.json for built-in defaults. User config overrides built-in values.

Config File Fields

Constructor Parameters

client = Client(**kwargs)

Core

Callbacks

Inbound routing (@client.on())

Register handlers on the client instance after construction. Routes are checked in registration order; first match wins.

Combine parameters for AND semantics (e.g. @client.on(msg_type="publish", tag="config-update")). See API Reference.

Use @client.on_state to receive remote state table updates; it pairs with REST state reads/writes. Polled at check_msg_rate on Python, Go, and JavaScript; pushed over MQTT on MicroPython.

Timing & Performance

Storage

Health

Async Mode

Memory Considerations

The client adapts to available RAM:

• Queue size: Max 150 messages, dynamically reduced based on gc.mem_free()
• Batch size: Max 75 messages, adjusted per-send based on available memory
• MQTT payload limit: 4096 bytes per message chunk
• Offline store: Capped at offline_max_records (default 1000) with oldest-first eviction so a long outage can't exhaust flash. The cap bounds file size, not write volume, and buffered messages are not guaranteed to survive a power cut (durability)

Flash footprint

SDK install size on flash (precompiled .mpy under /lib/tendrl; every install path ships .mpy, not .py source):

Use minimal for publish/subscribe only. Add the files package for HTTP file transfer. Use full when you need offline message queuing or the client database. Add the OTA package (updater) for remote app-code deployment; it's a standalone add-on, not bundled into Full. Streaming is a separate add-on for camera boards.

For boards with less than 300KB RAM, consider:

• Using the minimal installation (no database)
• Setting client_db=False
• Reducing max_batch_size to 5–10
• Setting client_db_in_memory=True (default, avoids flash writes)

MQTT Connection Details

The client automatically discovers and configures all MQTT connection parameters from your API key: broker address, credentials, and the topics your entity publishes and subscribes to. You don't configure any of this manually; provide a valid API key and the SDK handles the connection for you.

Example Configurations

Basic Sensor (ESP32)

{
    "api_key": "your_key",
    "wifi_ssid": "HomeNetwork",
    "wifi_pw": "password123"
}

client = Client(debug=True, send_heartbeat=True)

Memory-Constrained (Pico W)

On the Pico W client_db=False is required, not just a memory optimization: stock rp2 firmware has no btree module, so MicroTetherDB cannot load at all. The client detects this and disables storage with a warning rather than failing, but setting it explicitly documents the intent.

Stock rp2 firmware also has no frozen umqtt. You don't need to do anything about that: every Tendrl install path checks whether the board's firmware provides an MQTT client and pushes the vendored umqtt only when it doesn't.

client = Client(
    debug=False,
    client_db=False,
    max_batch_size=5,
    send_heartbeat=False
)

Async with Streaming (OpenMV)

client = Client(
    mode="async",
    debug=True,
    send_heartbeat=True,
    offline_storage=True
)

← Back to Contact docs