Structure of SmartHomeNG
After the base system is installed a closer look at the SmartHomeNG directory
/usr/local/smarthome/) is advised to learn something about its content:
# directories bin contains smarthome.py, the main application deprecated contains deprecated tools, which will be removed in an upcoming release of SmartHomeNG dev development files like a sample plugin doc the documentation of the project resides here etc should contain the basic configuration files (smarthome.yaml, plugin.yaml, logic.yaml) examples contains some example files for the configuration and the visu plugin items should contain one or more item configuration files. lib contains the core libraries of SmartHomeNG logics should contain the logic scripts media contains logos of SmartHomeNG modules loadable core modules. These modules extend the functionality of the core plugins contains the available plugins requirements you will find the requirements file here for the core and all plugins scenes scene files tests contains the test environment with tests and testdata tools contains little programs helping to maintain SmartHomeNG var its subdirectories contain various collected data var/cache contains cached item values var/db may contain a SQLite3 database var/log contains the logfiles var/rrd may contain a Round Robin Databases if rrd plugin is used (deprecated) # files CHANGELOG.md changes of this project. (deprecated, should be documented in doc) LICENSE GNU GENERAL PUBLIC LICENSE (Version 3, 29 June 2007) README.md a general information setup.py not functional right now tox.ini used for software testing
Important for configuration are the directories
Those are the locations were configuration is stored and maintained.
The following discusses how these directories are populated.
Config files in directory etc
The configuration is done by the widespread yaml format. Older versions used configobj file format which is like a well-known ini-file but with the ability to create multilevel sub-sections. It is still supported in SmartHomeNG but it is deprecated for a while and was removed from documentation.
If the backend-plugin is configured then a service can be used to
*.conf configuration snippets into
There is furthermore a service tool located at
that can be used to convert your whole configuration.
Please have a look at Tools.
To calculate sunrise, sunset, azimuth and elevation of the sun for a given time the coordinates of the physical location of the SmartHomeNG installation is needed.
Create a new
etc/ or copy the given
smarthome.yaml and edit it to your needs. It should look like the following:
lat: 51.1633 # latitude lon: 10.4476 # longitude elev: 500 # elevation tz: Europe/Berlin # timezone, the example will be fine for most parts of central Europe default_language: de # default language for use with the backend plugin and multi-language entries in metadata
The coordinates can be found out by using GPS of a mobile or via an adequate website (e.g. http://www.mapcoordinates.net/)
Plugins extend the core functionality of SmartHomeNG.
plugins directory contains a subdirectory for every available plugin.
etc/plugin.yaml holds the configuration for every plugin to be used during runtime.
For each plugin at least the plugin object name is needed and the attributes where to find the plugin and how to expect the classname to be.
The example below configures a plugin for the KNX bus to send and receive telegrams from and to eibd or knxd (both a software gateway to the KNX hardware bus).
In this case the object name is
knx, the place to look for the module is within subdirectory
plugins/knx/ and the class of the plugin is
The object name can be any valid Python name, the class name and class path need to match those of the plugin.
knx: plugin_name: knx # class_name: KNX # old way of configuration # class_path: plugins.knx # old way of configuration host: 127.0.0.1 port: 6720 # send_time; 600 # update date/time every 600 seconds, default none # time_ga: 1/1/1 # default none # date_ga: 1/1/2 # default none
There is a README.md for every plugin that gives the necessary configuration information. To continue reading follow the plugin page.
Referencing a plugin in the configuration
Up to SmartHomeNG v1.3 a plugin had to be referenced by the parameters
Now it is possible to reference it alone by specifing the parameter
the value would be the former class_path without the plugins. prefix. Since all plugins are
located in the
/plugins folder, the plugins. is redundant information.
If the plugin comes with a metadata definition (what allmost all plugins do), there is no need so specify
class_name parameter. This information is retrieved from the metadata.
Should the need arise to configure a plugin that is located outside the
class_path can be used.
Using an older version of a plugin
If you are not using the newest version of the SmartHomeNG core, if may be necessary to use an older version of a plugin. Some plugins come with embedded older versions. To load an older version of the plugin, you have to specify the parameter plugin_version in the configuration section of the plugin.
To find out, if a plugin comes with an older version (or versions), take a look at the plugin’s
directory. if you find a subdirectory with the name starting with
_pv_ the plugin comes with
an older (previous) version. The rest of the folder name specifies the version number. If you
find a subfolder
_pv_1_3_0, it contains the v1.3.0 of the plugin. To load that version, just
plugin_version: 1.3.0 to the plugin configuration.
Logics within SmartHomeNG are just Python scripts like the core, too. These scripts will be placed in /usr/local/smarthome/logics/. To let SmartHomeNG know about when to start a script and which script to use then it is needed to configure every logic script in logic.yaml:
MyLogic: filename: logic.py crontab: init
With the example above SmartHomeNG would look in
/usr/local/smarthome/logics/ for the file
logic.py. The logic would be started - once - when SmartHomeNG starts.
The core and also every module is able to output logging information.
The logging can be configured to be rich in detail for debugging purposes or rather smart with warning or general info.
There is a seperate document to explain how to configure logging.
To get started, simply copy the given
logging.yaml and edit it to your needs. It should look like the following:
%YAML 1.1 --- version: 1 shng_version: x disable_existing_loggers: false formatters: shng_busmonitor: format: '%(asctime)s;%(message)s;' datefmt: '%Y-%m-%d;%H:%M:%S' shng_simple: format: '%(asctime)s %(levelname)-8s %(name)-17s %(message)s' datefmt: '%Y-%m-%d %H:%M:%S' shng_detail: format: '%(asctime)s %(levelname)-8s %(module)-17s %(threadName)-12s %(message)s -- (%(filename)s:%(funcName)s:%(lineno)d)' datefmt: '%Y-%m-%d %H:%M:%S %Z' shng_items: format: '%(asctime)s %(levelname)-8s %(module)-12s %(message)s' datefmt: '%Y-%m-%d %H:%M:%S' #filters: # # loggerfilter: # (): lib.logutils.Filter # name: knx_busmonitor handlers: shng_warnings_file: class: logging.handlers.TimedRotatingFileHandler formatter: shng_simple level: WARNING utc: false when: midnight backupCount: 7 filename: ./var/log/smarthome-warnings.log encoding: utf8 shng_details_file: class: logging.handlers.TimedRotatingFileHandler formatter: shng_simple level: DEBUG utc: false when: midnight backupCount: 7 filename: ./var/log/smarthome-details.log encoding: utf8 # shng_busmonitor_file: # class: logging.handlers.TimedRotatingFileHandler # formatter: shng_busmonitor # level: DEBUG # when: midnight # backupCount: 7 # encoding: utf8 # filename: ./var/log/knx_busmonitor.log # develop_file: # class: logging.handlers.TimedRotatingFileHandler # formatter: shng_detail # level: DEBUG # utc: false # when: midnight # backupCount: 7 # filename: ./var/log/smarthome-develop.log # encoding: utf8 console: class: logging.StreamHandler formatter: shng_simple stream: ext://sys.stdout loggers: __main__: # WARNING LEVEL to add restart log messages to further logfiles handlers: [shng_details_file] level: WARNING # knx_busmonitor: # level: INFO # handlers: [shng_busmonitor_file] # ==================================== # Loggers for Python modules/packages # ------------------------------------ # cherrypy.error: # handlers: [shng_details_file] # level: INFO # jinja2: # handlers: [shng_details_file] # level: INFO # ================================ # Loggers for SmartHomeNG modules # -------------------------------- modules.http: handlers: [shng_details_file] level: WARNING # ================================ # Loggers for SmartHomeNG plugins # -------------------------------- # If the logger is created with logging.getLogger(__name__) # the logger name is plugins.<plugin-shortname> # plugins.backend: # handlers: [shng_details_file] # level: INFO # plugins.cli: # handlers: [shng_details_file] # level: WARNING # plugins.database: # handlers: [shng_details_file] # level: INFO # ================================== # Loggers for SmartHomeNG libraries # ---------------------------------- # lib.connection: # handlers: [develop_file] # level: WARNING # lib.item: # handlers: [develop_file] # level: WARNING # lib.logic: # handlers: [develop_file] # level: INFO # ============================== # Loggers for SmartHomeNG logics # ------------------------------ logics.ex_logging: handlers: [shng_details_file] level: INFO logics.ex_persist: handlers: [shng_details_file] level: INFO root: level: WARNING handlers: [shng_warnings_file] # level: INFO # handlers: [shng_warnings_file_info, console]
See further details at logging.
Item definitions in directory items
The items represent the heart of the configuration. An item can be accessed from any logic, plugin or eval. Any number of item configuration files may be used and any number of items may be defined (depends on your memory) in one of these files.
This directory contains yaml files with the definitions of the items SmartHomeNG can use. The yaml files can be named the way you want.
To find out more details about items and scenes configuration continue reading the items page.
Logic definitions in directory logics
This directory contains logics you write, which are used by SmartHomeNG. A logic is basically a file of Python code. It has some additional conventions. When and how the logic is executed is configured in the file etc/logics.yaml.
When using the Blockly Plugin to write a logic, the logic has two files. One is the Blockly code with the extension .blockly and one file with the Python code. That file has the extension .py.
To find out more details about logics continue reading the logics page.
SmartHomeNG start options
SmartHomeNG can be executed with the following options:
usage: smarthome.py [-h] [-v | -d | -i | -l | -s | -q | -V | --start] optional arguments: -h, --help show this help message and exit -v, --verbose DEPRECATED use logging.config (verbose (debug output) logging to the logfile) -d, --debug stay in the foreground with verbose output -i, --interactive open an interactive shell with tab completion and with verbose logging to the logfile -l, --logics reload all logics -s, --stop stop SmartHomeNG -q, --quiet DEPRECATED use logging config (reduce logging to the logfile) -V, --version show SmartHomeNG version --start start SmartHomeNG and detach from console (default)
If you start SmartHomeNG without any option, then SmartHomeNG will return the PID if already running.
Please be noted that due to the changed nature of logging the -v and -q options are deprecated and will be removed in a later release.