# Energy Bus

## Purpose

The `energy` bus exposes telemetry for the electrical energy domain: production, storage, grid exchange, and electrical load measurement points.

This bus is used for energy accounting and historian ingestion, not for user-facing room automation semantics.

Shared payload, metadata, time, and operational rules are defined in `mqtt_contract.md`.

Typical systems connected to this bus include:

- photovoltaic inverters

- battery systems (BMS and inverter side)

- UPS systems

- generators

- grid meters

- smart plugs used as electrical measurement points

## Scope and Ownership

The `energy` bus owns telemetry that describes electrical topology and electrical flows.

The `home` bus owns room-centric control semantics.

Examples:

- `vad/home/living-room/power/tv/value` is home automation state

- `vad/energy/load/living-room-entertainment/active_power/value` is electrical load telemetry

Rule:

- if the value is for user control in a room context, publish on `home`

- if the value is for electrical accounting, publish on `energy`

## Normative Topic Contract (v1)

All energy topics MUST follow:

`<site>/energy/<entity_type>/<entity_id>/<metric>/<stream>`

Where:

- `<site>`: deployment/site id, for example `vad`

- `<entity_type>`: one of `source`, `storage`, `grid`, `load`, `transfer`

- `<entity_id>`: stable kebab-case identifier (no spaces)

- `<metric>`: canonical metric name in snake_case

- `<stream>`: one of `value`, `last`, `set`, `meta`, `availability`

Examples:

- `vad/energy/source/pv-roof-1/active_power/value`

- `vad/energy/storage/battery-main/soc/value`

- `vad/energy/grid/main-meter/import_power/value`

- `vad/energy/load/living-room-entertainment/active_power/value`

- `vad/energy/transfer/pv-to-battery/power/value`

## Stream Semantics

- `value`: live semantic sample, whether it represents a numeric measurement, a durable state, or a transition-like signal

- `last`: retained last-known timestamped sample for startup/bootstrap decisions

- `meta`: static or slowly changing metadata

- `availability`: online/offline status

- `set`: write/request command topic (only where command is supported)

Rules:

- adapters SHOULD emit live hot-path data only on `value`

- adapters SHOULD deduplicate repeated `value` samples when the semantic value did not change

- adapters SHOULD publish retained `last` for the latest known timestamped sample

- legacy `state` and `event` topics SHOULD be treated as compatibility-only during migration and SHOULD NOT be introduced by new adapters

Command safety:

- `set` topics MUST NOT be retained

- command handlers SHOULD confirm via `value`

- payload profile and time semantics follow `mqtt_contract.md`

## Payload Contract

To optimize Node-RED flow cost, two payload profiles are defined.

### Profile A: Hot Path Scalar (recommended)

For high-frequency telemetry, `value` payload SHOULD be scalar (`number` or `boolean`).

Example:

- Topic: `vad/energy/source/pv-roof-1/active_power/value`

- Payload: `3245.7`

Metadata is published separately on retained `meta`.

Example:

- Topic: `vad/energy/source/pv-roof-1/active_power/meta`

- Payload:

```json

{

	"unit": "W",

	"description": "PV inverter AC active power",

	"source": "modbus_adapter",

	"precision": 0.1

}

```

### Profile B: Envelope JSON (optional)

When observation time or quality must travel with each point:

```json

{

	"value": 3245.7,

	"unit": "W",

	"observed_at": "2026-03-08T10:15:12Z",

	"quality": "good"

}

```

Recommendation:

- prefer Profile A for hot telemetry paths

- use Profile B for low-rate or quality-critical streams

- use Profile B when source timestamp fidelity matters

- use `last` with Profile B and `observed_at` when startup decisions require freshness evaluation

- do not repeat metadata or adapter internals in `value` payloads

- keep Profile B envelopes small and canonical

## Time Semantics

- `observed_at` means device observation time, not broker receive time

- if device timestamp exists, adapter MUST preserve it

- if missing, adapter MAY use ingestion timestamp and mark degraded quality

## Units and Naming

Canonical units SHOULD follow SI conventions:

- power: `W`

- energy: `Wh` or `kWh`

- voltage: `V`

- current: `A`

- frequency: `Hz`

- state of charge: `%`

Naming rules:

- `entity_id`: kebab-case (example `battery-main`)

- `metric`: snake_case (example `active_power`, `import_energy_total`)

