Skip to content
HomeMatic Module for MagicMirror
JavaScript CSS
Branch: master
Clone or download
Sickboy78 Merge pull request #5 from spitzlbergerj/master
Introduction of the config option numberUnit
Latest commit fc35483 Jul 23, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
icons added icon for car Apr 5, 2019
translations
LICENSE Initial commit Jan 5, 2019
MMM-Homematic.css added icon support Mar 11, 2019
MMM-Homematic.js sysvarNumberUnit -> numberUnit, applicable to sysvar_number AND other Jun 24, 2019
README.md Update README.md Jun 24, 2019
screenshot_01.png added icon support Mar 11, 2019
screenshot_02.png added icon support Mar 11, 2019
screenshot_03.png added icon support Mar 11, 2019

README.md

MMM-Homematic

HomeMatic Module for MagicMirror

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

This module makes use of the XML-API, which must be installed on your HomeMatic CCU to read the sensor values from.

This module supports output of text, icons and text or icons only.

screenshot_01

screenshot_02

screenshot_03

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. 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:

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"
				}
			]
		}
	}
]

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

...
<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
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
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=
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: %
numberUnit 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: " "
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.
Example value:
[{
id: 1234,
name: "front door",
type: window_warn_open,
},{
id: 4711,
name: "humidity laundry room",
type: "hum_warn_high",
threshold: "60"
}]
id 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 The display name of the device/datapoint.
This value is required.
Example values:
"front door"
"temperature living room"
type 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 The precision for displaying a value.
This value is only used for 'other', 'energie' and 'sysvar_number' types.
Example value: 2
threshold 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 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 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 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 Sets an icon for the device or system variable.
This value can either be one of the default icons or an URL to an external icon.
Possible values: "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" - an URL to an external icon
iconSize 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 Sets the position of the icon relative to the text.
This value only applies if an icon is set.
Possible values: "left" - "top" - "right"
Default value: "left"
iconColor 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 Sets the text invisible and shows only the icon.
This value only applies if an icon is set.
Possible values: "true" - "false"
Default value: "false"
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)

Further information

You can’t perform that action at this time.