Modul admin

Dieses Modul implementiert ein graphisches Administrations-Interface für SmartHomeNG. Das ermöglicht die vollständige Konfiguration von SmartHomeNG.

Das Modul implementiert eine Reihe von REST Interfaces, die vom „Web Interface“, einer Angular Applikation genutzt werden um die Daten im Browser anzuzeigen bzw. zu manipulieren. Das Web Interface wird über das http Modul bereit gestellt, wie es auch bei den Web Interfaces der Plugins der Fall ist.

API des Moduls

Im folgenden werden die einzelnen APIs des Moduls beschrieben.

API des Moduls admin.rest

RESTResource ist die Grundlegende Klasse um REST Interfaces über das im http Modul verwendete CherryPy zur Verfügung zu stellen.

class modules.admin.rest.RESTResource

REST Resource

cherrypy controller mixin to make it easy to build REST applications.

handles nested resources and method-based dispatching.

here’s a rough sample of what a controller would look like using this:

cherrypy.root = MainController() cherrypy.root.user = UserController()

class PostController(RESTResource):

def index(self,post):

return post.as_html()

index.expose_resource = True

def delete(self,post):

post.destroySelf() return „ok“

delete.expose_resource = True

def update(self,post,title=““,body=““):

post.title = title post.body = body return „ok“

update.expose_resource = True

def add(self, post, title=““, body=““)

post.title = title post.body = body return „ok“

update.expose_resource = True

def REST_instantiate(self, slug):

try:

return Post.select(Post.q.slug == slug, Post.q.userID = self.parent.id)[0]

except:

return None

def REST_create(self, slug):

return Post(slug=slug,user=self.parent)

class UserController(RESTResource):

REST_children = {‚posts‘ : PostController()}

def index(self,user):

return user.as_html()

index.expose_resource = True

def delete(self,user):

user.destroySelf() return „ok“

delete.expose_resource = True

def update(self,user,fullname=““,email=““):

user.fullname = fullname user.email = email return „ok“

update.expose_resource = True

def add(self, user, fullname=““, email=““):

user.fullname = fullname user.email = email return „ok“

add.expose_resource = True

def extra_action(self,user):

# do something else

extra_action.expose_resource = True

def REST_instantiate(self, username):

try:

return User.byUsername(username)

except:

return None

def REST_create(self, username):

return User(username=username)

then, the site would have urls like:

/user/bob /user/bob/posts/my-first-post /user/bob/posts/my-second-post

which represent REST resources. calling ‚GET /usr/bob‘ would call the index() method on UserController for the user bob. ‚PUT /usr/joe‘ would create a new user with username ‚joe‘. ‚DELETE /usr/joe‘ would delete that user. ‚GET /usr/bob/posts/my-first-post‘ would call index() on the Post Controller with the post with the slug ‚my-first-post‘ that is owned by bob.

API des Moduls api_plugins

class modules.admin.api_plugins.PluginsController(module)

Bases: RESTResource

read(id=None)

Handle GET requests for threads API

return an object with type info about all installed plugins

class modules.admin.api_plugins.PluginsInstalledController(module)

Bases: RESTResource

read(id=None)

return an object with data about all installed plugins

class modules.admin.api_plugins.PluginsConfigController(module)

Bases: RESTResource

read(id=None)

return an object with data about all configured plugins

class modules.admin.api_plugins.PluginsInfoController(module, shng_url_root)

Bases: RESTResource

blog_urls = {}

stop()

If the Controller has started threads or uses python modules that created threads, put cleanup code here.

read(id=None)

return a list of all configured plugin instances

class modules.admin.api_plugins.PluginsAPIController(module)

Bases: RESTResource

read(id=None)

return a list of all configured plugin instances

class modules.admin.api_plugins.PluginsLogicParametersController(module)

Bases: RESTResource

read(id=None)

return an object with data about the logic parameters of all configured plugins

API des Moduls api_plugin

