Awesome
custom_homematic
Homematic(IP) Integration for Home Assistant
Wiki with additional information Please support the community by adding more valuable information to the wiki.
ISSUES and DISCUSSIONS
Please report issues in hahomamatic repo. New discussions can be started and found in hahomamatic repo. Feature requests can be added as a discussion too. A good practice is to search in issues and discussions before starting a new one.
Homematic(IP) Local (documentation)
The HomeMatic integration provides bi-directional communication with your HomeMatic hub (CCU, Homegear etc.).
It uses an XML-RPC connection to set values on devices and subscribes to receive events the devices and the CCU emit.
You can configure this integration multiple times if you want to integrate multiple HomeMatic hubs into Home Assistant.
If you are using Homegear with paired Intertechno devices, uni-directional communication is possible as well.
Support for CUxD is not possible due to a missing Python library for BinRPC.
Please take the time to read the entire documentation before asking for help. It will answer the most common questions that come up while working with this integration.
Device support
HomeMatic and HomematicIP devices are integrated by automatically detecting the available parameters, for which suitable entities will be added to the corresponding device-object within Home Assistant.
However, for more complex devices (thermostats, some cover-devices and more) we perform a custom mapping to better represent the devices features. This is an internal detail you usually don't have to care about.
It may become relevant though if new hardware becomes available.
In such a case the automatic mode will be active. Therefore f.ex. a new thermostat-model might not include the climate
entity.
In such a case you may report the missing customization in the hahomematic repository.
Please report missing devices after you installed the integration and ensured it is missing or faulty.
Deactivated Entities
A lot of additional entities were initially created deactivated and can be activated, if necessary, in the advanced settings
of the entity.
Requirements
Hardware
This integration can be used with any CCU-compatible HomeMatic hub that exposes the required XML-RPC interface. This includes:
- CCU2/3
- RaspberryMatic
- Debmatic
- Homegear
- Home Assistant OS / Supervised with a suitable add-on + communication device
Due to a bug in previous version of the CCU2 / CCU3, this integration requires at least the following version for usage with homematic IP devices:
- CCU2: 2.53.27
- CCU3: 3.53.26
Firewall and required ports
To allow communication to your HomeMatic hub, a few ports on the hub have to be accessible from your Home Assistant machine. The relevant default ports are:
- BidCosRF (old wireless devices):
2001
/42001
(with enabled TLS) - HomematicIP (wireless and wired):
2010
/42010
(with enabled TLS) - HomeMatic wired (old wired devices):
2000
/42000
(with enabled TLS) - Virtual thermostat groups:
9292
/49292
(with enabled TLS) - JSON-RPC (used to get names and rooms):
80
/443
(with enabled TLS)
Advanced setups might consider this:
This integration starts a local XmLRPC server within HA, which automatically selects a free port or uses the optionally defined callback port.
This means that the CCU must be able to start a new connection to the system running HA and to the port. So check the firewall of the system running HA (host/VM) to allow communication from the CCU. This Traffic (state updates) is always unencrypted.
If running HA on docker it is recommended to use network_mode: host
, or specify callback host/port.
Authentication
This integration always passes credentials to the HomeMatic hub when connecting. For CCU and descendants (RaspberryMatic, debmatic) it is recommended to enable authentication for XmlRPC communication (Settings/Control panel/Security/Authentication). JsonRPC communication ia always authenticated.
The account used for communication is required to have admin privileges on your HomeMatic hub.
It is important to note though, that special characters within your credentials may break the possibility to authenticate.
Allowed characters for a CCU password are: A-Z
, a-z
, 0-9
, and .!$():;#-
.
The CCU WebUI also supports ÄäÖöÜüß
, but these characters are not supported by the XmlRPC servers.
If you are using Homegear and have not set up authentication, please enter dummy-data to complete the configuration flow.
Configuration
Adding Homematic(IP) Local to you Home Assistant instance can be done via the user interface, by using this My button: ADD INTEGRATION
Manual configuration steps
- Browse to your Home Assistant instance.
- In the sidebar click on Configuration
- From the configuration menu select: Integrations
- In the bottom right, click on the Add Integration button.
- From the list, search and select "Homematic(IP) Local".
- Follow the instruction on screen to complete the set up.
Auto-discovery
The integration supports auto-discovery for the CCU and compatible hubs like RaspberryMatic. The Home Assistant User Interface will notify you about the integrationg being available for setup. It will pre-fill the instance-name and IP address of your Homematic hub. If you have already set up the integration manually, you can either click the Ignore button or re-configure your existing instance to let Home Assistant know the existing instance is the one it has detected. After re-configuring your instance a HA restart is required.
Autodiscovery uses the last 10-digits of your rf-module's serial to uniquely identify your CCU, but there are rare cases, where the CCU API and the UPNP-Message contains/returns different values. In these cases, where the auto-discovered instance does not disappear after a HA restart, just click on the Ignore button.
Known cases are in combination with the rf-module HM-MOD-RPI-PCB
.
Configuration Variables
Central
instance_name:
required: true
description:
Name to identify your HomeMatic hub. This has to be unique for each configured hub. Allowed characters are a-z and 0-9.
If you want to connect to the same CCU instance from multiple HA installations this instance_name must be unique on every HA instance.
type: string
host:
required: true
description: Hostname or IP address of your hub.
type: string
username:
required: true
description: Username of the admin-user on your hub.
type: string
password:
required: true
description: Password of the admin-user on your hub.
type: string
tls:
required: true
description:
Enable TLS encryption. This will change the default for json_port from 80 to 443.
TLS must be enabled, if http to https forwarding is enabled in the CCU.
Traffic from CCU to HA (state updates) is always unencrypted.
type: boolean
default: false
verify_tls:
required: true
description: Enable TLS verification.
type: boolean
default: false
callback_host:
required: false
description: Hostname or IP address for callback-connection (only required in special network conditions).
type: string
callback_port:
required: false
description: Port for callback-connection (only required in special network conditions).
type: integer
json_port:
required: false
description: Port used the access the JSON-RPC API.
type: integer
sysvar_scan_enabled:
required: true
description: Enable system variable/program scanning.
type: boolean
default: true
sysvar_scan_interval:
required: true
description:
Interval in seconds between system variable/program scans. The minimum value is 5.
Intervals of less than 15s are not recommended, and put a lot of strain on slow backend systems in particular.
Instead, a higher interval with an on-demand call from the `homematicip_local.fetch_system_variables` service is recommended.
type: integer
default: 30
enable_system_notifications:
required: true
description:
Control if system notification should be displayed. Affects CALLBACK and PINGPONG notifications.
It's not recommended to disable this option, because this would hide problems on your system.
A better option is to solve the communication problems in your environment.
type: integer
default: true
Interface
This page always displays the default values, also when reconfiguring the integration.
hmip_rf_enabled:
required: true
description: Enable HomematicIP (wiredless and wired).
type: boolean
default: true
hmip_rf_port:
required: false
description: Port for HomematicIP (wireless and wired).
type: integer
default: 2010
bidos_rf_enabled:
required: true
description: Enable BidCos (HomeMatic wireless).
type: boolean
default: true
bidos_rf_port:
required: false
description: Port for BidCos (HomeMatic wireless).
type: integer
default: 2001
virtual_devices_enabled:
required: true
description: Enable heating groups.
type: boolean
default: true
virtual_devices_port:
required: false
description: Port for heating groups.
type: integer
default: 9292
virtual_devices_path:
required: false
description: Path for heating groups
type: string
default: /groups
hs485d_enabled:
required: true
description: Enable HomeMatic wired.
type: boolean
default: false
hs485d_port:
required: false
description: Port for HomeMatic wired.
type: integer
default: 2000
JSON-RPC Port
The JSON-RPC Port is used to fetch names and room information from the CCU. The default value is 80
. But if you enable TLS the port 443
will be used. You only have to enter a custom value here if you have set up the JSON-RPC API to be available on a different port.
If you are using Homegear the names are fetched using metadata available via XML-RPC. Hence the JSON-RPC port is irrelevant for Homegear users.
This value is always empty when the integration gets reconfigured.
callback_host and callback_port
These two options are required for special network environments. If for example Home Assistant is running within a Docker container and detects its own IP to be within the Docker network, the CCU won't be able to establish the connection to Home Assistant. In this case you have to specify which address and port the CCU should connect to. This may require forwarding connections on the Docker host machine to the relevant container. These values are always empty when the integration is reconfigured.
System variables
System variables are fetched every 30 seconds from backend (CCU/Homegear) and belong to a device of type CCU. You could also click on service on the integration's overview in HA.
System variables are initially created as deactivated entity.
The types of system variables in the CCU are:
- character string (Zeichenkette)
- list of values (Werteliste)
- number (Zahl)
- logic value (Logikwert)
- alert (Alarm)
System variables have a description that can be added in the CCU's UI.
If you add the marker hahm
to the description extended features for this system variable can be used in HA.
This hahm
marker is used to control the entity creation in HA.
Switching system variables from DEFAULT -> EXTENDED or EXTENDED -> DEFAULT requires a restart of HA or a reload of the integration.
When using Homegear system variables are handled like the DEFAULT.
This is how entities are created from system variables:
- DEFAULT: system variables that do not have the marker
hahm
in description:- character string, list of values, number -->
sensor
entity - alert, logic value -->
binary_sensor
entity
- character string, list of values, number -->
- EXTENDED: system variables that do have the marker
hahm
in description:- list of values -->
select
entity - number -->
number
entity - alarm, logic value —>
switch
entity - character string —>
text
entity
- list of values -->
Using select
, number
, switch
and text
results in the following advantages:
- System variables can be changed directly in the UI without additional logic.
- The general services for
select
,number
,switch
andtext
can be used. - The service
homematicip_local.set_variable_value
can, but no longer has to, be used to write system variables. - Use of device based automations (actions) is possible.
Services
The Homematic(IP) Local integration makes various custom services available.
homematicip_local.clear_cache
Clears the cache for a central unit from Home Assistant. Requires a restart.
homematicip_local.delete_device
Delete a device from Home Assistant.
homematicip_local.disable_away_mode
Disable the away mode for climate
devices. This only works with HomematicIP devices.
homematicip_local.enable_away_mode_by_calendar
Enable the away mode immediately or by start date and time (e.g. 2022-09-01 10:00), and specify the end by date and time (e.g. 2022-10-01 10:00). This only works with HomematicIP devices.
homematicip_local.enable_away_mode_by_duration
Enable the away mode immediately, and specify the end time by setting a duration (in hours). This only works with HomematicIP devices.
homematicip_local.export_device_definition
Exports a device definition (2 files) to
- 'Your home-assistant config directory'/homematicip_local/export_device_descriptions/{device_type}.json
- 'Your home-assistant config directory'/homematicip_local/export_paramset_descriptions/{device_type}.json
Please create a pull request with both files at pydevccu, if the device not exists, to support future development of this component. This data can be used by the developers to add customized entities for new devices.
homematicip_local.fetch_system_variables
Service to fetch system variables on demand from backend independent from default 30s schedule. Using this service too often could have a negative effect on the stability of your backend.
homematicip_local.force_device_availability
Reactivate a device in Home Assistant that has been made unavailable by an UNREACH event from CCU. This service will only override the availability status of a device and all its dependent entities. There is no communication to the backend to enforce a reactivation!
This is not a solution for communication problems with homematic devices. Use this only to reactivate devices with flaky communication to gain control again.
homematicip_local.get_device_value
Get a device parameter via the XML-RPC interface.
homematicip_local.get_paramset
Call to getParamset
on the XML-RPC interface.
Returns a paramset
homematicip_local.put_paramset
Call to putParamset
on the XML-RPC interface.
homematicip_local.set_cover_combined_position
Move a blind to a specific position and tilt position.
homematicip_local.set_device_value
Set a device parameter via the XML-RPC interface. Preferred when using the UI. Works with device selection.
homematicip_local.set_install_mode
Turn on the install mode on the provided Interface to pair new devices.
homematicip_local.set_variable_value
Set the value of a variable on your HomeMatic hub.
Value lists accept the 0-based list position or the value as input.
For booleans the following values can be used:
- 'true', 'on', '1', 1 -> True
- 'false', 'off', '0', 0 -> False
homematicip_local.turn_on_siren
Turn siren on. Siren can be disabled by siren.turn_off. Useful helpers for siren can be found here.
homematicip_local.light_set_on_time
Set on time for a light entity. Must be followed by a light.turn_on
.
Use 0 to reset the on time.
homematicip_local.switch_set_on_time
Set on time for a switch entity. Must be followed by a switch.turn_on
.
Use 0 to reset the on time.
homeassistant.update_entity
Update the value of an entity (only required for edge cases). An entity can be updated at most every 60 seconds.
This service is not needed to update entities in general, because 99,9% of the entities and values are getting updated by this integration automatically. But with this service, you can manually update the value of an entity - if you really need this in special cases, e.g. if the value is not updated or not available, because of design gaps or bugs in the backend or device firmware (e.g. rssi-values of some HM-devices).
Attention: This service gets the value for the entity via a 'getValue' from the backend, so the values are updated afterwards from the backend cache (for battery devices) or directly from the device (for non-battery devices). So even with using this service, the values are still not guaranteed for the battery devices and there is a negative impact on the duty cycle of the backend for non-battery devices.
homeassistant.update_device_firmware_data
Update the firmware data for all devices. For more information see updating the firmware
Events
Events fired by this integration that can be consumed by users.
homematic.keypress
This event type is used when a key is pressed on a device, and can be used with device triggers or event entities in automation, so manual event listening is not necessary.
In this context, the following must also be observed: Events for Homematic(IP) devices
The PRESS*
parameters are evaluated for this event type in the backend.
homematic.device_availability
This event type is used when a device is no longer available or is available again, and can be used with the blueprint Support for persistent notifications for unavailable devices.
The UNREACH
parameter is evaluated for this event type in the backend.
homematic.device_error
This event type is used when a device is in an error state. A sample usage is shown in the blueprint Show device errors.
The ERROR*
parameters are evaluated for this event type in the backend.
Additional information
What is the meaning of XmlRPC-Server received no events
?
This integration does not fetch new updates from the backend, it receives state changes and new values for devices from the backend by the XmlRPC server.
Therefore the integration additionally checks for the CCU, if this mechanism works:
Regardless of regular device updates, HA checks the availability of the CCU with a PING
every 15 seconds, and expects a PONG
event as a response on the XMLRPC server.
This persistent notification is only displayed in HA if the received PONG events and the device updates are missing for 10 minutes, but it also disappears again as soon as events are received again.
So the message means there is a problem in the communication from the backend to HA that was identified by the integration but not caused.
What is the meaning of Ping/Pong Mismatch on Interface
?
Only relevant for CCU.
As mentioned above, we send a PING event every 15s to check the connection and expect a corresponding PONG event from the backend.
If everything is OK the number of send PINGs matches the number of received PONGs.
If we receive less PONGs that means that there is another HA Instance with the same instance name, that has been started after this instance, that receives all events, which also includes value update of devices. Also a communication or CCU problem could be the cause for this.
If we receive more PONGs that means that there is another HA Instance with the same instance name, that has been started before this instance, so this instance also receives events from the other instance.
Solution: Check if there are multiple instances of this integration running with the same instance name, and re-add the integration on one HA instance with a different instance name.
Noteworthy about entity states
The integration fetches the states of all devices on initially startup and on reconnect from the backend (CCU/Homegear). Afterwards, the state updates will be sent by the CCU as events to HA. We don't fetch states, except for system variables, after initial startup.
After a restart of the backend (esp. CCU), the backend has initially no state information about its devices. Some devices are actively polled for updates, but many devices, esp. battery driven devices, cannot be polled, so the backend needs to wait for periodic update send by the device. This could take seconds, minutes and in rare cases hours.
That's why the last state of an entity will be recovered after a HA restart.
If you want to know how assured the displayed value is, there is an attribute value_state
at each entity with the following values:
valid
the value was either loaded from the CCU or received via an eventnot valid
there is no value. The state of the entity isunknown
.restored
the value has been restored from the last saved state after an HA restartuncertain
the value could not be updated from the CCU after restarting the CCU, and no events were received either.
If you want to be sure that the state of the entity is as consistent as possible, you should also check the value_state
attribute for valid
.
Sending state changes to backend
We try to avoid backend calls if value/state doesn't change:
- If an entity (e.g.
switch
) has only one parameter that represents its state, then a call to the backend will be made, if the parameter value sent is not identical to the current state. - If an entity (e.g.
cover
,climate
,light
) has multiple parameters that represent its state, then a call to the backend will be made, if one of these parameter values sent is not identical to its current state. - Not covered by this approach:
- platforms: lock and siren.
- services:
stop_cover
,stop_cover_tilt
,enable_away_mode_*
,disable_away_mode
,set_on_time_value
- system variables
Rename of device/channel in CCU not reflected in Home Assistant
Option 1: Just rename entity_id and name in HA
Option 2: Reload the Integration or restart HA, that will reload the names from CCU . This will show the the new entity name, if not changed manually in HA. The entity_id will not change.
Option 3: Use the service homematicip_local.delete_device. This deletes the device from all caches, and from entity/device_registry. A reload on the integration, or a restart of HA will recreate the device and entities. The new name will be reflected also in the entity_id.
Option 4: Delete and reinstall the Integration. That will recreate all devices and entities with new names (Should only be used on freshly installs systems)
Unignore device parameters
Not all parameters of a HomeMatic or HomematicIP device are created as entity. These parameters are filtered out to provide a better user experience for the majority of the users. If you need more parameters as entities have a look at this description. You use this at your own risk!!!
BUT remember: Some parameters are already created as entities, but are deactivated.
Devices with buttons
Devices with buttons (e.g. HM-Sen-MDIR-WM55 and other remote controls) may not be fully visible in the UI. This is intended, as buttons don't have a persistent state. An example: The HM-Sen-MDIR-WM55 motion detector will expose entities for motion detection and brightness (among other entities), but none for the two internal buttons. To use these buttons within automations, you can select the device as the trigger-type, and then select the specific trigger (Button "1" pressed etc.).
Fixing RSSI values
See this explanation how the RSSI values are fixed.
Changing the default platform for some parameters
HmIP-eTRv* / LEVEL, number to sensor entity
The LEVEL
parameter of the HmIP-eTRV can be written, i.e. this parameter is created as a number entity and the valve can be moved to any position.
However, this manual position is reversed shortly thereafter by the device's internal control logic, causing the valve to return to its original position almost immediately. Since the internal control logic of the device can neither be bypassed nor deactivated, manual control of the valve opening degree is not useful. The LEVEL
parameter is therefore created as a sensor, and thus also supports long-term statistics.
If you need the LEVEL
parameter as number entity, then this can be done by using the unignore feature by adding LEVEL to the file.
Pressing buttons via automation
It is possible to press buttons of devices from Home Assistant. A common usecase is to press a virtual button of your CCU, which on the CCU is configured to perform a specific action. For this you can use the homematicip_local.set_device_value
service. In YAML-mode the service call to press button 3
on a CCU could look like this:
service: homematicip_local.set_device_value
data:
device_id: abcdefg...
parameter: PRESS_SHORT
value: "true"
value_type: boolean
channel: 3
Events for Homematic(IP) devices
To receive button-press events for Homematic(IP) devices like WRC2 / WRC6 (wall switch) or SPDR (passage sensor) or the KRC4 (key ring remote control) or HM-PBI-4-FM (radio button interface) you have to create a program in the CCU:
- In the menu of your CCU's admin panel go to
Programs and connections
>Programs & CCU connection
- Go to
New
in the footer menu - Click the plus icon below
Condition: If...
and press the buttonDevice selection
- Select one of the device's channels you need (1-2 / 1-6 for WRC2 / WRC6 and 2-3 for SPDR)
- Select short or long key press
- Repeat Steps 3 - 5 to add all needed channels (the logic AND / OR is irrelevant)
- Save the program with the
OK
button - Trigger the program by pressing the button as configured in step 5. Your device might indicate success via a green LED or similar. When you select the device in
Status and control
>Devices
on the CCU, theLast Modified
field should no longer be empty - When your channels are working now, you can set the program to "inactive". Don't delete the program!
Hint: To deactivate the event for one channel, remove that channel from the program Hint: With RaspberryMatic no program is needed for buttons. Events can directly activated/deactivated within ->Settings->Devices. Click the "+" of e.g. a remote control then click directly the "button-channel". Press "activate". There is no direct feedback but a service message should appear.
Updating a device firmware
Homematic offers the possibility to update the device firmware. To do this, the firmware file must be uploaded in the CCU. The firmware is then transferred to the devices, which can take several hours or days per device. Update can then be clicked in the CCU and the device will update and reboot.
To simplify this process, this integration offers update entities per device.
Initially, the firmware file must be uploaded via the CCU. A query of available firmware information from eq3 does not take place. All firmware information used is provided by the local CCU.
Since the CCU does not send any events for firmware updates, the current status of firmware updates is requested via regular queries. Since device updates are usually very rare and the transmission takes a long time, the query is only made every 6 hours.
If devices whose firmware is currently being transferred were discovered via the update, their statuses are then queried every hour.
As soon as the firmware has been successfully transferred to the device, it can be updated on the device by clicking on install
. This information can be delayed up to 1 hour in HA.
Depending on whether an update command can be transmitted immediately or with a delay, either the updated firmware version is displayed after a short delay, or in process
/installing
is displayed again because a command transmission is being waited for. This state is now updated every 5 minutes until the installation is finished.
If shorter update cycles are desired, these can be triggered by the service homeassistant.update_device_firmware_data
, but this might have a negative impact on you CCU!
Examples in YAML
Set boolean variable to true:
---
action:
service: homematicip_local.set_variable_value
data:
entity_id: sesnsor.ccu2
name: Variablename
value: "3"
Manually turn on a switch actor:
---
action:
service: homematicip_local.set_device_value
data:
device_id: abcdefg...
channel: 1
parameter: STATE
value: "true"
value_type: boolean
Manually set temperature on thermostat:
---
action:
service: homematicip_local.set_device_value
data:
device_id: abcdefg...
channel: 4
parameter: SET_TEMPERATURE
value: "23.0"
value_type: double
Set the week program of a wall thermostat:
---
action:
service: homematicip_local.put_paramset
data:
device_id: abcdefg...
paramset_key: MASTER
paramset:
WEEK_PROGRAM_POINTER: 1
Set the week program of a wall thermostat with explicit rx_mode
(BidCos-RF only):
---
action:
service: homematicip_local.put_paramset
data:
device_id: abcdefg...
paramset_key: MASTER
rx_mode: WAKEUP
paramset:
WEEK_PROGRAM_POINTER: 1
BidCos-RF devices have an optional parameter for put_paramset which defines the way the configuration data is sent to the device.
rx_mode
BURST
, which is the default value, will wake up every device when submitting the configuration data and hence makes all devices use some battery. It is instant, i.e. the data is sent almost immediately.
rx_mode
WAKEUP
will send the configuration data only after a device submitted updated values to CCU, which usually happens every 3 minutes. It will not wake up every device and thus saves devices battery.
Available Blueprints
The following blueprints can be used to simplify the usage of HomeMatic and HomematicIP device:
- Support for 2-button Remotes: Support for two button remote like HmIP-WRC2.
- Support for 4-button Key Ring Remote Control: Support for two button remote like HmIP-KRCA.
- Support for 6-button Remotes: Support for two button remote like HmIP-WRC6.
- Support for 8-button Remotes: Support for two button remote like HmIP-RC8.
- Support for persistent notifications for unavailable devices: Enable persistent notifications about unavailable devices.
- Reactivate device by type. Reactivate unavailable devices by device type.
- Reactivate every device. Reactivate all unavailable devices. NOT recommended. Usage of
by device type
orsingle device
should be preferred. - Reactivate single device Reactivate a single unavailable device.
- Show device errors Show all error eventy emitted by a device. This is an unfiltered blueprint. More filters should be added to the trigger.
Feel free to contribute:
These blueprints on my own system and share them with you, but I don't want to investigate in blueprints for devices, that I don't own! Feel free to copy, improve or enhance these blueprints and adopt them to other devices, and if you like create a PR with a new blueprint.
Just copy these files to "your ha-config_dir"/blueprints/automation