Python API for Homematic. Easy to use.


Take a look at the documenation for implementation and usage details.


If you are looking for released versions.

Git Repository


Snapshot releases are updated on each commit to the repository, but are not officially released versions. So they might not be as stable as released versions.

pmatic - Python API for Homematic

The pmatic module provides access to the Homematic CCU which operates as the central unit in Homematic based home automation setups. You can use pmatic directly on the CCU or another system having Python installed. With pmatic you can write your own Python scripts to communicate with your CCU device.

What to do with pmatic?

Why pmatic?

Before I built this API I tried to create a small script to just check all my window sensors, record the time they are opened and then alarm me to close the window if it was open for too long. No problem I thought. Lesson learned: It is possible. But only while having a huuuuge pain. The scripting language is crapy, the web GUI editor misses basic things like syntax highlighting, undo/redo, auto saving and so on which make programming comfortable. Last but not least the debugging was a pain or not possible at all.

Should be possible to make this a lot easier.

I found several other middlewares and libraries for accessing the CCU2 APIs, but most of them required to be executed in somehow specific environments, were not platform independet or implemented in other crapy programming languages.

I know sure there is still much room for improvement and cleaner APIs, but for the moment I think even this small API wrapper is an improvement.

So how does it work?

pmatic has been implemented in Python. What? Python is not available on the CCU2, do I need to run it remotely on a separate device now? Yes, you can. But it is also possible to use it on the CCU2 by installing a python interpreter with the necessary modules on the device. We'll get back to it later.

So you have the option to run your pmatic scripts remotely and on the CCU2. The code stays the same. This means you can develop your scripts on your workstation, test and debug it using a remote connection to your CCU2.

You can use all the API methods provided by the CCU2. The data is parsed and available as python lists or dicts. You can then process the data in your Python code and use the editor of your choice, use all possible debugging and profiling features you can imagine with Python.

It's so much fun :-).

Even if you write pmatic in Python, you can also execute custom ReGa (Homematic Script) through pmatic and also process the output of these scripts, if you like.


pmatic is currently not expecting any special Python modules. pmatic is supported with Python 2.7, 3.4 and newer. Older versions of Python are not supported.

Potentially pmatic could even be used on Windows systems which have a Python interpreter installed. But I did not test it and I am pretty sure there are some changes needed to make it work. But maybe someone wants to make this work. Should not be too much work.


You can find several usage examples in the examples. I'll try to add more in the near future. Some more examples can be found in the documentation.

Just a short example:


import pmatic
ccu = pmatic.CCU()

for device in ccu.devices.query(device_type="HM-Sec-SC"):
    print("%-20s %6s" % (, device.is_open and "open" or "closed"))

Reporting Bugs, Feature Requests

Please use the issue tracker on the pmatic GitHub page.


Copyright (C) 2016 Lars Michelsen

All outcome of the project is licensed under the terms of the GNU GPL v2. Take a look at the LICENSE file for details.