class modules.admin.api_plugin.PluginController(module, jwt_secret=False)

Bases: RESTResource

get_body()

Get content body of received request header

Rückgabe:

test_for_old_config(config_filename)

get_config_filename()

read(id=None)

return an object with type info about all installed plugins

add(id=None)

handle_plugin_action(id, action)

update(id='', action='')

delete(id=None)

API des Moduls (WebApi)

class modules.admin.WebApi(webif_dir, module, shng_url_root, url_root)

Bases: RESTResource

Parameter:

• webif_dir (str) – Directory where the files of the web interface (shngadmin) are stored

• module (object) – Instance of the webif object

• shng_url_root (str) –

  …

• url_root (str) –

  …

README

README

# Module admin (README)

This module implements the administration interface for SmartHomeNG.


## Requirements

This module is running under SmmartHomeNG versions beyond develop version v1.5d. It requires Python >= 3.4 as well as ... . You can install the libraries (python modules) with:

```
(sudo apt-get install ...)
sudo pip3 install ...
```

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 carefull to use `pip3` and nor `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
admin:
    module_name: admin
```


## API des Moduls admin

Im folgenden sind die einzelnen Teile des REST APIs beschrieben, 
welches das admin Modul zur Verfügung stellt und intern nutzt.

Wenn zur Nutzung des einzelen APIs eine Authentifizierung notwendig 
ist, ist dieses erwähnt.


### AUTH API -  Authentification for clients

#### POST /api/auth/
Authentifiziert den Client bei SmartHomeNG und erhält einen
Token (JWT) bei erfolgreicher Authentifizierung.


### CONFIG API - Get and update information about the core's configuration

#### GET /api/config
liefert die Konfiguration des Core von SmartHomeNG

#### GET /api/config/\<module (or 'common')>
liefert die Konfiguration der Modules oder des allgemeinen 
(common) Teils von SmartHomeNG

#### PUT /api/config/\<module (or 'common')>
Macht ein Update auf den entsprechenden Teil der Konfiguration

-> authentication_needed = True


### LOGICS API - xxx

#### ???


### LOGS API - Get information about logs and get log content

#### GET /api/logs
liefert die Liste der vorhandenen logs

#### GET /api/logs/\<logname>
liefert den Inhalt einer log-Datei


### PLUGINS API - Get information about installed or configured plugins

#### GET /api/plugins
liefert die Liste der installierten Plugins

#### GET /api/plugins/config
liefert die gesamte config


## PLUGIN API  -  Handle a single plugin configuration

#### POST /api/plugin/config/\<neu> 
legt eine neue Confic-section Namens ‚\<neu>‘ an

-> authentication_needed = True

#### PUT /api/plugin/config/\<plgsection>
Macht ein Update auf die Section ‚\<plgsection>‘

-> authentication_needed = True

#### DELETE /api/plugin/config/\<plgsection> 
Löscht die Section ‚\<plgsection>‘

-> authentication_needed = True


## SCENES API  -  Get information about configured scenes

####GET /api/scenes
liefert die Liste der konfigurierten Szenen


## SCHEDULER API  -  Get information about configured schedulers

####GET /api/sched
liefert die Liste der konfigurierten Scheduler


## SCHEDULER API  -  Get information about the SmartHomeNG server configuration

####GET /api/serverinfo
liefert Informationen über die Konfiguration des SmartHomeNG Servers


## THREADS API  -  Get information about running threads

####GET /api/threads
liefert die Liste der laufenden Threads


## STATUS API  -  Get running status of the SmartHomeNG server instance

####GET /api/status
liefert den aktuellen Status von SmartHomeNG


## RESTART API  -  Restart the SmartHomeNG server instance

####GET /api/restart
Startet die SmartHomeNG Server Instanz neu


##


### Test if module admin is loaded

`admin` 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_admin = self._sh.get_module('admin')
except:
    self.mod_admin = None
    
