Manage your Residents

You can manage your residents either in your own scripts by using the pmatic.residents class or within the manager by configuring your residents using the GUI and then access the residents configured attributes like email address, mobile number or pushover tokens from your own pmatic scripts. Another interesting topic is the presence detection of your residents, take a look at that chapter below.

Presence detection with pmatic

An important task in home automation is to detect whether or not someone is at home or not. I personally use the presence information to route notifications to the different residents, for example to close a window when it is open for too long.

Currently pmatic comes with one presence plugin which uses the fritz!Box connected devices list (Home Network) to detect whether or not a device (person) is present. It explicitly does not use a direct ping to any device because it is not possible to detect e.g. the iPhone in the LAN by using ping by default. But the list of the fritz!Box works like a charm for any mobile phone I tested.

To make it even more comfortable the pmatic Manager has a dedicated GUI to configure your users and devices. Within the manager you can even trigger scripts when a user arrives or leaves.

Example: Logging presence every 5 minutes

To make it comfortable the pmatic Manager has a dedicated GUI to configure your users and devices. Within the manager you can even trigger scripts when a user arrives or leaves.

When executing scripts from the manager using inline scripts, you can access the residents configured via the manager by using the residents instance of the globally available CCU object. You don’t need to care for updating the data on your own or loading the residents. And you even don’t need to configure the fritz!Box credentials within the script as they are already configured within the manager.

You can simply start with the logic you like to implement. If you add a schedule that is being executed every 5 minutes, you get a log file in the path /tmp/presence-test.log which contains one entry for each resident which contains it’s name and presence status.

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

for resident in ccu.residents.residents:
    open("/tmp/presence-test.log", "a").write(time.strftime("%Y-%m-%d %H:%M:%S") + " " +
        resident.name + " " + (resident.present and "is at home\n" or "is not at home\n"))

However, it even possible to make your script being executed upon user arrival or departure using the “on resident presence” condition. This lets you get rid of the timed polling and you’ll have a log which only contains the changes in presence.

Example: Accessing resident properties

Once you have configured your residents, you can use their attributes like phone number, pushover token or email address in your scripts. Please take a look at this example:

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

lars = ccu.residents.get_by_name("Lars")
if lars is None:
    print("You don't have a resident \"Lars\". Feeling sorry.")
    sys.exit(1)

print("Mail           : %s" % lars.email)
print("Phone Phone    : %s" % lars.phone)
print("Pushover Token : %s" % lars.pushover_token)

# And now? Maybe send a notification using pmatic.notify?
# from pmatic.notify import Pushover
# Pushover.send("Hallo Lars :-)", user_token=lars.pushover_token, api_token="...")

This script will output something like this when you have a resident called Lars:

Mail           : lm@larsmichelsen.com
Mobile Phone   : +4912312312312
Pushover Token : KLAH:AWHFlawfkawjd;kawjd;lajw

The pmatic.residents module

class pmatic.residents.Residents

Bases: pmatic.utils.LogMixin

This class is meant to manage your residents and the presence of them.

from_config(cfg)

Build the Residents object, residents and devices from a persisted configuration dictionary.

to_config()

Returns a dictionary representing the whole residents configuration. This dictionary can be saved somewhere, for example in a file, loaded afterwards and handed over to from_config() to reconstruct the current Residents object.

from_state(state)

Updates the variable state data which can change during runtime on the current resident object.

to_state()

Returns a list of resident states. Each entry represents the state of a configured resident gathered with Resident.to_state().

enabled

Is set to True when the presence detection shal be enabled.

update()

Call this to update the presence information of all configured residents and their devices. This normally calls the presence plugins to update the presence information from the connected data source.

add(r)

Add a Resident object to the collection. This method automatically generates a new resident id for the object and stores this key within the object.

exists(resident_id)

Returns True when a resident with the given id exists. Otherwise False is returned.

get(resident_id)

Returns the Resident matching the given resident_id. Returns None when this resident does not exist.

get_by_name(resident_name)

Returns the first Resident matching the given resident_name. Returns None when there is no resident with this name.

remove(resident_id)

Removes the resident with the given resident_id from the Residents. Tolerates non existing resident ids.

clear()

Resets the Persence object to it’s initial state.

class pmatic.residents.Resident(presence)

Bases: pmatic.utils.LogMixin, pmatic.utils.CallbackMixin

id

The internal ID of the user. This must be a unique number within all residents.

name

The name of the resident. This can be any kind of string you like to name your resident.

email

The email address of the resident. You may use this to send mails to the resident from your scripts.

mobile

The mobile number of the resident. You may use this to send SMS to the resident from your scripts.

pushover_token

The pushover token of this resident. You may use this to send pushover messages to the resident from your scripts. Please take a look at the pmatic notification documentation (pmatic.notify) for details.

present

Is True when the user is present and False when not.

last_updated

Is set to the unix timestamp of the last update or None when not updated yet.

last_changed

Is set to the unix timestamp of the last presence change or None when not updated yet.

from_config(cfg)

to_config()

from_state(state)

to_state()

add_device(device)

Adds a PersonalDevice object to the resident. Please note that you need to use a specific class inherited from PersonalDevice, for example the PersonalDeviceFritzBoxHost class.

clear_devices()

Resets the device list to it’s initial state.

update_presence()

Updates the presence of this resident. When at least one device is active, the resident is treated to be present.

on_presence_updated(func)

Register a function to be called each time the presence of this resident is updated.

The function must accept a single argument which is the the current Resident object.

on_presence_changed(func)

Register a function to be called each time the presence of this resident is changed.

The function must accept a single argument which is the the current Resident object.

class pmatic.residents.PersonalDevice

Bases: object

type_name = u''

type_title = u''

classmethod types()

Returns a list of all available specific PersonalDevice classes

classmethod get(type_name)

Returns the subclass of PersonalDevice which matches the given type_name or None if there is no match.

from_config(cfg)

Restores the object attributes from the persisted configuration.

to_config()

Creates a dictionary which can be persisted and later loaded with from_config() to reconstruct this object again.

from_state(state)

to_state()

update_presence()

Can be overridden by specific personal device classes to update the information of this device.

name

Provides the name of this device.

active

Whether or not this device is currently active.

class pmatic.residents.PersonalDeviceFritzBoxHost

Bases: pmatic.residents.PersonalDevice, pmatic.utils.LogMixin

type_name = u'fritz_box_host'

type_title = u'fritz!Box Host'

connection = None

classmethod configure(address=None, protocol=None, port=None, user=None, password=None)

mac

Provides the MAC address of this device.

to_config()

Creates a dictionary which can be persisted and later loaded with from_config() to reconstruct this object again.

to_state()

Returns the variable aspects of this object which can change during runtime.

update_presence()

Update the presence information of this device.