MMM-Homematic

HomeMatic Module for MagicMirror

This module is an extension for MagicMirror that shows values from HomeMatic smart home components and system variables.

It makes use of the XML-API, which must be installed as a plugin on your HomeMatic CCU to read the sensor and variables values from.
Important: For XML-API versions 2.0 or higher an authentication token is required and must be set in your module config as 'ccuXmlApiTokenId'. It can be retrieved for example at your CCU addon webui page via Settings -> Control panel -> Additional software -> XML-API -> Set. There you click 'tokenregister.cgi' to create a new token or 'tokenlist.cgi', if you have already created a token. You also need to add this token, if you call devicelist.cgi, sysvarlist.cgi or state.cgi when retrieving the ise_id for your datapoints by adding ?sid=[TOKEN] to your url. For more information about how to create and use the authentication token see XML-API.

The module has a highly flexible and customizable output that supports text and/or icons in lines or in a vertical or horizontal table.

Example of style 'lines' with warn colors:

Example of style 'lines' with default icons and icon colors:

Example of large icon with iconOnly set to true:

Example of large font awesome icon with hideText set to true:

Example of style 'table_rows':

Example of font awesome icons with style 'table_columns':

Example of font awesome icons with style 'table_columns' and hideValue set to true:

Example of font awesome icons with style 'single_line' and showText set to false:

Installation

Navigate into your MagicMirror's modules folder and execute git clone https://github.com/Sickboy78/MMM-Homematic. A new folder will appear.
Go into the new folder cd MMM-Homematic
Execute npm install
Add it to the modules array in the config/config.js (see next steps below)

Using the module

To use this module, add it to the modules array in the config/config.js file:

Lines view:

modules: [
	{
		module: 'MMM-Homematic',
		position: 'top_center',
		header: 'SMART HOME',
		config:	{
			ccuHost: 'ccu3-webui',	// hostname of your ccu (e.g. for CCU3 default is "ccu3-webui")
			tempUnit: "°C",			// unit of your temperatur values
			datapoints: [			// the datapoints of your HomeMatic devices/sensors
				{
					id: "2297",
					name: "window Living Room",
					type: "window_warn_open",
					warnOnly: "true"
				},
				{
					id: "1274",
					name: "humidity Laundry Room",
					type: "hum_warn_high",
					threshold: 60
				},
				{
					id: "1264",
					name: "temperatur Laundry Room",
					type: "temp_warn_low",
					threshold: 10
				},
				{
					id: "11104",
					name: "washing machine",
					type: "mashine_warn_running",
					warnOnly: "false"
				},
				{
					id: "2904",
					name: "wind speed:",
					type: "sysvar_number_warn_high",
					precision: 2,
					threshold: 2,
					numberUnit: "km/h",
					warnColor: "blue",
				},
				{
					id: "12050",
					name: "Who is there? ",
					type: "stringvalue",
					warnOnly: "false"
				},
				{
					id: "12047",
					name: "NAME",
					type: "presence_warn_here",
					warnOnly: "false"
				},
				{
					id: "1831",
					name: "Today",
					type: "sysvar_valuelist_warn_equals",
					reference: "monday",
					warnColor: "red"
				}
			]
		}
	}
]

Table view without the value row:

modules: [
	{
		module: 'MMM-Homematic',
		position: 'top_center',
		header: 'SMART HOME',
		config:	{
			ccuHost: 'ccu3-webui',	// hostname of your ccu (e.g. for CCU3 default is "ccu3-webui")
			tempUnit: "°C",			// unit of your temperatur values
			useShortText: "true",	// use short text output optimized for table style
			style: 'table_columns',
			showValue: 'false',
			datapoints: [			// the datapoints of your HomeMatic devices/sensors
				{
					id: "15387",
					name: "Tesla",
					type: "window_warn_open",
					icon: "http://yourdomain/yourpath/youricon.png",
					iconSize: "small",
					iconColor: "green",
					warnColor: "red",
					warnOnly: "false",
				},

			]
		}
	}
]

HomeMatic is a registered trademark of eQ-3 AG

