Mitchell Foutz Source on GitHub

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

  1. git clone https://github.com/darblinko/industrial-monitor
    cd industrial-monitor
    uv sync
  2. uv run pytest -q
  3. uv run industrial-monitor demo
    uv run industrial-monitor ask "Why is pump 3 alarming and what do I check?"
  4. 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