Skip to content

Event System

ESP-GUARDX includes a comprehensive event detection and recording system that acts as a Black Box for your ESP installation. It automatically detects abnormal conditions and records detailed waveform data for post-event analysis.

How Events Work

1. Continuous Monitoring

The Event Monitor continuously compares real-time measurements against user-defined warn and trip thresholds. There are four categories of monitored parameters:

  • Power -- Voltage, current, frequency, THD, power factor, sequence components
  • Motor -- Overcurrent, undercurrent, temperature, vibration, locked rotor
  • Pump -- Intake pressure, flow rate, efficiency, torque, gas lock
  • Well -- Wellhead pressure, bottomhole temperature, water cut, GOR

2. Pre-Trigger Buffer (Black Box)

ESP-GUARDX continuously maintains a rolling buffer of the 10 most recent data packets (approximately 2 seconds of data). This means that when an event is detected, the system already has data from before the fault occurred.

This is critical for root cause analysis -- you can see what the system was doing in the moments leading up to the event.

3. Event Detection

When a monitored parameter crosses a threshold:

  1. The system marks the current timestamp as the trigger point
  2. The pre-trigger buffer (data from before the event) is saved
  3. Recording continues for a configurable duration after the event (post-trigger)
  4. The event is saved with full waveform data and metadata

4. Event Storage

Each event produces two files:

Binary Data File (.bin)

Contains the raw waveform data in a compact binary format:

  • Size: ~19.7 KB per data packet
  • Contents: 8-channel waveform data (4,096 samples), harmonic data (808 values), and power measurements (24 parameters)
  • Location: /home/root/event_recordings/

Metadata File (.json)

Contains event details in human-readable JSON format:

  • Event ID (unique identifier)
  • Trigger timestamp
  • Event category (Power, Motor, Pump, Well)
  • Trigger parameter name
  • Threshold values (warn and trip)
  • Measured value at trigger
  • Duration of event
  • Number of recorded packets

Event File Naming

Event files follow this naming convention:

EVT_YYYYMMDD_HHMMSS_<unique-id>.bin
EVT_YYYYMMDD_HHMMSS_<unique-id>.json

For example: EVT_20251015_110935_f17517ca.bin

Enabling Event Recording

Event recording must be enabled in Settings > Event Settings. When enabled:

  • The Event Monitor runs continuously in the background
  • Events are detected and recorded automatically
  • No operator intervention is required

When disabled, parameters are still displayed but no automatic recording occurs.

See Event Settings for configuration details.

Event Categories

Power Events

Detect abnormalities in the electrical supply:

  • Voltage deviations (over/under)
  • Current deviations (over/under)
  • Frequency deviations
  • THD exceeding limits
  • Power factor drops
  • Sequence component imbalance

Motor Events

Detect motor-related faults:

  • Overcurrent / undercurrent conditions
  • Locked rotor detection
  • Temperature alarms
  • Vibration alarms
  • Ground faults

Pump Events

Detect pump operating issues:

  • Low intake pressure (risk of gas lock or cavitation)
  • Flow rate deviations
  • Efficiency degradation
  • Torque overload
  • Gas lock conditions

Well Events

Detect well condition changes:

  • Wellhead pressure deviations
  • Temperature alarms
  • High water cut
  • High GOR
  • Sand production