homematic

Indigo plugin for HomeMatic / HomematicIP. It talks to a CCU3 or RaspberryMatic through the CCU-Jack addon and mirrors the whole installation into Indigo: devices, channels, rooms, system variables, programs and vendor info. It creates and populates the Indigo devices itself — you enter an IP number and the devices appear.

• Current version: 2022.15.22 (2026-08-26)
• Author: Karl Wachs
• Requirements: RaspberryMatic / CCU3 with the CCU-Jack addon installed
• Forum / support: http://forums.indigodomo.com/viewforum.php?f=164
• Change log: see Contents/changeLog.txt
• In the plugin: menu → PRINT parameters and help to logfile prints the full help, the device list and the address → Indigo-id mapping

Setup

1. Install the CCU-Jack addon on the CCU.
2. In the plugin config enter the IP number of the CCU. The port (default 2121) sits right next to it; it is the port CCU-Jack listens on and is configured on the CCU in /usr/local/addons/ccu-jack/ccu-jack.cfg — here you only tell the plugin which port to use.
3. If your CCU-Jack has users configured, fill in the LOGIN / TLS section (see below). Older installs without users need nothing.

About ten seconds later the new devices show up in Indigo. Everything else is optional.

Some device types can be configured further: which child devices to create (how many valves, which channels), whether to keep min/max/average and change/trend states, offsets per state, and so on. The plugin menu lets you ignore individual devices or take them back into use.

If a device type is missing you can often map it to an existing one in Contents/Server Plugin/params_user.py — for example a HMIP-BROLL that should behave like the already supported HMIP-FROLL.

How the communication works

                              INDIGO SERVER (Mac)
   +----------------------------------------------------------------------+
   |   Indigo  <-------------->  plugin.py (homematic)                     |
   |   devices, states,           - creates/updates the Indigo devices     |
   |   triggers, actions          - 3 worker threads (see below)           |
   +------------+--------------------------------------+------------------+
                |                                      ^
   REST / VEAP  |  http(s)://<ccu>:2121 (2122 TLS)     |  MQTT push
   read values, |  - complete info every ~2 min        |  every changed datapoint,
   send actions |  - values every x s  (poll mode)     |  topics device|virtdev|sysvar/status/#
                v                                      |  port 1883, or 8883 with TLS
   +----------------------------------------------------+------------------+
   |                        CCU-Jack  (addon on the CCU)                    |
   +------------------------------------+-----------------------------------+
                                        |  XML-RPC events / ReGa
                                        v
   +-----------------------------------------------------------------------+
   |            CCU3 / RaspberryMatic  -  BidCos-RF, HmIP-RF, CUxD          |
   +-----------------------------------------------------------------------+
                                        |
                    HmIP / HomeMatic radio + wired (HmIPW)
                                        v
        thermostats, valves, switches, power plugs, weather station,
        buttons, keypads, water/smoke/motion sensors, access points ...

Three threads do the work:

• getCompleteupdate — reads everything (devices, channels, rooms, sysvars, programs, vendor) every ~2 minutes and creates/updates the Indigo devices. Runs in every mode.
• getDeviceData — the value poller. In poll mode it reads on three schedules (fast datapoints like button presses, medium ones like wind, slow ones like temperature). In MQTT mode it only does the slow safety sweep.
• mqttListener — subscribes to CCU-Jack and feeds pushed values into the same update path. Only in MQTT mode.

Getting values: polling or MQTT push

The VALUE UPDATES section of the plugin config picks one of two ways. Reading the complete info stays on its own schedule in both.

1. POLLING every x secs (default). The plugin asks CCU-Jack for the values; a change is seen at the next poll, and the CCU is asked even when nothing changed.
2. MQTT push, built in client — CCU-Jack pushes every changed datapoint, so Indigo states change as the event happens. Nothing to install: miniMqtt.py is part of the plugin, and it does plain MQTT as well as MQTT over TLS.

The plugin also carries a driver for the external paho-mqtt module (updateMethod = mqttPaho, installable from menu → MQTT: check / install paho-mqtt). It is not offered in the config because it needs an install and buys nothing: running both clients side by side on a live CCU gives identical data — 2660 messages, 2141 distinct datapoints over 162 s, no differences.

In MQTT mode all values are re-read every few minutes anyway (default 5), so a missed message repairs itself. If the broker is unreachable or drops, the normal poll schedule takes over automatically and MQTT is picked up again when it returns. System variables are only pushed by CCU-Jack if their CCU description contains the word MQTT, so they keep being polled on a slow schedule.

MQTT status is visible on the homematic host device: mqttStatus and mqttMessages.

Why MQTT sends so much, and what the plugin drops

The CCU re-sends a device's whole channel-0 block every few seconds with identical values and only a new time stamp. That is not a fault: UNREACH = false arriving again is the device's heartbeat, which is how reachability is determined in the first place. On a normal installation it is roughly 65–70 % of all live MQTT traffic.

The listener drops those repeats before they are queued — IP_ADDRESS, UNREACH, CONFIG_PENDING, BOOTED, DUTY_CYCLE, LOW_BAT, ERROR_CODE, every *_STATUS and *_OVERFLOW datapoint, and any datapoint whose value is boolean false. Three rules hold:

