Basic Usage

Please take a look at the scripts below the examples directory for some sample scripts. I’ll try to add more in the near future.

List shutter contact states

Just to give you a quick view, here a simple example how to list all shutter contacts and their current states:

#!/usr/bin/python
import pmatic

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

When I execute this script on my CCU2, I get the following output:

Kind-Fenster         closed
Büro-Fenster         closed
Schlafzimmer-Links   closed
Bad-Fenster-Rechts   closed
Bad-Fenster-Links    closed
Wohnzimmer           closed

The same script can now be executed from another system, e.g. a linux workstation, just by adding the address and credentials to access the CCU.

 #!/usr/bin/python
 import pmatic
 ccu = pmatic.CCU(address="http://192.168.1.26", credentials=("Admin", "EPIC-SECRET-PW"))

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

Please note: I moved the CCU object definition to a separate line for readability.

If you execute the exact same script directly on the CCU you may notice that it works even if you leave the credentials in the script. So your scrips developed on your workstation can be moved to the CCU and executed on it without change.

List devices on low battery

Besides the current states of devices, you can also query for maintenance information like whether or not devices are currently reachable or have a low battery.

#!/usr/bin/python
import pmatic
ccu = pmatic.CCU(address="http://192.168.1.26", credentials=("Admin", "EPIC-SECRET-PW"))

print("Low battery: ")
for device in ccu.devices:
    if device.is_battery_low:
        print("  %s" % device.name)
else:
    print("  All battery powered devices are fine.")

Trigger actions

Or do you want to simulate key presses of your buttons (e.g. HM-PBI-4-FM)?

#!/usr/bin/python
import pmatic
ccu = pmatic.CCU(address="http://192.168.1.26", credentials=("Admin", "EPIC-SECRET-PW"))

for device in ccu.devices.query(device_name=u"Büro-Schalter"):
    if device.button(0).press_short():
        print("done.")
    else:
        print("failed!")

This scripts searches for the device having the name Büro-Schalter which is a HM-PBI-4-FM device. This device has 4 buttons which can be pressed for a short and long time. The script is simulating a short press of button 0 (the first button) and checks whether or not the command succeeded.

Print temperature updates

This example simply prints out all temperatures reported by the devices of type HM-CC-TC, HM-WDS10-TH-O and HM-CC-RT-DN.

This script is executed until terminated by the user (e.g. via CTRL+C). It listens for incoming events and prints a message to the user once the a temperature update is received.

This detection is using the events sent by the CCU. So the state updates are printed nearly instantly.

#!/usr/bin/python
import pmatic
ccu = pmatic.CCU(address="http://192.168.1.26", credentials=("Admin", "EPIC-SECRET-PW"))

devices = ccu.devices.query(device_type=["HM-CC-TC", "HM-WDS10-TH-O", "HM-CC-RT-DN"])

# This function is executed on each state update
def print_summary_state(param):
    print("%s %s" % (param.channel.device.name, param.channel.summary_state))

devices.on_value_updated(print_summary_state)

if not devices:
    print("Found no devices. Terminating.")
else:
    print("Waiting for changes...")

    ccu.events.init()
    ccu.events.wait()
    ccu.events.close()

List Rooms with their devices

You can even get the devices grouped by the rooms which they are associated with. Accessing the rooms is similar to the devices. See an example below which prints out all devices grouped by the rooms.

#!/usr/bin/python
import pmatic
ccu = pmatic.CCU(address="http://192.168.1.26", credentials=("Admin", "EPIC-SECRET-PW"))

for room in ccu.rooms:
    print(room.name)
    for device in room.devices:
        print(" ", device.name)

This script produces an output like this:

Wohnzimmer
  Wohnzimmer-Licht
  Wohnzimmer-Schalter
  Wohnzimmer-Tür
Schlafzimmer
  Schlafzimmer-Links-Heizung
Büro
  Büro-Fenster
  Büro-Lampe
  Büro-Schalter

Presence detection with the fritz!Box

Pmatic can assist you detecting the presence of your residents e.g. by communicating with the fritz!Box to check whether or not the mobile phone of a resident is currently active.

#!/usr/bin/python
import pmatic
ccu = pmatic.CCU(address="http://192.168.1.26", credentials=("Admin", "EPIC-SECRET-PW"))

