The vibration edge (vibration-edge) can post straight to OpexMX. Put OpexFlow in between and the same
windows gain a record of what arrived, a check against the contract, thinning that keeps one sensor under
the OpexMX rate limit, and a queue of what OpexMX refused or could not take. The edge needs no change: it
already lets you choose the URL it posts to.
The flow is the example Vibration edge to OpexMX (Examples, Plant). It runs with a mock OpexMX the moment it is deployed.
What the edge sends
| Edge output | Sent when | Goes to |
|---|---|---|
POST {url}/inference, camelCase JSON: sensorId, probability, label, alert, rms, timestamp, modelVersion; v2 (--method multifault) adds schemaVersion, taxonomyVersion, featureVersion, faults[], acquisition, severity |
every window with --push-mode continuous; with gated (default) on alert onset, every --burst-secs during an alert, on resolve and every --heartbeat-secs. --method fft sends it for a normal window unless --fft-push always |
OpexMX POST /api/vibration-monitoring/inference |
POST {url}/spectrum: sensorId, sampleRate, windowSize, unit, rms, bins[], alert, timestamp |
--method fft, for a fault window, or for every window with --fft-push always |
OpexMX POST /api/vibration-monitoring/spectrum |
MQTT opexmx/ingest/<sensorId>, the same data in snake_case |
--mqtt-host set |
the NATS MQTT gateway (see below) |
Every post carries Authorization: Bearer <token>. OpexMX binds one mx_… key to one sensor and answers 401
for a window of another sensor. OpexMX allows 120 requests per minute per key, shared by /inference and
/spectrum, and answers 429 with Retry-After above that.
The edge appends /inference and /spectrum to --opexmx-url itself, so pointing it at OpexFlow is one flag:
vibration-edge --serve --method fft --csv data/9mei_50hz.csv --fft-channel 2 --fft-unit g \
--sensor-id <sensor id> --rpm 3000 --line-freq 50 \
--push-mode continuous --fft-push always \
--opexmx-url http://<opexflow>:3600/api/ingest/vibration \
--opexmx-token <an OpexFlow API token>The two flow sources are vibration:inference and vibration:spectrum (POST /api/ingest/vibration/inference
and .../spectrum). The bearer token is OpexFlow’s, not OpexMX’s: the sensor’s mx_… key stays in OpexFlow
as a secret and is added when the window is forwarded.
The flow
vibration:inference -> Clean inference -> Contract v1/v2 -> Value rules ─┐
vibration:spectrum -> Clean spectrum -> Spectrum contract -> Value rules ┴-> Once per sensor + timestamp
-> Alert or normal -> [alert] 1 per ALERT_EVERY s -> Post alert (retry 4x) ─ still down: park (held for redrive)
-> [else] 1 per NORMAL_EVERY s -> Post normal (retry 4x) ─ still down: shed
a 4xx answer: dead-lettered by the http node for a person (it never takes the error wire)
once ──────────────> inference windows -> event -> local history
schedule (optional) -> every 15 s replay parked alerts| Step | Node | What it does |
|---|---|---|
| Clean | prep |
Casts numbers with decimal commas or as text ("0,91", rms.*, faults.*.probability; a value that is not a number fails the record and names the field), the alert flag, and the timestamp to UTC with a Z (OpexMX refuses the edge’s +00:00 on /spectrum; an offset such as +07:00 and nanoseconds are converted). Trims the label. Spectrum bins that are null (the edge writes NaN as null) or text are interpolated from their neighbours; a gap at either end stays null and the contract check refuses the window. Then it moves the fields OpexMX knows into request, so an unknown field is not forwarded, and sets kind. |
| Contract | validate |
The catalogue types vibration.inference (v1 passes, v2 requires faults[]) and vibration.spectrum. A broken window is quarantined in the dead-letter queue with every rule it broke. |
| Value rules | quality |
sensor_known (a window of another sensor), probability_0_1, label_present, rms not negative, sample_rate_positive, window_size_max (65536, OpexMX’s limit), bins_present, timestamp_not_ahead (a clock more than an hour ahead). Each is fail: the window is parked with the rule name. |
| Once | dedupe |
sensorId@timestamp/kind, one day. The edge resends the same body when OpexFlow answers late. The key is committed only after OpexMX took the window, so a failed delivery can be sent again. |
| Alert or normal | branch |
An alert is alert: true, or an inference whose label is not Mesin Normal (v2: the label is the top flagged fault). |
| Anti-flood | dedupe with a short TTL |
The first record per sensor and kind passes, the rest of that interval is dropped. Alerts: one per ALERT_EVERY s (default 2); normal windows and heartbeats: one per NORMAL_EVERY s (default 10). Two kinds and two lanes give at most 72 requests per minute per sensor, under the 120 limit, and an alert is never held back by a heartbeat that just passed. |
| Post | http with retry |
POST <OpexMX>/api/vibration-monitoring/{inference|spectrum}, auth: bearer (the sensor’s secret), body_from: request. Four attempts with 0.5 s doubling back-off (capped at 4 s, Retry-After honoured) for network errors, timeouts, 408, 429 and 5xx. error_on: transient: only a call still failing after the attempts takes the error wire; a 4xx does not. |
| Hold / shed | park / filter |
An alert that could not be delivered is parked with the reason [redrive:<sensor>] held, OpexMX unavailable: …; a normal window is shed (the next one is seconds away). |
| History | event + storage |
Every de-duplicated inference window is stored as the event vibration.inference (idempotent on sensorId@timestamp, kept 90 days, GET /api/events/log?type=vibration.inference&subject=<sensor>), before the thinning, so history holds every window while OpexMX gets the thinned stream. |
What was kept, and why
| Kept | Why a newer node does not replace it |
|---|---|
dedupe as the per-sensor throttle |
The only node with a hard guarantee of “at most one per N seconds”. deadband passes any change at once (a flapping probability still floods; its heartbeat is a floor, not a ceiling), and window emits an aggregate, not the original window OpexMX expects. A deadband in front of the normal lane would only add noise. |
| The redrive tick (optional) | park replaces the JavaScript hold step and keeps the alert safe, but no node replays parked rows on a schedule; without the tick a person replays them (Dead letters, or one POST /api/pipeline/dead-letters/replay). The tick is that call on a clock. |
non_idempotent: true on the post |
OpexMX ignores an Idempotency-Key, so a retry after a lost answer can store a window twice. Accepting that is better than losing the alert. |
Not possible with the new nodes: checking that bins is windowSize/2 + 1 long. quality has no array length and validate cannot compare two fields; OpexMX answers 400 and the window is dead-lettered with its message.
signal is not used: the edge sends results, not raw windows. If you send raw waveforms to OpexFlow, a signal node computes the spectrum, ISO 20816 zone and bearing frequencies there (see the example Vibration features), and the edge’s server-side sync of rpm and bearing settings is no longer needed.
Delivery and failure
| OpexMX answers | What happens |
|---|---|
201 |
Done. The key is committed. The edge gets 200. |
400, 401, 403, 404 |
The http node fails the record for good: dead-lettered at post_alert / post_normal with OpexMX’s answer. The edge gets 422 and does not resend. Fix the cause (register the sensor, correct the key secret, edit the record) and replay the row. |
429, 5xx, timeout, refused |
Retried four times. If it still fails: an alert is parked ([redrive:<sensor>]), a normal window is shed. The edge gets 422. |
The optional Redrive tick (enable it by giving the input This connector’s URL) replays rows tagged
[redrive:<sensor>] every 15 seconds, 200 at a time, through the whole flow. A replay passes the de-duplication
because the first delivery never committed its key. It needs OPEX_API_TOKEN in the environment and in
transform.executor.http_env_allowlist.
Limits:
- OpexMX does not de-duplicate. If it stored a window but the answer was lost, the retry or the replay stores it again.
- A retry holds the sensor’s lane for up to about 6 seconds, because records of one sensor run in order. During an outage the edge’s 10 s timeout can fire first; the edge then resends and the duplicate is dropped.
- During an outage every alert that passed the throttle is parked; the dead-letter queue keeps 10 000 rows.
- A window delivered late is stored by OpexMX with its delivery time, not the edge timestamp.
- OpexMX turns a database failure into
400, which is dead-lettered for a person; read the message (D1_ERROR) before correcting anything.
Several sensors
A source name exists once per instance, so give each sensor its own instance: the example asks for the Edge
source name (vibration, vibration-pump2, …), the Sensor id and the name of the secret with that sensor’s
key. The edge of that sensor posts to /api/ingest/<source name>. A window with another sensor id is refused, so a
mis-configured edge cannot write into a neighbour’s record.
Over MQTT instead
The edge can publish to the NATS MQTT gateway (--mqtt-host). MQTT carries snake_case keys in a machine record (metadata.value). Add a NATS or MQTT source and put prep steps in front
of the Clean node that flatten/rename it to the HTTP shape (sensor_id → sensorId, latency_us → inferenceLatUs,
faults[].gate_reason → gateReason); the flow has no such steps today (the earlier JavaScript version did), and MQTT carries no spectrum.