A vibration sensor or an edge device sends waveforms: a few thousand accelerometer samples per
channel. Condition monitoring does not work on the raw samples but on features of them: how strong
the vibration is, at which frequencies, whether the bearing’s defect frequencies stand out. The
signal node (“Vibration features” in the palette, group Machines and lines) computes those
features inside the flow, so a plant engineer can shape sensor data on the canvas without a script.
It is the OpexFlow side of vibration-analyzer-edge: the same window, the same maths, the same
numbers. The edge’s 79-feature ofv1 vector is reproduced and pinned against the edge’s golden
vectors at a tolerance of 1e-5, so a model trained for the edge can be fed from OpexFlow.
{ "id": "vib", "type": "signal", "label": "Vibration features",
"samples": "metadata.waveform",
"sample_rate": "${metadata.fs}",
"rpm": "${metadata.rpm}",
"spectrum": { "peaks": 5, "bins": 32, "fmax": 1000 },
"bands": [{ "name": "low", "hz": [10, 100] }],
"orders": [1, 2, 3],
"bearing": { "n_balls": 9, "ball_dia": 0.3126, "pitch_dia": 1.537 },
"velocity": { "unit": "g", "iso_class": "II" } }One record is one window. The node reads the samples, measures every channel, writes the result into
the record (by default at signal) and passes the record on. It keeps no state: the same window
always gives the same output, restart or not. Cutting a continuous stream into windows is the job of the
node in front of it.
The signal node
Input
| Field | Meaning |
|---|---|
samples |
Dot-path of the samples, default samples. On a machine record the data lives under metadata, e.g. metadata.waveform. |
layout |
channels (default): one array per channel. rows: one row per sample, one column per channel (a CSV). |
channels |
Names. Picks (and orders) the keys of an object; names the arrays of a list or the columns of rows. Default ch1, ch2, … |
sample_rate |
Required. Hz, a number or a ${path} template such as ${metadata.fs}. |
rpm |
Shaft speed, a number or ${path}. Only the outputs marked needs rpm use it. |
on_bad |
A sample that is not a finite number: fail (default), hold (repeat the last good value; the first good one fills a bad start), zero. |
samples may hold:
- one array of numbers (one channel, named
ch1), - an object
{"x": [...], "y": [...], "z": [...]}, - a list of arrays
[[...], [...]], - with
layout: rows, a list of rows[[x, y, z], ...].
Elements are numbers or numeric text. Decimal commas are read as such ("0,588399"); with both
separators the commas are thousands separators ("1,234.5"). null, other text, NaN and inf are bad
samples: they fail the record with the index of the first one, unless on_bad repairs them. The number
of repaired samples is reported as bad_samples per channel.
A window has 8 to 65,536 samples per channel (any length, not only powers of two), at most 16
channels. Frequencies above sample_rate / 2.56 are outside the analysis band (the edge’s anti-alias
guard) and are left out of every output; the node says so in warnings.
Output
The result goes to into (default signal):
{ "sample_rate_hz": 50.0, "rpm": 328.0, "window": "hann",
"channels": { "x": { "samples": 512, "bad_samples": 0, "time": { }, "spectrum": { }, "velocity": { } } },
"warnings": [] }On a machine record (one with a top-level machine) a path that is not one of the machine-data keys is
placed under metadata, so into: signal becomes metadata.signal. That keeps the record valid for a
filter or branch after the node. On any other JSON record the path is used as given. A filter reads
the same field either way as metadata.signal.channels.x.time.rms, because a filter views a plain JSON
record as a machine record whose metadata is that record.
drop_input: true removes the samples from the record once analysed, which keeps the frame small for
the sinks behind it. Per-channel and top-level warnings (an order above the band, a missing speed)
appear only when there is something to say.
Which outputs
Every output is selected by its key; absent means off. At least one must be on.
| Key | Needs rpm | What it gives |
|---|---|---|
time (default on) |
no | mean, rms, std, peak, peak_to_peak, crest, kurtosis, skewness. |
spectrum |
no | The amplitude spectrum, down-sampled to bins cells and/or its peaks strongest lines. |
bands |
no | Energy per named band in Hz. |
order_bands |
yes | Energy per named band in multiples of the running speed. |
orders |
yes | Amplitude and SNR at 1x, 2x, 3x … of the running speed. |
bearing |
geometry or orders |
BPFO, BPFI, BSF, FTF with amplitude and SNR of each and its harmonics. |
envelope |
no | Demodulated resonance band: kurtosis and the envelope spectrum. |
velocity |
no | RMS velocity in mm/s over a band, 1x/2x line velocity, and the ISO 20816 zone. |
ofv1 |
yes | The 79-feature vector of the vibration edge. |
Common settings: window (hann, the periodic Hann of the edge, default; or rect) and remove_dc
(default on: the mean, such as gravity or a sensor offset, is removed before every measure, as the
edge does for its recordings).
Time domain
rms is the root mean square of the signal after the mean is removed (remove_dc), std the
population standard deviation, peak the largest absolute value, peak_to_peak max minus min,
crest = peak / rms, kurtosis the excess kurtosis (a normal signal is 0, a sine is -1.5; impacts
push it up) and skewness the third standardised moment. A flat signal gives 0 for the last four
instead of dividing by zero. mean is the raw offset.
Spectrum
|rfft(x w)| / (sum(w) / 2) with a periodic Hann window w: a sine of amplitude A sitting on a bin
reads exactly A. Values are in the unit of the samples.
"spectrum": { "bins": 32, "peaks": 5, "fmin": 0, "fmax": 1000, "reduce": "max" }binscuts[fmin, fmax)into at most that many equal-width cells (never more than there are FFT bins) and reduces each withreduce(maxdefault,mean,rms). The output carries the cell centreshzand the amplitudesamp.peakslists the strongest local maxima as{hz, amp}.hzis refined by parabolic interpolation;ampis the strongest bin.fmaxdefaults tosample_rate / 2.56.
Bands and orders
"bands": [{ "name": "low", "hz": [10, 100] }],
"order_bands": [{ "name": "sub", "orders": [0.3, 0.8] }],
"orders": [1, 2, 3]A band holds the bins with low <= f < high (DC is never in a band). Each reports rms
(sqrt(sum(a^2) / 2 / ENBW), so a bin-centred sine of amplitude A gives A/√2 whatever the window),
peak and peak_hz, the fraction of the spectral power above DC, and the bins it spans. A band
narrower than the frequency resolution sample_rate / n holds no bin and is reported with a warning.
orders reads the line at order x rpm/60 Hz: the strongest bin within ±3 % of the frequency (at
least ±1.5 bins), reported as {order, hz, detected_hz, amp, snr_db}. snr_db is the peak against the
median of the ring around the window, clipped to -6…60 dB, exactly the SNR feature of ofv1. The
results are keyed "1x", "2x", "0.5x".
Without a usable rpm in the record (missing, not a number, 0 or negative: a stopped machine), the
rpm-based outputs are left out and a warning says so; the rest of the record is still analysed.
Bearing frequencies
"bearing": {
"n_balls": 9, "ball_dia": 0.3126, "pitch_dia": 1.537, "contact_angle_deg": 0,
"tolerance_pct": 2, "harmonics": 3
}From the geometry (needs rpm), with the shaft frequency fr = rpm / 60, the ratio
r = ball_dia / pitch_dia and the contact angle θ:
| Formula | |
|---|---|
| FTF (cage) | ½ · fr · (1 − r cos θ) |
| BSF (ball spin) | (pitch_dia / 2 ball_dia) · fr · (1 − (r cos θ)²) |
| BPFO (outer race) | (n / 2) · fr · (1 − r cos θ) |
| BPFI (inner race) | (n / 2) · fr · (1 + r cos θ) |
For the CWRU drive-end bearing (9 balls, 0.3126 and 1.537 in) this gives the published multipliers
3.5848 (BPFO), 5.4152 (BPFI), 0.3983 (FTF) and 2.357 (BSF). Instead of the geometry you can give the
frequencies directly: "hz": {"bpfo": 107.3, "bpfi": 162.2} (no rpm needed) or, as most catalogues
list them, as multiples of the speed: "orders": {"bpfo": 3.5848}. A directly given value overrides
the geometry for that defect; any subset works.
For every defect the node reports its hz (and order when the speed is known) and, for each of
harmonics (1 to 6, default 3), the line found within tolerance_pct (default 2 %, never below 1.5
bins): {h, hz, detected_hz, amp, snr_db} in the spectrum and, when envelope is on, in the envelope
spectrum as well (envelope list). A harmonic above sample_rate / 2.56 is skipped with a warning.
A bearing defect usually does not show at its own frequency in the plain spectrum: it amplitude-modulates a
structural resonance. Turn on envelope and read the envelope lines.
Envelope
"envelope": { "band": [2000, 5000], "spectrum": { "peaks": 5 } }The window is band-passed to band (the resonance the defect excites) with an FFT brick-wall filter,
demodulated with the analytic signal, and the envelope’s spectrum is taken with the same window and
normalisation. Reported: band_hz (the upper edge is capped at sample_rate / 2.56), the envelope mean
and rms, the envelope kurtosis, the band_kurtosis of the band-passed signal, and the
spectrum (default: the 5 strongest peaks; bins and peaks work as above). A band above the usable
range is skipped with a warning.
Velocity and the ISO 20816 zone
"velocity": { "unit": "g", "band": [10, 1000], "iso_class": "II" }Velocity RMS in mm/s by frequency-domain integration: mean removed, windowed, one-sided power
P[k] = 2 |X[k]|² / (N Σw²), divided by (2πf)² for an acceleration, summed over the band. unit is g
(9806.65 mm/s²), m/s2, mm/s2 (integrated), or mm/s, m/s (a velocity sensor, used as is).
Without a band it is the ISO band: 10-1000 Hz (2-1000 Hz below 600 rpm), upper edge min(1000, sample_rate / 2.56).
An explicit band is also capped at sample_rate / 2.56; the band used is reported as band_hz.
With the speed known, x1_mm_s and x2_mm_s are the RMS velocity of the 1x line and of the line at
twice the refined 1x frequency.
iso_class (I to IV) adds the zone. The upper bounds of zones A, B and C in mm/s RMS are the
class table of the edge (severity.rs):
| Class | A / B | B / C | C / D |
|---|---|---|---|
| I | 0.71 | 1.8 | 4.5 |
| II | 1.4 | 2.8 | 4.5 |
| III | 2.3 | 4.5 | 7.1 |
| IV | 3.5 | 7.1 | 11.0 |
A value on a bound belongs to the better zone (2.8 mm/s in class II is B, 2.81 is C). The result is
"iso": {"class": "II", "zone": "B", "limits_mm_s": [1.4, 2.8, 4.5]}. Instead of a class, give your own
limits as "limits_mm_s": [a, b, c] (rising, positive). A wrong unit scales every number: the zone is
only as good as the sensor calibration.
The ofv1 feature vector
"ofv1": { "env_band": [2000, 5000], "gear_teeth": 20, "named": false }The 79 order-normalised spectral and envelope features the edge’s multi-fault model is trained on
(order amplitudes and SNRs, energy fractions, kurtosis, crest, bearing envelope SNRs, gear-mesh and
sideband features, non-synchronous prominence, flatness and centroid). Output: {"version": "ofv1", "features": [ ... 79 numbers ... ]}; with named: true an object keyed by feature name
(ord_amp_1, env_bpfo_h1, …). It needs rpm, a window of an even length of at least 64 samples,
and the envelope band (env_band, or the band of envelope). The bearing geometry of bearing is
used for the bearing features. A window the reference rejects gives ofv1: null and a warning.
Parity with vibration-analyzer-edge
| Part | Status |
|---|---|
Hann window, amplitude spectrum abs(rfft(x w)) / (sum(w)/2) |
Same formula, f64. |
ofv1, all 79 features |
Ported in full. Pinned against the 7 golden cases of the edge (multifault_golden.json: tones, amplitude-modulated bearing carriers, gear sidebands, no geometry, invalid envelope band) at tolerance 1e-5. |
| Velocity RMS, 1x, 2x, band | Ported. Pinned against the edge’s severity_golden.json measure cases at 1e-5. |
| ISO class table and zone | Same table and the same boundary rule. |
| Bearing formulas | The edge’s, checked against hand values and the published CWRU multipliers. |
rules1 fault rules, the sevgate1 gate with baselines, the axial-channel 1x |
Not ported: they are fault decisions, not features. Use the features with a filter / branch, or send them to the model. |
The edge’s magnitude_spectrum is a different, older output (raw magnitudes, n - 1 window, power of
two only); the node uses the ofv1 window and normalisation, which is the edge’s calibrated one.
Cost, limits and restarts
- At most 65,536 samples per channel and 16 channels per record; a record above that fails with the limit named. A window over 4,096 samples in total is analysed on the blocking thread pool, so a long window does not stall other flows.
- The FFT is written in the binary (radix-2 for powers of two, a chirp-z transform for every other length): no extra dependency. A 65,536-sample window transforms in a few milliseconds.
- Restarts and state. None is kept. Nothing is stored, so a restart changes nothing and a replayed record gives the same output as the first time. The node is deterministic, which also makes it safe on a dead-letter replay.
Deploy-time checks
A flow with a wrong signal node does not deploy: the editor shows the problem on the node. Checked: the
sample rate is present and positive, paths are dot-paths, channel names are unique, at least one
output is selected, bins and peaks are in range, band and envelope ranges rise and are positive,
names are unique, the bearing geometry is complete and plausible (ball smaller than pitch), the unit and
ISO class exist, and every output that needs the running speed has an rpm source.
Worked example: a three-channel recording
The edge ships a real three-channel recording, data/datalog_3ch.csv: quoted decimal-comma numbers, no
timestamps, played at an assumed 50 Hz. The first 512 rows are the test input of the node
(apps/connector/tests/fixtures/vibration/datalog_3ch_512.csv). The logger writes a bare 0 for a zero
(row 51) and ends lines with CRLF, which is why the node accepts text.
The flow: a signed webhook source, the signal node, and an HTTP call that hands the features to the next system.
{ "id": "src", "type": "source", "match": "webhook:vibration",
"webhook": { "signature": { "scheme": "hmac_sha256", "header": "X-Signature", "prefix": "sha256=",
"secret": "${VIB_SECRET}" }, "respond": "on_done" } },
{ "id": "vib", "type": "signal", "samples": "samples", "layout": "rows",
"channels": ["x", "y", "z"], "sample_rate": "${fs}",
"spectrum": { "peaks": 3 },
"bands": [{ "name": "slow", "hz": [1, 5] }],
"velocity": { "unit": "g", "iso_class": "II" },
"drop_input": true }Post one window: the 512 rows exactly as the logger wrote them, decimal commas and all (the sample rate and the speed are assumed for the demo: 50 Hz, and 328 rpm, the strongest line of the y channel):
import csv, hashlib, hmac, json, urllib.request
rows = list(csv.reader(open("datalog_3ch_512.csv"))) # [["0,588399", "-0,0392266", "7,7668668"], ...]
body = json.dumps({"fs": 50, "rpm": 328, "samples": rows}).encode()
sig = "sha256=" + hmac.new(b"smoke-secret", body, hashlib.sha256).hexdigest()
urllib.request.urlopen(urllib.request.Request(
"http://127.0.0.1:3587/api/hooks/vibration", data=body, method="POST",
headers={"Content-Type": "application/json", "X-Signature": sig})) # 200 {"ok":true,"result":"done"}The record that leaves the signal node (channel y; numbers rounded to six digits, channels x and z
have the same shape):
{ "sample_rate_hz": 50.0, "rpm": 328.0, "window": "hann",
"channels": { "y": {
"samples": 512, "bad_samples": 0,
"time": { "mean": 0.693131, "rms": 0.757979, "std": 0.757979, "peak": 4.41966,
"peak_to_peak": 8.04145, "crest": 5.83085, "kurtosis": 3.38977, "skewness": 0.142275 },
"spectrum": { "df_hz": 0.0976562, "window": "hann", "range_hz": [0.0, 19.5312],
"peaks": [ { "hz": 5.48095, "amp": 0.252727 },
{ "hz": 16.4897, "amp": 0.18783 },
{ "hz": 19.2631, "amp": 0.170841 } ] },
"bands": { "slow": { "hz": [1.0, 5.0], "rms": 0.208502, "peak": 0.108481, "peak_hz": 2.73438,
"fraction": 0.0905653, "bins": 41 } },
"orders": { "1x": { "order": 1.0, "hz": 5.46667, "detected_hz": 5.48095, "amp": 0.252727, "snr_db": 10.5987 },
"2x": { "order": 2.0, "hz": 10.9333, "detected_hz": 10.9294, "amp": 0.0961509, "snr_db": 3.45172 },
"3x": { "order": 3.0, "hz": 16.4, "detected_hz": 16.4897, "amp": 0.18783, "snr_db": 7.90057 } },
"velocity": { "unit": "g", "band_hz": [2.0, 19.5312], "rms_mm_s": 135.024,
"x1_mm_s": 55.4489, "x2_mm_s": 11.7,
"iso": { "class": "II", "zone": "D", "limits_mm_s": [1.4, 2.8, 4.5] } } } } }Read it the way an engineer would: time.mean of channel z is 8.6, the gravity offset, which is
removed before every other number; the strongest line of y sits at 5.48 Hz, the assumed running
speed (1x, SNR 10.6 dB, well above the 3 to 5 dB of x); and the velocity is far above the 4.5 mm/s of
zone D because the demo assumes the samples are in g at a 50 Hz rate. With the real sample rate and
sensor unit these are the numbers to alert on. The bearing and envelope outputs need a sample rate well
above the resonance band they look at, so they are not used at 50 Hz; the vibration example flow runs
them on a 2.56 kHz window.
The values were cross-checked against an independent implementation (a naive DFT in plain Python) to
nine digits: RMS 0.2649226 for x, peak amplitude 0.0619795, band RMS 0.1230191, and velocity 14.03 mm/s
for the ISO band 10 to 19.5 Hz when no speed is given. (With the speed 328 rpm, below 600 rpm, the ISO
band starts at 2 Hz, which is why band_hz above is 2 to 19.5 and the velocity larger.)
A machine record works the same way. Post {"source": "vibration", ..., "machine": {"id": "press-1"}, "metadata": {"fs": 1024, "wave": [...]}} to /api/ingest/vibration/press-1 with the node set to
samples: metadata.wave, sample_rate: ${metadata.fs}. The result lands in metadata.signal, and a
filter metadata.signal.channels.ch1.time.rms > 0.5 right after it passes a 1.5 g sine (RMS 1.0607)
and drops a 0.1 g one.
Putting it in a flow
- Feed it a window per record: a webhook or ingest source, a message bus bridge, or the
vibrationexample (Examples in the editor, Vibration features and ISO 20816 zone), which runs on a built-in sample with Test. - After it, a
filterorbranchonmetadata.signal.channels.x.velocity.iso.zone, an alert, and the features on to OpexMX with anhttpnode or a sink. - Several channels give several results in one record; pick the one you act on in the next node’s path.
See also Flows for paths and templates, Business events for shaping what you send on, and Example flows.