Live Acquisition

Module: equser.pmon Dependencies: [daq] extra (avro, fastavro)

Real-time power monitor data acquisition from EQ Wave sensor hardware. Install with:

pip install equser[daq]

Note: Live acquisition requires physical EQ Wave sensor hardware connected via Ethernet.

PowerMonitor

The main acquisition class. Connects to an EQ Wave sensor over TCP, reads 10/12-cycle power quality measurements, and writes them to timestamped Parquet files with automatic file rotation.

from equser.pmon import PowerMonitor

with PowerMonitor('192.168.10.10') as monitor:
    monitor.run()  # Blocks until interrupted

Constructor

PowerMonitor(
    ip_address,
    connection=None,    # dict: port, retry_delay, num_retries, connect_timeout, data_timeout
    parquet=None,       # dict: interval, flush_every, compression
    data_dir=None,      # Override data directory (Path)
    convert_files_on_startup=True,
)

If connection or parquet are None, sensible defaults are used (see Configuration for details).

acquire(config_path=None)

Convenience function that loads configuration from a YAML file and starts monitoring with automatic reconnection. This is what equser pmon acquire calls internally.

from equser.pmon import acquire

acquire()                     # Use default config resolution
acquire('equser.yaml')        # Use specific config file

Avro-to-Parquet conversion

The sensor writes data in Avro format, which is automatically converted to Parquet. You can also convert files manually:

from equser.pmon import convert_avro_to_parquet

result = convert_avro_to_parquet('20250623_0750.avro')
print(result)  # Path to created .parquet file, or None on failure

The function signature:

convert_avro_to_parquet(
    avro_path,
    compression='ZSTD',        # ZSTD, SNAPPY, GZIP, or NONE
    compression_level=4,
    remove=False,               # Delete Avro file after conversion
)

For batch conversion from the CLI:

equser pmon convert data/*.avro --remove

Schema

The PMon schema defines 10/12-cycle power quality measurements. Use create_schema to generate an Avro schema for a given phase configuration:

from equser.pmon.schema import create_schema

schema, time_name, var_names = create_schema(num_phases=3)
print(time_name)    # 'time_us'
print(var_names[:5])
# ['FREQ', 'AVRMS', 'BVRMS', 'CVRMS', 'AIRMS']

Supports 1, 2, or 3-phase configurations. The full 3-phase field list:

Field descriptions are also available programmatically:

from equser.pmon import FIELD_DESCRIPTIONS
print(FIELD_DESCRIPTIONS['AFVAR'])
# 'Line A fundamental reactive power [var]'

Error hierarchy

DataAcquisitionError (RuntimeError)
├── SensorConnectionError (+ OSError)  — sensor connection failures
└── ConfigurationError (+ ValueError)  — invalid configuration

from equser.pmon.errors import SensorConnectionError, ConfigurationError

CLI

# Start acquisition
equser pmon acquire -c config.yaml

# Convert Avro to Parquet
equser pmon convert data/*.avro --remove