MetrologyInsight

Standards support (pre-compliance): This library implements measurement algorithms derived from several IEC standards. It is intended for development, evaluation, and pre-compliance testing. It has not been certified or validated as fully compliant with the referenced standards. See docs/COMPLIANCE_STATUS.md for the per-clause status.

High-performance, embedded-first electrical metrology DSP library written in Rust. Implements measurement algorithms derived from IEC 61000-4-30:2021 Class S (Power Quality Measurement Methods) and IEC 62053-21 (Static Meters for AC Active Energy).

Engineered for microcontrollers (e.g., ESP32-S3 / Xtensa, ARM Cortex-M) with zero hardware dependencies, fully compatible with no_std + alloc.

Key Features

• Multi-Phase Topology Support: Configurable 1 to 4 channels (Single-phase, Single-phase with neutral, 3-Phase 3-Wire, 3-Phase 4-Wire).
• True RMS Processing: Fractional cycle correction for ultra-precise Voltage and Current RMS measurements.
• High-Inertia Digital PLL: Grid frequency tracking (45 Hz – 65 Hz) with 10-second sliding frequency averages (IEC 61000-4-30 §5.1).
• Synchronous Resampling: Coherent windowing via linear-interpolation resampling to an integer number of cycles for leakage-free spectral analysis.
• FFT & Harmonics: 512-point RFFT processing up to the 50th harmonic order + total harmonic distortion (THD-V and THD-I).
• Comprehensive Power Metrics: Active (W), Reactive (VAR), Apparent (VA), and Power Factor (PF) per phase and 3-phase totals.
• Bi-Directional 4-Quadrant Energy: High-resolution i128 micro-joule (µJ) accumulators for active/reactive energy across Q1–Q4 (IEC 62053-21).
• Signed Phase Angles & Direction: Directional power flow determination (Inductive, Capacitive, In-Phase) with signed phase shift calculations ($\varphi = \theta_I - \theta_V$).
• Fortescue Unbalance Ratios: Symmetrical component analysis (Zero $U_0$ and Negative $U_2$ sequence ratios) for voltage and current.
• Flickermeter Implementation: Implementation of IEC 61000-4-15 Blocks 1–4 via IEC 61000-4-30 §5.3 (SOS Butterworth 35 Hz filter, weighting filter, instantaneous flicker $P_{\text{inst}}$ in realtime; $P_{\text{st}}$ / $P_{\text{lt}}$ classifiers available as library functions — pre-compliance).
• Power Quality Event Detection: Automated tracking of Voltage Dips, Swells, Interruptions, and Rapid Voltage Changes (RVC).
• IEC Quality Flags: Real-time diagnostic flags (PLL_UNSETTLED, SYNC_INCONSISTENT, OUT_OF_RANGE, EVENT_MARKED).
• Hardware-Agnostic: Works with any ADC front-end (ADS131M08, MCP3913, internal ADCs) by accepting normalized physical values.

Standards Compliance

Pre-compliance status — not certified. See docs/COMPLIANCE_STATUS.md for the per-clause breakdown.

Resource Requirements & Memory Footprint

no_std + alloc contract: no_std builds require a target with an alloc allocator (e.g. ARM Cortex-M, ESP32/Xtensa, RISC-V with a heap). The core heap-allocates on initialization via Box (see table below); targets without any allocator (e.g. bare riscv32i without a heap) are not supported. The alloc feature only adds optional test/simulation helpers and is not required for the core pipeline.

1. Code Footprint (Flash / .text Section)

2. Heap Memory Footprint (RAM / Dynamic Allocations)

Allocated safely via Box on initialization:

• Base Socket Allocation: MetrologyInsightSocket (352 Bytes)
• Per-Phase Data Struct: Box<PhaseData> (4,224 Bytes / 4.125 KiB)

3. Stack Memory Footprint (Thread Task Stack)

• MetrologyInsight Instance Size: 320 Bytes on stack (holds pointers, configuration struct, and active phase counter).
• DSP Processing Stack Usage: < 1.5 KiB peak stack usage during process_and_update_metrics() calls (temporary stack frames for trapezoidal integration and zero-crossing calculation).

Prerequisites & Building

1. Prerequisites

To compile and use MetrologyInsight, ensure you have the Rust toolchain installed:

• Rust Toolchain: Rust 2021 Edition (stable 1.75+ or Xtensa/ESP32 LLVM toolchains).
• Installation: Install Rust via rustup:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  

2. Standard Build & Test Suite (Host / Desktop OS)

By default (features = ["std"]), the crate compiles using realfft for host simulations, unit testing, and analytical evaluation:

