Module http
This module implements the possibility to write web interfaces for SmartHomeNG plugins.
API des Moduls
A formatted version of the http README.md can be found here:
A raw version of the README.md for copy and paste can be found below the metadata file.
The meta data file:
module.yaml
# Metadata for the plugin
module:
# Global module attributes
classname: Http
version: 1.7.2
sh_minversion: 1.5b
# sh_maxversion: # maximum shNG version to use this plugin (leave empty if latest)
description:
de: 'Modul zur Implementierung von Backend-Webinterfaces für Plugins'
en: 'Module for implementing a backend-webinterface for plugins'
fr: "Module pour l'implémentation d'interfaces web des extensions"
parameters:
# Definition of parameters to be configured in etc/module.yaml
connectionretries:
type: int
valid_min: 0
valid_max: 100
default: 5
description:
de: Maximale Anzahl an Verbindungsversuchen zum Start von smarthomeNG, um die lokale IP zu eruieren.
en: Maximum number of connection retries to retrieve local IP address
fr: Nombre maximum de tentatives de connexion pour récupérer l'adresse IP locale
user:
type: str
default: 'admin'
description:
de: Benutzername für den Web Zugriff (Basic Auth), falls ein Passwort definiert ist
en: username for the web access (basic auth), if a password is defined
fr: Nom d'utilisateur pour l'accès web (Auth basique) si un mot de passe est défini
password:
type: str
description:
de: Passwort (im Klartext) für den Web Zugriff
en: password (unencrypted) for the web access
fr: Mot de passe (texte clair) pour l'accès web
hashed_password:
type: password
description:
de: hashed Version des Passworts für den Web Zugriff, ersetzt den Parameter 'password'
en: hashed version of the password for the web access, supersedes the parameter 'password'
fr: version haché du mot de passe pour l'interface web, remplace le paramètre 'password'
service_user:
type: str
default: 'serviceuser'
description:
de: Benutzername für den Zugriff auf Webservices (Basic Auth), falls ein Passwort definiert ist
en: username for the access to webervices (basic auth), if a password is defined
fr: Nom d'utilisateur pour l'accès au service web (Auth basique) si un mot de passe est défini
service_password:
type: str
description:
de: Passwort (im Klartext) für den Zugriff auf Webservices
en: password (unencrypted) for the access to webervices
fr: Mot de passe (texte clair) pour l'accès aux services web
service_hashed_password:
type: password
description:
de: hashed Version des Passworts für den Zugriff auf Webservices, ersetzt den Parameter 'password'
en: hashed version of the password for the access to webervices, supersedes the parameter 'password'
fr: version haché du mot de passe pour l'accès au service web (Auth basique) si un mot de passe est défini
ip:
type: ipv4
description:
de: IP Adresse auf der das http Modul aktiv sein soll - muss normalerweise nicht angegeben werden
en: IP adress on which the http module should operate - not needed, has only to be specified for special configurations
fr: Adresse IP sur laquelle le module http devrait fonctionner - il n'est généralement pas nécessaire de la spécifier
port:
type: int
valid_min: 0
valid_max: 65535
default: 8383
description:
de: Portnummer für die Webinterfaces bei Nutzung von http
en: Port number for the access to web interfaces
fr: Numéro de port pour l'accès à l'interface web
tls_port:
type: int
valid_min: 0
valid_max: 65535
default: 8385
description:
de: Portnummer für die Webinterfaces bei Nutzung von https
en: Port number for the access to webervices when using https
fr: Numéro de port pour l'accès à l'interface web si utilisation de https
use_tls:
type: bool
default: False
description:
de: Auf True setzen, um Zugriffe über https:// zu ermöglichen (Zertifikat muss installiert sein)
en: Set to true to allow access over https:// (certificate has to be installed)
fr: Mettre sur 'true' pour activer les accès par https (certificats doivent être installés)
tls_cert:
type: str
default: shng.cer
description:
de: Name der Zertifikatsdatei mit der Endung '.cer' oder '.pem'. Die Datei muss im Verzeichnis ../etc liegen
en: Name of the certificate file. The file musst be stored in ../etc
fr: Nom du fichier contanent les certificats. Le fichier doit se trouver dans ../etc
tls_key:
type: str
default: shng.key
description:
de: Name der Datei mit dem privaten Schlüssel und der Endung '.key'. Die Datei muss im Verzeichnis ../etc liegen
en: Name of the private key file. The file musst be stored in ../etc
fr: Nom du fichier contanent les clés privés. Le fichier doit se trouver dans ../etc
servicesport:
type: int
valid_min: 0
valid_max: 65535
default: 8384
description:
de: Portnummer für die Webservices
en: Port number for the access to webervices
fr: Numéro de port pour les services web
showpluginlist:
type: bool
default: True
description:
de: Anzeige einer Liste der Plugins mit Webinterfaces unter der url /plugins
en: Show a list of plugins with web interfaces under the url /plugins
fr: Afficher une listes des extensions avec interface web sous l'url /plugins
showservicelist:
type: bool
default: False
description:
de: Anzeige einer Liste der Plugins mit Webservices unter der url /services
en: Show a list of plugins with webservices under the url /services
fr: Afficher une listes des extensions avec des services web sous l'url /services
starturl:
type: str
default: admin
description:
de: Weiterleitungs-Url, wenn SmartHomeNG im Browser nur mit <DNS-Name>:<Portnummer> aufgerufen wird.
en: Redirection-url, if SmartHomeNG is called in the browser only by <dns-name>:<portnumber>
fr: Url de redirection si SmartHomeNG est chargé par le navigateur en utilisant seulement <nom-dns>:<numéro de port>.
threads:
type: int
default: 4
description:
de: Anzahl Threads, die für jede CherryPy App eingerichtet wird
en: number of threads setup per CherryPy app
fr: numéro de tâches prévus par application CherryPy
valid_list:
- 2
- 3
- 4
- 5
- 6
- 7
- 8
showtraceback:
type: bool
default: False
description:
de: Traceback bei Python Exceptions in der Fehlermeldung im Browser anzeigen. (Sollte in Produktionsinstallationen False sein)
en: Show traceback of Python exceptions on the error page displayed in the browser. (Should be False in production environment)
fr: Montrer les traces des exepctions Python sur la page d'erreurs affiché dans le navigateur. (Normallement 'False' dans en environnement de production)
webif_pagelength:
type: int
default: 0
valid_list:
- -1
- 0
- 25
- 50
- 100
description:
de: 'Anzahl an Tabellen-Zeilen, die standardmäßig in einer Web Interface Tabelle pro Seite angezeigt werden.
0 = automatisch (so viele in das Browser-Fenster passen) , -1 = alle
(Wirkt sich nur auf Web Interfaces mit sortierbaren Tabellen aus)'
en: 'Amount of table lines being listed in a web interface table per page by default.
0 = automatic (as many as can be fitted into the browser window), -1 = all
(Only affects web interfaces with sortable tables)'
description_long:
de: 'Anzahl an Tabellen-Zeilen, die standardmäßig in einer Web Interface Tabelle pro Seite angezeigt werden.\n
Bei 0 wird die Tabelle automatisch an die Höhe des Browserfensters angepasst.\n
Bei -1 werden alle Tabelleneinträge auf einer Seite angezeigt.'
en: 'Amount of table lines being listed in a web interface table per page by default.\n
0 adjusts the table height automatically based on the height of the browser windows.\n
-1 shows all table entries on one page.'
README.md
# Module http (README)
This module allows plugins to implement a web interface. The API is described below. The first plugin to utilize this API is the backend plugin.
> Note: To write a plugin that utilizes this module, you have to be familiar with CherryPy.
## Requirements
This module is running under SmartHomeNG versions beyond v1.3. It requires Python >= 3.4 as well as the lib **cherrypy**. You can install the libraries (python modules) with:
```
(sudo apt-get install python-cherrypy)
sudo pip3 install cherrypy
```
And please pay attention that the lib(s) are installed for Python3 and not an older Python 2.7 that is probably installed on your system. Be careful to use `pip3` and not `pip`.
> Note: This module needs the module handling in SmartHomeNG to be activated. Make sure, that `use_modules`in `etc/smarthome.yaml` is **not** set to False!
## Configuration
### etc/module.yaml
```yaml
# etc/module.yaml
http:
module_name: http
# port: 8383
# servicesport: 8384
# showpluginlist: False
showservicelist: True
# starturl: backend
# threads: 8
# showtraceback: True
# webif_pagelength: 0
```
#### user (optional)
username for the web access. By default username `admin` is used.
#### password (optional)
password for the web access. By default empty. Without a password access is available for everyone.
#### hashed_password (optional)
hashed password for the web access. By default empty. Without a hashed password the parameter password is used.
#### service_user (optional
username for the access to webervices. By default username `serviceuser` is used.
#### service_password (optional)
password for the access to the web services. By default empty. Without a password access is available for everyone.
#### service_hashed_password (optional)
hashed password for access to the web services. By default empty. Without a hashed password the parameter Service_password is used.
#### port (optional)
The port on which the html interface listens. By default port **`8383`** is used.
#### servicesport (optional)
The port on which the html interface listens. By default port **`8384`** is used.
#### showpluginlist
If set to `False` no list of pluins with web interface is shown under `smarthomeNG.local:8383/plugins`. By default, **showpluginlist** is **True**.
#### showservicelist
If set to `True` a list of webservices is shown under `smarthomeNG.local:8384/services`. By default, ** showservicelist** is **False**.
#### starturl (optional)
The name of the plugin that is started when calling url `smarthomeNG.local:8383` without further detailing that url. If you want to startup the **backend** plugin for example: You set `starturl: backend`. That results in a redirect which redirects `smarthomeNG.local:8383` to `smarthomeNG.local:8383/backend`.
if `starturl` is not specified or point to an url that does not exist, a redirect to `smarthomeNG.local:8383/plugins` will take place (if ** showpluginlist** is **True**). It points to a page that lists all plugins that have registered a html interface and allows you to start those interfaces.
> Note: If you have redirected to a specific plugin, you can always get to the page with the list of all plugins that have registered a html interface, by entering the url `smarthomeNG.local:8383/plugins`.
#### threads (optional)
Number of worker threads to start by cherrypy (default 8, which may be too much for slow CPUs)
#### showtraceback
If set to **True, error-pages (except for error 404) will show the Python traceback for that error.
#### webif_pagelength
Amount of items being listed in a web interface table per page by default.
0 adjusts the table height automatically based on the height of the browser windows.
-1 shows all table entries on one page.
## API of module http
### Test if module http is loaded
`http` is a loadlable module. Therefore there is no guarantiee that it is present in every system. Before you can use this module, you have to make sure ist is loaded. You can do it by calling a method of the main smarthome object. Do it like this:
```
self.classname = self.__class__.__name__
try:
self.mod_http = self._sh.get_module('http')
except:
self.mod_http = None
if self.mod_http == None:
# Do what is necessary if you can't start a web interface
# for your plugin. For example:
self.logger.error('{}: Module ''http'' not loaded - Abort loading of plugin {0}'.format(self.classname))
return
```
### Registering a web application/interface
For registering a web interface (or a web application in CherryPy terminology) you first have to define an application configuration for cherrypy.
> Note: Be careful not to include a CherryPy ``global`` configuration.
An application configuration for CherryPy can look like this;
```
app_config = {
'/': {
'tools.staticdir.root': current_dir,
'tools.auth_basic.on': self._basic_auth,
'tools.auth_basic.realm': 'earth',
'tools.auth_basic.checkpassword': self.validate_password,
},
'/static': {
'tools.staticdir.on': True,
'tools.staticdir.dir': os.path.join(current_dir, 'static')
}
}
```
> Note: The `tools.auth_basic`entries in this example are for implementing a basic logon security. If you don`t want/need login security, delete those enties.
For registering a web application/interface you have to call the `register_app` of module `http`:
```
register_app(app_object,
appname,
app_config,
pluginclass, instance,
description)
```
For example:
```
appname = 'backend' # Name of the plugin
pluginclass = self.__class__.__name__
instance = self.get_instance_name()
self.mod_http.register_app(Backend(self, self.updates_allowed, language, self.developer_mode, self.pypi_timeout),
appname,
app_config,
pluginclass, instance,
description='Administration interface for SmartHomeNG')
```
## Implementing a web interface for you plugin
For details about implementing a web interface (CherryPy application) for your plugin, refer to the CherryPy documentation.
The documentation will tell you how to expose parts of your python code to be availabe through CheryPy`s http-server.
### Methods for implementing a web interface
#### get_local_ip_address()
Returns the ip address under which the web interface is listening.
#### get_local_hostname()
Returns the hostname (with domain) under which the web interface is listening.
#### get_local_port()
Returns the port under which the implemented web interfaces can be reached.
#### get_local_servicesport( ... )
Returns the port under which the implemented webservices can be reached.
#### register_app()
##### Parameters
- **app** - Instance of the CherryPy App
- **pluginname** - Standard would be: Shortname of the plugin (name of the plugin's directory)
- **conf** - dict with CherryPy App-Config
- **pluginclass** - Class of the plugin
- **instance** - Optional: Instance of the plugin (if multi-instance)
- **description** - Optional: Description to be shown on page with plugin-list
#### register_service( ... )
##### Parameters
- **service** - Instance of the CherryPy App
- **servicename** - Standard would be: Shortname of the plugin (name of the plugin's directory)
- **conf** - dict with CherryPy App-Config
- **pluginclass** - Class of the plugin
- **instance** - Optional: Instance of the plugin (if multi-instance)
- **description** - Optional: Description to be shown on page with services-list