Interface OpenemsComponent

All Known Subinterfaces:
ActivePowerVoltageCharacteristic, AllAlphabeticallyScheduler, AppManager, AsymmetricEss, AsymmetricMeter, AsymmetricMeterEvcs, Awattar, BackendApi, Balancing, BalancingSchedule, Battery, BatteryBoxC130, BmwBattery, BoschBpts5HybridCore, BpCharger, BpCore, BpEss, BpPvInverter, BridgeModbus, BridgeModbusSerial, BridgeModbusTcp, BridgeOnewire, ChannelSingleThreshold, ClusterVersionC, ComponentManager, ComponentManagerProvider, Controller, Corrently, Cycle, DailyScheduler, DebugLog, DelayedSellToGrid, DigitalInput, DigitalOutput, Edge2Edge, Edge2EdgeEss, EmergencyCapacityReserve, EssCluster, EssCycle, EssDcCharger, EssDcChargerFeneconCommercial40, EssFeneconCommercial40, EssFixActivePower, EssLinearPowerBand, EssSellToGridLimit, Evcs, EvcsCluster, EvcsWebastoNext, FeneconCommercialBattery, FeneconDessCharger, FeneconDessEss, FeneconDessGridMeter, FeneconDessPvMeter, FeneconHomeBattery, FeneconMiniEss, FeneconMiniGridMeter, FeneconMiniPvMeter, FeneconProEss, FixedOrderScheduler, FixStateOfCharge, GenericManagedEss, GenericManagedSymmetricEss, GenericOffGridEss, GoodWe, GoodWeBatteryInverter, GoodWeEmergencyPowerMeter, GoodWeEss, GoodWeEtCharger, GoodWeGridMeter, GridOptimizedCharge, HeatPump, Host, HybridEss, HybridManagedSymmetricBatteryInverter, Hypercharger, InfluxTimedata, KacoBlueplanetGridsave, KebaKeContact, KmtronicRelay4Port, KmtronicRelay8Port, LimitTotalDischargeController, ManagedAsymmetricEss, ManagedEvcs, ManagedSinglePhaseEss, ManagedSymmetricBatteryInverter, ManagedSymmetricEss, ManagedSymmetricPvInverter, MeasuringEvcs, Meta, MetaEss, MeterBControlEM300, MeterBgeTechDrt428M2, MeterCarloGavazziEm300, MeterJanitzaUmg511, MeterJanitzaUmg604, MeterKdk2puct, MeterMicrocareSdm630, MeterPqplusUmd96, MeterPqplusUmd97, MeterZiehlEfr4001Ip, ModbusComponent, ModbusSlave, ModbusTcpApi, ModbusTcpApiReadOnly, ModbusTcpApiReadWrite, MqttApiController, OffGridBatteryInverter, OffGridEss, OffGridSwitch, PersistenceModelPredictor, PhoenixContactMeter, PlexlogDatalogger, PowerComponent, Predictor24Hours, PredictorManager, ReactivePowerVoltageCharacteristic, RefuStore88k, RestApi, RestApiReadOnly, RestApiReadWrite, Rrd4jTimedata, Scheduler, Shelly25, ShellyPlug, SiemensPacMeter, SimilarDayPredictor, SimulatedThermometer, Sinexcel, SinglePhaseEss, SinglePhaseMeter, SingleRackVersionB, SingleRackVersionC, SocEvcs, SocomecMeter, SocomecMeterSinglephase, SocomecMeterThreephase, SolarLog, SoltaroBatteryVersionC, SoltaroCluster, StandbyController, StartStoppable, Sum, SunnyIslandEss, SurplusFeedToGridController, SymmetricBatteryInverter, SymmetricEss, SymmetricMeter, TeslaPowerwall2Core, Thermometer, Tibber, Timedata, TimedataProvider, TimeOfUseTariffDischarge, Vectis, VirtualMeter, Webasto, WeidmuellerUR20
All Known Implementing Classes:
Abl, AbstractCsvDatasource, AbstractEdge2Edge, AbstractEssDcChargerFeneconCommercial40, AbstractFeneconDessCharger, AbstractFixStateOfCharge, AbstractGenericManagedEss, AbstractGoodWe, AbstractGoodWeEtCharger, AbstractKmtronicRelay, AbstractManagedEvcsComponent, AbstractManagedOcppEvcsComponent, AbstractModbusBridge, AbstractModbusTcpApi, AbstractOpenemsComponent, AbstractOpenemsMbusComponent, AbstractOpenemsModbusComponent, AbstractOpenemsSunSpecComponent, AbstractPredictor24Hours, AbstractRestApi, AbstractSocomecMeter, AbstractSunSpecBatteryInverter, AbstractSunSpecMeter, AbstractSunSpecPvInverter, AbstractVirtualAddMeter, AcIsland, ActivePowerVoltageCharacteristicImpl, AdstecStoraxeEssImpl, AllAlphabeticallySchedulerImpl, AppManagerImpl, AsymmetricFixReactivePower, AsymmetricVirtualAdd, AwattarImpl, BackendApiImpl, BalancingImpl, BalancingScheduleImpl, BatteryBoxC130Impl, BatteryDummy, BmwBatteryImpl, BoschBpts5HybridCoreImpl, BoschBpts5HybridEss, BoschBpts5HybridMeter, BoschBpts5HybridPv, BpChargerImpl, BpCoreImpl, BpEssImpl, BpPvInverterImpl, BridgeMbusImpl, BridgeModbusSerialImpl, BridgeModbusTcpImpl, BridgeOnewireImpl, BydContainerWatchdog, ChannelSingleThresholdImpl, ChannelThreshold, ClusterVersionB, ClusterVersionCImpl, ComponentManagerImpl, ControllerChpSoc, ControllerHeatingElementImpl, CorrentlyImpl, CosPhi, CsvDatasourceDirect, CsvDatasourcePredefined, CycleImpl, DailySchedulerImpl, DebugDetailedLog, DebugLogImpl, DelayChargeController, DelayedSellToGridImpl, DezonyImpl, DigitalInputOutput, DummyAsymmetricMeter, DummyBattery, DummyComponentManager, DummyController, DummyCycle, DummyHost, DummyHybridEss, DummyInputOutput, DummyManagedAsymmetricEss, DummyManagedEvcs, DummyManagedSymmetricBatteryInverter, DummyManagedSymmetricEss, DummyManagedSymmetricPvInverter, DummyMetaEss, DummyModbusBridge, DummyOffGridBatteryInverter, DummyOffGridSwitch, DummyPredictor24Hours, DummyPredictorManager, DummySum, DummySymmetricMeter, DummyTimedata, Edge2EdgeEssImpl, EmergencyCapacityReserveImpl, EssAsymmetric, EssClusterImpl, EssCycleImpl, EssDcChargerFeneconCommercial40Pv1Impl, EssDcChargerFeneconCommercial40Pv2Impl, EssFeneconBydContainer, EssFeneconCommercial40Impl, EssFixActivePowerImpl, EssGridcon, EssGridconOnGrid, EssGridconOnOffGrid, EssLinearPowerBandImpl, EssSellToGridLimitImpl, EssSinglePhase, EssSymmetric, EvcsClusterImpl, EvcsControllerImpl, EvcsFixActivePower, EvcsPowerComponent, EvcsWebastoNextImpl, FeneconCommercialBatteryImpl, FeneconDessCharger1, FeneconDessCharger2, FeneconDessEssImpl, FeneconDessGridMeterImpl, FeneconDessPvMeterImpl, FeneconHomeBatteryImpl, FeneconMiniEssImpl, FeneconMiniGridMeterImpl, FeneconMiniPvMeterImpl, FeneconProEssImpl, FeneconProPvMeter, FixDigitalOutput, FixedOrderSchedulerImpl, FixStateOfChargeImpl, FroniusPvInverter, FundamentalFrequency, GenericManagedSymmetricEssImpl, GenericOffGridEssImpl, GoeChargerHomeImpl, GoodWeBatteryInverterImpl, GoodWeEmergencyPowerMeterImpl, GoodWeEssImpl, GoodWeEtCharger1, GoodWeEtCharger2, GoodWeGridMeterImpl, GridconPcsImpl, GridMeter, GridMeter, GridOptimizedChargeImpl, HardyBarthImpl, HeatPumpImpl, HighLoadTimeslot, HostImpl, HyperchargerImpl, IesKeywattSingleCcs, InfluxTimedataImpl, IoAlarm, IoOffGridSwitch, JsonLogicController, KacoBlueplanet, KacoBlueplanetGridsaveImpl, KebaKeContactImpl, KmtronicRelay4PortImpl, KmtronicRelay8PortImpl, KostalPikoCharger, KostalPikoCoreImpl, KostalPikoEss, KostalPikoGridMeter, KostalPvInverter, LimitTotalDischargeControllerImpl, MetaImpl, MeterAbbB23Mbus, MeterArtemesAM2, MeterBControlEM300Impl, MeterBgeTechDrt428M2Impl, MeterCarloGavazziEm300Impl, MeterDiscovergy, MeterGridcon, MeterJanitzaUmg511Impl, MeterJanitzaUmg604Impl, MeterJanitzaUmg96rme, MeterKdk2puctImpl, MeterMicrocareSdm630Impl, MeterPqplusUmd96Impl, MeterPqplusUmd97Impl, MeterSchneiderActi9Smartlink, MeterSmaShm20Impl, MeterWeidmueller525, MeterZiehlEfr4001IpImpl, MinDischargePeriod, ModbusSimulator, ModbusTcpApiReadOnlyImpl, ModbusTcpApiReadWriteImpl, MqttApiControllerImpl, NrcMeter, OcppServerImpl, OneWireThermometer, PeakShaving, PeakShaving, PersistenceModelPredictorImpl, PhaseRectification, PhoenixContactMeterImpl, PlexlogDataloggerImpl, PowerComponentImpl, PredictorManagerImpl, PrepareBatteryExtensionImpl, ProductionMeter, PvInverter, PvInverterCluster, PvInverterFixPowerLimit, PvInverterSellToGridLimit, ReactivePwrVoltChractersticImpl, RefuStore88kImpl, RestApiReadOnlyImpl, RestApiReadWriteImpl, RevPiDigitalIoDevice, Rrd4jTimedataImpl, SetBalancing, Shelly25Impl, ShellyPlugImpl, SiemensPacMeterImpl, SimilarDayPredictorImpl, SimulatedEvcs, SimulatedThermometerImpl, SimulatorApp, SimulatorTimedata, SinexcelImpl, SingleDatasourceDirect, SingleRack, SingleRackVersionBImpl, SingleRackVersionCImpl, SmaPvInverter, SocomecMeterSinglephaseImpl, SocomecMeterThreephaseImpl, SolarEdgeGridMeter, SolarEdgePvInverter, SolarLogImpl, StandbyControllerImpl, SumImpl, SunnyIslandEssImpl, SurplusFeedToGridControllerImpl, SymmetricFixReactivePower, SymmetricLimitActivePower, SymmetricRandomPower, SymmetricVirtualAdd, TeslaPowerwall2Battery, TeslaPowerwall2CoreImpl, TibberImpl, TimeOfUseTariffDischargeImpl, TimeslotPeakshaving, VectisImpl, VirtualSubtractMeter, Wago, WebastoImpl, WebsocketApi, WeidmuellerUR20Impl

public interface OpenemsComponent
This is the base interface for and should be implemented by every service component in OpenEMS Edge.

Every OpenEMS service has:

The recommended implementation of an OpenEMS component is via AbstractOpenemsComponent.

  • Method Details

    • id

      String id()
      Returns a unique ID for this OpenEMS component.
      Returns:
      the unique ID
    • alias

      String alias()
      Returns a human-readable name of this Component..
      Returns:
      the human-readable name
    • isEnabled

      boolean isEnabled()
      Returns whether this component is enabled.
      Returns:
      true if the component is enabled
    • servicePid

      default String servicePid()
      Returns the Service PID.
      Returns:
      the OSGi Service PID
    • serviceFactoryPid

      default String serviceFactoryPid()
      Returns the Service Factory-PID.
      Returns:
      the OSGi Service Factory-PID
    • getComponentContext

      org.osgi.service.component.ComponentContext getComponentContext()
      Returns the ComponentContext.
      Returns:
      the OSGi ComponentContext
    • _channel

      @Deprecated Channel<?> _channel(String channelName)
      Deprecated.
      Returns an undefined Channel defined by its ChannelId string representation.

      Note: It is preferred to use the typed channel()-method, that's why it is marked as @Deprecated.

      Parameters:
      channelName - the Channel-ID as a string
      Returns:
      the Channel or null
    • channel

      default <T extends Channel<?>> T channel(String channelName) throws IllegalArgumentException
      Returns a Channel defined by its ChannelId string representation.
      Type Parameters:
      T - the expected typed Channel
      Parameters:
      channelName - the Channel-ID as a string
      Returns:
      the Channel or throw Exception
      Throws:
      IllegalArgumentException - on error
    • channel

      default <T extends Channel<?>> T channel(ChannelId channelId) throws IllegalArgumentException
      Returns a Channel defined by its ChannelId.
      Type Parameters:
      T - the Type of the Channel. See Doc.getType()
      Parameters:
      channelId - the Channel-ID
      Returns:
      the Channel
      Throws:
      IllegalArgumentException - on error
    • channels

      Collection<Channel<?>> channels()
      Returns all Channels.
      Returns:
      a Collection of Channels
    • getModbusSlaveNatureTable

      static ModbusSlaveNatureTable getModbusSlaveNatureTable(AccessMode accessMode)
      Used for Modbus/TCP Api Controller. Provides a Modbus table for the Channels of this Component.
      Parameters:
      accessMode - filters the Modbus-Records that should be shown
      Returns:
      the ModbusSlaveNatureTable
    • getStateChannel

      default StateCollectorChannel getStateChannel()
      Gets the Component State-Channel.
      Returns:
      the StateCollectorChannel
    • getState

      default Level getState()
      Gets the Component State Level.
      Returns:
      the StateCollectorChannel
    • _getChannelAs

      default <T extends Channel<?>> T _getChannelAs(OpenemsComponent.ChannelId channelId, Class<T> type)
      Gets the Channel as the given Type.
      Type Parameters:
      T - the expected Channel type
      Parameters:
      channelId - the Channel-ID
      type - the expected Type
      Returns:
      the Channel
    • debugLog

      default String debugLog()
      Gets some output that is suitable for a continuous Debug log. Returns 'null' by default which causes no output.
      Returns:
      the debug log output
    • hasFaults

      default boolean hasFaults()
      Does this OpenEMS Component report any Faults?

      Evaluates all StateChannels and returns true if any Channel with Level.FAULT is set.

      Returns:
      true if there is a Fault.
    • updateReferenceFilter

      static boolean updateReferenceFilter(org.osgi.service.cm.ConfigurationAdmin cm, String pid, String member, String... ids)
      Sets a target filter for a Declarative Service @Reference member.

      Usage:

       updateReferenceFilter(config.service_pid(), "Controllers", controllersIds);
       

      Generates a 'target' filter on the 'Controllers' member so, that the the expected service to be injected needs to fulfill:

      • the service must be enabled
      • the service must not have the same PID as the calling component
      • the service "id" must be one of the provided "controllersIds"
      Parameters:
      cm - a ConfigurationAdmin instance. Get one using
                     @Reference
                     ConfigurationAdmin cm;
                     
      pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'; if null, PID filter is not added to the resulting target filter
      member - Name of the Method or Field with the Reference annotation
      ids - Component IDs to be filtered for; for empty list, no ids are added to the target filter
      Returns:
      true if the filter was updated. You may use it to abort the activate() method.
    • updateReferenceFilterRaw

      static boolean updateReferenceFilterRaw(org.osgi.service.cm.ConfigurationAdmin cm, String pid, String member, String filter)
      Sets a target filter for a Declarative Service @Reference member.

      Use this method only if you know what you are doing. Usually you will want to use the updateReferenceFilter(ConfigurationAdmin, String, String, String...) method instead.

      Usage:

       updateReferenceFilterRaw(config.service_pid(), "Controllers", "(enabled=true)");
       
      Parameters:
      cm - a ConfigurationAdmin instance. Get one using
                     @Reference
                     ConfigurationAdmin cm;
                     
      pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'; if null, PID filter is not added to the resulting target filter
      member - Name of the Method or Field with the Reference annotation, e.g.
      filter - The filter attribute
      Returns:
      true if the filter was updated. You may use it to abort the activate() method.
    • validateSingleton

      static boolean validateSingleton(org.osgi.service.cm.ConfigurationAdmin cm, String pid, String expectedId)
      Validates and possibly fixes the Component-ID of a Singleton.

      Singleton Components are allowed to live only exactly once in an OpenEMS instance. These Components are marked with an Annotation:

       @Designate(factory = false)
       

      By design it is required for these Singleton Components to have a predefined Component-ID, like '_cycle', '_sum', etc. This method makes sure the Component-ID matches this predefined ID - and if not automatically adjusts it.

      Sidenote: ideally it would be possible to use the Component Annotation

       @Component(property = { "id=_cycle" })
       

      for this purpose. Unfortunately this is not sufficient to have the 'id' property listed in EdgeConfig, ConfigurationAdmin, etc. This is why this workaround is required.

      Usage:

       if (OpenemsComponent.validateSingletonComponentId(this.cm, this.serviceFactoryPid(), SINGLETON_COMPONENT_ID)) {
              return;
       }
       
      Parameters:
      cm - a ConfigurationAdmin instance. Get one using
                         @Reference
                         ConfigurationAdmin cm;
                         
      pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'; if null, Component-ID can not be updated.
      expectedId - The expected predefined Component-ID
      Returns:
      true if the ID was updated. You may use it to abort the activate() method.
    • updateConfigurationProperty

      static void updateConfigurationProperty(org.osgi.service.cm.ConfigurationAdmin cm, String pid, String property, Object value)
      Update a configuration property.

      Usage:

       updateConfigurationProperty(cm, servicePid, "propertyName", "propertyValue");
       

      Parameters:
      cm - a ConfigurationAdmin instance. Get one using
                       @Reference
                       ConfigurationAdmin cm;
                       
      pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'
      property - Name of the configuration property
      value - New configuration value
    • logDebug

      static void logDebug(OpenemsComponent component, org.slf4j.Logger log, String message)
      Log a debug message including the Component ID.
      Parameters:
      component - the OpenemsComponent
      log - the Logger instance
      message - the message
    • logInfo

      static void logInfo(OpenemsComponent component, org.slf4j.Logger log, String message)
      Log a info message including the Component ID.
      Parameters:
      component - the OpenemsComponent
      log - the Logger instance
      message - the message
    • logWarn

      static void logWarn(OpenemsComponent component, org.slf4j.Logger log, String message)
      Log a warn message including the Component ID.
      Parameters:
      component - the OpenemsComponent
      log - the Logger instance
      message - the message
    • logError

      static void logError(OpenemsComponent component, org.slf4j.Logger log, String message)
      Log a error message including the Component ID.
      Parameters:
      component - the OpenemsComponent
      log - the Logger instance
      message - the message