industrial-monitor
A reference pipeline for condition monitoring of pumps and fans. Sensor messages in the Ruuvi RAWv2 format travel over MQTT to an FFT-based anomaly detector, and a maintenance assistant answers alarm questions with citations to a manual corpus and to the live plant state.
- Repository
- darblinko/industrial-monitor
- Revision
317ac05- Measured
- 2026-10-30
- License
- Apache-2.0
Problem
A vibration alarm reports that a number crossed a limit. The technician still needs the fault class, the evidence behind it and the procedure to follow. Two measurements decide whether such a system is usable: the share of fault windows the detector catches at a fixed false-alarm budget, and whether the assistant's answers cite passages that support them.
The false-alarm budget depends on the alarm rule. At the same z-score threshold of 2.6, alarming on every window above the threshold raised false alarms on 5.66% of healthy windows. Requiring 2 of 3 consecutive windows lowered that to 0.93%.
How it works
A simulator produces six machines (four pumps, two fans) with injected bearing wear, imbalance and temperature drift. Each acquisition window becomes two MQTT messages: a 24-byte RAWv2 status payload with the housing temperature, and a vibration burst of 1,024 acceleration samples at 1,344 Hz. The monitor extracts FFT features per window, scores them against a per-machine baseline learned from the first 40 windows, and publishes the machine state on its anomaly topic. The assistant reads that state and the manual corpus through three tools.
flowchart TB
sim["Simulator: 6 machines, injected faults"] --> bus
ble["Ruuvi tags over BLE (optional)"] --> bus
bus[("MQTT broker or in-process bus")] --> monitor["Plant monitor: FFT features, median and MAD z-scores, 2 of 3 rule"]
monitor -- "anomaly topic" --> bus
monitor --> state["Plant state snapshot"]
state --> agent["Maintenance assistant: tool-use loop"]
corpus["Manual corpus, BM25 search"] --> agent
agent --> answer["Answer with passage and status citations"]
Demo plant: pump 3 develops an outer-race bearing defect
The chart below is built from the JSON messages the monitor published on plant/demo/pump-3/anomaly during the demo run. The bearing envelope z-score crosses the threshold at the fault onset, window 70, and the alarm follows at window 71 with the second exceedance. The alarm at windows 59 to 60 is a false alarm: a kurtosis exceedance at window 58 and a temperature exceedance at window 59 together satisfy the 2 of 3 rule.
The acceleration spectrum shows where the impact energy goes. Each outer-race impact excites the 450 Hz housing resonance, so the largest bin between 300 and 600 Hz rises from 0.004 g in the healthy window to 0.149 g in the faulty one. The 20 to 25 Hz bin, which holds the 1x running-speed line at 24.75 Hz, reads 0.040 g and 0.043 g.
The envelope spectrum of the resonance band recovers the impact rate. The faulty window has lines at the ball pass frequency of the outer race (BPFO, 83.5 Hz) and its harmonics: the 82.5 Hz bin reads 0.001 g healthy and 0.200 g faulty, the 165 Hz bin 0.002 g and 0.078 g. The detector's bearing channel is the sum of the first three BPFO lines divided by the median envelope level between 10 and 300 Hz.
Measured results
The detector was evaluated on two simulated plants of 16 machines each: four healthy and four per fault class, two pumps and two fans in each, with varied running amplitude, noise and base temperature. The threshold was calibrated on the development plant (seed 101) to the lowest value with at most 1% false alarms under the 2 of 3 rule, then frozen at 2.6 and measured on the held-out plant (seed 202), which has different machines, fault onsets and noise. The held-out plant contributed 1,395 healthy and 1,805 fault windows after the 40-window baselines.
Imbalance is the weak class: 37.0% of imbalance windows below severity 0.25 are detected. In that range the simulated 1x amplitude grows by a factor of 1.15 to 1.75. Inference: this overlaps the healthy load variation, which the simulator draws from a lognormal factor with sigma 0.15.
Maintenance assistant
The assistant was scored on 20 golden questions: 17 answerable and 3 that the corpus does not cover. These numbers come from the deterministic extractive model that the tests use. They test the evaluation pipeline and set a baseline for it. They do not measure Claude, and no Claude run is recorded in the repository.
Run it
git clone https://github.com/darblinko/industrial-monitor cd industrial-monitor uv syncuv run pytest -quv run industrial-monitor demo uv run industrial-monitor ask "Why is pump 3 alarming and what do I check?"uv run industrial-monitor evaluate-detector uv run industrial-monitor evaluate-assistant uv run industrial-monitor export-landing
The MQTT path needs a broker: docker compose up -d starts Mosquitto on 127.0.0.1:1883. Run uv run industrial-monitor monitor in one terminal and uv run industrial-monitor simulate in another. ask reads the recorded demo state unless --state-file results/scratch/plant-state.json selects the state the monitor wrote. A Claude run needs ANTHROPIC_API_KEY and the flag --model claude on ask or evaluate-assistant.
Limitations
- All sensor data is simulated. No field data from a real pump or fan was used.
- The manual corpus is synthetic and written for this project. RP-1 and RF-1 are not real products, and their limits are illustrative.
- A RAWv2 advertisement carries one acceleration sample per axis. The vibration burst frame is defined by this project; no Ruuvi firmware emits it. Real Ruuvi tags supply the housing temperature only. A RAWv2 message updates the stored temperature; detection advances only on vibration bursts, so a machine that receives RAWv2 from a tag and no bursts from another source stays in the learning state.
- Alarming on every window above the threshold gives 5.66% false alarms and misses the 1% target. The 2 of 3 rule is required to meet it.
- The 2 of 3 rule counts exceedances on any channel, so two unrelated single-window exceedances raise an alarm, as at pump 3 windows 59 to 60.
- Imbalance below severity 0.25 is detected in 37.0% of windows, and the median imbalance alarm delay is 15.5 windows.
- The detection evaluation uses unquantized samples. The MQTT path quantizes samples to 1 mG, and its effect on the rates was not measured.
- The extractive model answered one of the three unanswerable questions (q20, pressure transmitter calibration) by citing RP-5.1, a passage on bearing housing temperature. Its decline rule (query term coverage below 0.5) was chosen after inspecting retrieval on the same golden set, so the decline rates are not held out.
- Docker Compose was validated with
docker compose configonly. The broker tests ran against a local Mosquitto 2.0.18. The BLE scanner was not tested against hardware.