ha_openems

ha_openems

Home Assistant integration that interfaces Fenecon FEMS and OpenEMS systems.

Overview

• The integration provides full read and write access to Fenecon and OpenEMS systems. Every property which is accessible or configurable via the regular UI is made available equally in the Home Assistant UI.
• Integration of every backend property, even if not accessible via the regular UI.
• Backend system configuration is made fully visible and accessible to the Home Assistant UI:
  • Components are made available as Home Assistant service devices.
  • Channels are made available as entities.
    
• Pre-configured UI cards for Storage, Charging Station and Optimized Charges apps. These cards are equal in the offered functionality as the regular Fenecon/OpenEMS built-in UI components.
• Works with Fenecon and OpenEMS single and multi-edge systems.
• Advanced configuration options to support non-standard connection types.
• FEMS update discovery and installation option
• Access to REST write App (if installed)

Table of contents

• Disclaimer
• Features / Common Use-cases
• Installation
• Configuration

Disclaimer

• This integration is not affiliated with Fenecon. The developers take no responsibility for anything that happens to your equipment due to this integration. I.e:
  • All component updates triggered from the integration are persisted to the system flash storage. Setting up automations which trigger such actions at high frequency, will lead to flash memory degradation, significantly shortening the lifespan of the card and increase the risk of immediate data corruption.
  • Be careful with controlling entities which are not enabled by default and for which you have not understood their impact.
  • By default, only a few pre-configured channels are enabled per component. However, there is no limitation how many channels can be enabled in parallel. Increasing the number too high numbers (100+), might overload the FEMS system, with unknown functional impact.
  • Functionality might break during FEMS & OpenEMS updates, as Fenecon might change APIs with upcoming version.

Features / Common Use-cases:

Energy Dashboard

Use the following entities to configure the Energy Dashboard:

Area	Option	Component	Channel	comment
Electricity Grid	Grid Consumption	_sum	GridBuyActiveEnergy
	Return to Grid	_sum	GridSellActiveEnergy
Solar Panels	Solar production	_sum	ProductionActiveEnergy	combined view
		pvInverter*	ActiveProductionEnergy	individual view
		charger*	ActualEnergy
Home Battery Storage	Battery systems	_sum	EssDcDischargeEnergy	combined view
		_sum	EssDcChargeEnergy
		ess*	DcChargeEnergy	individual view
		ess*	DcDischargeEnergy

Power Flow card plus

Use the following entities to configure the Power Flow card plus:

Area	Option	Component	Channel
Grid	Combined	_sum	GridActivePower
Solar		_sum	ProductionActivePower
Battery	Combined	_sum	EssDischargePower
	State of Charge	_sum	EssSoc
Home		_sum	ConsumptionActivePower

Apps (template UI cards)

To use the template cards, do the following:

1. The template cards depend on the following prerequisites (Please install via the marketplace):
   • Decluttering card
   • Config template card
   • Button card
   • Template entity row -> THIS IS A FORK, NOT THE DEFAULT REPO!!!
2. Navigate to the dashboard in which you want to use the card
3. Select edit mode (pencil on the top right corner)
4. From the 3-dots menu in the top right corner, select “raw editor”
5. Paste the full contents of openems_templates.yaml before the dashboard contents
6. Go back to regular edit mode
7. add a new user-defined card, using yaml.

EV Charging

Sample Card config

type: custom:decluttering-card
template: evcs_template
variables:
  - system: fems12345
  - evcs_id: 0
  - ctrlevcs_id: 0

Card variables

• system: Set to your FEMS/OpenEMS system name
• evcs_id: Set to your EVCS AppID. Eg 0 if your EVCS component is called evcs0. Default value: 0
• ctrlevcs_id: Set to your CtrlEVCS AppID. Eg 1 if your EVCS component is called ctrlEvcs1. Default value: 0

Card screenshot (German version)

Grid Optimized Charge

Sample Card config

type: custom:decluttering-card
template: optchrg_template
variables:
  - system: fems12345
  - ctrlgridoptimizedcharge_id: 0

Card variables

