Skip to content

Sickboy78/MMM-Homematic

Repository files navigation

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:

screenshot_01

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

screenshot_02

Example of large icon with iconOnly set to true:

screenshot_03

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

screenshot_04

Example of style 'table_rows':

screenshot_05

Example of font awesome icons with style 'table_columns':

screenshot_06

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

screenshot_07

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

screenshot_08

Installation

  1. Navigate into your MagicMirror's modules folder and execute git clone https://github.com/Sickboy78/MMM-Homematic. A new folder will appear.
  2. Go into the new folder cd MMM-Homematic
  3. Execute npm install
  4. 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

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

About

HomeMatic Module for MagicMirror

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published