| SmartHomeNG wird mit der Pycharm IDE entwickelt. |
+| 
| Das Admin Interface von SmartHomeNG wird mit WebStorm IDE entwickelt. |
+
+## Aktueller Status der Entwicklung
+
+[](https://travis-ci.com/smarthomeNG/smarthome)
+
+
+---
+
+# SmartHomeNG and other languages
+
+SmartHomeNG [1] is a software that serves as a basis for home automation. It interconnects multiple devices using plugins to access their specific interfaces.
+
+User documentation ([german](https://www.smarthomeNG.de/user)) and developer documentation ([part of the user documentation](https://www.smarthomeng.de/user/entwicklung/entwicklung.html)) can be found on [www.smarthomeNG.de](https://www.smarthomeNG.de)
Additional information can be found in the [SmartHomeNG Wiki](https://github.com/smarthomeNG/smarthome/wiki).
+It is possible to read the documentation with [Google's translation service](https://translate.google.com/translate?hl=&sl=de&tl=en&u=https://www.smarthomeng.de/dev/user/) in other languages as well.
+
+This readme file contains basic information about the root directories of SmartHomeNG for an overview.
+
+
## Used Tools
| Tool | Description |
@@ -25,24 +53,24 @@ Additional information can be found in the [SmartHomeNG Wiki](https://github.com
## Directory Structure
| directory | description|
-| --- | :--- |
+| --- | :--- |
|bin | the main python file is based here |
-|dev | if you plan to create a plugin then this is the folder you want to have a closer look at |
+|dev | sample files for creating own plugins and modules |
|doc | Source files for the user- and developer documentation |
-|etc | the three basic configuration files smarthome.yaml, module.yaml, plugin.yaml, logic.yaml and logging.yaml are located here, you will edit these files to reflect your basic settings|
-|items | put here your own files for your items |
-|lib | some more core python modules are in this directory. You won't need to change anything here
-|logics | here your logic files are put
-|modules | here are all loadable core-modules located (one subdirectory for every module)
-|plugins | here are all plugins located (one subdirectory for every plugin). The plugins have to be installed from a separate repository (smarthomeNG/plugins)
-|scenes | the scenes are stored here
-| tests | The code for the automated travis tests is stored here
-|tools | there are some tools which help you for creating an initial configuration
-|var | everything that is changed by smarthome is put here, e.g. logfiles, cache, sqlite database etc.
+|etc | the five basic configuration files smarthome.yaml, module.yaml, plugin.yaml, logic.yaml and logging.yaml are located here, you need to edit these files to reflect your basic settings |
+|items | put your own files for your items here |
+|lib | some more core python modules are in this directory. You won't need to change anything here |
+|logics | put your own files for your logics here |
+|modules | here are all loadable core-modules located (one subdirectory for every module) |
+|plugins | here are all plugins located (one subdirectory for every plugin). The plugins have to be installed from a separate repository (smarthomeNG/plugins) |
+|scenes | the scenes are stored here |
+|tests | the code for the automated travis tests is stored here |
+|tools | there are some tools which help you with creating an initial configuration |
+|var | everything that is changed by smarthome is put here, e.g. logfiles, cache, sqlite database etc. |
## Some more detailed info on the configuration files
-As of Version 1.5 the old conf format will still be valid but will be moved out of the docs since it's deprecated now for some time.
+As of Version 1.5 the old conf format will still be valid but is removed from the docs since it's been deprecated now for some time.
### etc/smarthome.yaml
Upon installation you will need to create this file and specify your location.
@@ -57,7 +85,7 @@ tz: Europe/Berlin
```
### etc/module.yaml
-Upon installation you will need to create this file and configure the modules and their parameters. On first start of SmartHomeNG this file is created from ```etc/module.yaml.default```.
+Upon installation you will need to create this file and configure the modules and their parameters. On first start of SmartHomeNG this file is created from ```etc/module.yaml.default```, if not already present.
An example is shown below:
@@ -76,7 +104,7 @@ admin:
```
### etc/plugin.yaml
-Upon installation you will need to create this file and configure the plugins and their parameters. On first start of SmartHomeNG this file is created from ```etc/plugin.yaml.default```.
+Upon installation you will need to create this file and configure the plugins and their parameters. On first start of SmartHomeNG this file is created from ```etc/plugin.yaml.default```, if not already present.
An example is shown below:
@@ -93,7 +121,7 @@ database:
cli:
plugin_name: cli
ip: 0.0.0.0
- update: True
+ update: true
websocket:
plugin_name: visu_websocket
@@ -147,5 +175,5 @@ If you want to read an item call `sh.item.path()` or to set an item `sh.item.pat
```python
# logics/sunset.py
if sh.global.sun(): # if sh.global.sun() == True:
- sh.gloabl.sun(False) # set it to False
+ sh.global.sun(False) # set it to False
```
diff --git a/bin/locale.yaml b/bin/locale.yaml
index 3239b67c5c..1ad8f159a6 100644
--- a/bin/locale.yaml
+++ b/bin/locale.yaml
@@ -75,6 +75,67 @@ global_translations:
'Letztes Update': {'de': '=', 'en': 'Last Update', 'fr': ''}
'Letzter Change': {'de': '=', 'en': 'Last Change', 'fr': ''}
+ #Translations for lib.scene:
+ "A second 'scenes' object has been created. There should only be ONE instance of class 'Scenes'!!! Called from: {frame1} ({frame2})":
+ 'de': "Ein zweites Szenenobjekt wurde erzeugt. Es darf jedoch nur EINE Instanz der Klasse 'Szenes' geben!!! Aufgerufen durch: {frame1} ({frame2})"
+ 'en': '='
+ "Directory '{scenes_dir}' not found. Ignoring scenes.":
+ 'de': "Directory '{scenes_dir}' nicht gefunden. Szenen werden ignoriert."
+ 'en': '='
+ "Scene {scene}, state {state}: action '{action}' is not a dict":
+ 'de': "Szene {scene}, Status {state}: Action '{action}' ist kein Dictionary"
+ 'en': '='
+ "Scene {scene}, state {state}: actions are not a list":
+ 'de': "Szene {scene}, Status {state}: Actionen sind keine Liste"
+ 'en': '='
+ "Reloaded all scenes":
+ 'de': "Alle Szenen neu geladen"
+ 'en': '='
+ "Problem reading scene file {file}: No .yaml or .conf file found with this name":
+ 'de': "Problem beim lesen der Szenen Datei {file}: Keine .yaml oder .conf Datei mit diesem Namen gefunden"
+ 'en': '='
+ "Problem evaluating: {value} - {exception}":
+ 'de': "Problem beim berechnen: {value} - {exception}"
+ 'en': '='
+ "Invalid state '{state}' for scene {scene}":
+ 'de': "Ungültiger Status '{state}' für Szene {scene}"
+ 'en': '='
+ "Learn set to 'False', because '{rvalue}' != '{value}'":
+ 'de': "Learn auf False gesetzt, weil '{rvalue}' != '{value}'"
+ 'en': '='
+ "Could not find item or logic '{ditemname}' specified in {file}":
+ 'de': "Item oder Logik '{ditemname}' nicht gefunden. Wurde in {file} spezifiziert"
+ 'en': '='
+ "unable to get self._scenes['{scenename}']['{action}'][0][2] <- {res}":
+ 'de': "self._scenes['{scenename}']['{action}'][0][2] kann nicht gelesen werden <- {res}"
+ 'en': '='
+
+ #Translations for lib.userfunctions:
+ "Imported userfunctions from '{mmodule}' v{version} - {description}":
+ 'de': "Userfunctions importiert aus '{module}' v{version} - {description}"
+ 'en': '='
+ "Error importing userfunctions from '{module}': {error}":
+ 'de': "Fehler beim importieren von Userfunctions aus '{module}': {error}"
+ 'en': '='
+ "Error reloading userfunctions '{module}': Module is not loaded, trying to newly import userfunctions '{module}' instead":
+ 'de': "Fehler beim Reload von Userfunctions '{module}': Modul ist nicht geladen, versuche stattdessen Userfunctions '{module}' neu zu importieren"
+ 'en': '='
+ "Error reloading userfunctions '{module}': {error} - old version of '{module}' is still active":
+ 'de': "Fehler beim Reload von userfunctions '{module}': {error} - alte Version von '{module}' ist noch aktiv"
+ 'en': '='
+ "Reloaded userfunctions '{module}'":
+ 'de': "Reload: Userfunctions '{module}' neu geladen"
+ 'en': '='
+ "Reload: Userfunctions '{module}' do not exist":
+ 'de': "Reload: Userfunctions '{module}' existieren nicht"
+ 'en': '='
+ "Reload: Loaded new userfunctions '{module}'":
+ 'de': "Reload: Neue Userfunctions '{module}' geladen"
+ 'en': '='
+ "No userfunctions are loaded, nothing to reload":
+ 'de': "Es existieren keine Userfunctions, es gibt nichts für einen Reload"
+ 'en': '='
+
lib.shtime_translations:
'defined': {'de': 'definiert', 'en': '='}
@@ -114,5 +175,12 @@ lib.shtime_translations:
'de': "Aufgerufen mit einem Parameter der nicht vom Typ 'datetime' ist: {dt1}, {dt2}"
'en': '='
"Called with point in time that is earlier than now: {dt}":
- 'de': 'Aufgerufen mit Zeitpunkt in der Vergangenheit'
+ 'de': 'Aufgerufen mit Zeitpunkt in der Vergangenheit: {dt}'
'en': '='
+ "Calculating beginning of week based on year {year}, week {week} and offset {offset}":
+ 'de': 'Berechne Wochenstart basierend auf Jahr {year}, Woche {week} und Offset {offset}'
+ 'en': '='
+ "Calculating length of month based on year {year}, month {month}{debug_month}":
+ 'de': 'Berechne Länge des Monats basierend auf Jahr {year}, Monat {month}{debug_month}'
+ 'en': '='
+
diff --git a/bin/shngversion.py b/bin/shngversion.py
index 2266edcf94..21dd836b82 100644
--- a/bin/shngversion.py
+++ b/bin/shngversion.py
@@ -69,9 +69,13 @@
# Update auf 1.8.1a wg. Kennzeichnung des Stands als "nach dem v1.8.1 Release"
# Update auf 1.8.2 wg. Release
+# Update auf 1.8.2a wg. Kennzeichnung des Stands als "nach dem v1.8.2 Release"
+# Update auf 1.8.2b wg. Erweiterung des Item Loggings"
+# Update auf 1.8.2c wg. Wegen Anpassungen an mem-logging / lib.log
+# Update auf 1.8.2d Unterstützung für User-Functions
-shNG_version = '1.8.2'
-shNG_branch = 'master'
+shNG_version = '1.8.2d'
+shNG_branch = 'develop'
# ---------------------------------------------------------------------------------
FileBASE = None
diff --git a/bin/smarthome.py b/bin/smarthome.py
index 83964e0d66..cc9c1a186b 100644
--- a/bin/smarthome.py
+++ b/bin/smarthome.py
@@ -54,6 +54,7 @@
# https://stackoverflow.com/questions/31469707/changing-the-locale-preferred-encoding-in-python-3-in-windows
+
#####################################################################
# Read command line arguments
#####################################################################
@@ -137,12 +138,12 @@
# Import SmartHomeNG Modules
#####################################################################
#import lib.config
-#import lib.connection
import lib.daemon
#import lib.item
#import lib.log
#import lib.logic
#import lib.module
+#import lib.network
#import lib.plugin
#import lib.scene
#import lib.scheduler
diff --git a/dev/sample_module/__init__.py b/dev/sample_module/__init__.py
index cef09d4ba8..133a904829 100644
--- a/dev/sample_module/__init__.py
+++ b/dev/sample_module/__init__.py
@@ -22,17 +22,19 @@
import os
import logging
-import json
-import cherrypy
+# import json
+# import cherrypy
from lib.model.module import Module
from lib.module import Modules
from lib.shtime import Shtime
+from lib.Utils import Utils
+
class SampleModule(Module):
- version = '1.7.0'
+ version = '1.0.0'
longname = '... module for SmartHomeNG'
port = 0
@@ -47,8 +49,7 @@ def __init__(self, sh, testparam=''):
self.logger = logging.getLogger(__name__)
self._sh = sh
self.shtime = Shtime.get_instance()
- self.logger.debug("Module '{}': Initializing".format(self._shortname))
-
+ self.logger.debug(f"Module '{self._shortname}': Initializing")
# Test if http module is loaded (if the module uses http)
# try:
@@ -63,20 +64,18 @@ def __init__(self, sh, testparam=''):
#
# self._showtraceback = self.mod_http._showtraceback
-
# get the parameters for the module (as defined in metadata module.yaml):
- self.logger.debug("Module '{}': Parameters = '{}'".format(self._shortname, dict(self._parameters)))
+ self.logger.debug(f"Module '{self._shortname}': Parameters = '{dict(self._parameters)}'")
try:
# self.broker_ip = self._parameters['broker_host']
pass
except KeyError as e:
self.logger.critical(
- "Module '{}': Inconsistent module (invalid metadata definition: {} not defined)".format(self._shortname, e))
+ f"Module '{self._shortname}': Inconsistent module (invalid metadata definition: {e} not defined)")
self._init_complete = False
return
- ip = get_local_ipv4_address()
-
+ ip = Utils.get_local_ipv4_address() # remove line if `ip` unused
def start(self):
"""
@@ -87,7 +86,6 @@ def start(self):
"""
pass
-
def stop(self):
"""
If the module has started threads or uses python modules that created threads,
@@ -99,33 +97,6 @@ def stop(self):
pass
-
-def get_local_ipv4_address():
- """
- Get's local ipv4 address of the interface with the default gateway.
- Return '127.0.0.1' if no suitable interface is found
-
- :return: IPv4 address as a string
- :rtype: string
- """
- s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
- try:
- s.connect(('8.8.8.8', 1))
- IP = s.getsockname()[0]
- except:
- IP = '127.0.0.1'
- finally:
- s.close()
- return IP
-
-
def translate(s):
+ # needed for AdminUI
return s
-
-
-#import socket
-
-#from lib.plugin import Plugins
-#from lib.utils import Utils
-
-
diff --git a/dev/sample_module/module.yaml b/dev/sample_module/module.yaml
index 3cd752a847..7c89233ccd 100644
--- a/dev/sample_module/module.yaml
+++ b/dev/sample_module/module.yaml
@@ -2,8 +2,8 @@
module:
# Global plugin attributes
classname: SampleModule
- version: 1.7.0
- sh_minversion: 1.7
+ version: 1.0.0
+ sh_minversion: 1.8
# sh_maxversion: # maximum shNG version to use this module (leave empty if latest)
# py_minversion: 3.6 # minimum Python version to use for this module
# py_maxversion: # maximum Python version to use for this module (leave empty if latest)
diff --git a/dev/sample_mqttplugin/__init__.py b/dev/sample_mqttplugin/__init__.py
index b4baa8d9a0..aac813ddd2 100644
--- a/dev/sample_mqttplugin/__init__.py
+++ b/dev/sample_mqttplugin/__init__.py
@@ -25,7 +25,7 @@
#
#########################################################################
-from lib.model.mqttplugin import *
+from lib.model.mqttplugin import MqttPlugin
from lib.item import Items
from .webif import WebInterface
@@ -41,7 +41,7 @@ class SampleMqttPlugin(MqttPlugin):
the update functions for the items
"""
- PLUGIN_VERSION = '1.7.0' # (must match the version specified in plugin.yaml), use '1.0.0' for your initial plugin Release
+ PLUGIN_VERSION = '1.0.0' # (must match the version specified in plugin.yaml), use '1.0.0' for your initial plugin Release
def __init__(self, sh):
"""
@@ -69,7 +69,7 @@ def __init__(self, sh):
# return
# if plugin should start even without web interface
- self.init_webinterface()
+ self.init_webinterface(WebInterface)
return
@@ -108,7 +108,7 @@ def parse_item(self, item):
can be sent to the knx with a knx write function within the knx plugin.
"""
if self.has_iattr(item.conf, 'foo_itemid'):
- self.logger.debug("parse item: {}".format(item))
+ self.logger.debug(f"parse item: {item.property.path}")
# subscribe to topic for relay state
# mqtt_id = self.get_iattr_value(item.conf, 'foo_itemid').upper()
@@ -154,13 +154,10 @@ def update_item(self, item, caller=None, source=None, dest=None):
if self.alive and caller != self.get_shortname():
# code to execute if the plugin is not stopped
# and only, if the item has not been changed by this this plugin:
- self.logger.info("Update item: {}, item has been changed outside this plugin".format(item.id()))
+ self.logger.info(f"Update item: {item.property.path}, item has been changed outside this plugin")
if self.has_iattr(item.conf, 'foo_itemtag'):
self.logger.debug(
- "update_item was called with item '{}' from caller '{}', source '{}' and dest '{}'".format(item,
- caller,
- source,
- dest))
+ f"update_item was called with item {item.property.path} from caller {caller}, source {source} and dest {dest}")
pass
diff --git a/dev/sample_mqttplugin/mqtt_shelly_example_simple.py b/dev/sample_mqttplugin/mqtt_shelly_example_simple.py
index d1f2a9a30e..11b30fedbc 100644
--- a/dev/sample_mqttplugin/mqtt_shelly_example_simple.py
+++ b/dev/sample_mqttplugin/mqtt_shelly_example_simple.py
@@ -29,8 +29,9 @@
import json
from lib.module import Modules
-from lib.model.mqttplugin import *
+from lib.model.mqttplugin import MqttPlugin
from lib.item import Items
+from .webif import WebInterface
class Shelly(MqttPlugin):
@@ -66,8 +67,8 @@ def __init__(self, sh):
# Initialization code goes here
self.shelly_items = [] # to hold item information for web interface
- # if plugin should start even without web interface
- self.init_webinterface()
+ # if plugin should start even without web interface
+ self.init_webinterface(WebInterface)
return
@@ -112,7 +113,7 @@ def parse_item(self, item):
can be sent to the knx with a knx write function within the knx plugin.
"""
if self.has_iattr(item.conf, 'shelly_id'):
- self.logger.debug("parsing item: {0}".format(item.id()))
+ self.logger.debug(f"parsing item: {item}")
shelly_id = self.get_iattr_value(item.conf, 'shelly_id').upper()
shelly_type = self.get_iattr_value(item.conf, 'shelly_type').lower()
@@ -125,7 +126,7 @@ def parse_item(self, item):
# subscribe to topic for relay state
topic = 'shellies/' + shelly_type + '-' + shelly_id + '/relay/' + shelly_relay
payload_type = item.property.type
- bool_values = ['off','on']
+ bool_values = ['off', 'on']
self.add_subscription(topic, payload_type, bool_values, item=item)
return self.update_item
@@ -153,12 +154,12 @@ def update_item(self, item, caller=None, source=None, dest=None):
:param source: if given it represents the source
:param dest: if given it represents the dest
"""
- self.logger.info("update_item: {}".format(item.id()))
+ self.logger.info(f"update_item: {item}")
if self.alive and caller != self.get_shortname():
# code to execute if the plugin is not stopped
# and only, if the item has not been changed by this this plugin:
- self.logger.info("update_item: {}, item has been changed outside this plugin".format(item.id()))
+ self.logger.info(f"update_item: {item}, item has been changed outside this plugin")
# publish topic with new relay state
shelly_id = self.get_iattr_value(item.conf, 'shelly_id').upper()
@@ -167,118 +168,4 @@ def update_item(self, item, caller=None, source=None, dest=None):
if not shelly_relay:
shelly_relay = '0'
topic = 'shellies/' + shelly_type + '-' + shelly_id + '/relay/' + shelly_relay + '/command'
- self.publish_topic(topic, item(), item, bool_values=['off','on'])
-
- # -----------------------------------------------------------------------
-
- def init_webinterface(self):
- """"
- Initialize the web interface for this plugin
-
- This method is only needed if the plugin is implementing a web interface
- """
- try:
- self.mod_http = Modules.get_instance().get_module('http') # try/except to handle running in a core version that does not support modules
- except:
- self.mod_http = None
- if self.mod_http == None:
- self.logger.error("Not initializing the web interface")
- return False
-
- import sys
- if not "SmartPluginWebIf" in list(sys.modules['lib.model.smartplugin'].__dict__):
- self.logger.warning("Web interface needs SmartHomeNG v1.5 and up. Not initializing the web interface")
- return False
-
- # set application configuration for cherrypy
- webif_dir = self.path_join(self.get_plugin_dir(), 'webif')
- config = {
- '/': {
- 'tools.staticdir.root': webif_dir,
- },
- '/static': {
- 'tools.staticdir.on': True,
- 'tools.staticdir.dir': 'static'
- }
- }
-
- # Register the web interface as a cherrypy app
- self.mod_http.register_webif(WebInterface(webif_dir, self),
- self.get_shortname(),
- config,
- self.get_classname(), self.get_instance_name(),
- description='')
-
- return True
-
-
-
-# -----------------------------------------------------------------------
-# Webinterface of the plugin
-# -----------------------------------------------------------------------
-
-import cherrypy
-from jinja2 import Environment, FileSystemLoader
-
-
-class WebInterface(SmartPluginWebIf):
-
- def __init__(self, webif_dir, plugin):
- """
- Initialization of instance of class WebInterface
-
- :param webif_dir: directory where the webinterface of the plugin resides
- :param plugin: instance of the plugin
- :type webif_dir: str
- :type plugin: object
- """
- self.logger = logging.getLogger(__name__)
- self.webif_dir = webif_dir
- self.plugin = plugin
- self.tplenv = self.init_template_environment()
-
- self.items = Items.get_instance()
-
- @cherrypy.expose
- def index(self, reload=None):
- """
- Build index.html for cherrypy
-
- Render the template and return the html file to be delivered to the browser
-
- :return: contents of the template after beeing rendered
- """
- self.plugin.get_broker_info()
-
- tmpl = self.tplenv.get_template('index.html')
- # add values to be passed to the Jinja2 template eg: tmpl.render(p=self.plugin, interface=interface, ...)
- return tmpl.render(p=self.plugin, items=sorted(self.items.return_items(), key=lambda k: str.lower(k['_path'])))
-
-
- @cherrypy.expose
- def get_data_html(self, dataSet=None):
- """
- Return data to update the webpage
-
- For the standard update mechanism of the web interface, the dataSet to return the data for is None
-
- :param dataSet: Dataset for which the data should be returned (standard: None)
- :return: dict with the data needed to update the web page.
- """
- if dataSet is None:
- # get the new data
- self.plugin.get_broker_info()
- data = {}
- data['broker_info'] = self.plugin._broker
- data['broker_uptime'] = self.plugin.broker_uptime()
- data['item_values'] = self.plugin._item_values
-
- # return it as json the the web page
- try:
- return json.dumps(data)
- except Exception as e:
- self.logger.error("get_data_html exception: {}".format(e))
- return {}
-
- return
-
+ self.publish_topic(topic, item(), item, bool_values=['off', 'on'])
diff --git a/dev/sample_mqttplugin/plugin.yaml b/dev/sample_mqttplugin/plugin.yaml
index 7ed9e10da3..cd93fae97f 100644
--- a/dev/sample_mqttplugin/plugin.yaml
+++ b/dev/sample_mqttplugin/plugin.yaml
@@ -12,12 +12,12 @@ plugin:
# documentation: https://github.com/smarthomeNG/smarthome/wiki/CLI-Plugin # url of documentation (wiki) page
# support: https://knx-user-forum.de/forum/supportforen/smarthome-py
- version: 1.7.0 # Plugin version
- sh_minversion: 1.7 # minimum shNG version to use this plugin
+ version: 1.0.0 # Plugin version
+ sh_minversion: 1.8 # minimum shNG version to use this plugin
# sh_maxversion: # maximum shNG version to use this plugin (leave empty if latest)
# py_minversion: 3.6 # minimum Python version to use for this plugin
# py_maxversion: # maximum Python version to use for this plugin (leave empty if latest)
- multi_instance: False # plugin supports multi instance
+ multi_instance: false # plugin supports multi instance
restartable: unknown
classname: SamplePlugin # class containing the plugin
diff --git a/dev/sample_mqttplugin/webif/__init__.py b/dev/sample_mqttplugin/webif/__init__.py
index 2e0335785e..6bd998cd0a 100644
--- a/dev/sample_mqttplugin/webif/__init__.py
+++ b/dev/sample_mqttplugin/webif/__init__.py
@@ -70,6 +70,8 @@ def index(self, reload=None):
:return: contents of the template after beeing rendered
"""
+ self.plugin.get_broker_info()
+
tmpl = self.tplenv.get_template('index.html')
# add values to be passed to the Jinja2 template eg: tmpl.render(p=self.plugin, interface=interface, ...)
return tmpl.render(p=self.plugin,
@@ -89,16 +91,18 @@ def get_data_html(self, dataSet=None):
"""
if dataSet is None:
# get the new data
+ self.plugin.get_broker_info()
data = {}
+ data['broker_info'] = self.plugin._broker
+ data['broker_uptime'] = self.plugin.broker_uptime()
+ data['item_values'] = self.plugin._item_values
- # data['item'] = {}
- # for i in self.plugin.items:
- # data['item'][i]['value'] = self.plugin.getitemvalue(i)
- #
# return it as json the the web page
- # try:
- # return json.dumps(data)
- # except Exception as e:
- # self.logger.error("get_data_html exception: {}".format(e))
- return {}
+ try:
+ return json.dumps(data)
+ except Exception as e:
+ self.logger.error("get_data_html exception: {}".format(e))
+ return {}
+
+ return
diff --git a/dev/sample_plugin/__init__.py b/dev/sample_plugin/__init__.py
index ce45afa689..8b47bbe00f 100644
--- a/dev/sample_plugin/__init__.py
+++ b/dev/sample_plugin/__init__.py
@@ -7,7 +7,7 @@
# https://www.smarthomeNG.de
# https://knx-user-forum.de/forum/supportforen/smarthome-py
#
-# Sample plugin for new plugins to run with SmartHomeNG version 1.5 and
+# Sample plugin for new plugins to run with SmartHomeNG version 1.8 and
# upwards.
#
# SmartHomeNG is free software: you can redistribute it and/or modify
@@ -25,7 +25,7 @@
#
#########################################################################
-from lib.model.smartplugin import *
+from lib.model.smartplugin import SmartPlugin
from lib.item import Items
from .webif import WebInterface
@@ -39,9 +39,13 @@ class SamplePlugin(SmartPlugin):
"""
Main class of the Plugin. Does all plugin specific stuff and provides
the update functions for the items
+
+ HINT: Please have a look at the SmartPlugin class to see which
+ class properties and methods (class variables and class functions)
+ are already available!
"""
- PLUGIN_VERSION = '1.7.1' # (must match the version specified in plugin.yaml), use '1.0.0' for your initial plugin Release
+ PLUGIN_VERSION = '1.0.0' # (must match the version specified in plugin.yaml), use '1.0.0' for your initial plugin Release
def __init__(self, sh):
"""
@@ -115,10 +119,11 @@ def parse_item(self, item):
can be sent to the knx with a knx write function within the knx plugin.
"""
if self.has_iattr(item.conf, 'foo_itemtag'):
- self.logger.debug("parse item: {}".format(item))
+ self.logger.debug(f"parse item: {item}")
# todo
# if interesting item for sending values:
+ # self._itemlist.append(item)
# return self.update_item
def parse_logic(self, logic):
@@ -145,11 +150,10 @@ def update_item(self, item, caller=None, source=None, dest=None):
if self.alive and caller != self.get_shortname():
# code to execute if the plugin is not stopped
# and only, if the item has not been changed by this this plugin:
- self.logger.info("Update item: {}, item has been changed outside this plugin".format(item.id()))
+ self.logger.info(f"Update item: {item.property.path}, item has been changed outside this plugin")
if self.has_iattr(item.conf, 'foo_itemtag'):
- self.logger.debug("update_item was called with item '{}' from caller '{}', source '{}' and dest '{}'".format(item,
- caller, source, dest))
+ self.logger.debug(f"update_item was called with item {item.property.path} from caller {caller}, source {source} and dest {dest}")
pass
def poll_device(self):
@@ -175,5 +179,3 @@ def poll_device(self):
# # the source should be included when updating the the value:
# item(device_value, self.get_shortname(), source=device_source_id)
pass
-
-
diff --git a/dev/sample_plugin/plugin.yaml b/dev/sample_plugin/plugin.yaml
index d9248b2318..17cda20d27 100644
--- a/dev/sample_plugin/plugin.yaml
+++ b/dev/sample_plugin/plugin.yaml
@@ -12,12 +12,12 @@ plugin:
# documentation: https://github.com/smarthomeNG/smarthome/wiki/CLI-Plugin # url of documentation (wiki) page
# support: https://knx-user-forum.de/forum/supportforen/smarthome-py
- version: 1.7.1 # Plugin version (must match the version specified in __init__.py)
- sh_minversion: 1.5 # minimum shNG version to use this plugin
+ version: 1.0.0 # Plugin version (must match the version specified in __init__.py)
+ sh_minversion: 1.8 # minimum shNG version to use this plugin
# sh_maxversion: # maximum shNG version to use this plugin (leave empty if latest)
# py_minversion: 3.6 # minimum Python version to use for this plugin
# py_maxversion: # maximum Python version to use for this plugin (leave empty if latest)
- multi_instance: False # plugin supports multi instance
+ multi_instance: false # plugin supports multi instance
restartable: unknown
classname: SamplePlugin # class containing the plugin
@@ -45,7 +45,7 @@ parameters:
param3:
type: str
# If 'mandatory' is specified, a 'default' attribute must not be specified
- mandatory: True
+ mandatory: true
description:
de: 'Demo Parameter der angegeben werden muss'
en: 'Demonstration parameter which has to be specified'
diff --git a/dev/sample_plugin/user_doc.rst b/dev/sample_plugin/user_doc.rst
index 18e218c0a2..fdfdbd311e 100644
--- a/dev/sample_plugin/user_doc.rst
+++ b/dev/sample_plugin/user_doc.rst
@@ -60,7 +60,8 @@ Hier können ausführlichere Beispiele und Anwendungsfälle beschrieben werden.
Web Interface
-------------
+Die Datei ``dev/sample_plugin/webif/templates/index.html`` sollte als Grundlage für Webinterfaces genutzt werden. Um Tabelleninhalte nach Spalten filtern und sortieren zu können, muss der entsprechende Code Block mit Referenz auf die relevante Table ID eingefügt werden (siehe Doku).
+
SmartHomeNG liefert eine Reihe Komponenten von Drittherstellern mit, die für die Gestaltung des Webinterfaces genutzt werden können. Erweiterungen dieser Komponenten usw. finden sich im Ordner ``/modules/http/webif/gstatic``.
Wenn das Plugin darüber hinaus noch Komponenten benötigt, werden diese im Ordner ``webif/static`` des Plugins abgelegt.
-
\ No newline at end of file
diff --git a/dev/sample_plugin/webif/templates/index.html b/dev/sample_plugin/webif/templates/index.html
index 0d49ce7ded..421d07c4f6 100644
--- a/dev/sample_plugin/webif/templates/index.html
+++ b/dev/sample_plugin/webif/templates/index.html
@@ -15,14 +15,37 @@
var objResponse = JSON.parse(response);
myProto = document.getElementById(dataSet);
for (var device in objResponse) {
-
+ */
}
}
}
+
+
{% endblock pluginscripts %}
@@ -70,7 +93,7 @@
{% endblock %}
{% set tabcount = 4 %}
@@ -90,6 +113,36 @@
{% block bodytab1 %}
| {{ _('Item') }} | +{{ _('Wert') }} | +
|---|---|
| {{ item._path }} | +{{ item() }} | +
| {{ _('Item') }} | @@ -88,8 +90,30 @@ To bring the webinterface up to life, the following steps should be followed: - 3. The logo on the topleft is automatically replaced with the logo of the **plugin type**. - If the webinterface should have an individaul logo, the file with the logo must be placed in - the directory **webif/static/img** and has to be named **plugin_logo**. It may be of type **.png**, **.jpg** or **.svg**. + 3. Add the following script code between ``{% block pluginscripts %}`` and + ``{% endblock pluginscripts %}`` to enable filtering and sorting of the tables. + The code ``$('#maintable').DataTable( { "paging": false, fixedHeader: true } );`` + has to be copied for every table using the sort/filter feature! + Make sure to adapt the table id (#maintable) accordingly: + .. code-block:: HTML + + + 4. The logo on the topleft is automatically replaced with the logo of the **plugin type**. + If the webinterface should have an individaul logo, the file with the logo must be placed in + the directory **webif/static/img** and has to be named **plugin_logo**. It may be of type **.png**, **.jpg** or **.svg**. diff --git a/doc/developer/source/requirements.rst b/doc/developer/source/requirements.rst index ca2416885f..82e6891045 100644 --- a/doc/developer/source/requirements.rst +++ b/doc/developer/source/requirements.rst @@ -30,4 +30,3 @@ If using a hardware platform without buffered real time clock it is mandatory to Otherwise SmartHomeNG will not start due to missing time information. Some libraries within SmartHomeNG still use functions depending on Unix flavour. -Thus SmartHomeNG does not run on Windows and MacOS right now. diff --git a/doc/requirements.txt b/doc/requirements.txt index f81c958c61..07c78bf22d 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,11 +1,29 @@ -sphinx>=3.0 +sphinx>=3.1,<4 sphinx-rtd-theme -recommonmark>=0.6.0 + +# create tabs for content for alternative ways to use like | Linux | MacOS | Windows | +# https://sphinx-tabs.readthedocs.io/en/latest/ +sphinx-tabs + +# the following extensions create collapsible parts of documentation +# sphinx-panels seem to be most extensive +#sphinx-togglebutton +#sphinx-toolbox +#sphinx-panels https://sphinx-panels.readthedocs.io/en/latest/ + +# recommonmark is marked deprecated as of April 30th, 2021 +#recommonmark>=0.6.0 +# the replacement to support Markdown like Readme.md is MyST +# see at https://www.sphinx-doc.org/en/master/usage/markdown.html and +# at https://myst-parser.readthedocs.io/en/latest/using/intro.html for a primer on MyST +myst-parser ruamel.yaml>=0.13.7,<=0.15.74;python_version<'3.7' ruamel.yaml>=0.15.0,<=0.15.74;python_version=='3.7' ruamel.yaml>=0.15.78,<=0.16.8;python_version>='3.8' -# to create pdf files install also +# to create pdf files it would be needed to install also # rst2pdf -# svglib \ No newline at end of file +# svglib +# but there is no fully working lib to convert svg to pdf currently so we can +# not create pdf files at the moment diff --git a/doc/user/source/_static/img/SmarthomeNG_V1.8.0.svg b/doc/user/source/_static/img/SmarthomeNG_V1.8.0.svg new file mode 100644 index 0000000000..c47d2b495f --- /dev/null +++ b/doc/user/source/_static/img/SmarthomeNG_V1.8.0.svg @@ -0,0 +1,2885 @@ + diff --git a/doc/user/source/admin/admin.rst b/doc/user/source/admin/admin.rst index a5e2e09956..5c7059a470 100644 --- a/doc/user/source/admin/admin.rst +++ b/doc/user/source/admin/admin.rst @@ -13,21 +13,8 @@ Administrations-Interface :greensup:`Update` ============================================ -Seit SmartHomeNG v1.2 steht eine graphische Oberfläche zur Verfügung, die bei der Administration -von SmartHomeNG hilft. Dazu implementiert SmartHomeNG einen eigenen Webserver, der in der Standardkonfiguration -auf **Port 8383** hört. - -Diese Oberfläche wurde bisher durch das **Backend Plugin** zur Verfügung gestellt. Das Backend Plugin ist unter -:doc:`/plugins/backend/user_doc` ausführlich beschrieben. Es wird jedoch in einer der kommenden Versionen entfernt, -da seit v1.6 ein neues graphisches Administrations-Interface zur Verfügung steht, welches eine Weiterentwicklung des -Backend Plugins ist und in der Funktionalität über die Möglichkeiten des Backend Plugins hinausgeht. - -Während das Backend Plugin vorwiegend zur Anzeige von Informationen über die SmartHomeNG Installation diente, ermöglicht -das Admin-Interface nach die vollständige Konfiguration von SmartHomeNG. - -Um einen problemlosen Übergang zu gewährleisten, steht das Backend Plugin für einen Übergangszeit weiter zur Verfügung. -Es ist als deprecated (veraltet) eingestuft und wird voraussichtlich mit v1.8 von SmartHomeNG entfernt. - +Seit SmartHomeNG v1.6 steht ein graphisches Administrations-Interface zur Verfügung, welches die vollständige +Administration von SmartHomeNG ermöglicht. Das Administrations-Interface wird durch folgenden Aufruf gestartet: @@ -37,7 +24,7 @@ Das Administrations-Interface wird durch folgenden Aufruf gestartet: Über die Systemkonfiguration kann eingestellt werden, dass ```http://
|---|
| {{ _('Item') }} | @@ -85,4 +87,29 @@ Die folgenden Schritte dienen dazu, das Webinterface mit Leben zu füllen: - 3. Das Logo oben links auf der Seite wird automatisch durch das Logo des konfigurierten Plugin-Typs ersetzt. Wenn das Webinterface ein eigenes Logo mitbringen soll, muss das entsprechende Bild im Verzeichnis ``webif/static/img`` mit dem Namen ``plugin_logo`` abgelegt sein. Die zulässigen Dateiformate sind **.png**, **.jpg** oder **.svg**. Dabei sollte die Größe der Bilddatei die Größe des angezeigten Logos (derzeit ca. 180x150 Pixel) nicht überschreiten, um unnötige Datenübertragungen zu vermeiden. + 3. Folgender Script Code muss zwischen ``{% block pluginscripts %}`` und + ``{% endblock pluginscripts %}`` eingefügt werden, um ein Filtern und Sortieren + der Tabellen zu ermöglichen. + Der Code ``$('#maintable').DataTable( { "paging": false, fixedHeader: true } );`` + muss für jede Tabelle, für die Filtern/Sortieren ermöglicht werden soll, kopiert werden. + Dabei ist sicher zu stellen, dass die ID (#maintable) jeweils richtig angepasst wird: + + .. code-block:: HTML + + + + 4. Das Logo oben links auf der Seite wird automatisch durch das Logo des konfigurierten Plugin-Typs ersetzt. Wenn das Webinterface ein eigenes Logo mitbringen soll, muss das entsprechende Bild im Verzeichnis ``webif/static/img`` mit dem Namen ``plugin_logo`` abgelegt sein. Die zulässigen Dateiformate sind **.png**, **.jpg** oder **.svg**. Dabei sollte die Größe der Bilddatei die Größe des angezeigten Logos (derzeit ca. 180x150 Pixel) nicht überschreiten, um unnötige Datenübertragungen zu vermeiden. diff --git a/doc/user/source/index.rst b/doc/user/source/index.rst index da0254d52a..19069cb7fb 100644 --- a/doc/user/source/index.rst +++ b/doc/user/source/index.rst @@ -7,7 +7,7 @@ SmartHomeNG Anwenderdokumentation ===================== -SmartHomeNG [#f1]_ ist ein System das als Metagateway zwischen verschiedenen "Dingen" fungiert und +SmartHomeNG ist ein System das als Metagateway zwischen verschiedenen "Dingen" fungiert und dient der Verbindung unterschiedlicher Geräte-Schnittstellen. Die Standard-Schnittstelle eines Gerätes wird durch das Metagateway so um viele zusätzliche Schnittstellen erweitert. So ist es möglich dass die Klingel mit der Musikanlage und TV spricht, und dessen Wiedergabe unterbricht @@ -35,8 +35,6 @@ oder im `Chat auf gitter.im
|---|