# Clone repository
git clone https://github.com/erhnam/metrology_insight.git
cd metrology_insight

# Compile debug target
cargo build

# Compile optimized release target
cargo build --release

# Run all unit tests
cargo test

# Run full real-time analytical simulation test suite with detailed output
cargo test --test sim_realtime -- --nocapture

3. Embedded no_std Compilation (Microcontrollers)

For embedded targets (e.g. ESP32-S3, ARM Cortex-M, RISC-V), disable default std features and specify no_std + alloc support:

# Add target toolchain if cross-compiling (e.g., ARM Cortex-M4F)
rustup target add thumbv7em-none-eabihf

# Build for no_std target
cargo build --target thumbv7em-none-eabihf --no-default-features --features alloc --release

Quick Start

Add metrology_insight to your Cargo.toml:

[dependencies]
metrology_insight = { version = "0.1.0", default-features = false, features = ["alloc"] }

Basic Example

use metrology_insight::{MetrologyInsight, MetrologyInsightConfig, SystemMode};

fn main() {
    // 1. Configure for an 8000 Hz ADC sample rate (e.g., ADS131M08 @ OSR=1024)
    let mut config = MetrologyInsightConfig::default();
    config.adc_samples_seconds = 8000.0;
    config.adc_samples_per_cycle = 160.0; // 8000 Hz / 50 Hz
    config.avg_sec = 160.0 / 8000.0;      // 1-cycle EWMA smoothing

    let mut insight = MetrologyInsight::new(config);
    insight.set_nominal_voltage(230.0);    // Synchronizes event & flicker thresholds

    let active_phases = SystemMode::ThreePhase4Wire.active_phases(); // 4

    // 2. Feed ADC samples into insight.socket.phases[i].{voltage, current}
    // ...
    
    // 3. Process DSP pipeline
    insight.process_and_update_metrics(active_phases);

    // 4. Access real-time metrics
    let v_rms  = insight.socket.phases[0].voltage.rms;
    let freq   = insight.socket.phases[0].voltage.pll_state.freq_10s;
    let p_kw   = insight.socket.power_metrics_total.real_power / 1000.0;
    let thd_v  = insight.socket.phases[0].voltage.thd;
    let flags  = insight.socket.phases[0].voltage.quality_flags;
    let u2_pct = insight.socket.unbalance_metrics.u2_neg_ratio_pct;

    println!("L1 RMS: {:.2} V | Freq: {:.3} Hz | P_total: {:.2} kW", v_rms, freq, p_kw);
}

Dynamic Runtime Configuration

// Update nominal voltage on the fly (automatically re-calibrates flicker and event limits)
insight.set_nominal_voltage(120.0); // US 120V Grid

// Tweak DSP parameters dynamically and re-apply
insight.config.pll.kp = 0.003;
insight.config.flicker.rms_tc_seconds = 30.0;
insight.apply_config();

Architecture & Crate Features

metrology_insight is structured into zero-cost modular DSP components:

src/
├── types.rs           # Core data structures, configuration & socket metrics
├── processing.rs      # Main execution pipeline coordinator
├── pll.rs             # Digital PLL frequency tracking
├── resampling.rs      # Kaiser/Sinc synchronous resampler
├── harmonics.rs       # 512-point RFFT & harmonic analysis
├── flicker.rs         # IEC 61000-4-15 Flickermeter filters
├── power.rs           # Real, reactive, apparent power & PF calculations
├── energy.rs          # 4-Quadrant micro-joule energy accumulators
├── unbalance.rs       # Fortescue symmetrical sequence components
├── events.rs          # Dips, Swells, Interruptions & RVC detectors
└── rvc.rs             # Rapid Voltage Change detector

Feature Flags

• std (default): Enables standard library support and FFT hardware acceleration.
• alloc: Optional — adds the test/simulation helpers (accuracy_test, generate_signal) to no_std builds. The core library itself always requires a target with an alloc allocator (see no_std contract).

Documentation

Comprehensive documentation of all functions, structs, and algorithms is available in:

• docs/API_REFERENCE.md
• docs/COMPLIANCE_STATUS.md — per-clause standards compliance status

License

MetrologyInsight is licensed under the Apache License 2.0.

• Permitted: Free use, modification, and distribution, including for commercial purposes, subject to the terms of the license.
• Full license text: LICENSE.md
• Copyright © 2026 Francisco Arcos.

Professional Services

If you are integrating MetrologyInsight into a product and need support, custom feature development, metrology expertise, or certification assistance (e.g., IEC 61000-4-30, IEC 62053-21), feel free to reach out via GitHub Issues.