frequenz-floss · tiyash-basu-frequenz · Jun 17, 2025 · Jun 17, 2025
@@ -22,6 +22,7 @@
 
         * The whole package and all proto files, messages, field, enums were renamed to `electrical_components`
         * `ComponentCategoryMetadataVariant` to `ElectricalComponentCategorySpecificInfo`
+        * `ComponentCategory` to `ElectricalComponentCategory`
         * `Component.category_type` to `ElectricalComponent.category_specific_info`
         * `ComponentCategoryMetadataVariant.metadata` to `ElectricalComponentCategorySpecificInfo.kind`
         * `ComponentErrorCode` to `ElectricalComponentDiagnosticCode`
@@ -34,6 +35,7 @@
             + `COMPONENT_CATEGORY_GRID` to `ELECTRICAL_COMPONENT_CATEGORY_GRID_CONNECTION_POINT`
             + `ComponentCategoryMetadataVariant.metadata.grid` to `ElectricalComponentCategorySpecificInfo.kind.grid_connection_point`
         * `InverterType.INVERTER_TYPE_SOLAR` to `InverterType.INVERTER_TYPE_PV` (to align with the more colloquial term "PV inverter")
+        * `ComponentCategory.COMPONENT_CATEGORY_RELAY` to `ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_BREAKER` (to better align with the common terminology used in electrical engineering).
 
     + `microgrid.sensors`:
 
@@ -78,6 +80,8 @@
 
 - The `v1` package has been renamed to `v1alpha7`. The current `v1` package now consists of the contents the same directory from the v0.6.x branch, which is the latest stable version of the API.
 
+- The enum `ComponentCategory` (now `ElectricalComponentCategory`) has been extended with new variants.
+
 ## New Features
 
 Added many new messages and enum values:
@@ -93,6 +97,14 @@ Added many new messages and enum values:
     + `ElectricalComponentDiagnosticCode` (previously `ComponentErrorCode`): New diagnostic codes to cover more cases, especially for inverters
     + `InverterType.INVERTER_TYPE_WIND_TURBINE`: Enum value to represent wind turbine inverters
 
+- `microgrid.ElectricalComponentCategory` (previously `microgrid.ComponentCategory`) has been extended with new enum values:
+    + `ELECTRICAL_COMPONENT_CATEGORY_PLC`
+    + `ELECTRICAL_COMPONENT_CATEGORY_STATIC_TRANSFER_SWITCH`
+    + `ELECTRICAL_COMPONENT_CATEGORY_UNINTERRUPTIBLE_POWER_SUPPLY`
+    + `ELECTRICAL_COMPONENT_CATEGORY_CAPACITOR_BANK`
+    + `ELECTRICAL_COMPONENT_CATEGORY_SMART_LOAD`
+    + `ELECTRICAL_COMPONENT_CATEGORY_WIND_TURBINE`
+
 - `microgrid.sensors`
 
     + Message linking microgrid and sensor IDs

@@ -26,66 +26,160 @@ import "frequenz/api/common/v1alpha7/microgrid/lifetime.proto";
 import "google/protobuf/timestamp.proto";
 
 // Enumerated electrical component categories.
