frequenz-microgrid-rs

High-level Rust interface for the Frequenz Microgrid API.

The crate connects to a Microgrid API server, builds a ComponentGraph 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

[dependencies]
frequenz-microgrid = "0.4"
chrono = "0.4"
tokio = { version = "1", features = ["macros", "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

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

[dev-dependencies]
frequenz-microgrid = { version = "0.4", features = ["test-utils"] }

What's included

• Microgrid / LogicalMeterHandle: typed formulas for grid, battery, pv, chp, ev_charger, consumer, producer, and individual components, parametrised over a metric in metric.
• BatteryPool: aggregated active-power bounds and state-of-charge for one or more batteries.
• MicrogridClientHandle: cloneable low-level gRPC handle with per-stream automatic reconnect.
• quantity: Power, Current, Voltage, ReactivePower, Energy, Frequency, Percentage. Unit conversions are explicit at every API 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.