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.

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

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

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

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

```json
"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 f<sub>r</sub> = rpm / 60, the ratio
r = ball_dia / pitch_dia and the contact angle θ:

| | Formula |
| --- | --- |
| FTF (cage) | ½ · f<sub>r</sub> · (1 − r cos θ) |
| BSF (ball spin) | (pitch_dia / 2 ball_dia) · f<sub>r</sub> · (1 − (r cos θ)²) |
| BPFO (outer race) | (n / 2) · f<sub>r</sub> · (1 − r cos θ) |
| BPFI (inner race) | (n / 2) · f<sub>r</sub> · (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

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

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

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

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

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

```json
{ "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](/docs/flows) for paths and templates, [Business events](/docs/business-events) for
shaping what you send on, and [Example flows](/docs/examples).