+//
+// This enum lists key microgrid components, most of which are typically capable
+// of being remotely controlled via digital interfaces (e.g., Modbus, MQTT,
+// OPC-UA).
 enum ElectricalComponentCategory {
   // The component category is unspecified. This should not be used.
   ELECTRICAL_COMPONENT_CATEGORY_UNSPECIFIED = 0;
 
   // The point where the local microgrid is connected to the grid.
+  //
+  // Represents the interface between a local microgrid and the public
+  // electricity grid, typically used for metering, protection, and isolation.
+  // This category itself is not remotely controllable, but can be associated
+  // with other devices (inverters, relays, etc.) that can be controlled to
+  // affect the grid connection point.
   ELECTRICAL_COMPONENT_CATEGORY_GRID_CONNECTION_POINT = 1;
 
-  // A meter, for measuring electrical metrics, e.g., current, voltage, etc.
+  // A meter for measuring electrical parameters.
+  //
+  // Measures electrical parameters such as voltage, current, power, energy,
+  // and frequency.
+  // Meters typically cannot be controlled remotely, but they can provide
+  // telemetry data.
+  // Examples: Janitza UMG 604, Janitza B24, ABB B24, etc.
   ELECTRICAL_COMPONENT_CATEGORY_METER = 2;
 
-  // An electricity generator, with batteries or solar energy.
+  // An inverter.
+  //
+  // Converts DC to AC power and vice-versa, enabling integration of batteries,
+  // PV arrays, or other renewables.
+  // Remotely controllable via digital protocols for power setpoints, modes,
+  // and status.
+  // Examples: SMA Sunny Tripower, Kaco Blueplanet, Refu RefuStore88k, etc.
   ELECTRICAL_COMPONENT_CATEGORY_INVERTER = 3;
 
   // A DC-DC converter.
+  //
+  // Converts electrical energy between different DC voltage levels.
+  // Typically remotely controllable for voltage, current, or mode adjustment.
+  // Examples: Victron Orion, Delta Electronics DC-DC converters, TDK Lambda.
   ELECTRICAL_COMPONENT_CATEGORY_CONVERTER = 4;
 
-  // A storage system for electrical energy, used by inverters.
+  // A battery energy storage system.
+  //
+  // Stores electrical energy and can be dispatched for load balancing, backup,
+  // or arbitrage.
+  // Remotely controllable for charging, discharging, and operational mode.
+  // Examples: Tesla Megapack, LG Chem RESU, etc.
   ELECTRICAL_COMPONENT_CATEGORY_BATTERY = 5;
 
-  // A station for charging electrical vehicles.
+  // An EV charger.
+  //
+  // Provides controlled charging for electric vehicles.
+  // Remotely controllable for starting/stopping charging and setting power
+  // limits.
+  // Examples: Alfen NG 9xx, KEBA KeContact P30, Siemens VersiCharge, etc.
   ELECTRICAL_COMPONENT_CATEGORY_EV_CHARGER = 6;
 
-  // A crypto miner.
-  ELECTRICAL_COMPONENT_CATEGORY_CRYPTO_MINER = 7;
+  // A circuit breaker.
+  //
+  // Provides protection and switching by disconnecting circuits as needed.
+  // Remotely controllable for opening/closing and status monitoring.
+  // Examples: Finder Series 62, Phoenix Contact PLC-Interface, Siemens Sirius,
+  // Schneider Electric Zelio, etc.
+  ELECTRICAL_COMPONENT_CATEGORY_BREAKER = 7;
 
-  // An electrolyzer for converting water into hydrogen and oxygen.
-  ELECTRICAL_COMPONENT_CATEGORY_ELECTROLYZER = 8;
+  // A pre-charge module.
+  //
+  // Ramps up DC voltage gradually to protect components during power-up.
+  // Remotely controllable to initiate or manage the pre-charge sequence.
+  // Examples: Precharge modules from Bender, Precharge controllers by Elcon,
+  // custom PLC-controlled circuits.
+  ELECTRICAL_COMPONENT_CATEGORY_PRECHARGER = 8;
 
-  // A heat and power combustion plant (CHP stands for combined heat and power).
+  // A combined heat and power (CHP) plant.
+  //
+  // Generates electricity and useful heat from a single energy source.
+  // Remotely controllable for start/stop commands and setpoint adjustments.
+  // Examples: 2G Agenitor, Viessmann Vitobloc, TEDOM Micro series, Bosch CHP.
   ELECTRICAL_COMPONENT_CATEGORY_CHP = 9;
 
-  // A relay.
-  // Relays generally have two states: open (connected) and closed
-  // (disconnected).
-  // They are generally placed in front of a component, e.g., an inverter, to
-  // control whether the component is connected to the grid or not.
-  ELECTRICAL_COMPONENT_CATEGORY_RELAY = 10;
-
-  // A precharge module.
-  // Precharging involves gradually ramping up the DC voltage to prevent any
-  // potential damage to sensitive electrical components like capacitors.
-  // While many inverters and batteries come equipped with in-built precharging
-  // mechanisms, some may lack this feature. In such cases, we need to use
-  // external precharging modules.
-  ELECTRICAL_COMPONENT_CATEGORY_PRECHARGER = 11;
-
-  // A fuse.
-  // Fuses are used to protect electrical components from overcurrents.
-  ELECTRICAL_COMPONENT_CATEGORY_FUSE = 12;
+  // An electrolyzer.
+  //
+  // Converts electrical energy into hydrogen and oxygen by electrolyzing water.
+  // Remotely controllable for operating mode and production rate.
+  // Examples: Siemens Silyzer, Nel Hydrogen PEM, ITM Power electrolyzers.
+  ELECTRICAL_COMPONENT_CATEGORY_ELECTROLYZER = 10;
 
   // A voltage transformer.
+  //
   // Voltage transformers are used to step up or step down the voltage, keeping
   // the power somewhat constant by increasing or decreasing the current.
   // If voltage is stepped up, current is stepped down, and vice versa.
   // Note that voltage transformers have efficiency losses, so the output power
   // is always less than the input power.
-  ELECTRICAL_COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER = 13;
+  ELECTRICAL_COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER = 11;
 
-  // An HVAC (Heating, Ventilation, and Air Conditioning) system.
-  ELECTRICAL_COMPONENT_CATEGORY_HVAC = 14;
+  // An HVAC system (Heating, Ventilation, and Air Conditioning).
+  //
+  // Manages indoor climate by controlling heating, cooling, and ventilation.
+  // Remotely controllable for setpoint and operational scheduling.
+  // Examples: Siemens Desigo, Trane Voyager, Daikin VRV, Schneider Electric
+  // SmartStruxure.
+  ELECTRICAL_COMPONENT_CATEGORY_HVAC = 12;
+
+  // An industrial controller or PLC (Programmable Logic Controller).
+  //
+  // Automates industrial processes, load shedding, and custom logic.
+  // Remotely controllable for process execution and telemetry via digital
+  // protocols.
+  // Examples: Siemens SIMATIC S7-1200/1500, Beckhoff CX-series IPC, Schneider
+  // M340, Wago PFC 200.
+  ELECTRICAL_COMPONENT_CATEGORY_PLC = 13;
+
+  // A crypto miner.
+  //
+  // Consumes power for blockchain computations and can be remotely curtailed or
+  // powered down.
+  // Examples: Bitmain Antminer, MicroBT WhatsMiner, Canaan AvalonMiner.
+  ELECTRICAL_COMPONENT_CATEGORY_CRYPTO_MINER = 14;
+
+  // A static transfer switch (STS).
+  //
+  // Switches between multiple power sources with minimal transfer time to
+  // maintain continuity.
+  // Remotely controllable for source selection and transfer commands.
+  // Examples: Socomec ATyS, ABB TruONE, Eaton Automatic Transfer Switch, ASCO
+  // Series 7000.
+  ELECTRICAL_COMPONENT_CATEGORY_STATIC_TRANSFER_SWITCH = 15;
+
+  // An uninterruptible power supply (UPS).
+  //
+  // Provides immediate backup power with battery and inverter integration.
+  // Remotely controllable for status, diagnostics, and sometimes operational
+  // commands.
+  // Examples: APC Symmetra PX, Eaton 93PM, Schneider Electric Galaxy, Vertiv
+  // Liebert EXL.
+  ELECTRICAL_COMPONENT_CATEGORY_UNINTERRUPTIBLE_POWER_SUPPLY = 16;
+
+  // A capacitor bank for power factor correction.
+  //
+  // Improves power quality by compensating reactive power.
+  // Remotely controllable for switching capacitors in or out.
+  // Examples: Siemens 3FK, ABB Capacitor Banks, Schneider Electric VarSet,
+  // Eaton PowerXL.
+  ELECTRICAL_COMPONENT_CATEGORY_CAPACITOR_BANK = 17;
+
+  // A wind turbine.
+  //
+  // Converts wind energy into electricity.
+  // Remotely controllable (in most commercial systems) for start/stop, output
+  // regulation, and status.
+  // Examples: Siemens Gamesa SG, Vestas V series, GE Cypress, Nordex Delta.
+  ELECTRICAL_COMPONENT_CATEGORY_WIND_TURBINE = 18;
 }
 
 // Enum to represent the various states that a component can be in.