Protocol Documentation¤
Table of Contents¤
frequenz/api/microgrid/battery.proto¤
Battery¤
Battery/BMS details
| Field | Type | Label | Description |
|---|---|---|---|
| properties | Properties | The component properties | |
| state | State | The battery state. | |
| errors | Error | repeated | A list of errors encountered the component. An empty list implies no error. |
| data | Data | A Battery data object. |
Data¤
Battery data.
| Field | Type | Label | Description |
|---|---|---|---|
| dc | frequenz.api.common.metrics.electrical.DC | DC electricity metrics. | |
| soc | frequenz.api.common.metrics.MetricAggregation | Battery's overall SoC. In percent (%). | |
| temperature | frequenz.api.common.metrics.MetricAggregation | The aggregated values of all the temperature measurements of a battery. In degree Celsius (°C). | |
| humidity | frequenz.api.common.metrics.MetricAggregation | The aggregated values of all the humidity measurements of a battery. In percent (%). |
Error¤
Error message.
| Field | Type | Label | Description |
|---|---|---|---|
| code | ErrorCode | The error code. | |
| level | frequenz.api.microgrid.common.ErrorLevel | The error severity level. | |
| msg | string | The error message. |
Metadata¤
The battery metadata.
| Field | Type | Label | Description |
|---|---|---|---|
| type | frequenz.api.common.components.BatteryType | The battery type. |
Properties¤
Battery properties.
| Field | Type | Label | Description |
|---|---|---|---|
| firmware_ver | string | The firmware version of the battery. | |
| capacity | float | The capacity of the battery. In Watt-hour (Wh). |
State¤
State message.
| Field | Type | Label | Description |
|---|---|---|---|
| component_state | ComponentState | The state of the overall component. | |
| relay_state | RelayState | The state of the DC relays. |
ComponentState¤
| Name | Number | Description |
|---|---|---|
| COMPONENT_STATE_UNSPECIFIED | 0 | Default value. This value is used only when the state information is not available. |
| COMPONENT_STATE_OFF | 1 | The battery is switched off. |
| COMPONENT_STATE_IDLE | 2 | The battery is idle. |
| COMPONENT_STATE_CHARGING | 3 | The battery is consuming electrical energy. |
| COMPONENT_STATE_DISCHARGING | 4 | The battery is generating electrical energy. |
| COMPONENT_STATE_ERROR | 5 | The battery is in a faulty state. |
| COMPONENT_STATE_LOCKED | 6 | The battery is online, but currently unavailable, possibly due to a pre-scheduled maintenance, or waiting for a resource to be loaded. |
| COMPONENT_STATE_SWITCHING_ON | 7 | The battery is starting up and needs some time to become fully operational. |
| COMPONENT_STATE_SWITCHING_OFF | 8 | The battery is switching off and needs some time to fully shut down. |
| COMPONENT_STATE_UNKNOWN | 9 | The state is provided by the device, but it can not be parsed as any of the above (known) states. |
ErrorCode¤
Enumerated Battery/BMS error codes.
| Name | Number | Description |
|---|---|---|
| ERROR_CODE_UNSPECIFIED | 0 | Unspecified. |
| ERROR_CODE_HIGH_CURRENT_CHARGE | 1 | Charge current is too high. |
| ERROR_CODE_HIGH_CURRENT_DISCHARGE | 2 | Discharge current is too high. |
| ERROR_CODE_HIGH_VOLTAGE | 3 | Voltage is too high. |
| ERROR_CODE_LOW_VOLTAGE | 4 | Voltage is too low. |
| ERROR_CODE_HIGH_TEMPERATURE | 5 | Temperature is too high. |
| ERROR_CODE_LOW_TEMPERATURE | 6 | Temperature is too low. |
| ERROR_CODE_HIGH_HUMIDITY | 7 | Humidity is too high. |
| ERROR_CODE_EXCEEDED_SOP_CHARGE | 8 | Charge current has exceeded component bounds. |
| ERROR_CODE_EXCEEDED_SOP_DISCHARGE | 9 | Discharge current has exceeded component bounds. |
| ERROR_CODE_SYSTEM_IMBALANCE | 10 | The battery blocks are not balanced with respect to each other. |
| ERROR_CODE_LOW_SOH | 11 | The State of health is low. |
| ERROR_CODE_BLOCK_ERROR | 12 | One or more battery blocks have failed. |
| ERROR_CODE_CONTROLLER_ERROR | 13 | The battery controller has failed. |
| ERROR_CODE_RELAY_ERROR | 14 | The battery's DC relays have failed. |
| ERROR_CODE_RELAY_CYCLE_LIMIT_REACHED | 15 | The battery's DC relays have been cycled for the maximum number of times mentioned in their lifetime specifications. |
| ERROR_CODE_FUSE_ERROR | 16 | The battery's fuse has failed. |
| ERROR_CODE_EXTERNAL_POWER_SWITCH_ERROR | 17 | The eternal power switch has failed. |
| ERROR_CODE_PRECHARGE_ERROR | 18 | The precharge operation has failed. |
| ERROR_CODE_SYSTEM_PLAUSIBILITY_ERROR | 19 | System plausibility checks have failed. |
| ERROR_CODE_SYSTEM_UNDERVOLTAGE_SHUTDOWN | 20 | System shut down due to extremely low voltage. |
| ERROR_CODE_CALIBRATION_NEEDED | 21 | The battery requires a calibration to reset its measurements. |
RelayState¤
| Name | Number | Description |
|---|---|---|
| RELAY_STATE_UNSPECIFIED | 0 | Default value. |
| RELAY_STATE_OPENED | 1 | The relays are open, and the DC power line to the inverter is disconnected. |
| RELAY_STATE_PRECHARGING | 2 | The relays are closing, and the DC power line to the inverter is being connected. |
| RELAY_STATE_CLOSED | 3 | The relays are closed, and the DC power line to the inverter is connected. |
| RELAY_STATE_ERROR | 4 | The relays are in an error state. |
| RELAY_STATE_LOCKED | 5 | The relays are locked, and should be available to accept commands shortly. |