From 0d9556a18e2b47b809a961acb4cb885f518d9dbb Mon Sep 17 00:00:00 2001 From: Aleksey Bakin Date: Mon, 27 Apr 2026 17:17:43 +0300 Subject: [PATCH] feat: generate docs --- .github/workflows/validate.yml | 12 + README.md | 3 + docs/energy/battery.md | 141 ++++++++ docs/energy/battery_inverter/1_phase.md | 215 +++++++++++++ docs/energy/battery_inverter/3_phase.md | 269 ++++++++++++++++ docs/energy/electrolyser.md | 118 +++++++ docs/energy/electrolyser/stack.md | 77 +++++ docs/energy/fuel_cell.md | 89 ++++++ docs/energy/hybrid_inverter/1_phase.md | 224 +++++++++++++ docs/energy/hybrid_inverter/3_phase.md | 278 ++++++++++++++++ docs/energy/power_meter/ac/1_phase.md | 86 +++++ docs/energy/power_meter/ac/3_phase.md | 140 ++++++++ docs/energy/pv_charge_controller.md | 152 +++++++++ docs/energy/pv_inverter/1_phase.md | 116 +++++++ docs/energy/pv_inverter/3_phase.md | 170 ++++++++++ docs/index.md | 98 ++++++ docs/lib/device/nameplate.md | 27 ++ docs/lib/energy/battery/charge/lifetime.md | 22 ++ docs/lib/energy/battery/charge_status.md | 22 ++ docs/lib/energy/battery/electrical.md | 30 ++ docs/lib/energy/battery/energy/lifetime.md | 22 ++ docs/lib/energy/battery/limits.md | 22 ++ docs/lib/energy/battery/nameplate.md | 40 +++ docs/lib/energy/battery/soc.md | 14 + docs/lib/energy/battery/soh.md | 14 + docs/lib/energy/battery/status.md | 24 ++ docs/lib/energy/battery/temperature.md | 14 + docs/lib/energy/charge_controller/status.md | 26 ++ docs/lib/energy/electrolyser/control.md | 4 + .../electrolyser/feed_water/conductivity.md | 14 + .../electrolyser/feed_water/pressure.md | 14 + .../electrolyser/feed_water/temperature.md | 14 + .../energy/electrolyser/h2_outlet_pressure.md | 14 + .../electrolyser/h2_production/lifetime.md | 22 ++ .../energy/electrolyser/h2_production/rate.md | 22 ++ .../electrolyser/h2_production/setpoint.md | 14 + .../energy/electrolyser/power_consumption.md | 14 + .../energy/electrolyser/stack/electrical.md | 30 ++ .../lib/energy/electrolyser/stack/pressure.md | 14 + .../energy/electrolyser/stack/temperature.md | 14 + docs/lib/energy/electrolyser/status.md | 28 ++ docs/lib/energy/fuel_cell/control.md | 4 + docs/lib/energy/fuel_cell/energy/lifetime.md | 14 + .../lib/energy/fuel_cell/h2_inlet_pressure.md | 14 + .../energy/fuel_cell/output/current_limit.md | 14 + .../lib/energy/fuel_cell/output/electrical.md | 30 ++ .../fuel_cell/output/voltage_setpoint.md | 14 + .../energy/fuel_cell/run_hours/lifetime.md | 14 + docs/lib/energy/fuel_cell/status.md | 26 ++ docs/lib/energy/inverter/ac/1_phase.md | 38 +++ docs/lib/energy/inverter/ac/3_phase.md | 86 +++++ docs/lib/energy/inverter/ac/current.md | 14 + docs/lib/energy/inverter/ac/energy/daily.md | 14 + .../lib/energy/inverter/ac/energy/lifetime.md | 14 + docs/lib/energy/inverter/ac/power.md | 14 + .../energy/inverter/grid/charge/enabled.md | 20 ++ docs/lib/energy/inverter/grid/mode.md | 18 ++ docs/lib/energy/inverter/grid/power.md | 14 + docs/lib/energy/inverter/grid/status.md | 21 ++ docs/lib/energy/inverter/load/power.md | 14 + docs/lib/energy/inverter/nameplate.md | 14 + docs/lib/energy/inverter/residual_current.md | 14 + docs/lib/energy/inverter/status.md | 26 ++ docs/lib/energy/inverter/temperature.md | 22 ++ docs/lib/energy/power_meter/ac/1_phase.md | 38 +++ docs/lib/energy/power_meter/ac/3_phase.md | 86 +++++ docs/lib/energy/power_meter/current.md | 14 + docs/lib/energy/power_meter/energy/daily.md | 14 + .../lib/energy/power_meter/energy/lifetime.md | 14 + docs/lib/energy/power_meter/power.md | 14 + .../power_quality/power_factor/1_phase.md | 30 ++ .../power_quality/power_factor/3_phase.md | 78 +++++ .../power_quality/power_factor/totals.md | 30 ++ docs/lib/energy/pv/current.md | 14 + docs/lib/energy/pv/energy/daily.md | 14 + docs/lib/energy/pv/energy/lifetime.md | 14 + docs/lib/energy/pv/power.md | 14 + docs/lib/energy/pv/string/electrical.md | 30 ++ docs/lib/energy/pv/string/energy.md | 14 + docs/lib/energy/pv/string/temperature.md | 14 + docs/lib/energy/pv/throttling.md | 13 + docs/lib/firmware/version.md | 13 + docs/lib/location/coordinates.md | 22 ++ docs/lib/sensor/gas/lel.md | 14 + docs/lib/sensor/gas/ppm.md | 14 + docs/lib/sensor/solar_irradiance.md | 14 + docs/lib/sensor/temperature/ambient.md | 14 + docs/sensor/ambient_temperature.md | 41 +++ docs/sensor/gas/hydrogen.md | 50 +++ docs/sensor/solar_irradiance.md | 41 +++ generate_docs.sh | 302 ++++++++++++++++++ 91 files changed, 4126 insertions(+) create mode 100644 docs/energy/battery.md create mode 100644 docs/energy/battery_inverter/1_phase.md create mode 100644 docs/energy/battery_inverter/3_phase.md create mode 100644 docs/energy/electrolyser.md create mode 100644 docs/energy/electrolyser/stack.md create mode 100644 docs/energy/fuel_cell.md create mode 100644 docs/energy/hybrid_inverter/1_phase.md create mode 100644 docs/energy/hybrid_inverter/3_phase.md create mode 100644 docs/energy/power_meter/ac/1_phase.md create mode 100644 docs/energy/power_meter/ac/3_phase.md create mode 100644 docs/energy/pv_charge_controller.md create mode 100644 docs/energy/pv_inverter/1_phase.md create mode 100644 docs/energy/pv_inverter/3_phase.md create mode 100644 docs/index.md create mode 100644 docs/lib/device/nameplate.md create mode 100644 docs/lib/energy/battery/charge/lifetime.md create mode 100644 docs/lib/energy/battery/charge_status.md create mode 100644 docs/lib/energy/battery/electrical.md create mode 100644 docs/lib/energy/battery/energy/lifetime.md create mode 100644 docs/lib/energy/battery/limits.md create mode 100644 docs/lib/energy/battery/nameplate.md create mode 100644 docs/lib/energy/battery/soc.md create mode 100644 docs/lib/energy/battery/soh.md create mode 100644 docs/lib/energy/battery/status.md create mode 100644 docs/lib/energy/battery/temperature.md create mode 100644 docs/lib/energy/charge_controller/status.md create mode 100644 docs/lib/energy/electrolyser/control.md create mode 100644 docs/lib/energy/electrolyser/feed_water/conductivity.md create mode 100644 docs/lib/energy/electrolyser/feed_water/pressure.md create mode 100644 docs/lib/energy/electrolyser/feed_water/temperature.md create mode 100644 docs/lib/energy/electrolyser/h2_outlet_pressure.md create mode 100644 docs/lib/energy/electrolyser/h2_production/lifetime.md create mode 100644 docs/lib/energy/electrolyser/h2_production/rate.md create mode 100644 docs/lib/energy/electrolyser/h2_production/setpoint.md create mode 100644 docs/lib/energy/electrolyser/power_consumption.md create mode 100644 docs/lib/energy/electrolyser/stack/electrical.md create mode 100644 docs/lib/energy/electrolyser/stack/pressure.md create mode 100644 docs/lib/energy/electrolyser/stack/temperature.md create mode 100644 docs/lib/energy/electrolyser/status.md create mode 100644 docs/lib/energy/fuel_cell/control.md create mode 100644 docs/lib/energy/fuel_cell/energy/lifetime.md create mode 100644 docs/lib/energy/fuel_cell/h2_inlet_pressure.md create mode 100644 docs/lib/energy/fuel_cell/output/current_limit.md create mode 100644 docs/lib/energy/fuel_cell/output/electrical.md create mode 100644 docs/lib/energy/fuel_cell/output/voltage_setpoint.md create mode 100644 docs/lib/energy/fuel_cell/run_hours/lifetime.md create mode 100644 docs/lib/energy/fuel_cell/status.md create mode 100644 docs/lib/energy/inverter/ac/1_phase.md create mode 100644 docs/lib/energy/inverter/ac/3_phase.md create mode 100644 docs/lib/energy/inverter/ac/current.md create mode 100644 docs/lib/energy/inverter/ac/energy/daily.md create mode 100644 docs/lib/energy/inverter/ac/energy/lifetime.md create mode 100644 docs/lib/energy/inverter/ac/power.md create mode 100644 docs/lib/energy/inverter/grid/charge/enabled.md create mode 100644 docs/lib/energy/inverter/grid/mode.md create mode 100644 docs/lib/energy/inverter/grid/power.md create mode 100644 docs/lib/energy/inverter/grid/status.md create mode 100644 docs/lib/energy/inverter/load/power.md create mode 100644 docs/lib/energy/inverter/nameplate.md create mode 100644 docs/lib/energy/inverter/residual_current.md create mode 100644 docs/lib/energy/inverter/status.md create mode 100644 docs/lib/energy/inverter/temperature.md create mode 100644 docs/lib/energy/power_meter/ac/1_phase.md create mode 100644 docs/lib/energy/power_meter/ac/3_phase.md create mode 100644 docs/lib/energy/power_meter/current.md create mode 100644 docs/lib/energy/power_meter/energy/daily.md create mode 100644 docs/lib/energy/power_meter/energy/lifetime.md create mode 100644 docs/lib/energy/power_meter/power.md create mode 100644 docs/lib/energy/power_quality/power_factor/1_phase.md create mode 100644 docs/lib/energy/power_quality/power_factor/3_phase.md create mode 100644 docs/lib/energy/power_quality/power_factor/totals.md create mode 100644 docs/lib/energy/pv/current.md create mode 100644 docs/lib/energy/pv/energy/daily.md create mode 100644 docs/lib/energy/pv/energy/lifetime.md create mode 100644 docs/lib/energy/pv/power.md create mode 100644 docs/lib/energy/pv/string/electrical.md create mode 100644 docs/lib/energy/pv/string/energy.md create mode 100644 docs/lib/energy/pv/string/temperature.md create mode 100644 docs/lib/energy/pv/throttling.md create mode 100644 docs/lib/firmware/version.md create mode 100644 docs/lib/location/coordinates.md create mode 100644 docs/lib/sensor/gas/lel.md create mode 100644 docs/lib/sensor/gas/ppm.md create mode 100644 docs/lib/sensor/solar_irradiance.md create mode 100644 docs/lib/sensor/temperature/ambient.md create mode 100644 docs/sensor/ambient_temperature.md create mode 100644 docs/sensor/gas/hydrogen.md create mode 100644 docs/sensor/solar_irradiance.md create mode 100755 generate_docs.sh diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index cd58227..85af017 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -31,3 +31,15 @@ jobs: if [ "$(echo "$body" | jq '.validation_errors | length')" -gt 0 ]; then exit 1 fi + + - name: Install yq + uses: mikefarah/yq@master + + - name: Check docs are up to date + run: | + bash generate_docs.sh + if ! git diff --quiet docs/; then + echo "Docs are out of date. Run 'bash generate_docs.sh' and commit the result." + git diff --stat docs/ + exit 1 + fi diff --git a/README.md b/README.md index 40a92f7..e163af2 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ A **profile** is a YAML file that declares the interface of a device for the res Standardizing device interfaces through profiles enables integration with different parts of the Enapter platform (REST, MQTT, OPC UA, Rule Engine) and ensures interoperability across different device vendors and models. +> **[Browse the full profile reference](docs/index.md)** — every profile and library component with all fields, types, units, and allowed values. + ## Key Concepts ### Profile References @@ -22,6 +24,7 @@ When a blueprint or profile lists other profiles in its [`implements`](https://v lib/ Reusable building blocks that define specific capabilities energy/ Device profiles for energy devices (inverters, batteries, power meters) sensor/ Device profiles for sensor devices (temperature, gas, irradiance) +docs/ Generated reference documentation for all profiles and library components guides/ Reference documentation for profile authors ``` diff --git a/docs/energy/battery.md b/docs/energy/battery.md new file mode 100644 index 0000000..5fbcd90 --- /dev/null +++ b/docs/energy/battery.md @@ -0,0 +1,141 @@ +# Battery/BMS + +A profile for battery systems and battery management systems (BMS). Covers state of charge, charge/discharge power and current, and nameplate attributes. Suitable for standalone battery banks and integrated BESS units. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Unique serial number of the device. + +### `battery_nominal_voltage` + +- **Display name:** Battery Nominal Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.nameplate`](../lib/energy/battery/nameplate.md) + +Nominal DC bus voltage of the battery system as specified by the manufacturer. Used to convert between charge (Ah) and energy (Wh) when the device only reports one of the two. + +### `battery_nameplate_capacity` + +- **Display name:** Battery Nameplate Capacity +- **Type:** `integer` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.battery.nameplate`](../lib/energy/battery/nameplate.md) + +Nameplate energy capacity of connected batteries according to manufacturer specifications. + +### `battery_type` + +- **Display name:** Battery Type +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.nameplate`](../lib/energy/battery/nameplate.md) + +Main type of the battery system. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `lead_based` | Lead-based | | +| `lithium_based` | Lithium-based | | +| `nickel_based` | Nickel-based | | +| `flow` | Flow | | +| `sodium_based` | Sodium-based | | +| `other` | Other | Other battery type, not covered by the standard types. | + +## Telemetry + +### `battery_charge_status` + +- **Display name:** Battery Charge Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.charge_status`](../lib/energy/battery/charge_status.md) + +Current charge direction or mode of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is not charging or discharging. No current is flowing. | +| `charging` | Charging | Battery is actively absorbing energy from the connected source. | +| `discharging` | Discharging | Battery is actively delivering energy to the connected load. | +| `float` | Float | Battery is fully charged and receiving trickle current to maintain full state of charge. | + +### `battery_voltage` + +- **Display name:** Battery Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.electrical`](../lib/energy/battery/electrical.md) + +Current DC voltage of the battery bank. + +### `battery_current` + +- **Display name:** Battery Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.battery.electrical`](../lib/energy/battery/electrical.md) + +DC current flow to/from the battery bank. Positive values indicate discharging (current flowing out of battery), negative values indicate charging (current flowing into battery). + +### `battery_power` + +- **Display name:** Battery Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.battery.electrical`](../lib/energy/battery/electrical.md) + +DC power to/from the battery bank. Positive values indicate discharging (power delivered to system), negative values indicate charging (power absorbed from system). + +### `battery_soc` + +- **Display name:** State of Charge +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.battery.soc`](../lib/energy/battery/soc.md) + +Battery state of charge percentage. + +### `battery_status` + +- **Display name:** Battery Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.status`](../lib/energy/battery/status.md) + +Current operational status of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is powered and ready to operate but is not connected. It will not start until commanded by a user. | +| `standby` | Standby | Battery has entered a low-power sleep mode after an extended period of inactivity. It will wake up autonomously when needed, but the transition back to connected may not be instantaneous. | +| `starting` | Starting | Battery is initializing and not yet available for charging or discharging. This covers contactor pre-charge, string SoC balancing, and other steps required before the battery can accept power commands. | +| `connected` | Connected | Battery is connected and available for charging or discharging. The actual charge direction is reported in battery_charge_status. | +| `fault` | Fault | Battery has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Battery is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + diff --git a/docs/energy/battery_inverter/1_phase.md b/docs/energy/battery_inverter/1_phase.md new file mode 100644 index 0000000..335c2e1 --- /dev/null +++ b/docs/energy/battery_inverter/1_phase.md @@ -0,0 +1,215 @@ +# Single-Phase Battery Inverter + +A profile for single-phase battery inverters (off-grid and grid-tied). Covers battery state of charge and charge/discharge power, AC output measurements, grid import/export and load power, operational status, and nameplate attributes. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +### `battery_nominal_voltage` + +- **Display name:** Battery Nominal Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nominal DC bus voltage of the battery system as specified by the manufacturer. Used to convert between charge (Ah) and energy (Wh) when the device only reports one of the two. + +### `battery_nameplate_capacity` + +- **Display name:** Battery Nameplate Capacity +- **Type:** `integer` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nameplate energy capacity of connected batteries according to manufacturer specifications. + +### `battery_type` + +- **Display name:** Battery Type +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Main type of the battery system. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `lead_based` | Lead-based | | +| `lithium_based` | Lithium-based | | +| `nickel_based` | Nickel-based | | +| `flow` | Flow | | +| `sodium_based` | Sodium-based | | +| `other` | Other | Other battery type, not covered by the standard types. | + +### `inverter_nameplate_capacity` + +- **Display name:** Nameplate Capacity +- **Type:** `integer` +- **Unit:** VA +- **Inherited from:** [`lib.energy.inverter.nameplate`](../../lib/energy/inverter/nameplate.md) + +Maximum apparent power rating of the inverter in VA (volt-amperes). + +## Telemetry + +### `battery_charge_status` + +- **Display name:** Battery Charge Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.charge_status`](../../lib/energy/battery/charge_status.md) + +Current charge direction or mode of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is not charging or discharging. No current is flowing. | +| `charging` | Charging | Battery is actively absorbing energy from the connected source. | +| `discharging` | Discharging | Battery is actively delivering energy to the connected load. | +| `float` | Float | Battery is fully charged and receiving trickle current to maintain full state of charge. | + +### `battery_voltage` + +- **Display name:** Battery Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +Current DC voltage of the battery bank. + +### `battery_current` + +- **Display name:** Battery Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC current flow to/from the battery bank. Positive values indicate discharging (current flowing out of battery), negative values indicate charging (current flowing into battery). + +### `battery_power` + +- **Display name:** Battery Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC power to/from the battery bank. Positive values indicate discharging (power delivered to system), negative values indicate charging (power absorbed from system). + +### `battery_soc` + +- **Display name:** State of Charge +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.battery.soc`](../../lib/energy/battery/soc.md) + +Battery state of charge percentage. + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +AC output frequency. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +AC power on phase L1. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +Current on phase L1. + +### `ac_total_power` + +- **Display name:** AC Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.power`](../../lib/energy/inverter/ac/power.md) + +Total AC power across all phases. Positive values indicate power being delivered to loads/grid, negative values indicate power being consumed, e.g. for charging batteries. + +### `grid_total_power` + +- **Display name:** Grid Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.grid.power`](../../lib/energy/inverter/grid/power.md) + +Power exchange with grid (positive for import, negative for export). + +### `load_total_power` + +- **Display name:** Load Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.load.power`](../../lib/energy/inverter/load/power.md) + +Total power consumed by local loads on the inverter AC output. Typically positive; negative values are possible but uncommon when a bidirectional load or generator is connected to the load port. + +### `inverter_status` + +- **Display name:** Inverter Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.inverter.status`](../../lib/energy/inverter/status.md) + +Current operational status of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Inverter is powered and ready to operate but is not converting power. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Inverter is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: DC voltage too low (night time for PV inverters), AC grid voltage unavailable for grid-tied inverters. | +| `starting` | Starting | Inverter is executing its startup sequence. This includes grid synchronization, self-tests, and ramp-up. Power conversion has not yet reached nominal operation. | +| `operating` | Operating | Inverter is actively converting power at its operating setpoint. | +| `throttled` | Throttled | Inverter is operating at reduced power output due to an external constraint or internal condition such as high temperature, grid frequency response, or power curtailment. | +| `stopping` | Stopping | Inverter is executing a controlled stop sequence, including grid disconnection and ramp-down. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Inverter has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Inverter is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + diff --git a/docs/energy/battery_inverter/3_phase.md b/docs/energy/battery_inverter/3_phase.md new file mode 100644 index 0000000..eb0e605 --- /dev/null +++ b/docs/energy/battery_inverter/3_phase.md @@ -0,0 +1,269 @@ +# Three-Phase Battery Inverter + +A profile for three-phase battery inverters (off-grid and grid-tied). Covers battery state of charge and charge/discharge power, AC output measurements, grid import/export and load power, operational status, and nameplate attributes. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +### `battery_nominal_voltage` + +- **Display name:** Battery Nominal Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nominal DC bus voltage of the battery system as specified by the manufacturer. Used to convert between charge (Ah) and energy (Wh) when the device only reports one of the two. + +### `battery_nameplate_capacity` + +- **Display name:** Battery Nameplate Capacity +- **Type:** `integer` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nameplate energy capacity of connected batteries according to manufacturer specifications. + +### `battery_type` + +- **Display name:** Battery Type +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Main type of the battery system. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `lead_based` | Lead-based | | +| `lithium_based` | Lithium-based | | +| `nickel_based` | Nickel-based | | +| `flow` | Flow | | +| `sodium_based` | Sodium-based | | +| `other` | Other | Other battery type, not covered by the standard types. | + +### `inverter_nameplate_capacity` + +- **Display name:** Nameplate Capacity +- **Type:** `integer` +- **Unit:** VA +- **Inherited from:** [`lib.energy.inverter.nameplate`](../../lib/energy/inverter/nameplate.md) + +Maximum apparent power rating of the inverter in VA (volt-amperes). + +## Telemetry + +### `battery_charge_status` + +- **Display name:** Battery Charge Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.charge_status`](../../lib/energy/battery/charge_status.md) + +Current charge direction or mode of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is not charging or discharging. No current is flowing. | +| `charging` | Charging | Battery is actively absorbing energy from the connected source. | +| `discharging` | Discharging | Battery is actively delivering energy to the connected load. | +| `float` | Float | Battery is fully charged and receiving trickle current to maintain full state of charge. | + +### `battery_voltage` + +- **Display name:** Battery Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +Current DC voltage of the battery bank. + +### `battery_current` + +- **Display name:** Battery Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC current flow to/from the battery bank. Positive values indicate discharging (current flowing out of battery), negative values indicate charging (current flowing into battery). + +### `battery_power` + +- **Display name:** Battery Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC power to/from the battery bank. Positive values indicate discharging (power delivered to system), negative values indicate charging (power absorbed from system). + +### `battery_soc` + +- **Display name:** State of Charge +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.battery.soc`](../../lib/energy/battery/soc.md) + +Battery state of charge percentage. + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +AC output frequency. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L1. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L1. + +### `ac_l2_voltage` + +- **Display name:** L2 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L2 to neutral. + +### `ac_l2_current` + +- **Display name:** L2 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L2. + +### `ac_l2_power` + +- **Display name:** L2 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L2. + +### `ac_l3_voltage` + +- **Display name:** L3 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L3 to neutral. + +### `ac_l3_current` + +- **Display name:** L3 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L3. + +### `ac_l3_power` + +- **Display name:** L3 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L3. + +### `ac_total_power` + +- **Display name:** AC Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.power`](../../lib/energy/inverter/ac/power.md) + +Total AC power across all phases. Positive values indicate power being delivered to loads/grid, negative values indicate power being consumed, e.g. for charging batteries. + +### `grid_total_power` + +- **Display name:** Grid Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.grid.power`](../../lib/energy/inverter/grid/power.md) + +Power exchange with grid (positive for import, negative for export). + +### `load_total_power` + +- **Display name:** Load Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.load.power`](../../lib/energy/inverter/load/power.md) + +Total power consumed by local loads on the inverter AC output. Typically positive; negative values are possible but uncommon when a bidirectional load or generator is connected to the load port. + +### `inverter_status` + +- **Display name:** Inverter Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.inverter.status`](../../lib/energy/inverter/status.md) + +Current operational status of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Inverter is powered and ready to operate but is not converting power. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Inverter is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: DC voltage too low (night time for PV inverters), AC grid voltage unavailable for grid-tied inverters. | +| `starting` | Starting | Inverter is executing its startup sequence. This includes grid synchronization, self-tests, and ramp-up. Power conversion has not yet reached nominal operation. | +| `operating` | Operating | Inverter is actively converting power at its operating setpoint. | +| `throttled` | Throttled | Inverter is operating at reduced power output due to an external constraint or internal condition such as high temperature, grid frequency response, or power curtailment. | +| `stopping` | Stopping | Inverter is executing a controlled stop sequence, including grid disconnection and ramp-down. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Inverter has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Inverter is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + diff --git a/docs/energy/electrolyser.md b/docs/energy/electrolyser.md new file mode 100644 index 0000000..8c6b8bf --- /dev/null +++ b/docs/energy/electrolyser.md @@ -0,0 +1,118 @@ +# Electrolyser + +Hydrogen electrolyser with production metrics, control commands, and operational status. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `electrolyser_status` + +- **Display name:** Electrolyser Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.electrolyser.status`](../lib/energy/electrolyser/status.md) + +Current operational status of the electrolyser. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Powered on and ready to start. No active production or transitional process in progress. | +| `starting` | Starting | Startup sequence in progress. May include pressurization, leak checks, and ramp-up phases before hydrogen production begins. | +| `producing` | Producing | Actively producing hydrogen. | +| `stopping` | Stopping | Controlled shutdown in progress. May include ramp-down and depressurization phases. | +| `standby` | Standby | Production automatically paused due to process conditions such as maximum outlet pressure. Will resume autonomously when conditions allow. | +| `fault` | Fault | A condition prevents normal operation. Operator intervention or an automated reset is required before the electrolyser can return to service. | +| `maintenance` | Maintenance | Operator-initiated service mode. The electrolyser is intentionally taken out of normal operation for inspection or servicing. | +| `purging` | Purging | Performing a gas purge cycle to remove residual gases from the system for safety or process reasons. | +| `preheating` | Preheating | Heating the electrolyte or stack to operating temperature before production can begin. | +| `keeping_warm` | Keeping Warm | Maintaining electrolyte or stack temperature during an idle period to enable faster restarts. | + +### `power_consumption` + +- **Display name:** Power Consumption +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.electrolyser.power_consumption`](../lib/energy/electrolyser/power_consumption.md) + +Total electrical power consumed by the electrolyser. + +### `h2_outlet_pressure` + +- **Display name:** H2 Outlet Pressure +- **Type:** `float` +- **Unit:** bar +- **Inherited from:** [`lib.energy.electrolyser.h2_outlet_pressure`](../lib/energy/electrolyser/h2_outlet_pressure.md) + +Hydrogen gas pressure at the electrolyser outlet, measured as gauge pressure relative to atmospheric. + +### `h2_production_rate` + +- **Display name:** H2 Production Rate +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.electrolyser.h2_production.rate`](../lib/energy/electrolyser/h2_production/rate.md) + +Current hydrogen production rate as a percentage of nominal capacity. + +### `h2_output_rate` + +- **Display name:** H2 Output Rate +- **Type:** `float` +- **Unit:** Nl/h +- **Inherited from:** [`lib.energy.electrolyser.h2_production.rate`](../lib/energy/electrolyser/h2_production/rate.md) + +Current hydrogen output flow rate at standard conditions. To convert to kg/h, divide by approximately 11126. + +### `h2_production_setpoint` + +- **Display name:** H2 Production Setpoint +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.electrolyser.h2_production.setpoint`](../lib/energy/electrolyser/h2_production/setpoint.md) + +Commanded hydrogen production rate as a percentage of nominal capacity. + +### `h2_produced_lifetime` + +- **Display name:** H2 Produced Lifetime +- **Type:** `float` +- **Unit:** Nl +- **Inherited from:** [`lib.energy.electrolyser.h2_production.lifetime`](../lib/energy/electrolyser/h2_production/lifetime.md) + +Cumulative hydrogen produced since installation at standard conditions. To convert to kg, divide by approximately 11126. + +### `h2_production_hours_lifetime` + +- **Display name:** H2 Production Hours Lifetime +- **Type:** `float` +- **Unit:** h +- **Inherited from:** [`lib.energy.electrolyser.h2_production.lifetime`](../lib/energy/electrolyser/h2_production/lifetime.md) + +Cumulative hours the electrolyser has spent actively producing hydrogen. + diff --git a/docs/energy/electrolyser/stack.md b/docs/energy/electrolyser/stack.md new file mode 100644 index 0000000..24bf32f --- /dev/null +++ b/docs/energy/electrolyser/stack.md @@ -0,0 +1,77 @@ +# Electrolyser Stack + +Individual electrolyser stack with electrical, temperature, and pressure measurements. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `stack_voltage` + +- **Display name:** Stack Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.electrolyser.stack.electrical`](../../lib/energy/electrolyser/stack/electrical.md) + +DC voltage across the electrolyser stack. + +### `stack_current` + +- **Display name:** Stack Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.electrolyser.stack.electrical`](../../lib/energy/electrolyser/stack/electrical.md) + +DC current through the electrolyser stack. + +### `stack_power` + +- **Display name:** Stack Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.electrolyser.stack.electrical`](../../lib/energy/electrolyser/stack/electrical.md) + +DC power consumed by the electrolyser stack. + +### `stack_temperature` + +- **Display name:** Stack Temperature +- **Type:** `float` +- **Unit:** Cel +- **Inherited from:** [`lib.energy.electrolyser.stack.temperature`](../../lib/energy/electrolyser/stack/temperature.md) + +Temperature of the electrolyser stack. + +### `stack_pressure` + +- **Display name:** Stack Pressure +- **Type:** `float` +- **Unit:** bar +- **Inherited from:** [`lib.energy.electrolyser.stack.pressure`](../../lib/energy/electrolyser/stack/pressure.md) + +Internal pressure of the electrolyser stack, measured as gauge pressure relative to atmospheric. + diff --git a/docs/energy/fuel_cell.md b/docs/energy/fuel_cell.md new file mode 100644 index 0000000..6bbcdd9 --- /dev/null +++ b/docs/energy/fuel_cell.md @@ -0,0 +1,89 @@ +# Fuel Cell + +Fuel cell system with power output, hydrogen supply monitoring, control commands, and operational status. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `fuel_cell_status` + +- **Display name:** Fuel Cell Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.fuel_cell.status`](../lib/energy/fuel_cell/status.md) + +Current operational status of the fuel cell. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Powered on and ready to start. No active power generation or transitional process in progress. | +| `starting` | Starting | Startup sequence in progress. May include gas line purging, pressurization, and temperature ramp phases before power generation begins. | +| `running` | Running | Actively generating electrical power. | +| `stopping` | Stopping | Controlled shutdown in progress. May include cooldown, gas purging, and depressurization phases. | +| `standby` | Standby | Power generation automatically paused due to process conditions such as low hydrogen supply pressure or battery voltage threshold. Will resume autonomously when conditions allow. | +| `derated` | Derated | Generating at reduced output due to stack degradation, hydrogen supply limitations, or temperature constraints. The fuel cell is operational but cannot deliver full rated power. | +| `fault` | Fault | A condition prevents normal operation. Operator intervention or an automated reset is required before the fuel cell can return to service. | +| `maintenance` | Maintenance | Operator-initiated service mode. The fuel cell is intentionally taken out of normal operation for inspection or servicing. | + +### `output_voltage` + +- **Display name:** Output Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.fuel_cell.output.electrical`](../lib/energy/fuel_cell/output/electrical.md) + +DC voltage at the fuel cell output. + +### `output_current` + +- **Display name:** Output Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.fuel_cell.output.electrical`](../lib/energy/fuel_cell/output/electrical.md) + +DC current at the fuel cell output. + +### `output_power` + +- **Display name:** Output Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.fuel_cell.output.electrical`](../lib/energy/fuel_cell/output/electrical.md) + +DC power delivered by the fuel cell. + +### `h2_inlet_pressure` + +- **Display name:** H2 Inlet Pressure +- **Type:** `float` +- **Unit:** mbar +- **Inherited from:** [`lib.energy.fuel_cell.h2_inlet_pressure`](../lib/energy/fuel_cell/h2_inlet_pressure.md) + +Hydrogen gas pressure at the fuel cell inlet, measured as gauge pressure relative to atmospheric. Fuel cell anode pressures are typically in the hundreds of millibar range. + diff --git a/docs/energy/hybrid_inverter/1_phase.md b/docs/energy/hybrid_inverter/1_phase.md new file mode 100644 index 0000000..dcb21de --- /dev/null +++ b/docs/energy/hybrid_inverter/1_phase.md @@ -0,0 +1,224 @@ +# Single-Phase Hybrid Inverter + +A profile for single-phase hybrid inverters with integrated PV input and battery management. Covers PV input power, battery state of charge and power, AC output measurements, grid and load power, operational status, and nameplate attributes. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +### `battery_nominal_voltage` + +- **Display name:** Battery Nominal Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nominal DC bus voltage of the battery system as specified by the manufacturer. Used to convert between charge (Ah) and energy (Wh) when the device only reports one of the two. + +### `battery_nameplate_capacity` + +- **Display name:** Battery Nameplate Capacity +- **Type:** `integer` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nameplate energy capacity of connected batteries according to manufacturer specifications. + +### `battery_type` + +- **Display name:** Battery Type +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Main type of the battery system. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `lead_based` | Lead-based | | +| `lithium_based` | Lithium-based | | +| `nickel_based` | Nickel-based | | +| `flow` | Flow | | +| `sodium_based` | Sodium-based | | +| `other` | Other | Other battery type, not covered by the standard types. | + +### `inverter_nameplate_capacity` + +- **Display name:** Nameplate Capacity +- **Type:** `integer` +- **Unit:** VA +- **Inherited from:** [`lib.energy.inverter.nameplate`](../../lib/energy/inverter/nameplate.md) + +Maximum apparent power rating of the inverter in VA (volt-amperes). + +## Telemetry + +### `battery_charge_status` + +- **Display name:** Battery Charge Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.charge_status`](../../lib/energy/battery/charge_status.md) + +Current charge direction or mode of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is not charging or discharging. No current is flowing. | +| `charging` | Charging | Battery is actively absorbing energy from the connected source. | +| `discharging` | Discharging | Battery is actively delivering energy to the connected load. | +| `float` | Float | Battery is fully charged and receiving trickle current to maintain full state of charge. | + +### `battery_voltage` + +- **Display name:** Battery Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +Current DC voltage of the battery bank. + +### `battery_current` + +- **Display name:** Battery Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC current flow to/from the battery bank. Positive values indicate discharging (current flowing out of battery), negative values indicate charging (current flowing into battery). + +### `battery_power` + +- **Display name:** Battery Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC power to/from the battery bank. Positive values indicate discharging (power delivered to system), negative values indicate charging (power absorbed from system). + +### `battery_soc` + +- **Display name:** State of Charge +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.battery.soc`](../../lib/energy/battery/soc.md) + +Battery state of charge percentage. + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +AC output frequency. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +AC power on phase L1. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +Current on phase L1. + +### `ac_total_power` + +- **Display name:** AC Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.power`](../../lib/energy/inverter/ac/power.md) + +Total AC power across all phases. Positive values indicate power being delivered to loads/grid, negative values indicate power being consumed, e.g. for charging batteries. + +### `grid_total_power` + +- **Display name:** Grid Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.grid.power`](../../lib/energy/inverter/grid/power.md) + +Power exchange with grid (positive for import, negative for export). + +### `load_total_power` + +- **Display name:** Load Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.load.power`](../../lib/energy/inverter/load/power.md) + +Total power consumed by local loads on the inverter AC output. Typically positive; negative values are possible but uncommon when a bidirectional load or generator is connected to the load port. + +### `inverter_status` + +- **Display name:** Inverter Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.inverter.status`](../../lib/energy/inverter/status.md) + +Current operational status of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Inverter is powered and ready to operate but is not converting power. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Inverter is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: DC voltage too low (night time for PV inverters), AC grid voltage unavailable for grid-tied inverters. | +| `starting` | Starting | Inverter is executing its startup sequence. This includes grid synchronization, self-tests, and ramp-up. Power conversion has not yet reached nominal operation. | +| `operating` | Operating | Inverter is actively converting power at its operating setpoint. | +| `throttled` | Throttled | Inverter is operating at reduced power output due to an external constraint or internal condition such as high temperature, grid frequency response, or power curtailment. | +| `stopping` | Stopping | Inverter is executing a controlled stop sequence, including grid disconnection and ramp-down. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Inverter has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Inverter is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + +### `pv_total_power` + +- **Display name:** PV Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.pv.power`](../../lib/energy/pv/power.md) + +DC power generated by all PV strings. + diff --git a/docs/energy/hybrid_inverter/3_phase.md b/docs/energy/hybrid_inverter/3_phase.md new file mode 100644 index 0000000..8b1ee03 --- /dev/null +++ b/docs/energy/hybrid_inverter/3_phase.md @@ -0,0 +1,278 @@ +# Three-Phase Hybrid Inverter + +A profile for three-phase hybrid inverters with integrated PV input and battery management. Covers PV input power, battery state of charge and power, AC output measurements, grid and load power, operational status, and nameplate attributes. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +### `battery_nominal_voltage` + +- **Display name:** Battery Nominal Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nominal DC bus voltage of the battery system as specified by the manufacturer. Used to convert between charge (Ah) and energy (Wh) when the device only reports one of the two. + +### `battery_nameplate_capacity` + +- **Display name:** Battery Nameplate Capacity +- **Type:** `integer` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Nameplate energy capacity of connected batteries according to manufacturer specifications. + +### `battery_type` + +- **Display name:** Battery Type +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.nameplate`](../../lib/energy/battery/nameplate.md) + +Main type of the battery system. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `lead_based` | Lead-based | | +| `lithium_based` | Lithium-based | | +| `nickel_based` | Nickel-based | | +| `flow` | Flow | | +| `sodium_based` | Sodium-based | | +| `other` | Other | Other battery type, not covered by the standard types. | + +### `inverter_nameplate_capacity` + +- **Display name:** Nameplate Capacity +- **Type:** `integer` +- **Unit:** VA +- **Inherited from:** [`lib.energy.inverter.nameplate`](../../lib/energy/inverter/nameplate.md) + +Maximum apparent power rating of the inverter in VA (volt-amperes). + +## Telemetry + +### `battery_charge_status` + +- **Display name:** Battery Charge Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.charge_status`](../../lib/energy/battery/charge_status.md) + +Current charge direction or mode of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is not charging or discharging. No current is flowing. | +| `charging` | Charging | Battery is actively absorbing energy from the connected source. | +| `discharging` | Discharging | Battery is actively delivering energy to the connected load. | +| `float` | Float | Battery is fully charged and receiving trickle current to maintain full state of charge. | + +### `battery_voltage` + +- **Display name:** Battery Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +Current DC voltage of the battery bank. + +### `battery_current` + +- **Display name:** Battery Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC current flow to/from the battery bank. Positive values indicate discharging (current flowing out of battery), negative values indicate charging (current flowing into battery). + +### `battery_power` + +- **Display name:** Battery Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.battery.electrical`](../../lib/energy/battery/electrical.md) + +DC power to/from the battery bank. Positive values indicate discharging (power delivered to system), negative values indicate charging (power absorbed from system). + +### `battery_soc` + +- **Display name:** State of Charge +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.battery.soc`](../../lib/energy/battery/soc.md) + +Battery state of charge percentage. + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +AC output frequency. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L1. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L1. + +### `ac_l2_voltage` + +- **Display name:** L2 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L2 to neutral. + +### `ac_l2_current` + +- **Display name:** L2 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L2. + +### `ac_l2_power` + +- **Display name:** L2 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L2. + +### `ac_l3_voltage` + +- **Display name:** L3 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L3 to neutral. + +### `ac_l3_current` + +- **Display name:** L3 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L3. + +### `ac_l3_power` + +- **Display name:** L3 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L3. + +### `ac_total_power` + +- **Display name:** AC Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.power`](../../lib/energy/inverter/ac/power.md) + +Total AC power across all phases. Positive values indicate power being delivered to loads/grid, negative values indicate power being consumed, e.g. for charging batteries. + +### `grid_total_power` + +- **Display name:** Grid Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.grid.power`](../../lib/energy/inverter/grid/power.md) + +Power exchange with grid (positive for import, negative for export). + +### `load_total_power` + +- **Display name:** Load Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.load.power`](../../lib/energy/inverter/load/power.md) + +Total power consumed by local loads on the inverter AC output. Typically positive; negative values are possible but uncommon when a bidirectional load or generator is connected to the load port. + +### `inverter_status` + +- **Display name:** Inverter Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.inverter.status`](../../lib/energy/inverter/status.md) + +Current operational status of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Inverter is powered and ready to operate but is not converting power. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Inverter is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: DC voltage too low (night time for PV inverters), AC grid voltage unavailable for grid-tied inverters. | +| `starting` | Starting | Inverter is executing its startup sequence. This includes grid synchronization, self-tests, and ramp-up. Power conversion has not yet reached nominal operation. | +| `operating` | Operating | Inverter is actively converting power at its operating setpoint. | +| `throttled` | Throttled | Inverter is operating at reduced power output due to an external constraint or internal condition such as high temperature, grid frequency response, or power curtailment. | +| `stopping` | Stopping | Inverter is executing a controlled stop sequence, including grid disconnection and ramp-down. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Inverter has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Inverter is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + +### `pv_total_power` + +- **Display name:** PV Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.pv.power`](../../lib/energy/pv/power.md) + +DC power generated by all PV strings. + diff --git a/docs/energy/power_meter/ac/1_phase.md b/docs/energy/power_meter/ac/1_phase.md new file mode 100644 index 0000000..138c395 --- /dev/null +++ b/docs/energy/power_meter/ac/1_phase.md @@ -0,0 +1,86 @@ +# Single-Phase Power Meter + +A profile for single-phase AC power meters. Covers voltage, current, power, and cumulative energy consumption. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.power_meter.ac.1_phase`](../../../lib/energy/power_meter/ac/1_phase.md) + +AC frequency at the measurement point. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.power_meter.ac.1_phase`](../../../lib/energy/power_meter/ac/1_phase.md) + +AC power on phase L1. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.power_meter.ac.1_phase`](../../../lib/energy/power_meter/ac/1_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.power_meter.ac.1_phase`](../../../lib/energy/power_meter/ac/1_phase.md) + +Current on phase L1. + +### `energy_lifetime` + +- **Display name:** Lifetime Energy +- **Type:** `float` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.power_meter.energy.lifetime`](../../../lib/energy/power_meter/energy/lifetime.md) + +Cumulative energy consumed by loads since installation. + +### `total_power` + +- **Display name:** Total Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.power_meter.power`](../../../lib/energy/power_meter/power.md) + +Total power across all connected loads. Positive values typically correspond to power being consumed by loads. + diff --git a/docs/energy/power_meter/ac/3_phase.md b/docs/energy/power_meter/ac/3_phase.md new file mode 100644 index 0000000..4a66e74 --- /dev/null +++ b/docs/energy/power_meter/ac/3_phase.md @@ -0,0 +1,140 @@ +# Three-Phase Power Meter + +A profile for three-phase AC power meters. Covers per-phase and total voltage, current, power, and cumulative energy consumption. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +AC frequency at the measurement point. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Current on phase L1. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Power on phase L1. + +### `ac_l2_voltage` + +- **Display name:** L2 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Voltage on phase L2 to neutral. + +### `ac_l2_current` + +- **Display name:** L2 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Current on phase L2. + +### `ac_l2_power` + +- **Display name:** L2 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Power on phase L2. + +### `ac_l3_voltage` + +- **Display name:** L3 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Voltage on phase L3 to neutral. + +### `ac_l3_current` + +- **Display name:** L3 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Current on phase L3. + +### `ac_l3_power` + +- **Display name:** L3 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.power_meter.ac.3_phase`](../../../lib/energy/power_meter/ac/3_phase.md) + +Power on phase L3. + +### `energy_lifetime` + +- **Display name:** Lifetime Energy +- **Type:** `float` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.power_meter.energy.lifetime`](../../../lib/energy/power_meter/energy/lifetime.md) + +Cumulative energy consumed by loads since installation. + +### `total_power` + +- **Display name:** Total Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.power_meter.power`](../../../lib/energy/power_meter/power.md) + +Total power across all connected loads. Positive values typically correspond to power being consumed by loads. + diff --git a/docs/energy/pv_charge_controller.md b/docs/energy/pv_charge_controller.md new file mode 100644 index 0000000..d84fdc2 --- /dev/null +++ b/docs/energy/pv_charge_controller.md @@ -0,0 +1,152 @@ +# PV Charge Controller + +A profile for solar charge controllers (MPPT and PWM). Covers PV input power, battery state of charge, charge/discharge current, battery nameplate attributes, and operational status. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Unique serial number of the device. + +### `battery_nominal_voltage` + +- **Display name:** Battery Nominal Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.nameplate`](../lib/energy/battery/nameplate.md) + +Nominal DC bus voltage of the battery system as specified by the manufacturer. Used to convert between charge (Ah) and energy (Wh) when the device only reports one of the two. + +### `battery_nameplate_capacity` + +- **Display name:** Battery Nameplate Capacity +- **Type:** `integer` +- **Unit:** Wh +- **Inherited from:** [`lib.energy.battery.nameplate`](../lib/energy/battery/nameplate.md) + +Nameplate energy capacity of connected batteries according to manufacturer specifications. + +### `battery_type` + +- **Display name:** Battery Type +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.nameplate`](../lib/energy/battery/nameplate.md) + +Main type of the battery system. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `lead_based` | Lead-based | | +| `lithium_based` | Lithium-based | | +| `nickel_based` | Nickel-based | | +| `flow` | Flow | | +| `sodium_based` | Sodium-based | | +| `other` | Other | Other battery type, not covered by the standard types. | + +## Telemetry + +### `battery_charge_status` + +- **Display name:** Battery Charge Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.battery.charge_status`](../lib/energy/battery/charge_status.md) + +Current charge direction or mode of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is not charging or discharging. No current is flowing. | +| `charging` | Charging | Battery is actively absorbing energy from the connected source. | +| `discharging` | Discharging | Battery is actively delivering energy to the connected load. | +| `float` | Float | Battery is fully charged and receiving trickle current to maintain full state of charge. | + +### `battery_voltage` + +- **Display name:** Battery Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.battery.electrical`](../lib/energy/battery/electrical.md) + +Current DC voltage of the battery bank. + +### `battery_current` + +- **Display name:** Battery Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.battery.electrical`](../lib/energy/battery/electrical.md) + +DC current flow to/from the battery bank. Positive values indicate discharging (current flowing out of battery), negative values indicate charging (current flowing into battery). + +### `battery_power` + +- **Display name:** Battery Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.battery.electrical`](../lib/energy/battery/electrical.md) + +DC power to/from the battery bank. Positive values indicate discharging (power delivered to system), negative values indicate charging (power absorbed from system). + +### `battery_soc` + +- **Display name:** State of Charge +- **Type:** `float` +- **Unit:** % +- **Inherited from:** [`lib.energy.battery.soc`](../lib/energy/battery/soc.md) + +Battery state of charge percentage. + +### `charge_controller_status` + +- **Display name:** Charge Controller Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.charge_controller.status`](../lib/energy/charge_controller/status.md) + +Current operational status of the charge controller. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Charge controller is powered and ready to operate but is not managing power conversion. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Charge controller is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: insufficient PV irradiance (night time), battery fully charged with no load. | +| `starting` | Starting | Charge controller is executing its startup sequence. This includes PV input detection, MPPT initialization, and battery compatibility checks. Power conversion has not yet begun. | +| `operating` | Operating | Charge controller is actively managing power conversion from PV input to battery. The actual charge mode is reported in battery_charge_status. | +| `throttled` | Throttled | Charge controller is operating at reduced power output due to an external constraint or internal condition such as high temperature, battery voltage limits, or input overvoltage. | +| `stopping` | Stopping | Charge controller is executing a controlled stop sequence. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Charge controller has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Charge controller is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + +### `pv_total_power` + +- **Display name:** PV Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.pv.power`](../lib/energy/pv/power.md) + +DC power generated by all PV strings. + diff --git a/docs/energy/pv_inverter/1_phase.md b/docs/energy/pv_inverter/1_phase.md new file mode 100644 index 0000000..9d6e309 --- /dev/null +++ b/docs/energy/pv_inverter/1_phase.md @@ -0,0 +1,116 @@ +# Single-Phase PV Inverter + +A profile for single-phase grid-tied PV inverters. Covers PV input power, AC output voltage/current/power, total AC power, operational status, and nameplate capacity. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +### `inverter_nameplate_capacity` + +- **Display name:** Nameplate Capacity +- **Type:** `integer` +- **Unit:** VA +- **Inherited from:** [`lib.energy.inverter.nameplate`](../../lib/energy/inverter/nameplate.md) + +Maximum apparent power rating of the inverter in VA (volt-amperes). + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +AC output frequency. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +AC power on phase L1. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.1_phase`](../../lib/energy/inverter/ac/1_phase.md) + +Current on phase L1. + +### `ac_total_power` + +- **Display name:** AC Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.power`](../../lib/energy/inverter/ac/power.md) + +Total AC power across all phases. Positive values indicate power being delivered to loads/grid, negative values indicate power being consumed, e.g. for charging batteries. + +### `inverter_status` + +- **Display name:** Inverter Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.inverter.status`](../../lib/energy/inverter/status.md) + +Current operational status of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Inverter is powered and ready to operate but is not converting power. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Inverter is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: DC voltage too low (night time for PV inverters), AC grid voltage unavailable for grid-tied inverters. | +| `starting` | Starting | Inverter is executing its startup sequence. This includes grid synchronization, self-tests, and ramp-up. Power conversion has not yet reached nominal operation. | +| `operating` | Operating | Inverter is actively converting power at its operating setpoint. | +| `throttled` | Throttled | Inverter is operating at reduced power output due to an external constraint or internal condition such as high temperature, grid frequency response, or power curtailment. | +| `stopping` | Stopping | Inverter is executing a controlled stop sequence, including grid disconnection and ramp-down. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Inverter has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Inverter is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + +### `pv_total_power` + +- **Display name:** PV Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.pv.power`](../../lib/energy/pv/power.md) + +DC power generated by all PV strings. + diff --git a/docs/energy/pv_inverter/3_phase.md b/docs/energy/pv_inverter/3_phase.md new file mode 100644 index 0000000..b35d2fa --- /dev/null +++ b/docs/energy/pv_inverter/3_phase.md @@ -0,0 +1,170 @@ +# Three-Phase PV Inverter + +A profile for three-phase grid-tied PV inverters. Covers PV input power, per-phase and total AC output power, operational status, and nameplate capacity. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +### `inverter_nameplate_capacity` + +- **Display name:** Nameplate Capacity +- **Type:** `integer` +- **Unit:** VA +- **Inherited from:** [`lib.energy.inverter.nameplate`](../../lib/energy/inverter/nameplate.md) + +Maximum apparent power rating of the inverter in VA (volt-amperes). + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +AC output frequency. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L1. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L1. + +### `ac_l2_voltage` + +- **Display name:** L2 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L2 to neutral. + +### `ac_l2_current` + +- **Display name:** L2 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L2. + +### `ac_l2_power` + +- **Display name:** L2 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L2. + +### `ac_l3_voltage` + +- **Display name:** L3 Voltage +- **Type:** `float` +- **Unit:** V +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Voltage on phase L3 to neutral. + +### `ac_l3_current` + +- **Display name:** L3 Current +- **Type:** `float` +- **Unit:** A +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Current on phase L3. + +### `ac_l3_power` + +- **Display name:** L3 Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.3_phase`](../../lib/energy/inverter/ac/3_phase.md) + +Power on phase L3. + +### `ac_total_power` + +- **Display name:** AC Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.inverter.ac.power`](../../lib/energy/inverter/ac/power.md) + +Total AC power across all phases. Positive values indicate power being delivered to loads/grid, negative values indicate power being consumed, e.g. for charging batteries. + +### `inverter_status` + +- **Display name:** Inverter Status +- **Type:** `string` +- **Inherited from:** [`lib.energy.inverter.status`](../../lib/energy/inverter/status.md) + +Current operational status of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Inverter is powered and ready to operate but is not converting power. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Inverter is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: DC voltage too low (night time for PV inverters), AC grid voltage unavailable for grid-tied inverters. | +| `starting` | Starting | Inverter is executing its startup sequence. This includes grid synchronization, self-tests, and ramp-up. Power conversion has not yet reached nominal operation. | +| `operating` | Operating | Inverter is actively converting power at its operating setpoint. | +| `throttled` | Throttled | Inverter is operating at reduced power output due to an external constraint or internal condition such as high temperature, grid frequency response, or power curtailment. | +| `stopping` | Stopping | Inverter is executing a controlled stop sequence, including grid disconnection and ramp-down. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Inverter has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Inverter is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + +### `pv_total_power` + +- **Display name:** PV Power +- **Type:** `float` +- **Unit:** W +- **Inherited from:** [`lib.energy.pv.power`](../../lib/energy/pv/power.md) + +DC power generated by all PV strings. + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a37cddc --- /dev/null +++ b/docs/index.md @@ -0,0 +1,98 @@ +# Profiles + +## Energy + +- [Battery/BMS](energy/battery.md) — `energy.battery` +- [Single-Phase Battery Inverter](energy/battery_inverter/1_phase.md) — `energy.battery_inverter.1_phase` +- [Three-Phase Battery Inverter](energy/battery_inverter/3_phase.md) — `energy.battery_inverter.3_phase` +- [Electrolyser](energy/electrolyser.md) — `energy.electrolyser` +- [Electrolyser Stack](energy/electrolyser/stack.md) — `energy.electrolyser.stack` +- [Fuel Cell](energy/fuel_cell.md) — `energy.fuel_cell` +- [Single-Phase Hybrid Inverter](energy/hybrid_inverter/1_phase.md) — `energy.hybrid_inverter.1_phase` +- [Three-Phase Hybrid Inverter](energy/hybrid_inverter/3_phase.md) — `energy.hybrid_inverter.3_phase` +- [Single-Phase Power Meter](energy/power_meter/ac/1_phase.md) — `energy.power_meter.ac.1_phase` +- [Three-Phase Power Meter](energy/power_meter/ac/3_phase.md) — `energy.power_meter.ac.3_phase` +- [PV Charge Controller](energy/pv_charge_controller.md) — `energy.pv_charge_controller` +- [Single-Phase PV Inverter](energy/pv_inverter/1_phase.md) — `energy.pv_inverter.1_phase` +- [Three-Phase PV Inverter](energy/pv_inverter/3_phase.md) — `energy.pv_inverter.3_phase` + +## Sensor + +- [Ambient Temperature Sensor](sensor/ambient_temperature.md) — `sensor.ambient_temperature` +- [Hydrogen Concentration Sensor](sensor/gas/hydrogen.md) — `sensor.gas.hydrogen` +- [Solar Irradiance Sensor](sensor/solar_irradiance.md) — `sensor.solar_irradiance` + +## Lib + +- [Device Nameplate](lib/device/nameplate.md) — `lib.device.nameplate` +- [Battery Cumulative Charge Statistics](lib/energy/battery/charge/lifetime.md) — `lib.energy.battery.charge.lifetime` +- [Battery Charge Status](lib/energy/battery/charge_status.md) — `lib.energy.battery.charge_status` +- [Battery Electrical Measurements](lib/energy/battery/electrical.md) — `lib.energy.battery.electrical` +- [Battery Cumulative Energy Statistics](lib/energy/battery/energy/lifetime.md) — `lib.energy.battery.energy.lifetime` +- [Battery Charge/Discharge Power Limits](lib/energy/battery/limits.md) — `lib.energy.battery.limits` +- [Battery Nameplate](lib/energy/battery/nameplate.md) — `lib.energy.battery.nameplate` +- [Battery State of Charge](lib/energy/battery/soc.md) — `lib.energy.battery.soc` +- [Battery State of Health](lib/energy/battery/soh.md) — `lib.energy.battery.soh` +- [Battery Status](lib/energy/battery/status.md) — `lib.energy.battery.status` +- [Battery Temperature](lib/energy/battery/temperature.md) — `lib.energy.battery.temperature` +- [Charge Controller Status](lib/energy/charge_controller/status.md) — `lib.energy.charge_controller.status` +- [Electrolyser Control](lib/energy/electrolyser/control.md) — `lib.energy.electrolyser.control` +- [Electrolyser Feed Water Conductivity](lib/energy/electrolyser/feed_water/conductivity.md) — `lib.energy.electrolyser.feed_water.conductivity` +- [Electrolyser Feed Water Pressure](lib/energy/electrolyser/feed_water/pressure.md) — `lib.energy.electrolyser.feed_water.pressure` +- [Electrolyser Feed Water Temperature](lib/energy/electrolyser/feed_water/temperature.md) — `lib.energy.electrolyser.feed_water.temperature` +- [Electrolyser H2 Outlet Pressure](lib/energy/electrolyser/h2_outlet_pressure.md) — `lib.energy.electrolyser.h2_outlet_pressure` +- [Electrolyser H2 Production Lifetime](lib/energy/electrolyser/h2_production/lifetime.md) — `lib.energy.electrolyser.h2_production.lifetime` +- [Electrolyser H2 Production Rate](lib/energy/electrolyser/h2_production/rate.md) — `lib.energy.electrolyser.h2_production.rate` +- [Electrolyser H2 Production Setpoint](lib/energy/electrolyser/h2_production/setpoint.md) — `lib.energy.electrolyser.h2_production.setpoint` +- [Electrolyser Power](lib/energy/electrolyser/power_consumption.md) — `lib.energy.electrolyser.power_consumption` +- [Electrolyser Stack Electrical](lib/energy/electrolyser/stack/electrical.md) — `lib.energy.electrolyser.stack.electrical` +- [Electrolyser Stack Pressure](lib/energy/electrolyser/stack/pressure.md) — `lib.energy.electrolyser.stack.pressure` +- [Electrolyser Stack Temperature](lib/energy/electrolyser/stack/temperature.md) — `lib.energy.electrolyser.stack.temperature` +- [Electrolyser Status](lib/energy/electrolyser/status.md) — `lib.energy.electrolyser.status` +- [Fuel Cell Control](lib/energy/fuel_cell/control.md) — `lib.energy.fuel_cell.control` +- [Fuel Cell Energy Generated Lifetime](lib/energy/fuel_cell/energy/lifetime.md) — `lib.energy.fuel_cell.energy.lifetime` +- [Fuel Cell H2 Inlet Pressure](lib/energy/fuel_cell/h2_inlet_pressure.md) — `lib.energy.fuel_cell.h2_inlet_pressure` +- [Fuel Cell Output Current Limit](lib/energy/fuel_cell/output/current_limit.md) — `lib.energy.fuel_cell.output.current_limit` +- [Fuel Cell Electrical](lib/energy/fuel_cell/output/electrical.md) — `lib.energy.fuel_cell.output.electrical` +- [Fuel Cell Output Voltage Setpoint](lib/energy/fuel_cell/output/voltage_setpoint.md) — `lib.energy.fuel_cell.output.voltage_setpoint` +- [Fuel Cell Run Hours Lifetime](lib/energy/fuel_cell/run_hours/lifetime.md) — `lib.energy.fuel_cell.run_hours.lifetime` +- [Fuel Cell Status](lib/energy/fuel_cell/status.md) — `lib.energy.fuel_cell.status` +- [Single-Phase Inverter](lib/energy/inverter/ac/1_phase.md) — `lib.energy.inverter.ac.1_phase` +- [Three-Phase Inverter](lib/energy/inverter/ac/3_phase.md) — `lib.energy.inverter.ac.3_phase` +- [Total AC Current](lib/energy/inverter/ac/current.md) — `lib.energy.inverter.ac.current` +- [AC Daily Energy](lib/energy/inverter/ac/energy/daily.md) — `lib.energy.inverter.ac.energy.daily` +- [Inverter Lifetime Energy](lib/energy/inverter/ac/energy/lifetime.md) — `lib.energy.inverter.ac.energy.lifetime` +- [Total AC Power](lib/energy/inverter/ac/power.md) — `lib.energy.inverter.ac.power` +- [Grid Charging/Feed-in Configuration Status](lib/energy/inverter/grid/charge/enabled.md) — `lib.energy.inverter.grid.charge.enabled` +- [Grid Connection Mode](lib/energy/inverter/grid/mode.md) — `lib.energy.inverter.grid.mode` +- [Grid Power](lib/energy/inverter/grid/power.md) — `lib.energy.inverter.grid.power` +- [Grid Connection Status](lib/energy/inverter/grid/status.md) — `lib.energy.inverter.grid.status` +- [Inverter Load Power](lib/energy/inverter/load/power.md) — `lib.energy.inverter.load.power` +- [Inverter Nameplate](lib/energy/inverter/nameplate.md) — `lib.energy.inverter.nameplate` +- [Inverter Residual Current](lib/energy/inverter/residual_current.md) — `lib.energy.inverter.residual_current` +- [Inverter Status](lib/energy/inverter/status.md) — `lib.energy.inverter.status` +- [Inverter Temperature](lib/energy/inverter/temperature.md) — `lib.energy.inverter.temperature` +- [Single-Phase AC Power Meter](lib/energy/power_meter/ac/1_phase.md) — `lib.energy.power_meter.ac.1_phase` +- [Three-Phase AC Power Meter](lib/energy/power_meter/ac/3_phase.md) — `lib.energy.power_meter.ac.3_phase` +- [Current Measurement](lib/energy/power_meter/current.md) — `lib.energy.power_meter.current` +- [Daily Energy](lib/energy/power_meter/energy/daily.md) — `lib.energy.power_meter.energy.daily` +- [Lifetime Energy](lib/energy/power_meter/energy/lifetime.md) — `lib.energy.power_meter.energy.lifetime` +- [Power Measurement](lib/energy/power_meter/power.md) — `lib.energy.power_meter.power` +- [Single-Phase Power Factor Measurement](lib/energy/power_quality/power_factor/1_phase.md) — `lib.energy.power_quality.power_factor.1_phase` +- [Three-Phase Power Factor Measurement](lib/energy/power_quality/power_factor/3_phase.md) — `lib.energy.power_quality.power_factor.3_phase` +- [Power Factor](lib/energy/power_quality/power_factor/totals.md) — `lib.energy.power_quality.power_factor.totals` +- [Total PV Current](lib/energy/pv/current.md) — `lib.energy.pv.current` +- [PV Daily Energy](lib/energy/pv/energy/daily.md) — `lib.energy.pv.energy.daily` +- [PV Lifetime Energy](lib/energy/pv/energy/lifetime.md) — `lib.energy.pv.energy.lifetime` +- [Total PV Power](lib/energy/pv/power.md) — `lib.energy.pv.power` +- [PV String Electrical Measurements](lib/energy/pv/string/electrical.md) — `lib.energy.pv.string.electrical` +- [PV String Energy](lib/energy/pv/string/energy.md) — `lib.energy.pv.string.energy` +- [PV String Temperature](lib/energy/pv/string/temperature.md) — `lib.energy.pv.string.temperature` +- [PV Throttling](lib/energy/pv/throttling.md) — `lib.energy.pv.throttling` +- [Firmware Version](lib/firmware/version.md) — `lib.firmware.version` +- [Location Coordinates](lib/location/coordinates.md) — `lib.location.coordinates` +- [Gas concentration in %LEL](lib/sensor/gas/lel.md) — `lib.sensor.gas.lel` +- [Gas Concentration in ppm](lib/sensor/gas/ppm.md) — `lib.sensor.gas.ppm` +- [Solar Irradiance](lib/sensor/solar_irradiance.md) — `lib.sensor.solar_irradiance` +- [Ambient Temperature](lib/sensor/temperature/ambient.md) — `lib.sensor.temperature.ambient` + diff --git a/docs/lib/device/nameplate.md b/docs/lib/device/nameplate.md new file mode 100644 index 0000000..40b90f3 --- /dev/null +++ b/docs/lib/device/nameplate.md @@ -0,0 +1,27 @@ +# Device Nameplate + +Includes typical nameplate information like vendor, model, and serial number. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` + +Unique serial number of the device. + diff --git a/docs/lib/energy/battery/charge/lifetime.md b/docs/lib/energy/battery/charge/lifetime.md new file mode 100644 index 0000000..3ca1761 --- /dev/null +++ b/docs/lib/energy/battery/charge/lifetime.md @@ -0,0 +1,22 @@ +# Battery Cumulative Charge Statistics + +Cumulative charge in Ah. Use for solar charge controllers and BMS devices that meter in ampere-hours natively. If the device meters in watt-hours, use lib.energy.battery.energy.lifetime instead. Ah and Wh are not interchangeable: Ah measures charge (coulombs), Wh measures energy (joules). To convert, use battery_nominal_voltage from lib.energy.battery.nameplate: battery_energy_in_lifetime = battery_charge_in_lifetime * battery_nominal_voltage battery_energy_out_lifetime = battery_charge_out_lifetime * battery_nominal_voltage Approximation error: below 3% for LFP, up to ~12% for lead-acid. Automation: prefer lib.energy.battery.energy.lifetime (Wh) for fleet-wide aggregation. When a device only provides Ah, apply the conversion above and document the assumptions. UI: prefer Wh from lib.energy.battery.energy.lifetime, fall back to Ah. + +## Telemetry + +### `battery_charge_in_lifetime` + +- **Display name:** Lifetime Charge In +- **Type:** `float` +- **Unit:** Ah + +Cumulative charge transferred into batteries since installation. + +### `battery_charge_out_lifetime` + +- **Display name:** Lifetime Charge Out +- **Type:** `float` +- **Unit:** Ah + +Cumulative charge transferred out of batteries since installation. + diff --git a/docs/lib/energy/battery/charge_status.md b/docs/lib/energy/battery/charge_status.md new file mode 100644 index 0000000..665fd6b --- /dev/null +++ b/docs/lib/energy/battery/charge_status.md @@ -0,0 +1,22 @@ +# Battery Charge Status + +Charge direction and mode for battery systems. + +## Telemetry + +### `battery_charge_status` + +- **Display name:** Battery Charge Status +- **Type:** `string` + +Current charge direction or mode of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is not charging or discharging. No current is flowing. | +| `charging` | Charging | Battery is actively absorbing energy from the connected source. | +| `discharging` | Discharging | Battery is actively delivering energy to the connected load. | +| `float` | Float | Battery is fully charged and receiving trickle current to maintain full state of charge. | + diff --git a/docs/lib/energy/battery/electrical.md b/docs/lib/energy/battery/electrical.md new file mode 100644 index 0000000..d83c214 --- /dev/null +++ b/docs/lib/energy/battery/electrical.md @@ -0,0 +1,30 @@ +# Battery Electrical Measurements + +Voltage, current, and power measurements for battery inverters, charge controllers, and battery management systems. + +## Telemetry + +### `battery_voltage` + +- **Display name:** Battery Voltage +- **Type:** `float` +- **Unit:** V + +Current DC voltage of the battery bank. + +### `battery_current` + +- **Display name:** Battery Current +- **Type:** `float` +- **Unit:** A + +DC current flow to/from the battery bank. Positive values indicate discharging (current flowing out of battery), negative values indicate charging (current flowing into battery). + +### `battery_power` + +- **Display name:** Battery Power +- **Type:** `float` +- **Unit:** W + +DC power to/from the battery bank. Positive values indicate discharging (power delivered to system), negative values indicate charging (power absorbed from system). + diff --git a/docs/lib/energy/battery/energy/lifetime.md b/docs/lib/energy/battery/energy/lifetime.md new file mode 100644 index 0000000..db4d5c5 --- /dev/null +++ b/docs/lib/energy/battery/energy/lifetime.md @@ -0,0 +1,22 @@ +# Battery Cumulative Energy Statistics + +Cumulative energy in Wh. Use for battery inverters, hybrid inverters, and AC-coupled systems. If the device meters in ampere-hours, use lib.energy.battery.charge.lifetime instead. Do not convert Ah to Wh silently; consumers need to know what unit they are working with. Automation: prefer Wh. For devices implementing lib.energy.battery.charge.lifetime instead, convert explicitly using battery_nominal_voltage from lib.energy.battery.nameplate: battery_energy_in_lifetime = battery_charge_in_lifetime * battery_nominal_voltage battery_energy_out_lifetime = battery_charge_out_lifetime * battery_nominal_voltage Approximation error: below 3% for LFP, up to ~12% for lead-acid. UI: prefer Wh, fall back to Ah from lib.energy.battery.charge.lifetime. + +## Telemetry + +### `battery_energy_in_lifetime` + +- **Display name:** Lifetime Energy In +- **Type:** `float` +- **Unit:** Wh + +Cumulative energy charged to batteries since installation. + +### `battery_energy_out_lifetime` + +- **Display name:** Lifetime Energy Out +- **Type:** `float` +- **Unit:** Wh + +Cumulative energy discharged from batteries since installation. + diff --git a/docs/lib/energy/battery/limits.md b/docs/lib/energy/battery/limits.md new file mode 100644 index 0000000..9bb0919 --- /dev/null +++ b/docs/lib/energy/battery/limits.md @@ -0,0 +1,22 @@ +# Battery Charge/Discharge Power Limits + +Maximum charge and discharge power limits in watts (W), consistent with inverter control, grid codes, and VPP setpoints. For devices (typically a BMS) that only report current limits in amperes, convert using battery_nominal_voltage from lib.energy.battery.nameplate: battery_max_charge_power (W) = max_charge_current_A * battery_nominal_voltage (V) battery_max_discharge_power (W) = max_discharge_current_A * battery_nominal_voltage (V) Use battery_nominal_voltage, not the instantaneous battery_voltage telemetry. battery_voltage fluctuates continuously and would make the limit value noisy even when the BMS has not changed the underlying current limit. Approximation error: ±5% for LFP, ±10-15% for lead-acid. Automation: treat these as operational guidance. The BMS enforces the actual limit. + +## Telemetry + +### `battery_max_charge_power` + +- **Display name:** Maximum Charge Power +- **Type:** `float` +- **Unit:** W + +Maximum allowed charging power as permitted by the battery system. + +### `battery_max_discharge_power` + +- **Display name:** Maximum Discharge Power +- **Type:** `float` +- **Unit:** W + +Maximum allowed discharging power as permitted by the battery system. + diff --git a/docs/lib/energy/battery/nameplate.md b/docs/lib/energy/battery/nameplate.md new file mode 100644 index 0000000..4c155ed --- /dev/null +++ b/docs/lib/energy/battery/nameplate.md @@ -0,0 +1,40 @@ +# Battery Nameplate + +Battery nameplate attributes for battery inverters, charge controllers, and battery management systems. + +## Properties + +### `battery_nominal_voltage` + +- **Display name:** Battery Nominal Voltage +- **Type:** `float` +- **Unit:** V + +Nominal DC bus voltage of the battery system as specified by the manufacturer. Used to convert between charge (Ah) and energy (Wh) when the device only reports one of the two. + +### `battery_nameplate_capacity` + +- **Display name:** Battery Nameplate Capacity +- **Type:** `integer` +- **Unit:** Wh + +Nameplate energy capacity of connected batteries according to manufacturer specifications. + +### `battery_type` + +- **Display name:** Battery Type +- **Type:** `string` + +Main type of the battery system. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `lead_based` | Lead-based | | +| `lithium_based` | Lithium-based | | +| `nickel_based` | Nickel-based | | +| `flow` | Flow | | +| `sodium_based` | Sodium-based | | +| `other` | Other | Other battery type, not covered by the standard types. | + diff --git a/docs/lib/energy/battery/soc.md b/docs/lib/energy/battery/soc.md new file mode 100644 index 0000000..0cb081c --- /dev/null +++ b/docs/lib/energy/battery/soc.md @@ -0,0 +1,14 @@ +# Battery State of Charge + +Implements the state of charge for a battery. + +## Telemetry + +### `battery_soc` + +- **Display name:** State of Charge +- **Type:** `float` +- **Unit:** % + +Battery state of charge percentage. + diff --git a/docs/lib/energy/battery/soh.md b/docs/lib/energy/battery/soh.md new file mode 100644 index 0000000..5ae98b6 --- /dev/null +++ b/docs/lib/energy/battery/soh.md @@ -0,0 +1,14 @@ +# Battery State of Health + +Implements the state of health for a battery. + +## Telemetry + +### `battery_soh` + +- **Display name:** State of Health +- **Type:** `float` +- **Unit:** % + +Battery state of health percentage. + diff --git a/docs/lib/energy/battery/status.md b/docs/lib/energy/battery/status.md new file mode 100644 index 0000000..14ab681 --- /dev/null +++ b/docs/lib/energy/battery/status.md @@ -0,0 +1,24 @@ +# Battery Status + +Operational status for standalone battery systems and battery management systems. Inverter-based devices (battery inverters, hybrid inverters) use inverter_status instead. + +## Telemetry + +### `battery_status` + +- **Display name:** Battery Status +- **Type:** `string` + +Current operational status of the battery. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Battery is powered and ready to operate but is not connected. It will not start until commanded by a user. | +| `standby` | Standby | Battery has entered a low-power sleep mode after an extended period of inactivity. It will wake up autonomously when needed, but the transition back to connected may not be instantaneous. | +| `starting` | Starting | Battery is initializing and not yet available for charging or discharging. This covers contactor pre-charge, string SoC balancing, and other steps required before the battery can accept power commands. | +| `connected` | Connected | Battery is connected and available for charging or discharging. The actual charge direction is reported in battery_charge_status. | +| `fault` | Fault | Battery has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Battery is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + diff --git a/docs/lib/energy/battery/temperature.md b/docs/lib/energy/battery/temperature.md new file mode 100644 index 0000000..ab69134 --- /dev/null +++ b/docs/lib/energy/battery/temperature.md @@ -0,0 +1,14 @@ +# Battery Temperature + +Implements the battery temperature. + +## Telemetry + +### `battery_temperature` + +- **Display name:** Battery Temperature +- **Type:** `float` +- **Unit:** Cel + +Battery temperature in Celsius. + diff --git a/docs/lib/energy/charge_controller/status.md b/docs/lib/energy/charge_controller/status.md new file mode 100644 index 0000000..b803a06 --- /dev/null +++ b/docs/lib/energy/charge_controller/status.md @@ -0,0 +1,26 @@ +# Charge Controller Status + +Operational status for PV charge controllers (MPPT and PWM). + +## Telemetry + +### `charge_controller_status` + +- **Display name:** Charge Controller Status +- **Type:** `string` + +Current operational status of the charge controller. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Charge controller is powered and ready to operate but is not managing power conversion. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Charge controller is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: insufficient PV irradiance (night time), battery fully charged with no load. | +| `starting` | Starting | Charge controller is executing its startup sequence. This includes PV input detection, MPPT initialization, and battery compatibility checks. Power conversion has not yet begun. | +| `operating` | Operating | Charge controller is actively managing power conversion from PV input to battery. The actual charge mode is reported in battery_charge_status. | +| `throttled` | Throttled | Charge controller is operating at reduced power output due to an external constraint or internal condition such as high temperature, battery voltage limits, or input overvoltage. | +| `stopping` | Stopping | Charge controller is executing a controlled stop sequence. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Charge controller has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Charge controller is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + diff --git a/docs/lib/energy/electrolyser/control.md b/docs/lib/energy/electrolyser/control.md new file mode 100644 index 0000000..117df4b --- /dev/null +++ b/docs/lib/energy/electrolyser/control.md @@ -0,0 +1,4 @@ +# Electrolyser Control + +Commands for controlling electrolyser hydrogen production. + diff --git a/docs/lib/energy/electrolyser/feed_water/conductivity.md b/docs/lib/energy/electrolyser/feed_water/conductivity.md new file mode 100644 index 0000000..d35895f --- /dev/null +++ b/docs/lib/energy/electrolyser/feed_water/conductivity.md @@ -0,0 +1,14 @@ +# Electrolyser Feed Water Conductivity + +Feed water conductivity measurement for electrolyser systems. + +## Telemetry + +### `feed_water_conductivity` + +- **Display name:** Feed Water Conductivity +- **Type:** `float` +- **Unit:** uS/cm + +Conductivity of the feed water supply. Lower values indicate higher purity. + diff --git a/docs/lib/energy/electrolyser/feed_water/pressure.md b/docs/lib/energy/electrolyser/feed_water/pressure.md new file mode 100644 index 0000000..bd2dfc0 --- /dev/null +++ b/docs/lib/energy/electrolyser/feed_water/pressure.md @@ -0,0 +1,14 @@ +# Electrolyser Feed Water Pressure + +Feed water pressure measurement for electrolyser systems. + +## Telemetry + +### `feed_water_pressure` + +- **Display name:** Feed Water Pressure +- **Type:** `float` +- **Unit:** bar + +Pressure of the feed water supply at the electrolyser inlet, measured as gauge pressure relative to atmospheric. + diff --git a/docs/lib/energy/electrolyser/feed_water/temperature.md b/docs/lib/energy/electrolyser/feed_water/temperature.md new file mode 100644 index 0000000..0a3b9a9 --- /dev/null +++ b/docs/lib/energy/electrolyser/feed_water/temperature.md @@ -0,0 +1,14 @@ +# Electrolyser Feed Water Temperature + +Feed water temperature measurement for electrolyser systems. + +## Telemetry + +### `feed_water_temperature` + +- **Display name:** Feed Water Temperature +- **Type:** `float` +- **Unit:** Cel + +Temperature of the feed water supply at the electrolyser inlet. + diff --git a/docs/lib/energy/electrolyser/h2_outlet_pressure.md b/docs/lib/energy/electrolyser/h2_outlet_pressure.md new file mode 100644 index 0000000..d68c6ea --- /dev/null +++ b/docs/lib/energy/electrolyser/h2_outlet_pressure.md @@ -0,0 +1,14 @@ +# Electrolyser H2 Outlet Pressure + +Hydrogen gas pressure at the electrolyser outlet. + +## Telemetry + +### `h2_outlet_pressure` + +- **Display name:** H2 Outlet Pressure +- **Type:** `float` +- **Unit:** bar + +Hydrogen gas pressure at the electrolyser outlet, measured as gauge pressure relative to atmospheric. + diff --git a/docs/lib/energy/electrolyser/h2_production/lifetime.md b/docs/lib/energy/electrolyser/h2_production/lifetime.md new file mode 100644 index 0000000..5ad54b1 --- /dev/null +++ b/docs/lib/energy/electrolyser/h2_production/lifetime.md @@ -0,0 +1,22 @@ +# Electrolyser H2 Production Lifetime + +Cumulative hydrogen production volume and production hours since installation. + +## Telemetry + +### `h2_produced_lifetime` + +- **Display name:** H2 Produced Lifetime +- **Type:** `float` +- **Unit:** Nl + +Cumulative hydrogen produced since installation at standard conditions. To convert to kg, divide by approximately 11126. + +### `h2_production_hours_lifetime` + +- **Display name:** H2 Production Hours Lifetime +- **Type:** `float` +- **Unit:** h + +Cumulative hours the electrolyser has spent actively producing hydrogen. + diff --git a/docs/lib/energy/electrolyser/h2_production/rate.md b/docs/lib/energy/electrolyser/h2_production/rate.md new file mode 100644 index 0000000..4dac257 --- /dev/null +++ b/docs/lib/energy/electrolyser/h2_production/rate.md @@ -0,0 +1,22 @@ +# Electrolyser H2 Production Rate + +Hydrogen production rate for electrolyser systems. Percentage value is relative to the nominal production capacity. The absolute output rate is reported in normal liters per hour (Nl/h) at standard conditions (0 deg C, 1 atm). To convert to kg/h, divide by approximately 11126 (1 kg H2 = 11126 Nl). + +## Telemetry + +### `h2_production_rate` + +- **Display name:** H2 Production Rate +- **Type:** `float` +- **Unit:** % + +Current hydrogen production rate as a percentage of nominal capacity. + +### `h2_output_rate` + +- **Display name:** H2 Output Rate +- **Type:** `float` +- **Unit:** Nl/h + +Current hydrogen output flow rate at standard conditions. To convert to kg/h, divide by approximately 11126. + diff --git a/docs/lib/energy/electrolyser/h2_production/setpoint.md b/docs/lib/energy/electrolyser/h2_production/setpoint.md new file mode 100644 index 0000000..609de57 --- /dev/null +++ b/docs/lib/energy/electrolyser/h2_production/setpoint.md @@ -0,0 +1,14 @@ +# Electrolyser H2 Production Setpoint + +Production setpoint control for electrolyser systems. Includes the setpoint telemetry and the command to change it. + +## Telemetry + +### `h2_production_setpoint` + +- **Display name:** H2 Production Setpoint +- **Type:** `float` +- **Unit:** % + +Commanded hydrogen production rate as a percentage of nominal capacity. + diff --git a/docs/lib/energy/electrolyser/power_consumption.md b/docs/lib/energy/electrolyser/power_consumption.md new file mode 100644 index 0000000..66896a0 --- /dev/null +++ b/docs/lib/energy/electrolyser/power_consumption.md @@ -0,0 +1,14 @@ +# Electrolyser Power + +Total electrical power consumption of the electrolyser. + +## Telemetry + +### `power_consumption` + +- **Display name:** Power Consumption +- **Type:** `float` +- **Unit:** W + +Total electrical power consumed by the electrolyser. + diff --git a/docs/lib/energy/electrolyser/stack/electrical.md b/docs/lib/energy/electrolyser/stack/electrical.md new file mode 100644 index 0000000..3402d82 --- /dev/null +++ b/docs/lib/energy/electrolyser/stack/electrical.md @@ -0,0 +1,30 @@ +# Electrolyser Stack Electrical + +Voltage, current, and power measurements for an electrolyser stack. + +## Telemetry + +### `stack_voltage` + +- **Display name:** Stack Voltage +- **Type:** `float` +- **Unit:** V + +DC voltage across the electrolyser stack. + +### `stack_current` + +- **Display name:** Stack Current +- **Type:** `float` +- **Unit:** A + +DC current through the electrolyser stack. + +### `stack_power` + +- **Display name:** Stack Power +- **Type:** `float` +- **Unit:** W + +DC power consumed by the electrolyser stack. + diff --git a/docs/lib/energy/electrolyser/stack/pressure.md b/docs/lib/energy/electrolyser/stack/pressure.md new file mode 100644 index 0000000..449aa47 --- /dev/null +++ b/docs/lib/energy/electrolyser/stack/pressure.md @@ -0,0 +1,14 @@ +# Electrolyser Stack Pressure + +Internal pressure measurement for an electrolyser stack. + +## Telemetry + +### `stack_pressure` + +- **Display name:** Stack Pressure +- **Type:** `float` +- **Unit:** bar + +Internal pressure of the electrolyser stack, measured as gauge pressure relative to atmospheric. + diff --git a/docs/lib/energy/electrolyser/stack/temperature.md b/docs/lib/energy/electrolyser/stack/temperature.md new file mode 100644 index 0000000..c6f223a --- /dev/null +++ b/docs/lib/energy/electrolyser/stack/temperature.md @@ -0,0 +1,14 @@ +# Electrolyser Stack Temperature + +Temperature measurement for an electrolyser stack. + +## Telemetry + +### `stack_temperature` + +- **Display name:** Stack Temperature +- **Type:** `float` +- **Unit:** Cel + +Temperature of the electrolyser stack. + diff --git a/docs/lib/energy/electrolyser/status.md b/docs/lib/energy/electrolyser/status.md new file mode 100644 index 0000000..2b5856e --- /dev/null +++ b/docs/lib/energy/electrolyser/status.md @@ -0,0 +1,28 @@ +# Electrolyser Status + +Operational status for electrolyser systems. Uses the standard status framework backbone with electrolyser-specific active status and approved optional statuses for common operational phases. + +## Telemetry + +### `electrolyser_status` + +- **Display name:** Electrolyser Status +- **Type:** `string` + +Current operational status of the electrolyser. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Powered on and ready to start. No active production or transitional process in progress. | +| `starting` | Starting | Startup sequence in progress. May include pressurization, leak checks, and ramp-up phases before hydrogen production begins. | +| `producing` | Producing | Actively producing hydrogen. | +| `stopping` | Stopping | Controlled shutdown in progress. May include ramp-down and depressurization phases. | +| `standby` | Standby | Production automatically paused due to process conditions such as maximum outlet pressure. Will resume autonomously when conditions allow. | +| `fault` | Fault | A condition prevents normal operation. Operator intervention or an automated reset is required before the electrolyser can return to service. | +| `maintenance` | Maintenance | Operator-initiated service mode. The electrolyser is intentionally taken out of normal operation for inspection or servicing. | +| `purging` | Purging | Performing a gas purge cycle to remove residual gases from the system for safety or process reasons. | +| `preheating` | Preheating | Heating the electrolyte or stack to operating temperature before production can begin. | +| `keeping_warm` | Keeping Warm | Maintaining electrolyte or stack temperature during an idle period to enable faster restarts. | + diff --git a/docs/lib/energy/fuel_cell/control.md b/docs/lib/energy/fuel_cell/control.md new file mode 100644 index 0000000..51368f5 --- /dev/null +++ b/docs/lib/energy/fuel_cell/control.md @@ -0,0 +1,4 @@ +# Fuel Cell Control + +Commands for controlling fuel cell power generation. + diff --git a/docs/lib/energy/fuel_cell/energy/lifetime.md b/docs/lib/energy/fuel_cell/energy/lifetime.md new file mode 100644 index 0000000..53431b1 --- /dev/null +++ b/docs/lib/energy/fuel_cell/energy/lifetime.md @@ -0,0 +1,14 @@ +# Fuel Cell Energy Generated Lifetime + +Cumulative electrical energy generated since installation. + +## Telemetry + +### `energy_generated_lifetime` + +- **Display name:** Energy Generated Lifetime +- **Type:** `float` +- **Unit:** Wh + +Cumulative electrical energy generated since installation. + diff --git a/docs/lib/energy/fuel_cell/h2_inlet_pressure.md b/docs/lib/energy/fuel_cell/h2_inlet_pressure.md new file mode 100644 index 0000000..66cf378 --- /dev/null +++ b/docs/lib/energy/fuel_cell/h2_inlet_pressure.md @@ -0,0 +1,14 @@ +# Fuel Cell H2 Inlet Pressure + +Hydrogen gas pressure at the fuel cell inlet. + +## Telemetry + +### `h2_inlet_pressure` + +- **Display name:** H2 Inlet Pressure +- **Type:** `float` +- **Unit:** mbar + +Hydrogen gas pressure at the fuel cell inlet, measured as gauge pressure relative to atmospheric. Fuel cell anode pressures are typically in the hundreds of millibar range. + diff --git a/docs/lib/energy/fuel_cell/output/current_limit.md b/docs/lib/energy/fuel_cell/output/current_limit.md new file mode 100644 index 0000000..c9e0fdd --- /dev/null +++ b/docs/lib/energy/fuel_cell/output/current_limit.md @@ -0,0 +1,14 @@ +# Fuel Cell Output Current Limit + +Maximum output current permitted by the fuel cell. Limits the DC-DC converter output to protect the stack and downstream equipment. + +## Telemetry + +### `output_current_limit` + +- **Display name:** Output Current Limit +- **Type:** `float` +- **Unit:** A + +Maximum DC output current permitted by the fuel cell. + diff --git a/docs/lib/energy/fuel_cell/output/electrical.md b/docs/lib/energy/fuel_cell/output/electrical.md new file mode 100644 index 0000000..d137339 --- /dev/null +++ b/docs/lib/energy/fuel_cell/output/electrical.md @@ -0,0 +1,30 @@ +# Fuel Cell Electrical + +Voltage, current, and power measurements for the fuel cell output. + +## Telemetry + +### `output_voltage` + +- **Display name:** Output Voltage +- **Type:** `float` +- **Unit:** V + +DC voltage at the fuel cell output. + +### `output_current` + +- **Display name:** Output Current +- **Type:** `float` +- **Unit:** A + +DC current at the fuel cell output. + +### `output_power` + +- **Display name:** Output Power +- **Type:** `float` +- **Unit:** W + +DC power delivered by the fuel cell. + diff --git a/docs/lib/energy/fuel_cell/output/voltage_setpoint.md b/docs/lib/energy/fuel_cell/output/voltage_setpoint.md new file mode 100644 index 0000000..3340f53 --- /dev/null +++ b/docs/lib/energy/fuel_cell/output/voltage_setpoint.md @@ -0,0 +1,14 @@ +# Fuel Cell Output Voltage Setpoint + +Target output voltage of the fuel cell. The internal DC-DC converter regulates individual stack outputs to deliver this voltage. + +## Telemetry + +### `output_voltage_setpoint` + +- **Display name:** Output Voltage Setpoint +- **Type:** `float` +- **Unit:** V + +Target DC output voltage of the fuel cell. + diff --git a/docs/lib/energy/fuel_cell/run_hours/lifetime.md b/docs/lib/energy/fuel_cell/run_hours/lifetime.md new file mode 100644 index 0000000..1fb9b0e --- /dev/null +++ b/docs/lib/energy/fuel_cell/run_hours/lifetime.md @@ -0,0 +1,14 @@ +# Fuel Cell Run Hours Lifetime + +Cumulative hours the fuel cell has spent actively generating power. + +## Telemetry + +### `run_hours_lifetime` + +- **Display name:** Run Hours Lifetime +- **Type:** `float` +- **Unit:** h + +Cumulative hours the fuel cell has spent actively generating power. + diff --git a/docs/lib/energy/fuel_cell/status.md b/docs/lib/energy/fuel_cell/status.md new file mode 100644 index 0000000..1b42883 --- /dev/null +++ b/docs/lib/energy/fuel_cell/status.md @@ -0,0 +1,26 @@ +# Fuel Cell Status + +Operational status for fuel cell systems. Uses the standard status framework backbone with fuel cell-specific active status and the approved derated status for reduced-output operation. + +## Telemetry + +### `fuel_cell_status` + +- **Display name:** Fuel Cell Status +- **Type:** `string` + +Current operational status of the fuel cell. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Powered on and ready to start. No active power generation or transitional process in progress. | +| `starting` | Starting | Startup sequence in progress. May include gas line purging, pressurization, and temperature ramp phases before power generation begins. | +| `running` | Running | Actively generating electrical power. | +| `stopping` | Stopping | Controlled shutdown in progress. May include cooldown, gas purging, and depressurization phases. | +| `standby` | Standby | Power generation automatically paused due to process conditions such as low hydrogen supply pressure or battery voltage threshold. Will resume autonomously when conditions allow. | +| `derated` | Derated | Generating at reduced output due to stack degradation, hydrogen supply limitations, or temperature constraints. The fuel cell is operational but cannot deliver full rated power. | +| `fault` | Fault | A condition prevents normal operation. Operator intervention or an automated reset is required before the fuel cell can return to service. | +| `maintenance` | Maintenance | Operator-initiated service mode. The fuel cell is intentionally taken out of normal operation for inspection or servicing. | + diff --git a/docs/lib/energy/inverter/ac/1_phase.md b/docs/lib/energy/inverter/ac/1_phase.md new file mode 100644 index 0000000..4f3818c --- /dev/null +++ b/docs/lib/energy/inverter/ac/1_phase.md @@ -0,0 +1,38 @@ +# Single-Phase Inverter + +Provides AC measurements for a single-phase inverter. + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz + +AC output frequency. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W + +AC power on phase L1. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L1. + diff --git a/docs/lib/energy/inverter/ac/3_phase.md b/docs/lib/energy/inverter/ac/3_phase.md new file mode 100644 index 0000000..4f3f970 --- /dev/null +++ b/docs/lib/energy/inverter/ac/3_phase.md @@ -0,0 +1,86 @@ +# Three-Phase Inverter + +Provides AC measurements for a three-phase inverter. + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz + +AC output frequency. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L1. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W + +Power on phase L1. + +### `ac_l2_voltage` + +- **Display name:** L2 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L2 to neutral. + +### `ac_l2_current` + +- **Display name:** L2 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L2. + +### `ac_l2_power` + +- **Display name:** L2 Power +- **Type:** `float` +- **Unit:** W + +Power on phase L2. + +### `ac_l3_voltage` + +- **Display name:** L3 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L3 to neutral. + +### `ac_l3_current` + +- **Display name:** L3 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L3. + +### `ac_l3_power` + +- **Display name:** L3 Power +- **Type:** `float` +- **Unit:** W + +Power on phase L3. + diff --git a/docs/lib/energy/inverter/ac/current.md b/docs/lib/energy/inverter/ac/current.md new file mode 100644 index 0000000..0424e02 --- /dev/null +++ b/docs/lib/energy/inverter/ac/current.md @@ -0,0 +1,14 @@ +# Total AC Current + +Provides total AC current measurement across all phases. + +## Telemetry + +### `ac_total_current` + +- **Display name:** AC Current +- **Type:** `float` +- **Unit:** A + +Total AC current across all phases. Positive values indicate current flowing out to grid/loads, negative values indicate current flowing in, e.g. for charging batteries. + diff --git a/docs/lib/energy/inverter/ac/energy/daily.md b/docs/lib/energy/inverter/ac/energy/daily.md new file mode 100644 index 0000000..dc37a6e --- /dev/null +++ b/docs/lib/energy/inverter/ac/energy/daily.md @@ -0,0 +1,14 @@ +# AC Daily Energy + +AC energy production since the start of the current day. + +## Telemetry + +### `ac_energy_daily` + +- **Display name:** AC Daily Energy +- **Type:** `float` +- **Unit:** Wh + +Energy produced (converted from DC to AC) since the start of the current day. Day boundary is determined by the timezone configured on the device. + diff --git a/docs/lib/energy/inverter/ac/energy/lifetime.md b/docs/lib/energy/inverter/ac/energy/lifetime.md new file mode 100644 index 0000000..4e1d25a --- /dev/null +++ b/docs/lib/energy/inverter/ac/energy/lifetime.md @@ -0,0 +1,14 @@ +# Inverter Lifetime Energy + +Cumulative AC energy production since installation. + +## Telemetry + +### `ac_energy_lifetime` + +- **Display name:** AC Lifetime Energy +- **Type:** `float` +- **Unit:** Wh + +Cumulative energy produced (converted from DC to AC) since installation. + diff --git a/docs/lib/energy/inverter/ac/power.md b/docs/lib/energy/inverter/ac/power.md new file mode 100644 index 0000000..b803bdf --- /dev/null +++ b/docs/lib/energy/inverter/ac/power.md @@ -0,0 +1,14 @@ +# Total AC Power + +Total AC power measurement across all phases. + +## Telemetry + +### `ac_total_power` + +- **Display name:** AC Power +- **Type:** `float` +- **Unit:** W + +Total AC power across all phases. Positive values indicate power being delivered to loads/grid, negative values indicate power being consumed, e.g. for charging batteries. + diff --git a/docs/lib/energy/inverter/grid/charge/enabled.md b/docs/lib/energy/inverter/grid/charge/enabled.md new file mode 100644 index 0000000..688f613 --- /dev/null +++ b/docs/lib/energy/inverter/grid/charge/enabled.md @@ -0,0 +1,20 @@ +# Grid Charging/Feed-in Configuration Status + +Information about grid charging/feeding-in configuration status. + +## Properties + +### `grid_charge_enabled` + +- **Display name:** Grid Charging Enabled +- **Type:** `boolean` + +Whether charging from grid is enabled. + +### `grid_feed_in_enabled` + +- **Display name:** Grid Feed-in Enabled +- **Type:** `boolean` + +Whether feeding energy to grid is enabled. + diff --git a/docs/lib/energy/inverter/grid/mode.md b/docs/lib/energy/inverter/grid/mode.md new file mode 100644 index 0000000..713d0df --- /dev/null +++ b/docs/lib/energy/inverter/grid/mode.md @@ -0,0 +1,18 @@ +# Grid Connection Mode + +Configured grid connection mode for the inverter. + +## Properties + +### `grid_mode` + +- **Display name:** Grid Mode +- **Type:** `string` + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `grid_tied` | Grid-tied | Inverter is configured to operate in grid-tied mode. | +| `off_grid` | Off-grid | Inverter is configured to operate off-grid (grid-forming mode). | + diff --git a/docs/lib/energy/inverter/grid/power.md b/docs/lib/energy/inverter/grid/power.md new file mode 100644 index 0000000..98c2451 --- /dev/null +++ b/docs/lib/energy/inverter/grid/power.md @@ -0,0 +1,14 @@ +# Grid Power + +Power exchange with the utility grid. + +## Telemetry + +### `grid_total_power` + +- **Display name:** Grid Power +- **Type:** `float` +- **Unit:** W + +Power exchange with grid (positive for import, negative for export). + diff --git a/docs/lib/energy/inverter/grid/status.md b/docs/lib/energy/inverter/grid/status.md new file mode 100644 index 0000000..bff5822 --- /dev/null +++ b/docs/lib/energy/inverter/grid/status.md @@ -0,0 +1,21 @@ +# Grid Connection Status + +Grid connection state for grid-tied and hybrid inverters. + +## Telemetry + +### `grid_status` + +- **Display name:** Grid Connection Status +- **Type:** `string` + +Current grid connection state of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `disconnected` | Disconnected | Inverter is not connected to the grid. This includes off-grid or island mode, pre-synchronization, or operator-initiated disconnection. | +| `connected` | Connected | Operating in grid-connected mode, grid connection is active. | +| `fault` | Fault | Grid parameters out of specified range (voltage, frequency, etc.), grid connection is temporarily disabled. | + diff --git a/docs/lib/energy/inverter/load/power.md b/docs/lib/energy/inverter/load/power.md new file mode 100644 index 0000000..e329d30 --- /dev/null +++ b/docs/lib/energy/inverter/load/power.md @@ -0,0 +1,14 @@ +# Inverter Load Power + +Power consumed by local loads on the inverter AC output. + +## Telemetry + +### `load_total_power` + +- **Display name:** Load Power +- **Type:** `float` +- **Unit:** W + +Total power consumed by local loads on the inverter AC output. Typically positive; negative values are possible but uncommon when a bidirectional load or generator is connected to the load port. + diff --git a/docs/lib/energy/inverter/nameplate.md b/docs/lib/energy/inverter/nameplate.md new file mode 100644 index 0000000..38830ce --- /dev/null +++ b/docs/lib/energy/inverter/nameplate.md @@ -0,0 +1,14 @@ +# Inverter Nameplate + +Nameplate attributes for battery, solar, and hybrid inverters. + +## Properties + +### `inverter_nameplate_capacity` + +- **Display name:** Nameplate Capacity +- **Type:** `integer` +- **Unit:** VA + +Maximum apparent power rating of the inverter in VA (volt-amperes). + diff --git a/docs/lib/energy/inverter/residual_current.md b/docs/lib/energy/inverter/residual_current.md new file mode 100644 index 0000000..3648549 --- /dev/null +++ b/docs/lib/energy/inverter/residual_current.md @@ -0,0 +1,14 @@ +# Inverter Residual Current + +Residual current monitoring for inverter ground fault detection. + +## Telemetry + +### `inverter_residual_current` + +- **Display name:** Residual Current +- **Type:** `float` +- **Unit:** mA + +Residual current detected by the inverter. + diff --git a/docs/lib/energy/inverter/status.md b/docs/lib/energy/inverter/status.md new file mode 100644 index 0000000..a6e352b --- /dev/null +++ b/docs/lib/energy/inverter/status.md @@ -0,0 +1,26 @@ +# Inverter Status + +Operational status for battery, solar, and hybrid inverters. + +## Telemetry + +### `inverter_status` + +- **Display name:** Inverter Status +- **Type:** `string` + +Current operational status of the inverter. + +**Values:** + +| Value | Name | Description | +|-------|------|-------------| +| `idle` | Idle | Inverter is powered and ready to operate but is not converting power. It will not start until commanded by a user or a rule. | +| `standby` | Standby | Inverter is not converting power but will autonomously resume operation when conditions are met. No command is required. Examples: DC voltage too low (night time for PV inverters), AC grid voltage unavailable for grid-tied inverters. | +| `starting` | Starting | Inverter is executing its startup sequence. This includes grid synchronization, self-tests, and ramp-up. Power conversion has not yet reached nominal operation. | +| `operating` | Operating | Inverter is actively converting power at its operating setpoint. | +| `throttled` | Throttled | Inverter is operating at reduced power output due to an external constraint or internal condition such as high temperature, grid frequency response, or power curtailment. | +| `stopping` | Stopping | Inverter is executing a controlled stop sequence, including grid disconnection and ramp-down. It will reach idle or standby when the sequence completes. | +| `fault` | Fault | Inverter has detected a condition that prevents normal operation. Operator attention is required before the device can resume. | +| `maintenance` | Maintenance | Inverter is in a maintenance or configuration mode. Normal operation has been suspended by an operator and will not resume until the operator exits this mode. | + diff --git a/docs/lib/energy/inverter/temperature.md b/docs/lib/energy/inverter/temperature.md new file mode 100644 index 0000000..e4994cc --- /dev/null +++ b/docs/lib/energy/inverter/temperature.md @@ -0,0 +1,22 @@ +# Inverter Temperature + +Provides temperature measurements for different parts of the inverter. + +## Telemetry + +### `inverter_heatsink_temperature` + +- **Display name:** Heatsink Temperature +- **Type:** `float` +- **Unit:** Cel + +Temperature of the inverter's heatsink. + +### `inverter_internal_temperature` + +- **Display name:** Internal Temperature +- **Type:** `float` +- **Unit:** Cel + +Internal temperature of the inverter. + diff --git a/docs/lib/energy/power_meter/ac/1_phase.md b/docs/lib/energy/power_meter/ac/1_phase.md new file mode 100644 index 0000000..10a457f --- /dev/null +++ b/docs/lib/energy/power_meter/ac/1_phase.md @@ -0,0 +1,38 @@ +# Single-Phase AC Power Meter + +Provides AC measurements for a single-phase power meter. + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz + +AC frequency at the measurement point. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W + +AC power on phase L1. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L1. + diff --git a/docs/lib/energy/power_meter/ac/3_phase.md b/docs/lib/energy/power_meter/ac/3_phase.md new file mode 100644 index 0000000..2e1ae30 --- /dev/null +++ b/docs/lib/energy/power_meter/ac/3_phase.md @@ -0,0 +1,86 @@ +# Three-Phase AC Power Meter + +Provides AC measurements for a three-phase power meter. + +## Telemetry + +### `ac_frequency` + +- **Display name:** AC Frequency +- **Type:** `float` +- **Unit:** Hz + +AC frequency at the measurement point. + +### `ac_l1_voltage` + +- **Display name:** L1 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L1 to neutral. + +### `ac_l1_current` + +- **Display name:** L1 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L1. + +### `ac_l1_power` + +- **Display name:** L1 Power +- **Type:** `float` +- **Unit:** W + +Power on phase L1. + +### `ac_l2_voltage` + +- **Display name:** L2 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L2 to neutral. + +### `ac_l2_current` + +- **Display name:** L2 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L2. + +### `ac_l2_power` + +- **Display name:** L2 Power +- **Type:** `float` +- **Unit:** W + +Power on phase L2. + +### `ac_l3_voltage` + +- **Display name:** L3 Voltage +- **Type:** `float` +- **Unit:** V + +Voltage on phase L3 to neutral. + +### `ac_l3_current` + +- **Display name:** L3 Current +- **Type:** `float` +- **Unit:** A + +Current on phase L3. + +### `ac_l3_power` + +- **Display name:** L3 Power +- **Type:** `float` +- **Unit:** W + +Power on phase L3. + diff --git a/docs/lib/energy/power_meter/current.md b/docs/lib/energy/power_meter/current.md new file mode 100644 index 0000000..3d90550 --- /dev/null +++ b/docs/lib/energy/power_meter/current.md @@ -0,0 +1,14 @@ +# Current Measurement + +Provides total current measurement for a power meter. + +## Telemetry + +### `total_current` + +- **Display name:** Total Current +- **Type:** `float` +- **Unit:** A + +Total current across all connected loads. Positive values typically correspond to current flowing out to loads. + diff --git a/docs/lib/energy/power_meter/energy/daily.md b/docs/lib/energy/power_meter/energy/daily.md new file mode 100644 index 0000000..d098834 --- /dev/null +++ b/docs/lib/energy/power_meter/energy/daily.md @@ -0,0 +1,14 @@ +# Daily Energy + +Energy consumption since the start of the current day. + +## Telemetry + +### `energy_daily` + +- **Display name:** Daily Energy +- **Type:** `float` +- **Unit:** Wh + +Energy consumed by loads since the start of the current day. Day boundary is determined by the timezone configured on the device. + diff --git a/docs/lib/energy/power_meter/energy/lifetime.md b/docs/lib/energy/power_meter/energy/lifetime.md new file mode 100644 index 0000000..6ffb98c --- /dev/null +++ b/docs/lib/energy/power_meter/energy/lifetime.md @@ -0,0 +1,14 @@ +# Lifetime Energy + +Cumulative energy consumption since installation. + +## Telemetry + +### `energy_lifetime` + +- **Display name:** Lifetime Energy +- **Type:** `float` +- **Unit:** Wh + +Cumulative energy consumed by loads since installation. + diff --git a/docs/lib/energy/power_meter/power.md b/docs/lib/energy/power_meter/power.md new file mode 100644 index 0000000..5ed5fa5 --- /dev/null +++ b/docs/lib/energy/power_meter/power.md @@ -0,0 +1,14 @@ +# Power Measurement + +Provides total power measurement for a power meter. + +## Telemetry + +### `total_power` + +- **Display name:** Total Power +- **Type:** `float` +- **Unit:** W + +Total power across all connected loads. Positive values typically correspond to power being consumed by loads. + diff --git a/docs/lib/energy/power_quality/power_factor/1_phase.md b/docs/lib/energy/power_quality/power_factor/1_phase.md new file mode 100644 index 0000000..5c0755f --- /dev/null +++ b/docs/lib/energy/power_quality/power_factor/1_phase.md @@ -0,0 +1,30 @@ +# Single-Phase Power Factor Measurement + +This profile provides power factor telemetry for a single-phase system. + +## Telemetry + +### `ac_l1_power_apparent` + +- **Display name:** Apparent Power +- **Type:** `float` +- **Unit:** VA + +Apparent power (S). + +### `ac_l1_power_reactive` + +- **Display name:** Reactive Power +- **Type:** `float` +- **Unit:** VAR + +Reactive power (Q). + +### `ac_l1_power_factor` + +- **Display name:** Power Factor +- **Type:** `float` +- **Unit:** 1 + +Ratio of active power to apparent power, range from -1 to 1. Positive values indicate lagging (inductive) power factor. Negative values indicate leading (capacitive) power factor. + diff --git a/docs/lib/energy/power_quality/power_factor/3_phase.md b/docs/lib/energy/power_quality/power_factor/3_phase.md new file mode 100644 index 0000000..b02aa42 --- /dev/null +++ b/docs/lib/energy/power_quality/power_factor/3_phase.md @@ -0,0 +1,78 @@ +# Three-Phase Power Factor Measurement + +This profile provides power factor telemetry for each phase of a three-phase system. + +## Telemetry + +### `ac_l1_power_apparent` + +- **Display name:** L1 Apparent Power +- **Type:** `float` +- **Unit:** VA + +Apparent power (S) on phase L1. + +### `ac_l1_power_reactive` + +- **Display name:** L1 Reactive Power +- **Type:** `float` +- **Unit:** VAR + +Reactive power (Q) on phase L1. + +### `ac_l1_power_factor` + +- **Display name:** L1 Power Factor +- **Type:** `float` +- **Unit:** 1 + +Ratio of L1 active power to L1 apparent power, range from -1 to 1. Positive values indicate lagging (inductive) power factor. Negative values indicate leading (capacitive) power factor. + +### `ac_l2_power_apparent` + +- **Display name:** L2 Apparent Power +- **Type:** `float` +- **Unit:** VA + +Apparent power (S) on phase L2. + +### `ac_l2_power_reactive` + +- **Display name:** L2 Reactive Power +- **Type:** `float` +- **Unit:** VAR + +Reactive power (Q) on phase L2. + +### `ac_l2_power_factor` + +- **Display name:** L2 Power Factor +- **Type:** `float` +- **Unit:** 1 + +Ratio of L2 active power to L2 apparent power, range from -1 to 1. Positive values indicate lagging (inductive) power factor. Negative values indicate leading (capacitive) power factor. + +### `ac_l3_power_apparent` + +- **Display name:** L3 Apparent Power +- **Type:** `float` +- **Unit:** VA + +Apparent power (S) on phase L3. + +### `ac_l3_power_reactive` + +- **Display name:** L3 Reactive Power +- **Type:** `float` +- **Unit:** VAR + +Reactive power (Q) on phase L3. + +### `ac_l3_power_factor` + +- **Display name:** L3 Power Factor +- **Type:** `float` +- **Unit:** 1 + +Ratio of L3 active power to L3 apparent power, range from -1 to 1. Positive values indicate lagging (inductive) power factor. Negative values indicate leading (capacitive) power factor. + diff --git a/docs/lib/energy/power_quality/power_factor/totals.md b/docs/lib/energy/power_quality/power_factor/totals.md new file mode 100644 index 0000000..9e8bf76 --- /dev/null +++ b/docs/lib/energy/power_quality/power_factor/totals.md @@ -0,0 +1,30 @@ +# Power Factor + +Power factor is the ratio of total active power to total apparent power. This profile is applicable to both single-phase and three-phase systems and is intended to be used with inverters, power meters, or other similar devices. In a single-phase system, the power factor is the ratio of active power to apparent power. In a three-phase system, the power factor is the ratio of total active power to total apparent power. + +## Telemetry + +### `ac_power_factor` + +- **Display name:** Power Factor +- **Type:** `float` +- **Unit:** 1 + +Ratio of total active power to total apparent power (Ptotal/Stotal), range from -1 to 1 Positive values indicate lagging (inductive) power factor. Negative values indicate leading (capacitive) power factor. + +### `ac_total_power_apparent` + +- **Display name:** Total Apparent Power +- **Type:** `float` +- **Unit:** VA + +Total apparent power (S) - vector sum of active and reactive power across all phases. + +### `ac_total_power_reactive` + +- **Display name:** Total Reactive Power +- **Type:** `float` +- **Unit:** VAR + +Total reactive power (Q) across all phases - power that returns to the source in each cycle. + diff --git a/docs/lib/energy/pv/current.md b/docs/lib/energy/pv/current.md new file mode 100644 index 0000000..3e68b36 --- /dev/null +++ b/docs/lib/energy/pv/current.md @@ -0,0 +1,14 @@ +# Total PV Current + +Total PV current measurement across all strings. + +## Telemetry + +### `pv_total_current` + +- **Display name:** PV Current +- **Type:** `float` +- **Unit:** A + +Total DC current flow from all PV strings. + diff --git a/docs/lib/energy/pv/energy/daily.md b/docs/lib/energy/pv/energy/daily.md new file mode 100644 index 0000000..2bf56f2 --- /dev/null +++ b/docs/lib/energy/pv/energy/daily.md @@ -0,0 +1,14 @@ +# PV Daily Energy + +PV energy production since the start of the current day. + +## Telemetry + +### `pv_energy_daily` + +- **Display name:** PV Daily Energy +- **Type:** `float` +- **Unit:** Wh + +Energy generated by all PV strings since the start of the current day. Day boundary is determined by the timezone configured on the device. + diff --git a/docs/lib/energy/pv/energy/lifetime.md b/docs/lib/energy/pv/energy/lifetime.md new file mode 100644 index 0000000..2cf7d1f --- /dev/null +++ b/docs/lib/energy/pv/energy/lifetime.md @@ -0,0 +1,14 @@ +# PV Lifetime Energy + +Cumulative PV energy production since installation. + +## Telemetry + +### `pv_energy_lifetime` + +- **Display name:** PV Lifetime Energy +- **Type:** `float` +- **Unit:** Wh + +Cumulative energy produced by all PV strings since installation. + diff --git a/docs/lib/energy/pv/power.md b/docs/lib/energy/pv/power.md new file mode 100644 index 0000000..4cefbd8 --- /dev/null +++ b/docs/lib/energy/pv/power.md @@ -0,0 +1,14 @@ +# Total PV Power + +Total PV power measurement across all strings. + +## Telemetry + +### `pv_total_power` + +- **Display name:** PV Power +- **Type:** `float` +- **Unit:** W + +DC power generated by all PV strings. + diff --git a/docs/lib/energy/pv/string/electrical.md b/docs/lib/energy/pv/string/electrical.md new file mode 100644 index 0000000..f7302d5 --- /dev/null +++ b/docs/lib/energy/pv/string/electrical.md @@ -0,0 +1,30 @@ +# PV String Electrical Measurements + +Voltage, current, and power measurements for a single PV MPPT string. + +## Telemetry + +### `pv_string_voltage` + +- **Display name:** PV String Voltage +- **Type:** `float` +- **Unit:** V + +DC voltage of the solar panel string. + +### `pv_string_current` + +- **Display name:** PV String Current +- **Type:** `float` +- **Unit:** A + +DC current of the solar panel string. + +### `pv_string_power` + +- **Display name:** PV String Power +- **Type:** `float` +- **Unit:** W + +DC power of the solar panel string. + diff --git a/docs/lib/energy/pv/string/energy.md b/docs/lib/energy/pv/string/energy.md new file mode 100644 index 0000000..c486525 --- /dev/null +++ b/docs/lib/energy/pv/string/energy.md @@ -0,0 +1,14 @@ +# PV String Energy + +Cumulative energy production for a single PV MPPT string. + +## Telemetry + +### `pv_string_energy_lifetime` + +- **Display name:** PV String Lifetime Energy +- **Type:** `float` +- **Unit:** Wh + +Cumulative energy produced by this PV string since installation. + diff --git a/docs/lib/energy/pv/string/temperature.md b/docs/lib/energy/pv/string/temperature.md new file mode 100644 index 0000000..cdac488 --- /dev/null +++ b/docs/lib/energy/pv/string/temperature.md @@ -0,0 +1,14 @@ +# PV String Temperature + +Temperature measurement for a single PV MPPT string. + +## Telemetry + +### `pv_string_temperature` + +- **Display name:** PV String Temperature +- **Type:** `float` +- **Unit:** Cel + +Temperature of the solar panel string. + diff --git a/docs/lib/energy/pv/throttling.md b/docs/lib/energy/pv/throttling.md new file mode 100644 index 0000000..669884f --- /dev/null +++ b/docs/lib/energy/pv/throttling.md @@ -0,0 +1,13 @@ +# PV Throttling + +PV throttling capability defines when the PV system is operating at reduced power output, e.g. due to high temperature. + +## Telemetry + +### `pv_throttled` + +- **Display name:** PV Throttled +- **Type:** `boolean` + +Whether the PV system is operating at reduced power output, e.g. due to high temperature. + diff --git a/docs/lib/firmware/version.md b/docs/lib/firmware/version.md new file mode 100644 index 0000000..7920ab2 --- /dev/null +++ b/docs/lib/firmware/version.md @@ -0,0 +1,13 @@ +# Firmware Version + +Device firmware version information. + +## Properties + +### `firmware_version` + +- **Display name:** Firmware Version +- **Type:** `string` + +Version of the device firmware. + diff --git a/docs/lib/location/coordinates.md b/docs/lib/location/coordinates.md new file mode 100644 index 0000000..dcf77b2 --- /dev/null +++ b/docs/lib/location/coordinates.md @@ -0,0 +1,22 @@ +# Location Coordinates + +Geographic coordinates in decimal degrees. + +## Properties + +### `latitude` + +- **Display name:** Latitude +- **Type:** `float` +- **Unit:** deg + +Latitude coordinate in decimal degrees. + +### `longitude` + +- **Display name:** Longitude +- **Type:** `float` +- **Unit:** deg + +Longitude coordinate in decimal degrees. + diff --git a/docs/lib/sensor/gas/lel.md b/docs/lib/sensor/gas/lel.md new file mode 100644 index 0000000..208a0d1 --- /dev/null +++ b/docs/lib/sensor/gas/lel.md @@ -0,0 +1,14 @@ +# Gas concentration in %LEL + +Indicates the ability to measure gas concentration in %LEL (Lower Explosive Limit). + +## Telemetry + +### `gas_lel` + +- **Display name:** Gas Percent of Lower Explosive Limit (%LEL) +- **Type:** `float` +- **Unit:** %LEL + +Gas concentration as a percentage of the Lower Explosive Limit (LEL) - the minimum concentration at which the gas can ignite in air. 0% LEL indicates no gas is present. At 100% LEL the gas has reached the ignition threshold; concentrations above this are within the explosive range up to the Upper Explosive Limit (UEL). + diff --git a/docs/lib/sensor/gas/ppm.md b/docs/lib/sensor/gas/ppm.md new file mode 100644 index 0000000..b6c7e33 --- /dev/null +++ b/docs/lib/sensor/gas/ppm.md @@ -0,0 +1,14 @@ +# Gas Concentration in ppm + +Gas concentration measurement in parts per million. + +## Telemetry + +### `gas_ppm` + +- **Display name:** Gas Parts Per Million (ppm) +- **Type:** `float` +- **Unit:** [ppm] + +Gas concentration in parts per million (ppm). This indicates the amount of gas present in the air, where 1 ppm means one part of gas per million parts of air. + diff --git a/docs/lib/sensor/solar_irradiance.md b/docs/lib/sensor/solar_irradiance.md new file mode 100644 index 0000000..2c6fce3 --- /dev/null +++ b/docs/lib/sensor/solar_irradiance.md @@ -0,0 +1,14 @@ +# Solar Irradiance + +Indicates the ability to measure solar irradiance. + +## Telemetry + +### `solar_irradiance` + +- **Display name:** Solar Irradiance +- **Type:** `float` +- **Unit:** W/m2 + +The amount of solar power received per unit area. + diff --git a/docs/lib/sensor/temperature/ambient.md b/docs/lib/sensor/temperature/ambient.md new file mode 100644 index 0000000..0a1d37f --- /dev/null +++ b/docs/lib/sensor/temperature/ambient.md @@ -0,0 +1,14 @@ +# Ambient Temperature + +Indicates the ability to measure ambient temperature. + +## Telemetry + +### `ambient_temperature` + +- **Display name:** Ambient Temperature +- **Type:** `float` +- **Unit:** Cel + +The temperature of the environment in which the system operates. + diff --git a/docs/sensor/ambient_temperature.md b/docs/sensor/ambient_temperature.md new file mode 100644 index 0000000..a39a13b --- /dev/null +++ b/docs/sensor/ambient_temperature.md @@ -0,0 +1,41 @@ +# Ambient Temperature Sensor + +Ambient temperature sensor reporting air temperature in degrees Celsius. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `ambient_temperature` + +- **Display name:** Ambient Temperature +- **Type:** `float` +- **Unit:** Cel +- **Inherited from:** [`lib.sensor.temperature.ambient`](../lib/sensor/temperature/ambient.md) + +The temperature of the environment in which the system operates. + diff --git a/docs/sensor/gas/hydrogen.md b/docs/sensor/gas/hydrogen.md new file mode 100644 index 0000000..3c757ba --- /dev/null +++ b/docs/sensor/gas/hydrogen.md @@ -0,0 +1,50 @@ +# Hydrogen Concentration Sensor + +Hydrogen gas detector reporting gas concentration. + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `gas_lel` + +- **Display name:** Gas Percent of Lower Explosive Limit (%LEL) +- **Type:** `float` +- **Unit:** %LEL +- **Inherited from:** [`lib.sensor.gas.lel`](../../lib/sensor/gas/lel.md) + +Gas concentration as a percentage of the Lower Explosive Limit (LEL) - the minimum concentration at which the gas can ignite in air. 0% LEL indicates no gas is present. At 100% LEL the gas has reached the ignition threshold; concentrations above this are within the explosive range up to the Upper Explosive Limit (UEL). + +### `gas_ppm` + +- **Display name:** Gas Parts Per Million (ppm) +- **Type:** `float` +- **Unit:** [ppm] +- **Inherited from:** [`lib.sensor.gas.ppm`](../../lib/sensor/gas/ppm.md) + +Gas concentration in parts per million (ppm). This indicates the amount of gas present in the air, where 1 ppm means one part of gas per million parts of air. + diff --git a/docs/sensor/solar_irradiance.md b/docs/sensor/solar_irradiance.md new file mode 100644 index 0000000..54a62a0 --- /dev/null +++ b/docs/sensor/solar_irradiance.md @@ -0,0 +1,41 @@ +# Solar Irradiance Sensor + +Solar irradiance sensor (pyranometer) reporting irradiance in W/m². + +## Properties + +### `vendor` + +- **Display name:** Vendor +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Manufacturer of the device. + +### `model` + +- **Display name:** Model +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Model name/number. + +### `serial_number` + +- **Display name:** Serial Number +- **Type:** `string` +- **Inherited from:** [`lib.device.nameplate`](../lib/device/nameplate.md) + +Unique serial number of the device. + +## Telemetry + +### `solar_irradiance` + +- **Display name:** Solar Irradiance +- **Type:** `float` +- **Unit:** W/m2 +- **Inherited from:** [`lib.sensor.solar_irradiance`](../lib/sensor/solar_irradiance.md) + +The amount of solar power received per unit area. + diff --git a/generate_docs.sh b/generate_docs.sh new file mode 100755 index 0000000..3d84811 --- /dev/null +++ b/generate_docs.sh @@ -0,0 +1,302 @@ +#!/usr/bin/env bash +# Generate Markdown documentation for all profiles. +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")" && pwd)" +DOCS_DIR="$ROOT/docs" + +yqr() { + yq e "$1" "$2" | sed 's/^null$//' +} + +# Convert lib.energy.battery.soc -> lib/energy/battery/soc.yml +dotpath_to_file() { + local dotpath="$1" + local rel="${dotpath#lib.}" + echo "$ROOT/lib/${rel//\./\/}.yml" +} + +# Convert lib.energy.battery.soc -> docs/lib/energy/battery/soc.md +dotpath_to_doc() { + local dotpath="$1" + local rel="${dotpath#lib.}" + echo "$DOCS_DIR/lib/${rel//\./\/}.md" +} + +# Compute relative path from $1 (doc file) to $2 (target file) +relpath() { + python3 -c "import os,sys; print(os.path.relpath(sys.argv[2], os.path.dirname(sys.argv[1])))" "$1" "$2" +} + +# Normalize multiline YAML strings to single line +normalize() { + echo "$1" | tr '\n' ' ' | sed 's/ */ /g; s/^ *//; s/ *$//' +} + +render_enum() { + local lib_file="$1" field_key="$2" section="$3" + echo "" + echo "**Values:**" + echo "" + echo "| Value | Name | Description |" + echo "|-------|------|-------------|" + + local keys + keys="$(yqr ".${section}.${field_key}.enum | keys | .[]" "$lib_file")" + for val in $keys; do + local name desc + name="$(yqr ".${section}.${field_key}.enum.${val}.display_name" "$lib_file")" + desc="$(yqr ".${section}.${field_key}.enum.${val}.description" "$lib_file")" + desc="$(normalize "$desc")" + [[ -z "$name" ]] && name="$val" + echo "| \`${val}\` | ${name} | ${desc} |" + done +} + +render_field() { + local field_key="$1" section="$2" lib_file="$3" lib_dotpath="$4" doc_path="$5" + local lib_doc rel + lib_doc="$(dotpath_to_doc "$lib_dotpath")" + rel="$(relpath "$doc_path" "$lib_doc")" + + local display_name type unit desc has_enum + display_name="$(yqr ".${section}.${field_key}.display_name" "$lib_file")" + type="$(yqr ".${section}.${field_key}.type" "$lib_file")" + unit="$(yqr ".${section}.${field_key}.unit" "$lib_file")" + desc="$(yqr ".${section}.${field_key}.description" "$lib_file")" + desc="$(normalize "$desc")" + has_enum="$(yqr ".${section}.${field_key} | has(\"enum\")" "$lib_file")" + + echo "### \`${field_key}\`" + echo "" + echo "- **Display name:** ${display_name}" + echo "- **Type:** \`${type}\`" + if [[ -n "$unit" ]]; then + echo "- **Unit:** ${unit}" + fi + echo "- **Inherited from:** [\`${lib_dotpath}\`](${rel})" + + if [[ -n "$desc" ]]; then + echo "" + echo "$desc" + fi + + if [[ "$has_enum" == "true" ]]; then + render_enum "$lib_file" "$field_key" "$section" + fi + + echo "" +} + +generate_doc() { + local profile_path="$1" + local rel_profile="${profile_path#$ROOT/}" + local doc_path="$DOCS_DIR/${rel_profile%.yml}.md" + + mkdir -p "$(dirname "$doc_path")" + + local display_name desc + display_name="$(yqr '.display_name' "$profile_path")" + desc="$(yqr '.description' "$profile_path")" + desc="$(normalize "$desc")" + + { + echo "# ${display_name}" + echo "" + if [[ -n "$desc" ]]; then + echo "$desc" + echo "" + fi + + local has_properties=false has_telemetry=false + local implements + implements="$(yqr '.implements[]' "$profile_path" 2>/dev/null || true)" + + # First pass: check what sections exist + for lib_dotpath in $implements; do + local lib_file + lib_file="$(dotpath_to_file "$lib_dotpath")" + if [[ ! -f "$lib_file" ]]; then + echo "WARNING: $lib_file not found" >&2 + continue + fi + local prop_keys tel_keys + prop_keys="$(yqr '.properties | keys | .[]' "$lib_file" 2>/dev/null || true)" + tel_keys="$(yqr '.telemetry | keys | .[]' "$lib_file" 2>/dev/null || true)" + if [[ -n "$prop_keys" ]]; then has_properties=true; fi + if [[ -n "$tel_keys" ]]; then has_telemetry=true; fi + done + + if [[ "$has_properties" == "true" ]]; then + echo "## Properties" + echo "" + for lib_dotpath in $implements; do + local lib_file + lib_file="$(dotpath_to_file "$lib_dotpath")" + [[ -f "$lib_file" ]] || continue + local keys + keys="$(yqr '.properties | keys | .[]' "$lib_file" 2>/dev/null || true)" + for key in $keys; do + render_field "$key" "properties" "$lib_file" "$lib_dotpath" "$doc_path" + done + done + fi + + if [[ "$has_telemetry" == "true" ]]; then + echo "## Telemetry" + echo "" + for lib_dotpath in $implements; do + local lib_file + lib_file="$(dotpath_to_file "$lib_dotpath")" + [[ -f "$lib_file" ]] || continue + local keys + keys="$(yqr '.telemetry | keys | .[]' "$lib_file" 2>/dev/null || true)" + for key in $keys; do + render_field "$key" "telemetry" "$lib_file" "$lib_dotpath" "$doc_path" + done + done + fi + } > "$doc_path" + + echo " ${doc_path#$ROOT/}" +} + +generate_lib_doc() { + local lib_path="$1" + local rel_lib="${lib_path#$ROOT/}" + local doc_path="$DOCS_DIR/${rel_lib%.yml}.md" + + mkdir -p "$(dirname "$doc_path")" + + local display_name desc + display_name="$(yqr '.display_name' "$lib_path")" + desc="$(yqr '.description' "$lib_path")" + desc="$(normalize "$desc")" + + { + echo "# ${display_name}" + echo "" + if [[ -n "$desc" ]]; then + echo "$desc" + echo "" + fi + + local prop_keys tel_keys + prop_keys="$(yqr '.properties | keys | .[]' "$lib_path" 2>/dev/null || true)" + tel_keys="$(yqr '.telemetry | keys | .[]' "$lib_path" 2>/dev/null || true)" + + if [[ -n "$prop_keys" ]]; then + echo "## Properties" + echo "" + for key in $prop_keys; do + local f_display_name f_type f_unit f_desc f_has_enum + f_display_name="$(yqr ".properties.${key}.display_name" "$lib_path")" + f_type="$(yqr ".properties.${key}.type" "$lib_path")" + f_unit="$(yqr ".properties.${key}.unit" "$lib_path")" + f_desc="$(yqr ".properties.${key}.description" "$lib_path")" + f_desc="$(normalize "$f_desc")" + f_has_enum="$(yqr ".properties.${key} | has(\"enum\")" "$lib_path")" + + echo "### \`${key}\`" + echo "" + echo "- **Display name:** ${f_display_name}" + echo "- **Type:** \`${f_type}\`" + if [[ -n "$f_unit" ]]; then + echo "- **Unit:** ${f_unit}" + fi + if [[ -n "$f_desc" ]]; then + echo "" + echo "$f_desc" + fi + if [[ "$f_has_enum" == "true" ]]; then + render_enum "$lib_path" "$key" "properties" + fi + echo "" + done + fi + + if [[ -n "$tel_keys" ]]; then + echo "## Telemetry" + echo "" + for key in $tel_keys; do + local f_display_name f_type f_unit f_desc f_has_enum + f_display_name="$(yqr ".telemetry.${key}.display_name" "$lib_path")" + f_type="$(yqr ".telemetry.${key}.type" "$lib_path")" + f_unit="$(yqr ".telemetry.${key}.unit" "$lib_path")" + f_desc="$(yqr ".telemetry.${key}.description" "$lib_path")" + f_desc="$(normalize "$f_desc")" + f_has_enum="$(yqr ".telemetry.${key} | has(\"enum\")" "$lib_path")" + + echo "### \`${key}\`" + echo "" + echo "- **Display name:** ${f_display_name}" + echo "- **Type:** \`${f_type}\`" + if [[ -n "$f_unit" ]]; then + echo "- **Unit:** ${f_unit}" + fi + if [[ -n "$f_desc" ]]; then + echo "" + echo "$f_desc" + fi + if [[ "$f_has_enum" == "true" ]]; then + render_enum "$lib_path" "$key" "telemetry" + fi + echo "" + done + fi + } > "$doc_path" + + echo " ${doc_path#$ROOT/}" +} + +generate_index() { + local index_path="$DOCS_DIR/index.md" + { + echo "# Profiles" + echo "" + + for category in energy sensor; do + echo "## ${category^}" + echo "" + find "$ROOT/$category" -name '*.yml' -print0 | sort -z | while IFS= read -r -d '' profile_path; do + local display_name rel dotpath + display_name="$(yqr '.display_name' "$profile_path")" + rel="${category}/${profile_path#$ROOT/$category/}" + rel="${rel%.yml}.md" + dotpath="${rel%.md}" + dotpath="${dotpath//\//.}" + echo "- [${display_name}](${rel}) — \`${dotpath}\`" + done + echo "" + done + + echo "## Lib" + echo "" + find "$ROOT/lib" -name '*.yml' -print0 | sort -z | while IFS= read -r -d '' lib_path; do + local display_name rel dotpath + display_name="$(yqr '.display_name' "$lib_path")" + rel="lib/${lib_path#$ROOT/lib/}" + rel="${rel%.yml}.md" + dotpath="lib.${rel#lib/}" + dotpath="${dotpath%.md}" + dotpath="${dotpath//\//.}" + echo "- [${display_name}](${rel}) — \`${dotpath}\`" + done + echo "" + } > "$index_path" + + echo " ${index_path#$ROOT/}" +} + +# Clean and regenerate +rm -rf "$DOCS_DIR" + +for lib_path in $(find "$ROOT/lib" -name '*.yml' | sort); do + generate_lib_doc "$lib_path" +done + +for profile_path in $(find "$ROOT/energy" "$ROOT/sensor" -name '*.yml' | sort); do + generate_doc "$profile_path" +done + +generate_index