Home

Awesome

custom_homematic

Homematic(IP) Integration for Home Assistant

Installation

State of the integration

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:

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:

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:

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

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:

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:

Using select, number, switch and text results in the following advantages:

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

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:

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:

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:

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:

  1. In the menu of your CCU's admin panel go to Programs and connections > Programs & CCU connection
  2. Go to New in the footer menu
  3. Click the plus icon below Condition: If... and press the button Device selection
  4. Select one of the device's channels you need (1-2 / 1-6 for WRC2 / WRC6 and 2-3 for SPDR)
  5. Select short or long key press
  6. Repeat Steps 3 - 5 to add all needed channels (the logic AND / OR is irrelevant)
  7. Save the program with the OK button
  8. 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, the Last Modified field should no longer be empty
  9. 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:

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