Topic Flexibility

The principle

OhioIoT doesn't force you into a single topic format. The platform understands topics between 2 and 5 segments long after the username/deviceID/ prefix (the two segments the broker and the dashboard use to route data to the right account and device). The shorter your topic, the more structure goes into the JSON payload. The longer your topic, the simpler the payload.

Every example below results in the exact same data point arriving at the dashboard: a number called "temp" on the "temperature" graph, with value 72.5, from device a8f3k2m1.

5 segments — everything in the topic

The simplest payload. One value, one topic.

topic:   larry/a8f3k2m1/numb/temperature/temp
payload: 72.5

This is what the Minimalist SDK's mqtt.publish("~/~/numb/temperature/temp", 72.5) produces (the ~/~/ expands to username/deviceID/). Each publish call sends one field.

4 segments — fields in the payload

Move the field name into a JSON object to send multiple fields in one message:

topic:   larry/a8f3k2m1/numb/temperature
payload: {"temp": 72.5, "setpoint": 70}

Both "temp" and "setpoint" appear as series on the "temperature" graph. One MQTT message instead of two.

3 segments — graphs in the payload

Move graph names into the JSON to send data for multiple graphs at once:

topic:   larry/a8f3k2m1/numb
payload: {
    "temperature": {"temp": 72.5, "setpoint": 70},
    "humidity":    {"indoor": 42}
}

This creates two graphs — "temperature" and "humidity" — in a single message.

2 segments — types in the payload

The most compact form. A single message carries multiple data types — numbers, booleans, and status — all at once:

topic:   larry/a8f3k2m1
payload: {
    "numb": {
        "temperature": {"temp": 72.5, "setpoint": 70}
    },
    "bool": {
        "climate": {"heating": true}
    },
    "status": {
        "firmware": "v1.2.0",
        "uptime":   "14h"
    }
}

This is useful for devices that wake up, take all their readings, send one message, and go back to sleep. Everything about the device's state in a single publish.

Gateway mode

There's one more shape: the gateway pattern. A single device — a Raspberry Pi, an ESP32 acting as a hub — publishes data on behalf of multiple devices in one message:

topic:   larry/gateway
payload: {
    "gateway": {
        "sensor_01": {
            "numb": {
                "temperature": {"temp": 72.5}
            }
        },
        "sensor_02": {
            "numb": {
                "temperature": {"temp": 68.1}
            },
            "status": {
                "battery": "82%"
            }
        }
    }
}

The platform unpacks this and treats each nested device as if it had published independently. On the dashboard, you'll see device cards for "sensor_01" and "sensor_02" — not the gateway device itself.

Which format should I use?

For most projects, 5 segments (the default from the Minimalist SDK) is the right choice. It's the simplest to write, the easiest to debug in the serial monitor, and the easiest to understand when you're reading someone else's code.

Use shorter topics when you have a specific reason:

Battery-powered devices that need to minimize radio time — send everything in one 2-segment message, then sleep.

Gateway devices that aggregate data from BLE sensors, serial peripherals, or other non-WiFi sources — use the gateway pattern.

High-frequency publishers that want to reduce MQTT overhead — fewer messages means fewer TCP round-trips.

Start with 5 segments. Compress when you have a reason to.