• only a repeat is dropped, never a change — an alarm going on and the alarm clearing both get through, only the quiet repeats after it are dropped;
• buttons, keypads and STATE are never filtered — there a press is signalled by a new time stamp on an unchanged value, so dropping "the same value again" would delete the press;
• the unfiltered full re-read stays as the safety net behind all of it.

The lists live at the top of Contents/Server Plugin/plugin.py (k_mqttDropUnchanged, k_mqttDropUnchangedSuffix, k_mqttNeverDrop) and are meant to be edited.

Login and TLS (newer CCUs)

Older CCU-Jack installs answer everybody — leave the LOGIN / TLS section empty and nothing changes. Newer ones have users configured, and then the plugin has to log in. One login is used for everything, the REST calls and MQTT, because CCU-Jack validates both against the same users in ccu-jack.cfg.

• Use HTTPS for the normal (REST) calls → CCU-Jack's TLS port, default 2122
• MQTT over TLS → the secured MQTT port; ticking it moves the port 1883 → 8883 for you
• Accept the CCU certificate without checking it → leave this ON. The CCU makes its own self-signed certificate, so it cannot be verified against anybody; with verification on, every TLS connection is refused before the login is even tried. Switch it off only if you installed your own certificate on the CCU.

If a login is missing or wrong you get a plain message rather than silence — CCU returned 401 (not authorized) ... this CCU needs a LOGIN for the REST side, connect refused, rc:4/5 ... user xxx was rejected for MQTT.

Optional per-state statistics

Sensor states can carry derived states, each behind its own checkbox in the device edit dialog:

• min/max/average — MinToday / MaxToday with time stamps, MinYesterday / MaxYesterday, AveToday / AveYesterday and the measurement counters.
• change / trend — ChangeMinutes10/20, ChangeHours01/02/06/12/24 and a Trend state, with configurable trend interval and threshold.

AveToday is time-weighted: a reading counts by how long it was valid, not by how often it arrived, so a sensor that reports rapidly for a few minutes does not outweigh a quiet hour.

When a state is actually written

Sensors jitter. Writing every 0.01 degree would fire triggers, fill the SQL log and redraw control pages for a reading that did not really move, so some states are only written when they changed by a minimum amount — temperature 0.1°, humidity 1 %, illumination 3 lux, brightness and RSSI 1. The table is k_stateMinChange / k_stateMinChangePrefix in Contents/Server Plugin/params.py; set a value to 0 (or remove the entry) to write every change.

Two things follow that same limit, because they carry a copy of the same reading and have to show the same number as the state they come from:

• sensorValue only mirrors the state named in the device's displayS property, so it is judged by that state's limit,
• a doubled state (k_doubleState, e.g. humidityInput1 → Humidity) inherits the limit of its source.

Min/max and the change/trend history are fed from the raw incoming reading, not the throttled one, so a short peak shows up in MaxToday even when the display state is held back.

Actions

Switch relays and outputs on/off, set dimmers and colours, set thermostat set-points and boost, write system variables, drive the display of a WRCD, and trigger the ASIR siren (optical and acoustic). Buttons, keypads and alarm devices need a small program on the CCU so their channels get a fresh time stamp — the details are in the plugin's built-in help (menu → PRINT parameters and help to logfile).

Tools

Contents/Server Plugin/mqttMonitor.py is a stand-alone monitor. It runs without Indigo and without the plugin and prints every value CCU-Jack pushes, together with the Indigo link it maps to. It can run both MQTT clients at once and report whether they received the same data.

python3 "<plugin>/Contents/Server Plugin/mqttMonitor.py" 192.168.1.49
python3 "<plugin>/Contents/Server Plugin/mqttMonitor.py" 192.168.1.49 -f 003B5F29ACC45C -s 120 --show-time
python3 "<plugin>/Contents/Server Plugin/mqttMonitor.py" 192.168.1.49 --tls -P 8883 -u user -p pass

-c both (the default) runs the built-in client and paho side by side; a leading R marks a retained value, i.e. the stored state the broker replays right after subscribing.

Debugging

The DEBUG section of the plugin config has one checkbox per area. (8) MQTT: show every value pushed by the CCU writes one line per received message into the Indigo event log, dropped ones included and marked drop:

MQTT received #2363         /device/003AA0C98D9668/0/RSSI_DEVICE   v:-59    ts:15:07:48 s:0
MQTT received #2364    drop /device/003AA0C98D9668/0/DUTY_CYCLE    v:False  ts:15:07:48 s:0

On a large installation that is a lot of lines — switch it off again when you are done.

Note: if you replace the plugin bundle in Indigo's Plugins folder manually or with a sync tool instead of double-clicking the .indigoPlugin, always reload the plugin in Indigo afterwards. Files copied in from another machine may also carry macOS's quarantine flag; if Indigo complains that the plugin cannot be verified, clear it once with sudo xattr -r -d com.apple.quarantine "<Indigo>/Plugins".