• system: Set to your FEMS/OpenEMS system name
• ctrlgridoptimizedcharge_id: Set to your grid optimized charge AppID. Eg 5 if your optchrg component is called ctrlGridOptimizedCharge5. Default value: 0

Card screenshot (German version)
Note: unapplicable options are automatically hidden and thus not visible in the screenshot

Emergency Capacity Reserve

Sample Card config

type: custom:decluttering-card
template: ess_template
variables:
  - system: fems12345
  - ctrlemergencycapacityreserve_id: 0

Card variables

• system: Set to your FEMS/OpenEMS system name
• ctrlemergencycapacityreserve_id: Set to your emergency capacity AppID. Eg 0 if the component is called ctrlEmergencyCapacityReserve0. Default value: 0

Card screenshot (German version)

Heating Element

Sample Card config

type: custom:decluttering-card
template: heating_template
variables:
  - system: fems12345
  - ctrlioheatingelement_id: 0

Card variables

• system: Set to your FEMS/OpenEMS system name
• ctrlioheatingelement_id: Set to your heating element AppID. Eg 0 if the component is called ctrlioheatingelement0. Default value: 0

Card screenshot (German version)

SG-Ready Heat Pump

Sample Card config

type: custom:decluttering-card
template: heatpump_template
variables:
  - system: fems12345
  - ctrlioheatpump_id: 0

Card variables

• system: Set to your FEMS/OpenEMS system name
• ctrlioheatpump_id: Set to your heat pump AppID. Eg 0 if the component is called ctrlIoHeatPump0. Default value: 0

Card screenshot (German version)

Detailed battery diagnosis dashboard (component: battery*)

The integration is supports calculation of additional information, derived from other sensors, which are not provided by FEMS by default. By that, ΔU calculations for the entire battery system and individual battery modules are provided. A pre-configured dashboard battery_diagnosis_dashboard_fems12345.yaml can be used as a starting point for a personal dashboard configuration:

Before using the default dashboard (by copying the files content and pasting it into the dashboard raw yaml editor), please replace all occurrences of the string “fems12345” with the ID of your personal FEMS or openems system.

Furthermore, the dashboard uses the following entities which are to the majority not enabled by default. Before using the dashboard, please enable the components and entities as described in the Configuration chapter further below in this manual.

The dashboard also makes use of the Mushroom and Button card UI widgets. In order to use these, please install via the marketplace.

Entities to be enabled, used within the default dashboard configuration:

• _sum
  • ConsumptionActiveEnergy, ConsumptionActivePower, ConsumptionActivePowerL1, ConsumptionActivePowerL2, ConsumptionActivePowerL3, EssActiveChargeEnergy, EssActiveDischargeEnergy, EssActivePower, EssActivePowerL1, EssActivePowerL1, EssActivePowerL3, EssDcChargeEnergy, EssDcDischargeEnergy, GridActivePower, GridActivePowerL1, GridActivePowerL2, GridActivePowerL3, GridBuyActiveEnergy, GridSellActiveEnergy, ProductionActiveEnergy, ProductionDcActualPower
• battery0
  • Current, Level1CellUnderVoltage, Level2CellUnderVoltage, LowMinVoltageFault, LowMinVoltageFaultBatteryStopped, LowMinVoltageWarning, MaxCellTemperature, MaxCellVoltage, MinCellTemperature, MinCellVoltage, ModbusCommunicationFailed, RunFailed, Soc, Soh, StatusAlarm, StatusWarning, Tower0Level1CellUnderVoltage, Tower0Level2CellUnderVoltage, Tower0Module0CellVoltageDifference, Tower0Module1CellVoltageDifference, Tower0Module2CellVoltageDifference, Tower0Module3CellVoltageDifference, Tower0PackVoltage, Tower0StatusAlarm, Tower0StatusFault, Tower0StatusWarning, VoltageDifference
• charger0
  • ActualPower
• charger1
  • ActualPower

Additional commonly used components

BatteryInverter*

Contains entities for inverter properties like:

• temperatures of inverter, air, …
  • bmspacktemperature
  • airtemperature
  • radiatortemperature
• The state of health: bmssoh

meter*

Here you find the grids frequency.

REST Write App

Use the service rest_write_sensor to cyclically send REST commands to the backend:

