Logic items within SmartHome.py are simple python scripts. SmartHome.py expects the logic scripts in /usr/local/smarthome/logics/.
The most important object is ‘sh’. This is the smarthome object. It contains every detail about the smarthome. With this object it is possible to access all items, plugins and basic functions of SmartHome.py. To get the value of an item call the name of it: sh.area.item(). To set a new value just specify it as argument: sh.area.item(new_value).
#!/usr/bin/env python
# put on the light in the living room, if it is not on
if not sh.living_room.light():
sh.living_room.light('on')
It is very important to access the items always with parantheses ()! Otherwise an error could occur.
It is possible to iterate over sh and the item objects.
for item in sh:
print item
for child_item in item:
print child_item
Beside the ‘sh’ object other important predefined objects are available.
This object provides access to the current logic object. It is possible to change logic attributes (crontab, cycle, ...) during runtime. They will be lost after restarting SmartHome.py. while logic.alive: creates an endless loop. This way SmartHome.py could stop the loop at shutdown. Next section (trigger) describes the special function logic.trigger(). Predefined attributs of the logic object:
Equal to sh.trigger(), but it triggers only the current logic. This function is useful to run the logic (again) at a specified time.
trigger is a runtime environment for the logic, which provides some information about the event that triggered the logic.
It is a dictionary which can be used by: trigger['by'], trigger['source'], trigger['dest'] and trigger['value'].
This object is useful to generate log messages. It provides five different log levels: debug, info, warning, error, critical. logger.level(str) e.g. logger.info(‘42’). The log messages are stored in the log file and the latest 50 entries are also in ‘sh.log’ available. So its possible to access the messages by plugins (visu) and logics. Attention: the datetime in every log entry is the timezone aware localtime.
# a simple loop over the log messages
for entry in sh.log:
print(entry) # remark: if SmartHome.py is run in daemon mode output by 'print' is not visible.
These two functions return a timezone-aware datetime object. Its possible to compute with different timezones. sh.tzinfo() and sh.utcinfo() address a local and the UTC timezone.
This module provides access to parameters of the sun. In order to use this module, it is required to specify the latitude (e.g. lat = 51.1633) and longitude (e.g. lon = 10.4476) in the smarthome.conf file!
# sh.sun.pos([offset]) specifies an minute offset.
azimut, altitude = sh.sun.pos() # return the current sun position
azimut, altitude = sh.sun.pos(30) # return the sun position 30 minutes
# in the future.
# sh.sun.set([offset]) specifies a degree offset.
sunset = sh.sun.set() # Returns a utc! based datetime object with the next
# sunset.
sunset_tw = sh.sun.set(-6) # Would return the end of the twilight.
# sh.sun.rise([offset]) specifies a degree offset.
sunrise = sh.sun.rise() # Returns a utc! based datetime object with the next
# sunrise.
sunrise_tw = sh.sun.rise(-6) # Would return the start of the twilight.
Besides the three functions (pos, set, rise) it provides two more. sh.moon.light(offset) provides a value from 0 - 100 of the illuminated surface at the current time + offset. sh.moon.phase(offset) returns the lunar phase as an integer [0-7]: 0 = new moon, 4 = full moon, 7 = waning crescent moon
Returns an item object for the specified path. E.g. sh.return_item('first_floor.bath')
Returns all item objects. for item in sh.return_items(): logger.info(item.id())
Returns all items matching a regular expression path and optional attribute. for item in sh.match_items('*.lights'): # selects all items ending with 'lights' logger.info(item.id()) for item in sh.match_items('*.lights:special'): # selects all items ending with 'lights' and attribute 'special' logger.info(item.id())
Returns all items with the specified config attribute for item in sh.find_items('my_special_attribute'): logger.info(item.id())
Returns all children items with the specified config attribute.
This global function triggers any specified logic by its name. sh.trigger(name [, by] [, source] [, value] [, dt]) name (mandatory) defines the logic to trigger. by a name of the calling logic. By default its set to ‘Logic’. source the reason for triggering. value a variable. dt timezone aware datetime object, which specifies the triggering time.
This method changes some runtime options of the logics. sh.scheduler.change('alarmclock', active=False) disables the logic ‘alarmclock’. Besides the active flag, it is possible to change: cron and cycle.
The sh.tools object provide some useful functions:
Pings a computer and returns True if the computer responds, otherwise False. sh.office.laptop(sh.tools.ping('hostname'))
Calculate the dewpoint for the provided temperature and humidity. sh.office.dew(sh.tools.dewpoint(sh.office.temp(), sh.office.hum())
Return a website as a String or ‘False’ if it fails. sh.tools.fetch_url('https://www.regular.com') Its possible to use ‘username’ and ‘password’ to authenticate against a website. sh.tools.fetch_url('https://www.special.com', 'username', 'password') Or change the default ‘timeout’ of two seconds. sh.tools.fetch_url('https://www.regular.com', timeout=4)
Converts an datetime object to a unix timestamp.
Converts an datetime object to a json timestamp.
Converts the relative humidity to the absolute humidity.
In the logic environment are several python modules already loaded: