Merge pull request #847 from onkelandy/withings

withings_health: Small update and user_doc conversion

withings_health/__init__.py

@@ -7,8 +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
-#  upwards.
+#  Plugin for withings health devices
 #
 #  SmartHomeNG is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -37,7 +36,7 @@
 
 
 class WithingsHealth(SmartPlugin):
-    PLUGIN_VERSION = "1.8.2"
+    PLUGIN_VERSION = "1.8.3"
 
     def __init__(self, sh):
         super().__init__()
@@ -129,8 +128,10 @@ def _update(self):
                         userid=self._user_id,
                         client_id=self._client_id,
                         consumer_secret=self._consumer_secret)
-
-                    self._client = WithingsApi(self._creds, refresh_cb=self._store_tokens)
+                    try:
+                        self._client = WithingsApi(self._creds, refresh_cb=self._store_tokens)
+                    except Exception as e:
+                        self.logger.error("Client can not be initialized.")
                 else:
                     self.logger.error(
                         "Token is expired, run OAuth2 again from Web Interface (Expiry Date: {}).".format(

withings_health/plugin.yaml

@@ -9,10 +9,9 @@ plugin:
     tester: 'psilo909'
     state: ready
     keywords: health
-    documentation: 'http://smarthomeng.de/user/plugins_doc/config/withings_health.html'
     support: 'https://knx-user-forum.de/forum/supportforen/smarthome-py/1141179-nokia-health-plugin'
 
-    version: 1.8.2                 # Plugin version
+    version: 1.8.3                 # Plugin version
     sh_minversion: 1.7             # minimum shNG version to use this plugin
 #    sh_maxversion:                # maximum shNG version to use this plugin (leave empty if latest)
     multi_instance: True           # plugin supports multi instance
@@ -38,7 +37,6 @@ parameters:
 
     consumer_secret:
         type: str
-        default: 300
         mandatory: True
         description:
             de: 'Consumer-Geheimnis von https://account.health.nokia.com/partner/dashboard_oauth2'

withings_health/user_doc.rst

@@ -0,0 +1,152 @@
+.. index:: Plugins; withings_health
+.. index:: withings_health
+
+===============
+withings_health
+===============
+
+.. image:: webif/static/img/plugin_logo.png
+   :alt: plugin logo
+   :width: 300px
+   :height: 300px
+   :scale: 50 %
+   :align: left
+
+Dieses Plugin ermöglicht den Abruf von Daten aus der Withings (ehemals Nokia)
+`Health API (https://developer.withings.com/api)`_. Derzeit bietet es nur
+Unterstützung für den "Withings WS-50 Smart Body Analyzer", eine WLAN-fähige Waage.
+
+
+Vorbereitung
+============
+
+Dieses Plugin benötigt die withings-api.
+
+Sie müssen sich unter `Withings Account (https://account.withings.com/)`_ registrieren und im Dashboard
+eine Applikation anlegen. Der Name ist frei wählbar, die (lokale) Callback-URL wird über die Weboberfläche des Plugins angezeigt: <http://<IP>:<Webinterface-Port>/plugin/withings_health.
+Wenn Sie sich bei der `Withings App (https://app.withings.com/)`_ einloggen, kann die achtstellige Zahl
+in der URL ausgelesen und in der Pluginkonfiguration als user_id angegeben werden.
+
+Weiters muss das Plugin struct mittles ``struct: withings_health.body`` eingebunden werden.
+
+Der OAuth2-Prozess muss dann über die Weboberfläche des
+Plugins ausgelöst werden. Daher müssen zumindest die ersten vier Elemente des folgenden Beispiels
+vorhanden sein müssen (access_token, token_expiry, token_type, refresh_token).
+
+Falls Ihre SmartHomeNG-Instanz zu lange offline ist, verfallen die Token.
+Sie müssen dann den OAuth2-Prozess über das Webinterface neu starten. In diesem Fall werden Fehler protokolliert!
+
+Konfiguration
+=============
+
+.. important::
+
+      Detaillierte Informationen zur Konfiguration des Plugins sind unter :doc:`/plugins_doc/config/withings_health` zu finden.
+
+
+plugin.yaml
+-----------
+
+.. code-block:: yaml
+
+   withings_health:
+       plugin_name: withings_health
+       user_id: <your user id>
+       client_id: <your client id>
+       consumer_secret: <your consumer secret>
+       cycle: 300
+       instance: withings_health
+
+
+items.yaml
+----------
+
+Bitte beachten Sie, dass es Abhängigkeiten bei den Werten gibt. So wird z.B. der
+Körpermaßindex nur berechnet, wenn eine Körpergröße vorhanden ist. Diese wird nur einmal übertragen, nämlich
+wenn die Waage das erste Mal mit den Withings (ehemals Nokia) Servern kommuniziert.
+Notfalls muss der Wert manuell hinterlegt werden.
+
+Die ersten vier Elemente sind obligatorisch, da sie für OAuth2-Daten benötigt werden!
+Die sinnvollste Herangehensweise ist hier, das Plugin struct ``body`` komplett zu integrieren.
+
+.. code-block:: yaml
+
+   body:
+
+       access_token:
+           type: str
+           visu_acl: ro
+           cache: yes
+           withings_type@withings_health: access_token
+
+       token_expiry:
+           type: num
+           visu_acl: ro
+           cache: yes
+           withings_type@withings_health: token_expiry
+
+       token_type:
+           type: str
+           visu_acl: ro
+           cache: yes
+           withings_type@withings_health: token_type
+
+       refresh_token:
+           type: str
+           visu_acl: ro
+           cache: yes
+           withings_type@withings_health: refresh_token
+
+       weight:
+           type: num
+           visu_acl: ro
+           withings_type@withings_health: weight
+
+       height:
+           type: num
+           visu_acl: ro
+           withings_type@withings_health: height
+
+       bmi:
+           type: num
+           visu_acl: ro
+           withings_type@withings_health: bmi
+
+       bmi_text:
+           type: str
+           visu_acl: ro
+           withings_type@withings_health: bmi_text
+
+       fat_ratio:
+           type: num
+           visu_acl: ro
+           withings_type@withings_health: fat_ratio
+
+       fat_free_mass:
+           type: num
+           visu_acl: ro
+           withings_type@withings_health: fat_free_mass
+
+       fat_mass_weight:
+           type: num
+           visu_acl: ro
+           withings_type@withings_health: fat_mass_weight
+
+       heart_rate:
+           type: num
+           visu_acl: ro
+           withings_type@withings_health: heart_rate
+
+Web Interface
+=============
+
+Das Webinterface sollte zur erstmaligen Herstellung der Verbindung (Authentifizierung) genutzt werden.
+
+Außerdem werden die Informationen zu den passenden Items angezeigt.
+
+.. image:: assets/withings_webif.png
+   :height: 1656px
+   :width: 3328px
+   :scale: 25%
+   :alt: Web Interface
+   :align: center

withings_health/webif/__init__.py

@@ -105,11 +105,17 @@ def index(self, reload=None, state=None, code=None, error=None):
                 self.plugin._client = None
 
         tmpl = self.tplenv.get_template('index.html')
+        try:
+            token_expiry_val = datetime.datetime.fromtimestamp(
+                self.plugin.get_item('token_expiry').property.value, tz=self.plugin.shtime.tzinfo())
+        except Exception as e:
+            self.logger.error("Please integrate the plugin struct to make the plugin work correctly.")
+            token_expiry_val = 0
         return tmpl.render(plugin_shortname=self.plugin.get_shortname(), plugin_version=self.plugin.get_version(),
                            interface=None, item_count=len(self.plugin.get_items()),
                            plugin_info=self.plugin.get_info(), tabcount=2, callback_url=self.plugin.get_callback_url(),
                            tab1title="Withings Health Items (%s)" % len(self.plugin.get_items()),
                            tab2title="OAuth2 Data", authorize_url=self._auth.get_authorize_url(),
-                           p=self.plugin, token_expiry=datetime.datetime.fromtimestamp(self.plugin.get_item(
-                'token_expiry')(), tz=self.plugin.shtime.tzinfo()), now=self.plugin.shtime.now(), code=code,
+                           p=self.plugin, token_expiry=token_expiry_val,
+                           now=self.plugin.shtime.now(), code=code,
                            state=state, reload=reload, language=self.plugin.get_sh().get_defaultlanguage())

withings_health/webif/templates/index.html

@@ -93,7 +93,7 @@ <h5>{{ _('Withings Health Items') }} ({{ p.get_items()|length }})</h5>
 			{{ _('OAuth2 Authorization URL') }}
 		</td>
 		<td class="py-1" colspan="3">
-			{{ _('Hier zuerst registrieren:') }} <a class="text-shng" href="https://account.withings.com/partner/add_oauth2" target="_blank">https://account.withings.com/partner/add_oauth2</a><br/>
+			<a class="text-shng" href="https://account.withings.com/partner/add_oauth2" target="_blank">{{ _('Hier zuerst registrieren') }} </a><br/>
 			<a class="text-shng" href="{{ authorize_url }}" target="_blank">{{ _('Hier klicken, um OAuth2 Prozess zu starten!') }}</a>
 		</td>
 	</tr>
@@ -118,4 +118,4 @@ <h5>{{ _('Withings Health Items') }} ({{ p.get_items()|length }})</h5>
 		<td class="py-1">{{ p.get_item('refresh_token')() }}</td>
 	</tr>
 </table>
-{% endblock %}
+{% endblock %}