Parameter	Meaning	Default value
entity	The channel to update
value	The new target value
timeout	Duration until when cyclic updates will be sent. Use 0 for sending values until the next service call for the same entity.	0
update cycle	Cycle in which a new request will be sent. This is necessary because by default, FEMS will reset REST value requests after 60 seconds by default. Setting update cycle to 0 will trigger a single REST call only.	30

Note: Values sent via REST write are not reflected by the backend and thus not visible in Home Assistant.

Update multiple component properties at once

Calling e.g. switch.turn_on and select.select_option one after the other sends one updateComponentConfig request per action. Use the action openems.update_component_config with a component device to send several properties of a component in a single request:

action: openems.update_component_config
data:
  device_id: <device id of "fems12345 ctrlEvcs0">
  properties:
    enabledCharging: true
    chargeMode: force_charge

Property names are the component configuration names (e.g. chargeMode) or channel names (e.g. _PropertyChargeMode). Values are given like in the corresponding entities: options of selects in snake_case, numbers scaled like the number entity, times as HH:MM. Number limits are not checked.

In the automation editor, the same is available as device action “Update component configuration”, which offers one field per property of the selected component.

Installation

For installation, select “Fenecon FEMS & OpenEMS” integration directly from the home assistant marketplace.

Configuration

Navigate to Settings -> Devices & Services -> Integrations. Click “Add Integration” and select “Fenecon FEMS & OpenEMS” from the list.

Main configuration dialog

Enter your connection details:

Parameter	Description
Host	The hostname or IP address of your Fenecon or OpenEMS system. E.g. fems12345 or 192.168.1.100
Username	The username to access the system. Use x for local monitoring access. For FEMS online monitoring, your Email address is used as username
Password	For local monitoring of FEMS systems, common values are user (read-only access) or owner (write access)
Connection Type	Choose 1 of the 5 supported connection types: FEMS local monitoring (port 80) OpenEMS local monitoring (port 8082) Direct edge Websocket connection (port 8085). This is the standard connection type and preselected by default Fenecon online monitoring at portal.fenecon.de (hostname option will not be used) Custom Websocket URL (hostname option will not be used)
Custom URL*	Custom Websocket URL, eg: ws://192.168.1.100:8888/websocket

*Options Connection Type and Custom URL are visible only after expanding the More options section.

Advanced options

In order to change advanced options, start the options flow by selecting the Configure option right next to the config entry name:

Afterwards, a menu will show up. Here, select "advanced options. A dialog will appear which allows to change advanced options. The following options are available currently:

Parameter	Description
Ignore decreasing if total increasing	For entities which are reported with state class “Total increasing”, drop values from the backend which are smaller than the current value.
Limit data updates	In order to reduce the amount of recorder data and the overall system load, this option allows to reduce the update frequency of entity values. Value in seconds. Zero means, values are published immediately after being received (typically 1x per second).

Selection of components and channels to be integrated

After setting up the config entry, there is a default list of entities which is enabled. Entities for channels outside of these components are initially not created. Other entities within the created components are disabled by default.

In order to add or remove entities of additional or unwanted components, start the options flow by selecting the Configure option right next to the config entry name:

Afterwards, a menu will show up. Choose the component selection option. A dialog will appear which allows to enable or disable each component in the configured system (screenshot shortened. Depending on your system configuration, there can be 20 to 50 components available in the list):

Select entities that will be active in Home Assistant

Also for enabled components, most of the entities created are disabled by default. In order to adjust the selection, click the entities number of the config entry (“1038 entities” in the screenshot above). This will open the entities dialog. In this dialog, (1) activate multi-select, (2) select the entities you want to enable or disable, then (3) enable / disable the selected items via the 3 dot menu on the top right:

**Only enabled entities will be subscribed in the backed!**

Check the backend for configuration changes, change connection details

In case of changes in the backend, users can check the backend for changes and with that update the config entries list of components and channels. In order to do so, select the 3 dots next to the config entry. From the resulting menu, select Reload

Furthermore, in case the connection details shall be adjusted, you can use the same menu and select Reconfigure. This will bring up the main config dialog and allow you to make all necessary changes.