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
- 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 |
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:
- The template cards depend on the following prerequisites (Please install via the marketplace):
- Navigate to the dashboard in which you want to use the card
- Select edit mode (pencil on the top right corner)
- From the 3-dots menu in the top right corner, select “raw editor”
- Paste the full contents of openems_templates.yaml before the dashboard contents
- Go back to regular edit mode
- 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 nameevcs_id: Set to your EVCS AppID. Eg 0 if your EVCS component is called evcs0. Default value: 0ctrlevcs_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 namectrlgridoptimizedcharge_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 namectrlemergencycapacityreserve_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 namectrlioheatingelement_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 namectrlioheatpump_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
- charger1
Additional commonly used components
BatteryInverter*
Contains entities for inverter properties like:
- temperatures of inverter, air, …
bmspacktemperatureairtemperatureradiatortemperature
- 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 defaultFenecon 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.
评论