Extension of this module with system variables, switches and more tested devices by @spitzlbergerj

Howto get your datapoint IDs

Install the XML-API on your HomeMatic CCU. Installation guide can be found here: XML-API
For datapoints from sensors or actors call the list of devices via the XML-API using http://ccu3-webui/addons/xmlapi/devicelist.cgi, replacing 'ccu3-webui' with the hostname or IP address of your CCU. For system variables call http://ccu3-webui/addons/xmlapi/sysvarlist.cgi

Important: For XML-API versions 2.0 or higher an authentication token is required. It can be retrieved for example at your CCU addon webui page via Settings -> Control panel -> Additional software -> XML-API -> Set. There you click 'tokenregister.cgi' to create a new token or 'tokenlist.cgi', if you have already created a token. You must add this token, if you call devicelist.cgi, sysvarlist.cgi or state.cgi. For example: http://ccu3-webui/addons/xmlapi/sysvarlist.cgi?sid=[TOKEN]

Find the ise_id of your device or system variable in the output, which may look like this:

...
<device name="window contact living room" address="001098A98A1C03" ise_id="2086" interface="HmIP-RF" device_type="HmIP-SWDO-I" ready_config="true">
<channel name="window contact living room:0" type="30" address="001098A98A1C03:0" ise_id="2087" direction="UNKNOWN" parent_device="2086" index="0" group_partner="" aes_available="false" transmission_mode="AES" visible="true" ready_config="true" operate="true"/>
<channel name="HmIP-SWDO-I 001098A98A1C03:1" type="37" address="001098A98A1C03:1" ise_id="2115" direction="SENDER" parent_device="2086" index="1" group_partner="" aes_available="false" transmission_mode="AES" visible="true" ready_config="true" operate="true"/>
</device>
...

In this case we are looking for the ise_id of the device "window contact living room", which is "2086". Or for system variables the output may look like this:

...
<systemVariable name="presence.person1" variable="1" value="true" value_list="" ise_id="12047" min="" max="" unit="" type="2" subtype="2" logged="true" visible="true" timestamp="1548509644" value_name_0="abwesend" value_name_1="anwesend"/>
<systemVariable name="presence.string" variable="person1,person2,person3" value="person1,person2,person3" value_list="" ise_id="12050" min="" max="" unit="" type="20" subtype="11" logged="false" visible="true" timestamp="1548509644" value_name_0="" value_name_1=""/>
<systemVariable name="washing mashine" variable="0" value="false" value_list="" ise_id="11104" min="" max="" unit="" type="2" subtype="2" logged="true" visible="true" timestamp="1548444197" value_name_0="not running" value_name_1="running"/>
</systemVariables>
...

In this case we are looking for the ise_id of the system variable "washing mashine", which is "11104".

Next two steps are only necessary for datapoints of sensors or actors. For system variables you can skip them and go directly to the last step.

Call the state of the device via the XML-API using http://ccu3-webui/addons/xmlapi/state.cgi?device_id=1234, replacing 'ccu3-webui' with the hostname or IP address of your CCU and '1234' with the ise_id from the previous step.
Find the ise_id of the desired datapoint of your device in the output.
For window/door contact sensors it is the datapoint of type="STATE", for temperature sensors it is the datapoint with the type="ACTUAL_TEMPERATURE", for humidity sensors its type="HUMIDITY" and for shutter actuators it's type="LEVEL".
The output may look like this:

<state>
<device name="window contact living room" ise_id="2086" unreach="false" config_pending="false">
<channel name="window contact living room:0" ise_id="2087">
...
</channel>
<channel name="HmIP-SWDO-I 001098A991646A:1" ise_id="2296">
<datapoint name="HmIP-RF.001098A991646A:1.STATE" type="STATE" ise_id="2297" value="0" valuetype="16" valueunit="""" timestamp="1546779254"/>
</channel>
</device>
</state>

In this case we are looking for the ise_id of the datapoint of type="STATE" of the device "window contact living room", which is "2297".
Or the output looks like this:

<state>
<device name="climate sensor laundry room" ise_id="1238" unreach="false" config_pending="false">
<channel name="climate sensor laundry room:0" ise_id="1239">
...
</channel>
<channel name="HmIP-STHD 000E98A991C6C7:1" ise_id="1262">
<datapoint name="HmIP-RF.000E98A991C6C7:1.ACTIVE_PROFILE" type="ACTIVE_PROFILE" ise_id="1263" value="1" valuetype="16" valueunit="" timestamp="1546779623"/>
<datapoint name="HmIP-RF.000E98A991C6C7:1.ACTUAL_TEMPERATURE" type="ACTUAL_TEMPERATURE" ise_id="1264" value="16.800000" valuetype="4" valueunit="" timestamp="1546779623"/>
<datapoint name="HmIP-RF.000E98A991C6C7:1.ACTUAL_TEMPERATURE_STATUS" type="ACTUAL_TEMPERATURE_STATUS" ise_id="1265" value="0" valuetype="16" valueunit="" timestamp="1546779623"/>
...
</channel>
</device>
</state>

In this case we are looking for the ise_id of the datapoint of type="ACTUAL_TEMPERATURE" of the device "climate sensor laundry room", which is "1264".

Use the ise_id from the previous step as ID for your datapoint in the module config.

Tested devices

Type	Description	datapoint type
window	HomeMatic IP Window / Door Contact (HmIP-SWDO-I)	type="STATE"
window	HomeMatic Window / Door Contact optical (HM-Sec-SCo)	type="STATE"
temp	HomeMatic IP Temperature and Humidity Sensor with Display (HmIP-STHD)	type="ACTUAL_TEMPERATURE"
temp	HomeMatic radiator thermostat (HM-CC-RT-DN)	type="ACTUAL_TEMPERATURE"
temp	HomeMatic radiator thermostat (HM-CC-RT-DN)	type="SET_TEMPERATURE"
temp	HomeMatic wall thermostat (HM-TC-IT-WM-W-EU)	type="ACTUAL_TEMPERATURE"
temp	HomeMatic wall thermostat (HM-TC-IT-WM-W-EU)	type="SET_TEMPERATURE"
hum	HomeMatic IP Temperature and Humidity Sensor with Display (HmIP-STHD)	type="HUMIDITY"
hum	HomeMatic wall thermostat (HM-TC-IT-WM-W-EU)	type="ACTUAL_HUMIDITY"
shutter	HomeMatic Wireless Shutter Actuator 1-channel, flush-mount (HM-LC-Bl1PBU-FM)	type="LEVEL"
switch	HomeMatic Wireless Switch Actuator 1-channel, flush-mount (HM-LC-Sw1-FM)	type="STATE"
switch	HomeMatic Wireless Switch Actuator 2-channel, flush-mount (HM-LC-Sw2-FM)	type="STATE"
other	Wireless Switch Actuator 1-channel with power metering, plug adapter type F (HM-ES-PMSw1-Pl)	type="ENERGY_COUNTER"
other	Wireless Switch Actuator 1-channel with power metering, plug adapter type F (HM-ES-PMSw1-Pl)	type="POWER"
other	Wireless Switch Actuator 1-channel with power metering, plug adapter type F (HM-ES-PMSw1-Pl)	type="CURRENT"
other	Wireless Switch Actuator 1-channel with power metering, plug adapter type F (HM-ES-PMSw1-Pl)	type="VOLTAGE"
other	Wireless Switch Actuator 1-channel with power metering, plug adapter type F (HM-ES-PMSw1-Pl)	type="FREQUENCY"

Tested System variable types

Type	Description
boolean	Display of the two possible values true or false as e.g. "is ok" or "is not ok". The textual representation of the two values is the same for all logic system variables.
alarm	Display of the two possible values true or false as e.g. "triggered" or "not triggered". The textual representation of the two values is the same for all alarm system variables.
boolean, mashine state	As before, but special logic value for e.g. machines whose status is to be displayed as running or not running.
boolean, presence state	As before, but special logic value presence for e.g. persons who can be here or not here.
string	Displays the character string stored in the system variable.
number	Displays the numeric value of the system variable.
value list	Displays the currently selected value of the value list.

Default icons

Name	Icon
default_icon_mail
default_icon_presence
default_icon_temp
default_icon_hum
default_icon_window
default_icon_door
default_icon_shutter
default_icon_socket_eu
default_icon_socket_us
default_icon_washmachine
default_icon_car

Configuration options

Option	Description
`initialLoadDelay`	The initial delay before loading. If you have multiple modules that use the same API key, you might want to delay one of the requests. (Milliseconds) Possible values: `1000` - `5000` Default value: `0`
`updateInterval`	How often does the content needs to be fetched? (Seconds) Default value: `30` (1/2 minute)
`animationSpeed`	Speed of the update animation. (Milliseconds) Possible values:`0` - `5000` Default value: `1000` (1 seconds)
`ccuProtocol`	The protocol to use for your CCU. Most likely default value is good. Possible values: `http://` - `https://` Default value: `http://`
`ccuHost`	The hostname of your CCU. Depends on your version of CCU. For CCU1 you have to give your CCU a fixed IP address and use it. For CCU2 it is most likely "homematic-ccu2". For CCU3 it is most likely "ccu3-webui" (default). For RaspberryMatic it is the hostname you have set in the network settings of your Raspberry PI. Default value: `ccu3-webui`
`ccuXmlApiUrl`	The URL path of the XML API. Most likely default value is good. But may change with newer versions of XML API, see XML-API. Default value: `/addons/xmlapi`
`ccuXmlApiTokenId`	The Security Token for XML API. Must be set for XML-API version 2.0 or higher. The token can be retrieved by calling the tokenregister.cgi script of the XML-API. For more information see XML-API.
`ccuStateServiceUrl`	The name of the XML API Service for getting states/values from devices/datapoints. Most likely default value is good. But may change with newer versions of XML API, see XML-API. Default value: `/state.cgi`
`ccuSysvarServiceUrl`	The name of the XML API Service for getting values from system variables of type value list. Most likely default value is good. But may change with newer versions of XML API, see XML-API. Default value: `/sysvar.cgi`
`ccuDatapointIdParameter`	The name of the URL Parameter expected by the XML API Service to identify a datapoint of a device. Most likely default value is good. But may change with newer versions of XML API, see XML-API. Default value: `?datapoint_id=`
`ccuIseIdParameter`	The name of the URL Parameter expected by the XML API Service to identify a system variable. Most likely default value is good. But may change with newer versions of XML API, see XML-API. Default value: `?ise_id=`
`style`	The style of output. Possible values: `lines` - `single_line` - `table_rows` - `table_columns` Default value: `lines`
`useShortText`	Toggles between long and short text output. Short text output is optimized for table style. Possible values: `true` - `false` Default value: `false`
`tempUnit`	The unit of temperature. Possible values: `°C` - `°F` - `K` Default value: `°C`
`humUnit`	The unit of humidity. Possible values: `%` - `g/m³` Default value: `%`
`shutterUnit`	The unit of the shutter actuator. Possible values: `%` - `pc` Default value: `%`
`showText`	Toggles whether the text with the names of the devices or variables is displayed. Possible values: `"true"` - `"false"` Default value: `"true"`
`showValue`	Toggles whether the values of the devices or variables is displayed. Possible values: `"true"` - `"false"` Default value: `"true"`
`locale`	String for country-specific formatting of numbers. Possible values: see Tags for Identifying Languages Example values: `de-DE` - `en-US` Default value: `config.language(default:en)`
`datapoints`	An array of datapoint objects. Each datapoint object represents one value/state of a device or sysvar. Each datapoint object needs at least an id, a name and a type, but can have many more options set, as shown below. Example value: `[{ id: 1234, name: "front door", type: window_warn_open, },{ id: 4711, name: "humidity laundry room", type: "hum_warn_high", threshold: "60" }]`
`id (of datapoint)`	The ID of the datapoint to read a value from. This value is required. On howto get your ID see Howto get your datapoint IDs. Example value: `1234`
`name (of datapoint)`	The display name of the device/datapoint. This value is required. Example values: `"front door" "temperature living room"`
`type (of datapoint)`	The type of the device/datapoint. This value is required. Depends on the datapoint/device you want to display. For a list of tested devices see Tested devices. Possible values for devices: `window` - A door or window sensor. (e.g. a HomeMatic IP Window / Door Contact) `window_warn_open` - Same as 'window', but with a warning if open. `window_warn_closed` - Same as 'window', but with a warning if closed. `temp` - A temperature sensor. (e.g. a HomeMatic IP Temperature and Humidity Sensor with Display) `temp_warn_high` - Same as 'temp', but with a warning if value is equal or greater than the threshold. `temp_warn_low` - Same as 'temp', but with a warning if value is equal or less than the threshold. `hum` - A humidity sensor. (e.g. a HomeMatic IP Temperature and Humidity Sensor with Display) `hum_warn_high` - Same as 'hum', but with a warning if value is equal or greater than the threshold. `hum_warn_low` - Same as 'hum', but with a warning if value is equal or less than the threshold. `shutter` - A shutter actuator. (e.g. a HomeMatic Wireless Shutter Actuator) `shutter_warn_high` - Same as 'shutter', but with a warning if value is equal or greater than the threshold. `shutter_warn_low` - Same as 'shutter', but with a warning if value is equal or less than the threshold. `switch` - A switch actuator. (e.g. a HomeMatic Wireless Switch Actuator) `switch_warn_on` - Same as 'switch', but with a warning if switch is on. `switch_warn_off` - Same as 'switch', but with a warning if switch is off. `energie_a` - A switch actuator with power and energie metering - electric current in Ampere `energie_v` - A switch actuator with power and energie metering - electric potential in Volt `energie_p` - A switch actuator with power and energie metering - power in Watt `energie_e` - A switch actuator with power and energie metering - energie in Watt hours `energie_ek` - A switch actuator with power and energie metering - energie in kilo Watt hours `energie_f` - A switch actuator with power and energie metering - frequency in Hertz `energie_x_warn_low` - Same as 'energie_x', but with a warning if value is equal or less than the threshold.. `energie_x_warn_high` - Same as 'energie_x', but with a warning if value is equal or greater than the threshold. `other` - A general sensor with a readable number value. `other_warn_high` - Same as 'other',but with a warning if value is equal or greater than the threshold. `other_warn_low` - Same as 'other',but with warning if value is equal or less than the threshold. Possible values for system variables: `sysvar_boolean` - Display of the two possible values true or false as e.g. "is ok" or "is not ok". The textual representation of the two values is the same for all logic system variables. `sysvar_boolean_warn_true` - Same as 'boolean', but with a warning if true. `sysvar_boolean_warn_false` - Same as 'boolean', but with a warning if false. `sysvar_alarm` - Display of the two possible values true or false as e.g. "triggered" or "not triggered". The textual representation of the two values is the same for all alarm system variables. `sysvar_alarm_warn_triggered` - Same as 'alarm', but with a warning if triggered. `sysvar_alarm_warn_not_triggered` - Same as 'alarm', but with a warning if not triggered. `sysvar_mashine` - As before, but special logic value for e.g. machines whose status is to be displayed as running or not running. `sysvar_mashine_warn_running` - Same as 'mashine', but with a warning if running. `sysvar_mashine_warn_not_running` - Same as 'mashine', but with a warning if not running. `sysvar_presence` - As before, but special logic value presence for e.g. persons who can be here or not here. `sysvar_presence_warn_here` - Same as 'presence', but with a warning if here. `sysvar_presence_warn_away` - Same as 'presence', but with a warning if away. `sysvar_string` - Displays the character string stored in the system variable. `sysvar_string_warn_empty` - Same as 'string', but with a warning if string is empty. `sysvar_string_warn_not_empty` - Same as 'string', but with a warning if string is not empty. `sysvar_number` - Displays the numeric value of the system variable. `sysvar_number_warn_high` - Same as 'number', but with a warning if the value is higher than `threshold`. `sysvar_number_warn_low` - Same as 'number', but with a warning if the value is lower than `threshold`. `sysvar_valuelist` - Displays the current value of the value list system variable. `sysvar_valuelist_warn_equals` - Same as 'sysvar_valuelist', but with a warning if the value equals `reference`. `sysvar_valuelist_warn_not_equals` - Same as 'sysvar_valuelist', but with a warning if the value not equals `reference`.
`precision (of datapoint)`	The precision for displaying a value. This value is only used for 'other', 'energie' and 'sysvar_number' types. Example value: `2` Default value: `0`
`numberUnit (of datapoint)`	The unit of a numeric value. This value is only used for 'other' and 'sysvar_number' types. Possible values: any string value for example `"km/h"` Default value: `" "`
`threshold (of datapoint)`	A threshold value for displaying a warning. This value is required if you have defined a type with a high/low warning. Must be a number without unit. Example value: `60`
`reference (of datapoint)`	A reference value for displaying a warning. This value is required if you have defined a type with a equals/not equals warning. Example value: `"error"`
`warnOnly (of datapoint)`	Toggles whether an output is always shown or only for a warning. This value only applies if type is a kind of warning. Possible values: `"true"` - `"false"` Default value: `"false"`
`warnColor (of datapoint)`	Sets the warning color for this device or system variable. This value only applies if type is a kind of warning. Possible values: `"red"` - `"green"` - `"blue"` - `"yellow"` - `"white"` Default value: `"red"`
`icon (of datapoint)`	Sets an icon for the device or system variable. This value can either be one of the default icons or an icon from font awesome or an URL to an external icon. Possible values for default icons: `"default_icon_mail"` - `"default_icon_presence"` - `"default_icon_temp"` - `"default_icon_hum"` - `"default_icon_window"` - `"default_icon_door"` - `"default_icon_shutter"` - `"default_icon_socket_eu"` - `"default_icon_socket_us"` - `"default_icon_washmachine"` - `"default_icon_car"` Possible values for font awesome icons: all this icons start with "fa-": `"fa-car"` or `fa-door-open` or you use an URL to an external icon
`iconSize (of datapoint)`	Sets the size of the icon. This value only applies if an icon is set. Possible values: `"x-small"` - `"small"` - `"medium"` - `"large"` - `"x-large"` Default value: `"medium"`
`iconPosition (of datapoint)`	Sets the position of the icon relative to the text and value. If no icon is set, this value still determines in which row/column the text and value is shown for table styles. Left and top are synonyms as are right and bottom. Hint:Meaning of top changed from synonym for center to synonym for left with introduction of table styles. Possible values: `"left"` - `"top"` - `"center"` - `"right"` - `"bottom"` Default value: `"left"`
`iconColor (of datapoint)`	Sets the color of the icon. This value only applies when using the default icons or an external icon with transparency. If a warning is triggered, this color gets overwritten with warnColor. Possible values: `"red"` - `"green"` - `"blue"` - `"yellow"` - `"white"` Default value: `"white"`
`iconOnly (of datapoint)`	Sets the text invisible and shows only the icon. This value only applies if an icon is set. This value overwrites the global values showText and showValue for the item it is set on. Possible values: `"true"` - `"false"` Default value: `"false"`

Changelog

1.2.0 (2023-10-26)

(Sickboy78) XML-API 2.x integration

1.1.3 (2023-03-12)

(Sickboy78) added new style single_line

1.1.2 (2023-03-12)

(Sickboy78) fixed sysvar precision threshold bug
(Sickboy78) set default precision to 0

1.1.1 (2023-01-22)

(Sickboy78) fixed https issues, allowed self-signed certificates for XML-API

1.1.0 (2022-01-16)

(Sickboy78) moved XML-API requests to backend, added node_helper.js
(Sickboy78) code refactoring

1.0.0

(Sickboy78) initial version
(spitzlbergerj) added system variables, switches and more devices

Further information

HomeMatic - HomeMatic website
XML-API - XML-API for HomeMatic CCU
Homematic-Scripts - Scripts for your HomeMatic installation by @spitzlbergerj.
MMM-Homematic-Thermostats - A very good Magic Mirror Module for Homematic radiator thermostats.

Sickboy78 / MMM-Homematic