# Maybe you need to configure your fritz!Box credentials to be able to fetch the
# presence information of the configured devices. Other available parameters are
# port=49000, user="username".
from pmatic.residents import PersonalDeviceFritzBoxHost
PersonalDeviceFritzBoxHost.configure("fritz.box", password="EPIC-SECRET-PW")

# Now create a residents manager instance and configure it. Currently the easiest
# way is to use it is to use the from_config() method with the following data:
ccu.residents.from_config({
    "residents": [
        {
            "id"             : 0,
            "name"           : "Lars",
            "email"          : "",
            "mobile"         : "",
            "pushover_token" : "",
            "devices": [
                {
                    "type_name": "fritz_box_host",
                    "mac": "30:10:E6:10:D4:B2",
                },
            ]
        }
    ],
})

# You may use ccu.residents.load(config_file="...") and the counterpart
# ccu.residents.load(config_file="...") to load and store your resident config.

# After initialization you can run either .update() on the residents instance
# or .update_presence() on a specific resident to update the presence information
# from the data source, in this case the fritz!Box.
ccu.residents.update()

for resident in ccu.residents.residents:
    #resident.update_presence()
    print(resident.name + " " + (resident.present and "is at home" or "is not at home"))

This script produces an output like this:

Lars is at home

Having this piece of information you can now modify your scripts to behave differently, depending on which of your residents is at home. Take a look at the Presence detection with pmatic chapter for details.

Computing the sun’s position in the sky

If you want to control the window shutters automatically, knowledge of the sun’s position in the sky is important. It can be computed with the function sun_position which is included in module pmatic/utils.py. It uses the algorithm from Wikipedia and was validated by comparing the results with the high-precision astronomy software Guide 9.0. The positional accuracy is generally better than 1/100 degree. Since the function does not take atmospheric refraction into account, the error is somewhat largerv ery close to the horizon.

The function returns a tuple of two coordinates: the sun’s azimuth and its elevation. The azimuth is the angle along the horizon between North and the point underneath the sun, counted positive to the East. The elevation is the angle between the sun and the horizon.

Example

#!/usr/bin/python
from math import radians, degrees
from time import strftime, localtime

import pmatic.utils as utils

latitude = 50.5
longitude = 8.3

print "Computing the current position of the sun for", longitude, "degrees eastern longitude and", latitude, \
    "degrees northern latitude."
print strftime("Date and time: %a, %d %b %Y %H:%M:%S", localtime())
azimuth, altitude = utils.sun_position(radians(longitude), radians(latitude))

print "Azimut: ", degrees(azimuth), ", Altitude: ", degrees(altitude)

This script produces an output like this:

Computing the current position of the sun for 8.3 degrees eastern longitude and 50.5 degrees northern latitude.
Date and time: Wed, 06 Jul 2016 12:26:54
Azimut:  149.656647766 , Altitude:  59.3890451373

Computing the dew point temperature

For the automation of ventilation systems the dew point temperature of the outside air must be known. It can be computed with the function dew_point which is included in module pmatic/utils.py. It uses the algorithm from Wikipedia. The algorithm was validated with independent data tables published in the internet.

The function takes the air temperature (in degrees Celsius) and humidity (a value between 0. and 1.) as input and returns the dew point temperature (in degrees Celsius).

Example

#!/usr/bin/python
import pmatic.utils as utils

temperature = 22.
humidity = 0.60

print "Temperature (C): ", temperature, ", Humidity (%): ",\
    humidity * 100., ", Dew point (C): ", utils.dew_point(temperature, humidity)

This script produces an output like this:

Temperature (C):  22.0 , Humidity (%):  60.0 , Dew point (C):  13.8751835583

Some use cases

You might use pmatic for different kind of software. Some ideas:

• Manually triggered one shot scripts

  The most simple use cases I can imagine is to create small scripts which are executed, gather some information, print them or do anything else with it and then finish. Of curse these scripts could also trigger something.

  An example could be a script which triggers a power switch when you turn on your workstation which is then powering on some kind of ambient light.

  Take a look at the example directory for more ideas.

• Continously running daemons

  A program which is e.g. starting with the system/CCU, permanently running, observing things and performing actions depending on the gathered information.

  This daemon could either continously poll the needed information on it’s own using the APIs pmatic provides or register for specific events happening and then perform custom actions.

• Scripts executed based on events

  You can use the pmatic manager to deal with the CCUs events and create schedules which are triggered when events for specific devices are received.

  It is also possible to do the event handling on your own. Take a look at the “Print temperature updates” example above.