Merge pull request #1 from shsms/logical_meter

Implement the logical meter

Author: shsms

.github/workflows/ci.yaml

@@ -0,0 +1,20 @@
+name: Rust CI
+
+on:
+  push:
+    branches: [ v0.x.x ]
+  pull_request:
+  merge_group:
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Run tests
+        uses: frequenz-floss/gh-action-cargo-test@v1.0.0

.github/workflows/dco-merge-queue.yml

@@ -0,0 +1,11 @@
+# Based on https://github.com/hyperledger/besu/pull/5207/files
+name: DCO
+on:
+  merge_group:
+
+jobs:
+  DCO:
+    runs-on: ubuntu-latest
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    steps:
+      - run: echo "This DCO job runs on merge_queue event and doesn't check PR contents"

.github/workflows/release-notes-check.yml

@@ -0,0 +1,30 @@
+name: Release Notes Check
+
+on:
+  merge_group:
+  pull_request:
+    types:
+      # On by default if you specify no types.
+      - "opened"
+      - "reopened"
+      - "synchronize"
+      # For `skip-label` only.
+      - "labeled"
+      - "unlabeled"
+
+
+jobs:
+  check-release-notes:
+    name: Check release notes are updated
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    steps:
+      - name: Check for a release notes update
+        if: github.event_name == 'pull_request'
+        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1
+        with:
+          file-pattern: "RELEASE_NOTES.md"
+          prereq-pattern: "src/**"
+          skip-label: "cmd:skip-release-notes"
+          failure-message: "Missing a release notes update. Please add one or apply the ${skip-label} label to the pull request"

.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "submodules/frequenz-api-microgrid"]
+	path = submodules/frequenz-api-microgrid
+	url = https://github.com/frequenz-floss/frequenz-api-microgrid

Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "frequenz-microgrid-rs"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+name = "frequenz_microgrid"
+path = "src/lib.rs"
+
+[dependencies]
+chrono = "0.4"
+frequenz-microgrid-component-graph = { git = "https://github.com/frequenz-floss/frequenz-microgrid-component-graph-rs.git", rev = "ab3b998" }
+frequenz-microgrid-formula-engine = { git = "https://github.com/frequenz-floss/frequenz-microgrid-formula-engine-rs.git", rev = "e0567c0" }
+frequenz-resampling = { git = "https://github.com/frequenz-floss/frequenz-resampling-rs.git", rev = "ce84d66" }
+prost = "0.13"
+prost-types = "0.13"
+tokio = { version = "1.45", features = ["rt", "rt-multi-thread"] }
+tonic = "0.13"
+tracing = { version = "0.1" }
+tracing-subscriber = { version = "0.3" }
+
+
+[build-dependencies]
+tonic-build = "0.13"
+prost-build = "0.13"

build.rs

@@ -0,0 +1,20 @@
+// License: MIT
+// Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+fn main() -> Result<(), std::io::Error> {
+    let config = tonic_build::Config::new();
+
+    tonic_build::configure()
+        .compile_protos_with_config(
+            config,
+            &["submodules/frequenz-api-microgrid/proto/frequenz/api/microgrid/v1/microgrid.proto"],
+            &[
+                "submodules/frequenz-api-microgrid/proto",
+                "submodules/frequenz-api-microgrid/submodules/frequenz-api-common/proto",
+                "submodules/frequenz-api-microgrid/submodules/api-common-protos",
+            ],
+        )
+        .inspect_err(|e| {
+            eprintln!("Could not compile protobuf files. Error: {e:?}");
+        })
+}

examples/logical_meter.rs

@@ -0,0 +1,52 @@
+// License: MIT
+// Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+use chrono::TimeDelta;
+use frequenz_microgrid::{
+    Error, LogicalMeterConfig, LogicalMeterHandle, Metric, MicrogridClientHandle,
+};
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing_subscriber::fmt::fmt()
+        .with_file(true)
+        .with_line_number(true)
+        .init();
+
+    let client = MicrogridClientHandle::new("http://[::1]:8800");
+    let mut logical_meter = LogicalMeterHandle::try_new(
+        client,
+        LogicalMeterConfig {
+            resampling_interval: TimeDelta::try_seconds(1).unwrap(),
+        },
+    )
+    .await?;
+
+    // Create a formula that calculates `grid_power - battery_power`.
+    let formula_grid = logical_meter.grid(Metric::AcActivePower)?;
+    let formula_battery = logical_meter.battery(None, Metric::AcActivePower)?;
+    let formula_consumer = logical_meter.consumer(Metric::AcActivePower)?;
+
+    let formula = (logical_meter.grid(Metric::AcActivePower)?
+        - logical_meter.battery(None, Metric::AcActivePower)?
+        + logical_meter.consumer(Metric::AcActivePower)?)?;
+
+    let mut rx = formula.subscribe().await?;
+    let mut grid_rx = formula_grid.subscribe().await?;
+    let mut battery_rx = formula_battery.subscribe().await?;
+    let mut consumer_rx = formula_consumer.subscribe().await?;
+
+    loop {
+        let sample = rx.recv().await.unwrap();
+        let grid_sample = grid_rx.recv().await.unwrap();
+        let battery_sample = battery_rx.recv().await.unwrap();
+        let consumer_sample = consumer_rx.recv().await.unwrap();
+        tracing::info!(
+            "grid({}) - battery({}) + consumer({}) = {}",
+            grid_sample.value().unwrap(),
+            battery_sample.value().unwrap(),
+            consumer_sample.value().unwrap(),
+            sample.value().unwrap()
+        );
+    }
+}

src/client.rs

@@ -0,0 +1,11 @@
+// License: MIT
+// Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+//! A clonable client for the microgrid API.
+
+mod instruction;
+mod microgrid_client_actor;
+mod retry_tracker;
+
+mod microgrid_client_handle;
+pub use microgrid_client_handle::MicrogridClientHandle;

src/client/instruction.rs

@@ -0,0 +1,30 @@
+// License: MIT
+// Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+//! Instructions that can be sent to the client actor from client handles.
+
+use tokio::sync::{broadcast, oneshot};
+
+use crate::{
+    Error,
+    proto::common::v1::microgrid::components::{Component, ComponentConnection, ComponentData},
+};
+
+/// Instructions that can be sent to the client actor from client handles.
+#[derive(Debug)]
+pub(super) enum Instruction {
+    GetComponentDataStream {
+        component_id: u64,
+        response_tx: oneshot::Sender<broadcast::Receiver<ComponentData>>,
+    },
+    ListComponents {
+        component_ids: Vec<u64>,
+        categories: Vec<i32>,
+        response_tx: oneshot::Sender<Result<Vec<Component>, Error>>,
+    },
+    ListConnections {
+        starts: Vec<u64>,
+        ends: Vec<u64>,
+        response_tx: oneshot::Sender<Result<Vec<ComponentConnection>, Error>>,
+    },
+}