The pmatic Module

CCU - The Central Object

A simple to use API to the Homematic CCU

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

Take a look at <https://github.com/LarsMichelsen/pmatic> for details.

pmatic.logging(log_level=None)

Enables logging of pmatic log messages to stderr.

When log_level is not set, it will default to WARNING if you did not configure the logging on your own in your application. Otherwise all log messages of pmatic which are of the given level or more severe will be logged to stderr.

This is only a default to be used e.g. in simple scripts. If you need more flexible logging, you are free to configure the logging module on your own.

class pmatic.CCU(**kwargs)

Provides the simple to use access to the CCU.

This is the main object to be used with pmatic. It provides top level access to all kind of entities like devices, channels, parameters, rooms and so on. It is possible to either poll information from the CCU or wait for incoming state update events provided by the CCU.

If your program is executed right on the CCU, you don’t need to provide any of the optional arguments.

The optional arguments address and credentials are needed if you execute your program not on the CCU. You need to provide the host address of the CCU, which can be an IP address or resolvable host name as address argument. The credentials need to be given as two element tuple of username and password, for example ("admin", "secretpw") which are then used to access the CCU.

The default TCP connect timeout for the HTTP requests to the CCU is set to 10 seconds. If you like to change the timeout, you need to set the argument connect_timeout to a number of seconds of your choice.

close()

Is used to close the connections with the CCU and the eventual open event listener

devices

This property provides access to the collection of all known devices.

This collection is an instance of pmatic.ccu.CCUDevices, which is a subclass of the room collection class pmatic.entities.Devices.

events

Using this property you can use the XML-RPC event listener of pmatic.

Provides access to the XML-RPC pmatic.events.EventListener instance.

residents

Provides access to the resident and presence management functionality of pmatic. See pmatic.residents.Residents for details.

rooms

Provides access to the collection of all known rooms.

This collection is an instance of pmatic.ccu.CCURooms, which is a subclass of the room collection class pmatic.entities.Rooms.

exception pmatic.PMException

This is the base exception for all exceptions raised by pmatic.

This exception is either a base class for all other pmatic specific exceptions but also directly raised in a lot of places where no more specific exception type exists.

exception pmatic.PMConnectionError

Is raised when the connection with the CCU could not be established.

This exception is raised by pmatic.api in situations where the CCU could not be contacted. Normally such an exception means that the just failed action can be tried again later.

For example when the CCU is currently not reachable this kind of exception is raised. Means it is worth it to try again later with same parameters.

exception pmatic.PMDeviceOffline

Is raised when trying to read e.g. values from the device but it is offline.

exception pmatic.PMActionFailed

Is raised when setting a value (parameter) of a channel fails.

exception pmatic.PMUserError

This exception is used when this situation is explicitly an error caused by the user.

For example invalid user input in forms of the pmatic manager or similar.

CCUDevices - Top Level Collection of Devices

class pmatic.ccu.CCUDevices(ccu)

Bases: pmatic.entities.Devices

The central device management class.

CCUDevices class is just like the pmatic.entities.Devices class, with the difference that it provides the CCUDevices.query() method which can be used to create new pmatic.entities.Devices collections. Another difference is, that it is initializing all devices configured in the CCU as device objects when generic methods to access the devices like len() are called on the object.

query([device_type=None[, device_name=None[, device_name_regex=None[, device_address=None]]]])

Use this function to query the CCU for a collection of devices.

The devices are returned in a pmatic.entities.Devices collection. Additionally the device objects are cached in the centrall pmatic.CCU object for later reference, when e.g. another search is asking for the same device. In case the same object is returned.

The object can be filtered using different filter parameters.

The device_type can be used to either search for devices of one specific or multiple types. The device type needs to be given as string which needs to be the exact product name, for example device_type="HM-Sec-SC". If you want to get multiple device types, you can do it like this: device_type=["HM-Sec-SC", "HM-CC-RT-DN"].

You can also search for specific devices by their names. The first option is to search for the exact name of one single device by setting the device_name to the name of the device, for example: device_name="Wohnzimmer-Fenster". Please note that this filter is case sensitive and a full exact match for the device name.

If you need more flexible filtering by the name, you can use the device_name_regex filter. You can either provide a regex in form of a string which is then matched with the device name from the start of the name (prefix match). One example to match all device names ending with -Fenster: device_name_regex=".*-Fenster$". You can also provide the result of re.compile() as value of device_name_regex. This is useful if you want to specify some special regex flags for your matching regex.

