18 · Streaming from a device over MQTT#
Publishing readings straight from your own hardware into Mechbase.
Get a device you built or bought to stream its readings into Mechbase without a
person in the loop. This chapter is written for a developer wiring a sensor,
gateway, or PLC up to Mechbase over MQTT — you publish a small JSON message
to a topic, and it lands on a measurement point as an ordinary reading. Every
example is copy-paste; replace the <PLACEHOLDERS>.
If your hardware is a MaintNode edge device, you don’t need this chapter — MaintNode uploads to Mechbase on its own (over HTTPS, not MQTT). See MaintNode devices and automatic data. This chapter is for streaming from your own device.
The one-paragraph version#
Your device connects to an MQTT broker and publishes a JSON message to a topic named for your installation, device, and channel. Mechbase subscribes to that broker, reads the message, looks up which measurement point the device’s channel is mapped to, and creates a reading there. From that point on it’s an ordinary reading — it trends, gets scored against the point’s alarm rule, and drives the asset’s health state. Three things make the rest of this chapter make sense:
One topic per channel —
mechbase/{installation_id}/{device_id}/{channel}.One small JSON payload per message — every payload carries a
tsand atype, and there are five types.A mapping binds the channel to a point — you set that up once in Mechbase; without it, the message is rejected.
Before you start: what you need#
Your broker details. Mechbase reads its broker from a per-installation setting, and the actual host and credentials aren’t fixed in the product — get them from your Mechbase administrator:
Host — the broker hostname. There’s no default; it’s configured per installation.
Port — defaults to
1883.TLS — off unless your broker is configured for it. If it is, your administrator will tell you the TLS port.
Username / password — both optional. Some brokers require them, some don’t. Use them only if your administrator hands them to you.
Your installation ID. The numeric ID of the installation these readings
belong to. You can read it from the address bar while using Mechbase
(.../installations/<ID>/...), or ask an administrator. It goes into the topic
as {installation_id}.
A device ID. Any stable identifier for your device — a serial number or
name. It goes into the topic as {device_id}, and you’ll enter the same value
in Mechbase when you map the channel to a point.
Connect to the broker#
Any MQTT client works. The examples below use the standard paho-mqtt client for Python — the point is the connection parameters, not the library:
pip install paho-mqtt
import paho.mqtt.client as mqtt
BROKER_HOST = "<from your administrator>"
BROKER_PORT = 1883 # default; a TLS broker may use a different port
USERNAME = "<from your administrator>" # optional — omit if not required
PASSWORD = "<from your administrator>" # optional
client = mqtt.Client()
if USERNAME:
client.username_pw_set(USERNAME, PASSWORD)
# client.tls_set() # uncomment ONLY if your broker uses TLS
client.connect(BROKER_HOST, BROKER_PORT, keepalive=60)
Username and password are sent only if set — leave them out entirely if your broker doesn’t require them.
TLS is off unless your broker uses it. Enable it only when your administrator says so.
keepalive— pick whatever suits your device. Mechbase’s own subscriber-to-broker connection uses a 60-second keepalive, but that’s an internal Mechbase setting and is independent of your client’s keepalive; you don’t have to match it.
Note: Mechbase subscribes to
mechbase/{installation_id}/+/+for your installation — one broker connection covers all your devices and channels. You just publish; Mechbase is already listening.
The topic format#
Publish to:
mechbase/{installation_id}/{device_id}/{channel}
mechbase— the topic prefix.mechbaseis the default; your administrator will tell you if your installation uses a different one.{installation_id}— your installation’s numeric ID.{device_id}— your device’s identifier.{channel}— the channel number on the device.
Mechbase splits the topic on / and requires exactly four parts — anything
else is ignored. The {channel} segment is read as an integer when it’s all
digits; a non-numeric segment is read as no channel (null), which is how
you address a single-channel device (more in
How a channel maps to a point).
INSTALLATION_ID = 42
DEVICE_ID = "pump-07"
CHANNEL = 1
topic = f"mechbase/{INSTALLATION_ID}/{DEVICE_ID}/{CHANNEL}"
The payloads#
Every message is a JSON object with two required fields — ts (an integer
Unix timestamp in epoch milliseconds, minimum: 0) and type — plus the
fields for that type. Five type values are accepted: waveform, spectrum,
scalar, status, production.
Publish the JSON as the message body:
import json, time
# ts is epoch milliseconds — multiply the Unix seconds from time.time() by 1000
payload = {"ts": int(time.time() * 1000), "type": "scalar", "value": 72.5, "unit": "C"}
client.publish(topic, json.dumps(payload))
Scalar — a single value#
{"ts": 1719763200000, "type": "scalar", "value": 72.5, "unit": "C"}
Required: ts, type, value (a number). Optional: unit (a string). This is
the everyday case — one reading, one number.
What Mechbase does with a scalar depends on the type of the point it lands on:
On most points it’s simply the reading’s value.
On an ultrasound point it’s stored as the dB level.
On a State point it’s an on/off sample — any value above 0 is on — recorded as periods rather than a trend. Ideal for a fault contact or a run lamp.
On a Production (running-hours) point it’s taken as an hour-meter total that resets the running-hours count. To say running or stopped, send a
productionmessage instead (below).
Note:
typemust be exactly one of the five values above — it’s a closed set. A message with any othertypefails validation and is rejected, so nothing is stored.
Waveform — a time-domain signal#
{"ts": 1719763200000, "type": "waveform", "fs": 5120, "samples": [...]}
Required: ts, type, fs, samples.
fs— the sample rate (a number, must be greater than0).samples— an array of numbers, at least1and at most the waveform cap (see Size and sample caps).
Spectrum — a frequency-domain signal#
{"ts": 1719763200000, "type": "spectrum", "fmax": 2000, "lines": [...]}
Required: ts, type, fmax, lines.
fmax— the maximum frequency (a number, must be greater than0).lines— an array of numbers, at least1and at most the spectrum-line cap (see below).
Status — a heartbeat#
{"ts": 1719763200000, "type": "status", "battery": 85, "firmware": "1.2.3"}
Required: ts, type. Optional: battery (integer 0–100), rssi
(integer), firmware (string).
Heads-up: a status message does not create a reading. It only updates the device’s last-seen time on its active mappings — it’s a heartbeat, not a measurement. Don’t expect it to show on a trend.
Production — running or stopped#
{"ts": 1719763200000, "type": "production", "on": true}
Required: ts, type, on (a boolean). Use it to tell Mechbase whether the
machine is running. Repeats of the current state are deduplicated — send it
whenever you like; only genuine changes are recorded.
Size and sample caps#
Arrays are bounded so a buggy or hostile device can’t drive an unbounded payload into a single reading:
Field |
Cap |
Why |
|---|---|---|
Waveform |
|
Samples persist to a |
Spectrum |
|
Matches the analyser’s FFT line cap, so a spectrum message can’t bloat a row. |
Both arrays also require at least one element. Exceed a cap and the message is rejected.
Heads-up: the spectrum
linesarray is stored but currently has no reader anywhere in Mechbase — it’s bounded only to stop row bloat, and may be removed. If you need frequency-domain data on a trend, prefer scalar band values or send awaveformand let Mechbase’s analysis path handle it.
How a channel maps to a point#
A message only lands somewhere if the topic’s device and channel are mapped to
a measurement point. The mapping binds (installation, device_id, channel) to
one point. You create it in Mechbase, not over MQTT:
Open the measurement point you want the readings to land on and click Edit (
E).Under Sources, click Add source, and leave Source type on MQTT — the same Sources list that holds MaintNode channels (Working with assets).
Enter the Device ID exactly as it appears in your topic’s
{device_id}.Enter the Channel number. Leave it blank for single-channel devices — a blank channel is stored as
nulland matches a topic whose{channel}segment is non-numeric.Click Add source. A device ID and channel can feed only one point; Mechbase tells you if that pair is already in use.
At ingest, Mechbase looks up the mapping for the message’s device and channel:
Found — it creates the reading against that point. The reading also carries the
sensor_id(your device ID) and, when a channel is set, thesensor_channel, in its metadata.Not found — the message is rejected and logged as
No mapping for {device_id}/{channel}. Nothing is stored. This is the first thing to check if a reading doesn’t appear.
So the join between your hardware and Mechbase is one line on a point: this point is fed by that device channel. After that, everything about trends and alarms applies automatically, exactly as in MaintNode devices and automatic data.
Verifying it arrived#
Publish a scalar message and confirm the loop end to end:
Check the point. Open the mapped measurement point in Mechbase — the new reading should appear on its trend with the value and timestamp you sent, and the point’s Sources shows MQTT
, CH with a live dot. On the edit page, the source row shows when it was last seen. (Astatusmessage won’t add a reading; it only bumps the device’s last-seen time.)No reading? Check, in order — the topic has exactly four parts and the right installation ID and prefix; the Device ID and Channel on the point’s source match the topic byte-for-byte; and, for arrays, you’re under the caps.
For waveforms, the raw samples persist to a Mechbase data-recorder file
(.dr). Download it from the reading’s Attachments — see
A single reading’s page
— and read it in Python with the dr-files package:
pip install dr-files
https://pypi.org/project/dr-files/ · https://github.com/arpedon/dr-files
If the .dr opens and the sample count and rate match what you published, the
whole path is working.
Quick reference#
Thing |
Value |
|---|---|
Topic |
|
Topic parts |
Exactly 4, split on |
Channel |
Integer when all digits; otherwise |
Default prefix |
|
Default port |
|
Keepalive |
|
Auth |
Username/password (both optional), TLS optional — from your administrator |
Required in every payload |
|
Payload types |
|
Waveform |
|
Spectrum |
|
Scalar |
|
Status |
|
Production |
|
Waveform persistence |
|
No mapping |
Message rejected: |
Read |
|