Skip to content

Vibration and signal features

The signal node turns a window of waveform samples into condition-monitoring features: RMS, FFT, bands, orders, bearing frequencies, envelope, velocity with the ISO 20816 zone, and the vibration edge's 79-feature ofv1 vector.

Updated View as Markdown

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" }
  • bins cuts [fmin, fmax) into at most that many equal-width cells (never more than there are FFT bins) and reduces each with reduce (max default, mean, rms). The output carries the cell centres hz and the amplitudes amp.
  • peaks lists the strongest local maxima as {hz, amp}. hz is refined by parabolic interpolation; amp is the strongest bin.
  • fmax defaults to sample_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 vibration example (Examples in the editor, Vibration features and ISO 20816 zone), which runs on a built-in sample with Test.
  • After it, a filter or branch on metadata.signal.channels.x.velocity.iso.zone, an alert, and the features on to OpexMX with an http node 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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close