MagicMirror² Module: MMM-Homematic-Heaters

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

The module displays the following information:

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

Picture: © MAF1981, private

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...
Finally, how it looks like in German language:

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/MAF1981/MMM-Homematic-Heaters

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-Heaters',
    header: 'Myhome: Heaters',
    position: 'top_left', // This can be any of the regions.
    config: {
      devices: [
        {
         id: '1112',
         label: 'Living Room',
         showSetTemperature: false,
         showCurrentMode: true,
         showFaultReporting: true
        }
        //Add all other devices you want to show
      ],
      ccu2IP: '127.0.0.1',
      xmlapiURL: 'config/xmlapi',
      updateInterval: 120000
    }
 }
]

Configuration options

The following properties can be configured:

Option	Description
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
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)

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.

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)