Home Assistant custom component for retrieving sensor information from Studer-Innotec devices. This component connects directly over the local network using the Studer xcom protocol.
The custom component is comfirmed to be compatible with:
- Xtender XTH 8000-48, XTM 4000-48
- Xcom-CAN (BSP connection to a third party BMS)
- Xcom-LAN (which actually is a Xcom232i with a Moxy NPort 5110A)
- BMS
- RCC-03
- VarioTrack
It should also be able to detect and handle
- Xtender (any other XTH, XTS and XTM models)
- VarioString
- RCC-02
This custom component provides a more reliable alternative to polling data from the Studer Portal via http as described in Read Studer Parameters via Xcom-LAN and Rest Sensor.
This device depends on having a Studer Xcom-LAN (i.e. an Xcom-232i and a Moxa ethernet gateway) acting as a Xcom client and connecting to this integration. For older systems this will be a separate component, for future systems Studer have indicated that LAN connection will become part of the Xtender range.
The Studer Xcom-LAN is able to simultaneously send data to the Studer online portal as well as sending data to this integration.
This custom integration is available via HACS (Home Assistant Community Store).
- In the HACS page, seach for 'Studer'.
- Click on the found item to display this readme (this page).
- At the bottom of the page press 'Download'
- Restart Home Assistant.
- Follow the UI based Initial Configuration
-
Under the
<config directory>/custom_components/directory create a directory calledstuder_xcom. Copying all files in/custom_components/studer_xcom/folder from this repo into the new<config directory>/custom_components/studer_xcom/directory you just created.This is how your custom_components directory should look like:
custom_components ├── studer_xcom │ ├── translations │ │ └── en.json │ ├── __init__.py │ ├── binary_sensor.py │ ├── button.py │ ├── config_flow.py │ ├── const.py │ ├── coordinator.py │ ├── diagnostics.py │ ├── entity_base.py │ ├── manifest.json │ ├── number.py │ ├── select.py │ ├── sensor.py │ ├── strings.json │ └── switch.py
-
Restart Home Assistant.
-
Follow the UI based Initial Configuration
To start the setup of this custom integration:
- go to Home Assistant's Integration Dashboard
- Press 'Add Integration'
- Search for 'Studer-Innotec'
- Follow the prompts in the configuration steps
The integration will try to detect the url to the Moxa Web Config in the local network. This is a fully automatic step, no user input needed.
Do not run Configuration via a Nabu Casa cloud connection, as that will lead to the process getting stuck at the end of this step (known issue). Running Configuration from within the local network does not have this issue. See section Knowledge base for more information.
The following properties are required to connect to Xcom client on the local network
- AC voltage: choose between 120 Vac or 240 Vac; used to select the correct Xcom params min and max values
- Port: specify the port as set in the Moxa NPort configuration. Default 4001
If the discovery of Studer devices in step 3 fails then the configuration returns to the screen of step 2. In that case, check the configuration of the Xcom-LAN device as described in document Xcom-LAN config.md
The integration will wait until the Xcom client connects to it. Next, it will try to detect any connected Studer devices. This is a fully automatic step, no user input needed.
After succcessful setup, all dicovered devices from the Studer installation should show up.
On the individual device pages, the hardware related device information is presented. Also displayed here are all default created entities, typically grouped into main entity sensors, controls and diagnostics.
Any entities that you do not need can be manually disabled using the HASS GUI. Or use the steps described under Custom Configuration to add or remove entities.
The initial configuration will add default info and params entities for the detected Studer devices. Via the custom configuraton, other info and param entities can be added or removed for each device.
To configure:
- Go to Home Assistant's Integration Dashboard
- Click to open the 'Studer-Innotec' integration
- Click on 'Configure'
The integration will wait until the Xcom client connects to it. Next, it will try to detect any newly connected Studer devices. This is a fully automatic step, no user input needed.
An overview is shown of (default selected) params and info numbers for each detected device. In this screen, the actions dropdown box allows you to:
- Add a param or info number to a device via a menu structure
- Add param or info numbers to a device by directly entering the numbers
- Remove param or info numbers from a device by entering the numbers
- Set advanced options
Once you are satisfied with the presented info and params numbers, select action 'Done' and press submit to create all entities (sensors, switches, numbers, etc).
A full list of available numbers can be found in the library used by this integration:
Or it can be downloaded from Studer-Innotec:
- Open www.studer-innotec.com in a browser
- Go to Downloads -> Openstuder -> communication protocol xcom 232i
- In the downloaded zip open file 'Technical specification - Xtender serial protocol appendix - 1.6.38.pdf'
Restrict yourself to only those parameters you actually use and try to keep the time needed for fetching Studer Xcom data below 20 seconds. While in debug mode (see below), keep an eye on the log (Settings -> System -> Log -> Load Full Logs ), and search for lines looking like:
2024-08-26 09:57:46.383 DEBUG (MainThread) [custom_components.studer_xcom.coordinator] Finished fetching Studer Xcom data in 1.450 seconds (success: True)
Note: the first data retrieval after a restart will always take longer than subsequent data retrievals.
When the value of a Studer param is changed via this integration (via a Number, Select or Switch entity), these are written via Xcom to the affected device. Changes are stored in the device's RAM memory, not in its flash memory as you can only write to flash a limited number of times over its lifetime.
However, reading back the value from the entity will be from flash. As a result, the change to the entity value is not visible in the RCC or remote console. You can only tell from the behavior of the PV system that the Studer param was indeed changed.
After a restart/reboot of the PV system the system will revert to the value from Flash. So you may want to periodically repeat the write of changed param values via an automation.
IMPORTANT:
Be very carefull in changing params marked as having level Expert, Installer or even Qualified Service Person. If you do not know what the effect of a Studer param change is, then do not change it!
Please set your logging for the this custom component to debug during initial setup phase. If everything works well, you are safe to remove the debug logging.
logger:
default: warn
logs:
custom_components.studer_xcom: debugSpecial thanks to the following people for providing the information this custom integration is based on:
It is recommended to run Configuration on the local network, i.e. from a computer within the same network as where Home Assistant and the Studer devices are connected to.
If for some reasone you do need to run Configuration remotely (via a Nabu Casa cloud connection), then use the following method:
- Connect to the remote Home Assistant
- Install the Firefox addon
- Open a firefox web browser window via the addon and connect to homeassistant.local:8123
- Add and configure the Studer-Innotec integration.
The numbering given to the Xtender (and VarioTrack, VarioString) devices is directly related to the internal address that Studer uses for communication between the RCC and the devices. So XT1 is address 101, to XT9 at address 109. Similar, VT1 is address 301, to VT15 at address 315 and VS1 is address 701 to VS15 on address 715.
This naming is consistent with the naming as used in the Studer Portal on the DataLog and Messages tabs.
When adding a new physical device to an installation, attention should be paid to the position in which the device is added to in the CAN bus chain to the RCC. The devices are numbered, lowest number with the device on the end of the chain and ending with the one closest to the RCC (which may be counter intuitive).
So when inserting a new physical device at the end of the CAN bus chain, that device will get number 1 (XT1, VT1 or VS1) and all existing devices (of the same type) will get their number incremented. Instead, it is usually more logical to insert the device as first from the RCC, linking all existing devices to the new device. That will give the device the next number up and leaves the existing devices with their existing number.
The clock inside the Studer RCC will slowly drift out of sync with actual time. Moreover, it will not automatically switch from and to daylight savings time leading to a one hour offset during half of the year.
Both these issues can easily be resolved by configuring the following automation in Home Assistant; it will correct the time once a day. The chosen trigger time of 3:05am is so that it is after any daylight savings time adjustment.
alias: Studer RCC Sync Time
description: ""
triggers:
- trigger: time_pattern
hours: "3"
minutes: "0"
seconds: "5"
conditions: []
actions:
- action: datetime.set_value
target:
entity_id: datetime.studer_4001_rcc_5002
data:
datetime: "{{ now() }}"
mode: restart
The local Xcom-LAN will do a daily upload of datalogs to the Studer portal servers. This occurs at midnight on the RCC clock and can take up to 45 minutes.
For larger systems the datalog uploads can fail when the Studer integration requests data updates at that same time (observed in a system with 16 Studer devices). In smaller systems no such conflict is observed.
To prevent problems it is better to configure the Studer integration to not send requests to the Xcom-LAN module during the daily datalog uploads. This requires the following three settings:
-
Disable automatic polling for updates of Studer entities.
- Go to Settings -> Integrations -> Studer Innotec
- Press the ⋮ and choose System Options
- Turn OFF 'Enable polling for changes'
-
Add custom polling for updates of Studer entities.
-
Go to Settings -> Automations -> Create Automation
-
Define the new automation according to the following yaml:
alias: Studer update entities description: "" triggers: - trigger: time_pattern seconds: /30 conditions: - condition: time after: "01:00:00" before: "23:59:00" actions: - action: homeassistant.update_entity data: entity_id: - sensor.studer_4001_bsp_7032 mode: singleNote that you only need to set one entity_id and it does not matter which studer entity is chosen. A trigger to update one entity will result in update of all Studer entities. The chosen entity_id above is 'sensor.studer_4001_bsp_7032' (BSP State of Charge). Another logical candidate is 'datetime.studer_4001_rcc_5002' (RCC Datetime).
-
-
Make sure the RCC Datetime is regularly synchronised so that time drift and start or end of Daylight savings will not invalidate the time condition in the automation of step 2. See knowledge base section Synchronise Time.
