frequenz-microgrid-rs

High-level Rust interface for the Frequenz Microgrid API.

The crate connects to a Microgrid API server, builds a component graph from the live topology, and exposes typed, formula-driven streams of microgrid metrics — grid power, battery state-of-charge, PV reactive power, consumer current, and so on — without requiring callers to write the per-component formulas by hand.

Support for controlling components is coming soon.

Quick start

cargo add frequenz-microgrid chrono tokio --features tokio/macros,tokio/rt-multi-thread

Stream the grid's active power once per second:

use chrono::TimeDelta;
use frequenz_microgrid::{Error, LogicalMeterConfig, Microgrid, metric};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let microgrid = Microgrid::try_new(
        "http://[::1]:8800",
        LogicalMeterConfig::new(TimeDelta::try_seconds(1).unwrap()),
    )
    .await?;

    let mut grid = microgrid
        .logical_meter()
        .grid::<metric::AcPowerActive>()?
        .subscribe()
        .await?;

    while let Ok(sample) = grid.recv().await {
        println!("{:?}: {:?}", sample.timestamp(), sample.value());
    }
    Ok(())
}

Microgrid::try_new blocks (with retries) until the server is reachable and returns a graph that builds successfully, so applications can start before their backing service is ready.

Testing with the in-crate mock

The test-utils feature ships a MockMicrogridApiClient (plus MockComponent and TokioSyncedClock helpers) for downstream tests. Enable it as a dev-dependency:

cargo add --dev frequenz-microgrid --features test-utils

What's included

• Microgrid / LogicalMeterHandle: typed formulas for grid, battery, pv, chp, ev_charger, steam_boiler, consumer, producer, and individual components, parametrised over a metric.
• BatteryPool, PvPool and SteamBoilerPool: aggregated active-power bounds and health-partitioned telemetry for a set of batteries, PV inverters or steam boilers.
• MicrogridClientHandle: cloneable low-level gRPC handle with per-stream automatic reconnect.
• Typed quantities — Power, Current, Voltage, ReactivePower, Energy, Frequency, Percentage — with unit conversions explicit at every API surface.

Formulas compose without subscribing. +, -, * f32, / f32, * Percentage, coalesce, min, max and avg build one expression. The logical meter evaluates it once per resampling tick, so all operands, of any metric, are read from the same tick's resampled values.

use frequenz_microgrid::{metric, quantity::Power};

let logical_meter = microgrid.logical_meter();
let net = logical_meter.grid::<metric::AcPowerActive>()?
    - logical_meter.pv::<metric::AcPowerActive>(None)?
    + Power::from_kilowatts(100.0);
let mut rx = net.subscribe().await?;

See the API documentation for the full surface.

Configuring the underlying graph

LogicalMeterConfig::with_component_graph_config forwards a ComponentGraphConfig to the frequenz-microgrid-component-graph builder, exposing knobs like prefer_meters_in_component_formulas, include_phantom_loads_in_consumer_formula, and per-formula overrides. If not set, the graph crate's Default::default() is used.

Contributing

See the Contributing Guide.

License

Licensed under the MIT License.