The device_address can be used to get a specific device by it’s address. This is an exact match filter. So you can either get a device collection of one device or an empty one back.

clear()

Remove all objects from this devices collection.

Devices - Collections of Devices

class pmatic.entities.Devices(ccu)

Manages a collection of CCU devices.

get(address, deflt=None)

Returns the device matching the given device address.

If there is none matching the given address either None or the value specified by the optional attribute deflt is returned.

add(device)

Add a Device object to the collection.

exists(address)

Check whether or not a device with the given address is in this collection.

addresses()

Returns a list of all addresses of all initialized devices.

delete(address)

Deletes the device with the given address from the pmatic runtime.

The device is not deleted from the CCU. When the device is not known, the method is tollerating that.

clear()

Remove all objects from this devices collection.

get_device_or_channel_by_address(address)

Returns the device or channel object of the given address.

Raises a KeyError exception when no device exists for this address in the already fetched objects.

on_value_changed(func)

Register a function to be called each time a value of a device in this collection changed.

on_value_updated(func)

Register a function to be called each time a value of a device in this collection updated.

__iter__()

Provides an iterator over the devices of this collection.

__len__()

Is e.g. used by len(). Returns the number of devices in this collection.

Device - Device connected with the CCU

class pmatic.entities.Device(ccu, spec)

classmethod from_dict(ccu, spec)

Creates a new device object from the attributes given in the spec dictionary.

The spec dictionary needs to contain the mandatory attributes with values of the correct format. Depending on the device type specified by the spec dictionary, either a specific device class or the generic Device class is used to create the object.

maintenance

Returns the ChannelMaintenance object of this device. It provides access to generic maintenance information available on this device.

set_logic_attributes(attrs)

Used to update the logic attributes of this device.

Applying the attributes in the dictionary to this object. Special handling for some attributes which are already set by the low level attributes and for the channel attributes which are also part of attrs.

is_online

Is True when the device is currently reachable. Otherwise it is False.

is_battery_low

Is True when the battery is reported to be low.

When the battery is in normal state, it is False. It might be a non battery powered device, then it is None.

has_pending_config

Is True when the CCU has pending configuration changes for this device. Otherwise it is False.

has_pending_update

Is True when the CCU has a pending firmware update for this device. Otherwise it is False.

rssi

Is a two element tuple of the devices current RSSI (Received Signal Strength Indication).

The first element is the devices RSSI, the second one the CCUs RSSI.

In case of the CCU itself or a non radio device it is set to (None, None).

inhibit

The actual inhibit state of the device.

Getter:Whether or not the device is currently locked, provided as params.ParameterBOOL. Setter:Specify the new inhibit state as boolean. Type:params.ParameterBOOL/bool

summary_state

Provides a textual summary state of the device.

Gives you a string representing some kind of summary state of the device. This string does not necessarly contain all state information of the devices.

When a device is unreachable, it does only contain this information.

This default method concatenates values and titles of channel values and provides them as string. The values are sorted by the titles.

channel_by_address(address)

Returns the channel object having the requested address.

When the device has no such channel, a KeyError() is raised.

on_value_changed(func)

Register a function to be called each time a value of this device has changed.

on_value_updated(func)

Register a function to be called each time a value of this device has updated.

Channel - Manages values

class pmatic.entities.Channel(device, spec)

classmethod from_channel_dicts(device, channel_dicts)

Creates channel instances associated with the given device instance from the given attribute dictionaries.

Uses the list of channel attribute dictionaries given with channel_dicts to create a dictionary of specific Channel instances (like e.g. ChannelShutterContact) or the generic Channel class. Normally each channel should have a specific class. In case an unknown channel needs to be created a debug message is being logged. The dictionary uses the index of the channel (the channel id) as key for entries.

The dictionary of the created channels is then returned.

values

Provides access to all value objects of this channel.

The values are provided as dictionary where the name of the parameter is used as key and some kind of specific params.Parameter instance is the value.

summary_state

Represents a summary state of the channel.

Formats values and titles of channel values and returns them as string.

Default formating of channel values. Concatenates titles and values of all channel values except the maintenance channel. The values are sorted by the titles.

on_value_changed(func)

Register a function to be called each time a value of this channel parameters has changed.

on_value_updated(func)

