MagicMirror² Module: MMM-Homematic-Thermostats

A MagicMirror Module for your radio controlled Homematic (eQ-3) radiator thermostats of type: HM-CC-RT-DN and wall thermostats of type HM-TC-IT-WM-W-EU
According documentation, it should also work with devices of type HM-CC-RT-DN-BoM.

from @spitzlberger extended by wall thermostats, style "table", humidity display, warnings, forming of numbers, ... (2019-02-16)

The module displays the following information:

The name of the heater The current temperature The target temperature The current humidity (only wall thermostat) The current mode The fault reporting (i.e. low battery), if any Supported languages are: English, Deutsch

Picture: © MAF1981, private

Picture: © spitzlbergerj, GPL-3.0

Screenshots

Default screen:	Default screen with a fault message:
Example: Heater in Kid's room is in manually mode:	Example: Heater in Kid's room is in holiday mode (party mode in terms of HomeMatic):
Screen showing all information: showSetTemperature: true showCurrentMode: true showFaultReporting: true	Minimalistic screen: showSetTemperature: false showCurrentMode: false showFaultReporting: false
If you prefer it more colorful, just change the stylesheet...
In German language:
And finally the style "Table" with warnings for temperature and humidity above and below the threshold:

Pre-requisites

The following dependencies are required and must be installed to be able to use this module:

• MagigMirror²
  Obviously yes... without the mirror even this module is useless :-)
  Requires at least MM version: 2.1.0
• XML-API addon
  The XML-API addon must be installed on your Homematic central control unit (CCU1 / CCU2).
• xmldom
  The xmldom DOMParser and XMLSerializer must be installed for node.js
• iconv-lite
  The iconv-lite is required to deal with the correct character encoding iso-8859-1 (i.e.: German umlauts ä ü ö) after receiving data via the XML-API.
• moment.js
  The moment.js library is required to parse the dates coming via XML-API (i.e. to display the end date if a device is in vacation mode). Because moment.js is even used by MagicMirror's default modules, you should already have it installed.
• WiFi/Network - Your CCU2 and your Raspberry Pi has to be connected to your local network. The module communicates with the CCU2 by using HTTP GET-request to retrieve the information. Therfore, each device has to be known by the CCU2 as well.

Installation

In your terminal, go to your MagicMirror's Module folder:

cd ~/MagicMirror/modules

Clone this repository:

git clone https://github.com/spitzlbergerj/MMM-Homematic-Thermostats
cd MMM-Homematic-Thermostats
npm install xmldom

Configure the module in your config.js file as followed.

Using the module

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

modules: [
{
	module: 'MMM-Homematic-Thermostats',
	header: 'Myhome: Thermostats',
	position: 'top_left', // This can be any of the regions.
	config: {
		ccu2IP: '127.0.0.1',
		xmlapiURL: 'config/xmlapi',
		updateInterval: 120000,
		style: "table",
		setTempInBrackets: false,
		localeStr: 'de-DE',
		warnColor: 'blue',
		devices: [
			{
				id: '1112',
				label: 'Living Room',
				showSetTemperature: false,
				showCurrentMode: true,
				showFaultReporting: true,
				showHumidity: true,
				precisionTemp: 1,
				precisionHum: 0,
				warnTempHigh: true,
				warnTempLow: true,
				warnHumHigh: true,
				warnHumLow: true,
				tempThresholdLow: 23,
				tempThresholdHigh: 24,
				humThresholdLow: 34,
				humThresholdHigh: 70,
			}
			//Add all other devices you want to show
		],
	}
}
]

Configuration options

The following properties can be configured:

Option	Description
ccu2IP	Optional - The IP address of your HomeMatic central control unit. If not set, the default is: homematic-ccu2
xmlapiURL	Optional - The URL to the XML-API addon on your HomeMatic central control unit. Is appended to ccu2IP. If not set, the default is: config/xmlapi
updateInterval	Optional - The update interval in milliseconds. If not set, the default is: 300000 (5 minutes)
style	Optional - Determines whether the individual thermostats are displayed as separate lines or as rows in a table. Possible values: 'lines' or 'table' Default is 'lines'
setTempInBrackets	Optional - determines whether the set target temperature is to be displayed in brackets. Possible values: true or false Default is true
localeStr	Optional - String for country-specific formatting of numbers. Possible values: see Tags for Identifying Languages Default is 'de-DE'
warnColor	Optional - sets the warning color. This value only applies if a value is out of threshold and a warning option is set. Possible values: 'red', 'green', 'blue', 'yellow', 'white' Default is 'red'
devices	Required - Add all your devices that should appear in the MagicMirror. Each device must include the following properties: Option Description id The unique ise_id to identify the device. All ids can be extracted by calling the following URL of the installed XML-API addon: http://ccu2IP/xmlapiURL/devicelist.cgi label The label for the device (i.e.: Living Room). If not present or empty, the internal device name is shown instead. showSetTemperature Whether to show or to hide the target temperature. Default is false showCurrentMode Whether to show or to hide the current state (i.e.: Heater off). Default is true showFaultReporting Whether to show or to hide any faults of the device (i.e.: Low battery warning). Default is true showHumidity (only available for wall thermostats) Whether to show or to hide the humidity. Default is true precisionTemp Decimal places for temperature values. Default is 2 precisionHum Decimal places for humidity values. Default is 0 warnTempHigh Determines whether a warning is displayed when the temperature threshold tempThresholdHigh is exceeded (or equal) by displaying the value in warnColor. Default is 'false' warnTempLow Determines whether a warning is displayed when the temperature falls below or is equal the threshold tempThresholdLow by displaying the value in warnColor. Default is 'false' warnHumHigh Determines whether a warning is displayed when the humidity threshold humThresholdHigh is exceeded (or equal) by displaying the value in warnColor. Default is 'false' warnHumLow Determines whether a warning is displayed when the humidity falls below or is equal the threshold humThresholdLow by displaying the value in warnColor. Default is 'false' tempThresholdLow Temperature lower threshold. Default is 5 tempThresholdHigh Temperature upper threshold. Default is 24 humThresholdLow Humidity lower threshold. Default is 35 humThresholdHigh Humidity upper threshold. Default is 60

Troubleshooting

Make sure that the XML-API addon is working fine. If you've setup the XML-API addon and your HomeMatic central control unit (CCU2) with default values, you should be able to see a list of all your connected devices by clicking the following URL:
http://homematic-ccu2/config/xmlapi/devicelist.cgi
Is everything fine, it should look like:

Side notes

• The requests via the XML-API addon does not require a login! If your HomeMatic control central unit is accessible without special protection via the Internet, this can be a serious security issue!
• The XML-API does not currently support the following information: Temperature offset, window open detection, descaling, keylock and some more parameter
• What is the percentage in the mode? Example:
  
  It shows the current valve state of the device.

Next steps

I'm planning to implement my HomeMatic window handles with the module to show the window state (open, closed). The window handles are of type HM-Sec-RHS.

Notice

There is a very good Magic Mirror Module MMM-Homematic for displaying individual values (windows open or closed, energy consumption of washing machine, ...) or system variables.

Further information

• homematic.com - HomeMatic website
• homematic-inside.de - Best HomeMatic community (blogs, tipps, addons,...)
• homematic-forum.de - Forum to get help
• HomeMatic script documentation / specification
• XML-API section on homematic-inside.de
• FHEM wiki for HM-CC-RT-DN - All information about the device type (German only)