# 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](../maintnode.md). 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:

```bash
pip install paho-mqtt
```

```python
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](#how-a-channel-maps-to-a-point)).

```python
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:

```python
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

```json
{"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

```json
{"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](#size-and-sample-caps)).

### Spectrum — a frequency-domain signal

```json
{"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

```json
{"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

```json
{"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](../assets.md#how-a-point-gets-its-data-sources)).
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](../maintnode.md).

## 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 <device>, CH <n>* 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](#size-and-sample-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](../measurements.md#a-single-readings-page)
— and read it in Python with the **dr-files** package:

```bash
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](https://pypi.org/project/dr-files/) |