Register a function to be called each time a value of this channel parameters has been updated.

CCURooms - Top Level Collection of Rooms

class pmatic.ccu.CCURooms(ccu)

Bases: pmatic.entities.Rooms

The central room management class.

The CCURooms class is just like the pmatic.entities.Rooms class, with the difference that it provides the CCURooms.query() method which can be used to create new pmatic.entities.Rooms collections. Another difference is, that it is initializing all rooms configured in the CCU as room objects when generic methods to access the rooms like len() are called on the object.

query([room_name=None[, room_name_regex=None]])

Use this function to query the CCU for a collection of rooms.

The room objects are returned in a pmatic.entities.Rooms collection. Additionally the room objects are cached in the central pmatic.CCU object for later reference, when e.g. another search is asking for the same room. In case the same object is returned.

The object can be filtered using different filter parameters.

You can search for specific rooms by their names. The first option is to search for the exact name of one single room by setting the room_name to the name of the room, for example: room_name="Wohnzimmer". Please note that this filter is case sensitive and a full exact match for the room name.

If you need more flexible filtering by the name, you can use the room_name_regex filter. You can either provide a regex in form of a string which is then matched with the room name from the start of the name (prefix match). One example to match all room names ending with -2-Floor: room_name_regex=".*-2-Floor$". You can also provide the result of re.compile() as value of room_name_regex. This is useful if you want to specify some special regex flags for your matching regex.

clear()

Remove all Room objects from this collection.

Rooms - Collections of Rooms

class pmatic.entities.Rooms(ccu)

Manages a collection of rooms.

get(room_id, deflt=None)

Returns the Room matching the given room id.

If there is none matching the given ID either None or the value specified by the optional attribute deflt is returned.

ids

Provides a sorted list of all ids of all initialized room.

add(room)

Add a Room to the collection.

exists(room_id)

Check whether or not a Room with the given id is in this collection.

delete(room_id)

Deletes the Room with the given id from the pmatic runtime.

The room is not deleted from the CCU. When the room is not known, the method is tollerating that.

clear()

Remove all Room objects from this collection.

__iter__()

Provides an iterator over the rooms of this collection.

__len__()

Is e.g. used by len(). Returns the number of rooms in this collection.

Room - A Configured Room

class pmatic.entities.Room(ccu, spec)

devices

Provides access to a collection of Device objects which have at least one channel associated with this room.

The collections is a Devices instance.

channels

Holds a list of channel objects associated with this room.

EventListener - Listen for CCU Events

class pmatic.events.EventListener(ccu, listen_address=None, interface_id=None)

Manages events received from the CCU XML-RPC API.

This class can tell the CCU to send status update events to pmatic using it’s XML-RPC API. The EventListener registers with the CCU to get status updates. The CCU then synchronizes the known objects with pmatic and starts sending status updates. These status updates are then received by this class and handed over to the pmatic.entities.Device objects managed by the central CCU object to update their current state information.

The first argument ccu must be the CCU instance to be associated with this object.

The optional argument listen_address can be set to exactly tell the CCU to which host address and TCP port to send it’s XML-RPC calls. This defaults to the host address of your local system and TCP port 9123. You are free to set another port of your choice by specifying it as tuple of two elements like e.g. ("", 1337). The first element needs to contain the host address of the system pmatic is running on and is normally automatically gathered. But you can also set a fixed address if you like.

The second optional argument interface_id is an identifier which needs to be unique on your local system at any time. As far as I can tell this is only relevant when you plan to register multiple EventListener objects at the same time, on the same system and the same network port. If you start multiple listeners within the same proccess the identifier is automatically made unique and don’t need to be set.

rpc_server_url

Contains the URL the RPC server of this EventListener is listening on.

This URL is the URL sent to the CCU by init().

init()

Initializes this objects RPC server and registers with the CCU.

This method opens the XML-RPC server on the configured listen_address and sends an API call to the CCU to register the just started XML-RPC server. The CCU is then sending XLM-RPC messages to this server.

initialized

Is set to true when the XML-RPC have been started and registered with the CCU.

close()

Stops listening for XML-RPC messages and terminates the local XML-RPC server.

wait(timeout=None)

Waits for the event listener to terminate.

This is useful to let your code stay idle (for some time) and just wait for incoming events from the CCU.

When a timeout is configured this method returns when the listener terminates (for some reason) or the timeout happens.

