Mechbase Manual

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 ts and a type, 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. mechbase is 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 production message instead (below).

Note: type must be exactly one of the five values above — it’s a closed set. A message with any other type fails 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 than 0).

  • samples — an array of numbers, at least 1 and 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 than 0).

  • lines — an array of numbers, at least 1 and 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

2,097,152 (2 × 1024 × 1024)

Samples persist to a .dr file at 2 bytes/sample — this caps one message at ~2M samples, roughly 4 MB on the wire.

Spectrum lines

6,400

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 lines array 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 a waveform and 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:

  1. Open the measurement point you want the readings to land on and click Edit (E).

  2. Under Sources, click Add source, and leave Source type on MQTT — the same Sources list that holds MaintNode channels (Working with assets).

  3. Enter the Device ID exactly as it appears in your topic’s {device_id}.

  4. Enter the Channel number. Leave it blank for single-channel devices — a blank channel is stored as null and matches a topic whose {channel} segment is non-numeric.

  5. 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, the sensor_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:

  1. 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. (A status message won’t add a reading; it only bumps the device’s last-seen time.)

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

mechbase/{installation_id}/{device_id}/{channel}

Topic parts

Exactly 4, split on /

Channel

Integer when all digits; otherwise null (single-channel)

Default prefix

mechbase

Default port

1883 (TLS off unless configured)

Keepalive

60 s on Mechbase’s subscriber connection (internal; your client’s is independent)

Auth

Username/password (both optional), TLS optional — from your administrator

Required in every payload

ts (integer, epoch milliseconds, minimum: 0) and type

Payload types

waveform, spectrum, scalar, status, production

Waveform

fs (> 0), samples (1 – 2,097,152 numbers)

Spectrum

fmax (> 0), lines (1 – 6,400 numbers)

Scalar

value (number), unit (string, optional)

Status

battery 0–100, rssi int, firmware str — all optional; heartbeat only, no reading

Production

on (boolean); repeats deduplicated

Waveform persistence

.dr file at 2 bytes/sample (~4 MB max message)

No mapping

Message rejected: No mapping for {device_id}/{channel}

Read .dr files

pip install dr-files · pypi.org/project/dr-files

Markdown · PDF · Updated 16 Nov 2026