Crate frequenz_microgrid

Expand description

§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, consumer, producer, and individual components, parametrised over a metric.
BatteryPool and PvPool: aggregated active-power bounds and health-partitioned telemetry for a set of batteries or PV inverters.
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.

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.

Re-exports§

pub use client::MicrogridClientHandle;

Modules§

client: A clonable client for the microgrid API.
metric: Metrics supported by the logical meter.
quantity: This module defines various physical quantities and their operations.

Structs§

BatteryPool: An interface for abstracting over a pool of batteries in the microgrid.
BatteryPoolSnapshot
Bounds: A set of lower and upper bounds for any metric.
ComponentGraphConfig: Configuration options for the ComponentGraph.
ComponentHealthPartition: A set of components partitioned by health status and annotated with the latest telemetry sample for each.
Error: An error that occurred in frequenz_microgrid.
InverterBatteryGroup: A set of inverters and batteries wired together in an MxN configuration: M inverters in parallel on the AC side, N batteries in parallel on the DC side, with the inverter side in series with the battery side.
InverterBatteryGroupStatus: A snapshot of an inverter-battery group’s components, partitioned by health status and annotated with the latest telemetry sample for each component (see ComponentHealthPartition).
LogicalMeterConfig
LogicalMeterHandle: This provides an interface stream high-level metrics from a microgrid.
Microgrid: A high-level interface for the Microgrid API.
PvPool: A pool of PV inverters in the microgrid.
PvPoolSnapshot: A snapshot of a PV pool’s inverters, partitioned by health status and annotated with the latest telemetry sample for each (see ComponentHealthPartition).
Sample: Represents a measurement of a microgrid metric, made at a specific time.

Enums§

ErrorKind: The kind of error that occurred.
Formula: A composable Formula.

Traits§

FormulaSubscriber