if self.mod_admin == None:
    # Do what is necessary if you can't use the admin interface
    # for your plugin. For example:
    self.logger.error('{}: Module ''admin'' not loaded - Abort loading of plugin {0}'.format(self.classname))
    return
```

Metadaten

Auskommentierte Parameter in den Metadaten sind noch nicht implementiert. Die Implementierung dieser Parameter wird im Rahmen der Weiterentwicklung von SmartHomeNG erfolgen:

module.yaml

# Metadata for the plugin
module:
    # Global module attributes
    classname: Admin
    version: 1.8.2
    sh_minversion: 1.7.2c
#    sh_maxversion: 1.3             # maximum shNG version to use this plugin (leave empty if latest)
    description:
        de: 'Dieses Modul implementiert das Administrationinterface von SmartHomeNG'
        en: 'This module implements the administration interface for SmartHomeNG'
        fr: "Ce module implémente l'interface d'administration pour SmartHomeNG"

parameters:
    login_expiration:
        type: num
        default: 48
        description:
            de: 'Ablaufdauer des Logins in Stunden (ab Loginzeitpunkt)'
            en: 'Expiration time of the login in hours (counting from time of login)'
            fr: "Temps d'expiration de l'identification en heures (à partir du moment de l'identification)"

    login_autorenew:
        type: bool
        gui_type: yes_no
        default: True
        description:
            de: 'Bestehendes Login-Token automatisch verlängern'
            en: 'Automatically extend an existing login-token'
#            fr: ""

    pypi_timeout:
        type: int
        default: 5
        description:
            de: 'Timeout bei der Abfrage der pypi Website'
            en: 'Timeout for getting data from the pypi website'
            fr: "Délai d'attente pour obtenir des données du site Web Pypi"

    itemtree_fullpath:
        type: bool
        gui_type: yes_no
        default: True
        description:
            de: 'Im Item-Tree die Items mit vollem Pfad-Namen anzeigen'
            en: 'Display items with full path in item tree'
            fr: "Afficher le chemin complèt des objets dans l'arborescence"

    itemtree_searchstart:
        type: num
        default: 2
        description:
            de: 'Minimale Anzahl eingegebener Zeichen ab denen die Suche im Item-Tree beginnt'
            en: 'Minimum number of entered characters to start searching the item tree'
            fr: "Nombre minimum de caractères entrés pour démarrer la recherche dans l'arborescence"

    websocket_host:
        type: ip
        description:
            de: 'IP Adresse für den websocket Zugriff'
            en: 'ip address to use for websocket access'
            fr: "Adresse IP à utiliser pour l'accès websocket"

    websocket_port:
        type: int
        valid_min: 0
        valid_max: 65535
        default: 2424
        description:
            de: 'Port der für den Websocket Zugriff verwendet wird'
            en: 'Port that is used for the websocket protocol'
            fr: "Port à utiliser pour l'accès websocket"

    log_chunksize:
        type: int
        valid_min: 25
        valid_max: 5000
        default: 1000
        description:
            de: 'Größe der gelesenen Blöcke bei der Anzeige großer Logdateien'
            en: 'Size of blocks (chunks) read when displaying large logfiles'
            fr: "Taille des morceaux lus lors de l'affichage de fichiers journaux volumineux"

    developer_mode:
        type: bool
        default: False
        gui_type: on_off

        description:
            de: 'Entwickler Modus aktivieren (Ist für das Core Entwickler Team gedacht)'
            en: 'Activate developer mode'

    rest_dispatch_force_exception:
        type: bool
        gui_type: yes_no
        default: False
        description:
            de: 'Sollen WARNINGs aus REST_dispatch_execute als EXECPTION geloggt werden?'
            en: 'Activate developer mode'

    click_dropdown_header:
        type: bool
        gui_type: yes_no
        default: False
        description:
            de: 'Click auf Kopfeintrag von Dropdown Menüs erlauben'
            en: 'Allow click on header of dropdown menus'