## Metric Classes

The `energy` bus may carry both measurement-style metrics and counter-style metrics.

Measurement-style examples:

- `active_power`

- `voltage`

- `current`

- `frequency`

- `soc`

- `charge_power`

- `discharge_power`

Counter-style cumulative examples:

- `energy_total`

- `import_energy_total`

- `export_energy_total`

## MQTT Delivery Policy

Default policy:

- `value`: QoS 1, retain false

- `last`: QoS 1, retain true

- `meta`: QoS 1, retain true

- `availability`: QoS 1, retain true (use LWT where available)

- `set`: QoS 1, retain false

Cold-start rule:

- startup consumers SHOULD subscribe to retained `last` for the latest known measurement

- `last` SHOULD include `observed_at` so consumers can reject stale measurements

- consumers MAY unsubscribe from `last` after bootstrap and continue on live `value`

If uncertain, choose QoS 1.

## Node-RED Implementation Optimizations

Because translation is implemented in Node-RED, the contract is optimized for low-overhead flows.

Guidelines:

- keep canonical topic depth fixed to 6 segments after `<site>` to simplify wildcard routing

- avoid per-message heavy JSON transforms on high-rate streams

- split metadata to retained `meta` topics to avoid repeated payload bloat

- publish canonical MQTT-ready messages as early as possible after normalization

- emit MQTT-ready messages only at the publish boundary

- do not carry adapter-internal normalization structures on forwarded `msg` objects

- discard temporary normalization fields before publish

- keep high-rate `value` streams extremely lightweight

- centralize mapping tables in one `function` or `change` node set (device id, metric id, unit)

- use one normalization subflow reused per adapter/protocol

- avoid broad `#` subscriptions in hot paths; use specific wildcard patterns

Suggested Node-RED routing subscriptions:

- `+/energy/+/+/+/value`

- `+/energy/+/+/+/last`

- `+/energy/+/+/+/meta`

- `+/energy/+/+/+/availability`

## Energy Flow Semantics

### Production

Energy generated by a source, usually under `entity_type=source`.

Examples:

- `active_power`

- `energy_total`

### Storage

Energy held in storage, under `entity_type=storage`.

Examples:

- `soc`

- `charge_power`

- `discharge_power`

### Grid

Import/export metrics at connection points, under `entity_type=grid`.

Examples:

- `import_power`

- `export_power`

- `import_energy_total`

- `export_energy_total`

### Load

Electrical load measurement points, under `entity_type=load`.

Examples:

- `active_power`

- `energy_total`

Note: this is electrical telemetry semantics, not room-control semantics.

### Transfer

Flow between subsystems, under `entity_type=transfer`.

Examples:

- `pv-to-battery`

- `battery-to-home`

## Historian Relationship

The `energy` bus is a primary source for historian ingestion, but not all energy metrics use the same persistence path.

Measurement-style metrics such as `active_power`, `voltage`, `current`, `frequency`, `soc`, `charge_power`, and `discharge_power` are compatible with `tdb_ingestion/mqtt_ingestion_api.md`.

For those metrics, workers should map each incoming message to:

- `metric_name`

- `device_id`

- `value`

- `observed_at`

`device_id` recommendation:

- `<entity_type>.<entity_id>`

Historian defaults:

- `value` streams SHOULD be ingested by default for measurement-style metrics

- `last` streams SHOULD NOT be ingested as normal telemetry samples

- `meta.historian.mode` SHOULD describe whether a `value` stream represents `sample`, `state`, or `event` semantics

- when Profile A scalar is used, `observed_at` will usually fall back to ingestion time

- enum-like state values may need explicit encoding before they can be written through the current PostgreSQL historian API

- counter-style totals such as `energy_total`, `import_energy_total`, and `export_energy_total` SHOULD remain on the `energy` bus but SHOULD follow the separate contract in `tdb_ingestion/counter_ingestion_api.md` rather than being forced through the current measurement API

Example:

- Topic: `vad/energy/storage/battery-main/soc/value`

- `metric_name = soc`

- `device_id = storage.battery-main`

## Design Principles

- keep semantic ownership clear between buses

- make energy accounting reconstructable from `energy` topics

- optimize for deterministic adapter behavior

- optimize for low-cost Node-RED translation on high-frequency streams

- keep contract stable and extensible