This method returns True when the timeout happened and the listener is still alive or False when the listener has been terminated.

on_value_changed(func)

Register a function to be called each time any value of a device is changed.

on_value_updated(func)

Register a function to be called each time a value of any device is updated.

callback(cb_name, *args, **kwargs)

Execute all registered callbacks for this event.

Parameters

Parameter

class pmatic.params.Parameter(channel, spec)

Bases: pmatic.utils.CallbackMixin

Parameters are the objects which are encapusaling the individual values of the channels and devices.

The Parameter objects are assigned to channels by their names. Which subtype of the Parameter class is used for a particular value is determined by the type specified by the CCU.

datatype = u'string'

readable

Whether or not this value can be read.

writable

Whether or not this value can be set.

supports_events

Whether or not this value supports events.

name

Provides the formated name of this parameter. This name is generated from the name attribute provided by the CCU, but slightly adapted to look better for humans in texts. All underscores are replaced with spaces and the name is formated as title.

If you want to get the CCU internal name, use the attribute internal_name.

value

The current value of this paramter.

Getter:Provides the current value of this parameter as reported by the CCU. It raises a PMException when the parameter can not be read. Setter:Specify the new value. Returns a PMException when the parameter can not be written or a validation error occurs. It sets the value on the CCU. In case this fails a PMActionFailed exception is raised.

set(value)

Set a new value for this parameter. This is equal to setting the property value with the difference that this method returns True on success and False when a PMActionFailed exception would be raised.

set_to_default()

Sets the value to the default value (reported by the CCU).

last_updated

Provides the unix time when the value has been updated the last time.

This is measured since the creation of the object (startup of pmatic).

It raises a PMException when the parameter can not be read.

last_changed

Provides the unix time when the value has been changed the last time.

This is measured since the creation of the object (startup of pmatic).

It raises a PMException when the parameter can not be read.

is_visible_to_user

Whether or not this parameter should be visible to the end-user.

is_internal

Whether or not this parameter is an internal flag.

is_transformer

Whether or not modifying this parameter changes behaviour of this channel.

Can only be changed when no links are configured for this channel.

is_service

Whether or not a maintenance message is available.

is_service_sticky

Whether or not there is a sticky maintenance message.

formated()

Formats the current value in a human readable way. Whatever that means.

__str__()

Returns the formated value. Data type differs depending on Python version.

In Python 2 it returns an UTF-8 encoded string. In Python 3+ it returns a unicode string of type str.

__bytes__()

Returns the formated value UTF-8 encoded. Only relevant for Python 3.

__unicode__()

Returns the formated value as unicode string. Only relevant for Python 2.

ParameterSTRING

class pmatic.params.ParameterSTRING(channel, spec)

Bases: pmatic.params.Parameter

ParameterNUMERIC

class pmatic.params.ParameterNUMERIC(channel, spec)

Bases: pmatic.params.Parameter

__eq__(other)

__ne__(other)

__gt__(other)

__lt__(other)

__ge__(other)

__le__(other)

ParameterINTEGER

class pmatic.params.ParameterINTEGER(channel, spec)

Bases: pmatic.params.ParameterNUMERIC

datatype = u'integer'

formated()

Formats the current value with a %d format and adds a unit if there is a unit reported by the CCU.

ParameterFLOAT

class pmatic.params.ParameterFLOAT(channel, spec)

Bases: pmatic.params.ParameterNUMERIC

datatype = u'string'

formated()

Formats the current value with a %0.2f format and adds a unit if there is a unit reported by the CCU.

ParameterENUM

class pmatic.params.ParameterENUM(channel, spec)

Bases: pmatic.params.ParameterINTEGER

possible_values

Provides a python list of possible values.

The indexes in this list represent the digit to be used as value.

formated()

Returns the textual representation of the current value as also found in the list provided by the possible_values property.

ParameterBOOL

class pmatic.params.ParameterBOOL(channel, spec)

Bases: pmatic.params.Parameter

datatype = u'boolean'

ParameterACTION

class pmatic.params.ParameterACTION(channel, spec)

Bases: pmatic.params.ParameterBOOL

ParameterControlMode

class pmatic.params.ParameterControlMode(channel, spec)

Bases: pmatic.params.ParameterENUM

formated()

Returns the current control mode while it is converting the CCU internal naming scheme to the pmatic ones. It replaces the -MODE suffix and changes MANU to MANUAL.