diff --git a/.gitignore b/.gitignore index 000d0ac..de318ad 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,7 @@ Thumbs.db # i18n intermediate files admin/i18n/flat.txt -admin/i18n/*/flat.txt \ No newline at end of file +admin/i18n/*/flat.txt + +# ioBroker dev-server +.dev-server/ diff --git a/README.md b/README.md index b496f9b..8dd961a 100644 --- a/README.md +++ b/README.md @@ -27,185 +27,11 @@ Please use the "adapter list" in ioBroker to install a stable version of this ad iobroker add lametric ``` -## Configuration +## Documentation -Tested with LaMetric firmware *2.2.2* (recommended) +[🇺🇸 Documentation](./docs/en/basics.md) -You can get your personal key [here](https://developer.lametric.com/). - -![api-key](docs/apiKey.png) - -## Features - -- Set display brightness (percent, auto-mode/manual-mode) -- Set audio volume (percent) -- Configure screensaver (enable/disable, time based, when dark) -- Activate/Deactivate bluetooth and change bluetooth name -- Switch between apps (next, previous, go to specific app) -- Send notifications with blockly (with configurable priority, sound, icons, text, ...) -- Control special apps like clock, radio, stopwatch or weather -- Use *My Data (DIY)* LaMetric App to display persistent information - -Features are limited by the [official API features](https://lametric-documentation.readthedocs.io/en/latest/reference-docs/lametric-time-reference.html). - -## Blockly Examples - -You can use a simple string as message, which will be shown as a single frame - -![single frame](docs/blockly1.png) - -To show multiple frames, you can also provide an array as message - -![multiple frames](docs/blockly2.png) - -If you want to use chart frames, you have to specify an array of numbers as a frame - -![chart data frames](docs/blockly3.png) - -## My Data (DIY) *(version > 1.1.0)* - -LaMetric offers an app (on the integrated app market) to poll custom data. This app is called [My Data DIY](https://apps.lametric.com/apps/my_data__diy_/8942). This adapter creates a new state in the required format. -You can use the Simple API Adapter to transfer the data to the LaMetric Time. - -```ioBroker LaMetric Adapter -> State with Frame information <- Simple API Adapter <- My Data DIY App <- LaMetric``` - -### Configuration (with authentication) - -1. Install the [Simple API ioBroker Adapter](https://github.com/ioBroker/ioBroker.simple-api) -2. Create a new ioBroker user called "lametric" with a custom password (e.g. HhX7dZl3Fe) -3. Add the "lametric" user to the group "users" -4. Install this *My Data DIY* App on your LaMetric Time (use Market) -5. Open the *My Data (DIY)* app settings and configure the simple api url (see below) -6. Go to the adapter configuration and configure the frames with your custom information (icon and text) - -``` -http://172.16.0.219:8087/getPlainValue/lametric.0.mydatadiy.obj/?json -http://172.16.0.219:8087/getPlainValue/lametric.0.mydatadiy.obj/?json&user=lametric&pass=HhX7dZl3Fe -``` - -**Important: use json flag of SimpleAPI Adapter (available since 2.6.2)** - -**Ensure to update IP, port, user and password in the URL if necessary!** - -### Configuration (without authentication) - -1. Install the [Simple API ioBroker Adapter](https://github.com/ioBroker/ioBroker.simple-api) -2. Install this *My Data DIY* App on your LaMetric Time (use Market) -3. Open the *My Data (DIY)* app settings and configure the simple api url (see below) -4. Go to the adapter configuration and configure the frames with your custom information (icon and text) - -``` -http://172.16.0.219:8087/getPlainValue/lametric.0.mydatadiy.obj/ -``` - -**Ensure to update IP and port in the URL if necessary!** - -### Frame Configuration *(version > 1.1.0)* - -- Use the plus icon to add as many frames as you want -- Icon: Choose an icon from the [official website](https://developer.lametric.com/icons) and put the ID in the configuration field. **Important: Add an i (for static icons) or an a (for animated icons) as a prefix for that ID. (Example: `i3389`) -- Text: Just type the text information for the frame. You can use states in curly braces. These information will be replaced with the corresponding value of the state. (Example: `{youtube.0.channels.HausAutomatisierungCom.statistics.subscriberCount} Subscribers`) - -Example configuration of 2 frames: - -![example frame config](docs/myDataDIYConfig.png) - -## Special Apps / Widgets *(version > 1.1.2)* - -You can control some apps with custom information - -### clock.clockface - -Allowed values are: - -- one of `weather`, `page_a_day`, `custom` or `none` -- custom icon data in format `data:image/png;base64,` or `data:image/gif;base64,` - -Example: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAOklEQVQYlWNUVFBgwAeYcEncv//gP04FMEmsCmCSiooKjHAFMEF0SRQTsEnCFcAE0SUZGBgYGAl5EwA+6RhuHb9bggAAAABJRU5ErkJggg==` - -### countdown.configure - -Allowed value: Time in seconds - -## Scripts - -To show the message on your la metric just send a message to this instance with script adapter: - -```JavaScript -sendTo( - "lametric.0", - "notification", - { - priority: "[info|warning|critical]", - iconType: "[none|info|alert]", - sound: "", - lifeTime: , - icon: "", - text: "", - cycles: - } -); -``` - -Example single frame: - -```JavaScript -sendTo( - "lametric.0", - "notification", - { - priority: "info", - iconType: "none", - sound: "cat", - lifeTime: 5000, - icon: "i31820", - text: "test", - cycles: 1 - } -); -``` - -Example multiple frames: - -```JavaScript -sendTo( - "lametric.0", - "notification", - { - priority: "info", - iconType: "none", - sound: "cat", - lifeTime: 5000, - icon: "i31820", - text: ["frame 1", "frame 2", "frame 3"], - cycles: 1 - } -); -``` - -Example to show some information cyclic: - -```JavaScript -let i = 0; -function show() { - console.log('Show ' + i); - sendTo( - "lametric.0", - "notification", - { - priority: "info", - iconType: "info", - lifeTime: 5000, - icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAYdEVYdFNvZnR3YXJlAHBhaW50Lm5ldCA0LjEuNWRHWFIAAAAySURBVBhXY4AAYdcKk1lngCSUDwHIfAQbzgLqgDCgIqRLwFkQCYQoBAD5EATl4wQMDADhuxQzaDgX0gAAAABJRU5ErkJggg==", - text: "Hi " + i, - cycles: 1 - } - ); - i++; -} -setInterval(show, 10000); -show(); -``` +[🇩🇪 Dokumentation](./docs/de/basics.md) ## Sentry diff --git a/docs/de/basics.md b/docs/de/basics.md new file mode 100644 index 0000000..3ca18ac --- /dev/null +++ b/docs/de/basics.md @@ -0,0 +1,184 @@ +![Logo](../../admin/lametric.png) + +# ioBroker.lametric + +## Anforderungen + +- *LaMetric Time* mit Firmware *2.2.2* (oder neuer) + +## Configuration + +Du bekommst deinen Geräte-Schlüssel (API-Key) [hier](https://developer.lametric.com/user/devices). + +![api-key](docs/apiKey.png) + +## Features + +- Verändern der Display-Helligkeit (prozentual, Automatik/Manueller Modus) +- Verändern der Lautstärke (prozentual) +- Konfiguration des Bildschirmschoners (aktivieren/deaktivieren, Zeitbasiert, wenn dunkel) +- Bluetooth aktivieren/deaktivieren, Bluetooth Name verändern +- Zwischen Apps wechseln (nächste, vorige, gehe zu spezifischer App) +- Versenden von Notifications (mit konfigurierbarer Priorität, Sound, Icons, Text, ...) +- Kontrolle von speziellen Apps wie ``clock``, ``radio``, ``stopwatch`` oder ``weather`` +- Nutzung der *My Data (DIY)* LaMetric App um regelmäßig Informationen darzustellen + +Alle Funktionen sind nur durch die [offizielle API](https://lametric-documentation.readthedocs.io/en/latest/reference-docs/lametric-time-reference.html) limitiert. + +## Blockly Beispiele + +Senden eines einfachen Textes, welcher als einzelner Frame angezeigt wird + +![single frame](docs/blockly1.png) + +Um mehrere Frames darzustellen, kann eine Liste von Texten übergeben werden + +![multiple frames](docs/blockly2.png) + +Um Graphen darzustellen, muss ein Array aus Zahlen als Liste in einem Frame übergeben werden. + +![chart data frames](docs/blockly3.png) + +## My Data (DIY) *(version > 1.1.0)* + +*LaMetric* bietet (über den integrierten App-Store) eine zusätzliche App an, um eigene Informationen darzustellen. Diese App heißt [My Data DIY](https://apps.lametric.com/apps/my_data__diy_/8942). Dieser Adapter erstellt einen Datenpunkt im erforderlichen Format. +Du kannst den Simple API Adapter nutzen, um Daten zur LaMetric Time zu übertragen. + +```ioBroker LaMetric Adapter -> State with Frame information <- Simple API Adapter <- My Data DIY App <- LaMetric``` + +### Konfiguration (mit Authentisierung) + +1. Installiere den [Simple API ioBroker Adapter](https://github.com/ioBroker/ioBroker.simple-api) +2. Erstelle einen neuen ioBroker-Nutzer mit dem Namen ``lametric`` und einem eigenen Passwort (z.B. ``HhX7dZl3Fe``) +3. Füge den neuen ``lametric``-Nutzer zur Gruppe ``users`` hinzu +4. Installiere die App *My Data DIY* über den App-Store auf deiner *LaMetric Time* +5. Öffne die Einstellungen der *My Data (DIY)* App und konfiguriere die URL des Simple API Adapters (siehe unten) +6. Gehe in die Adaptereinstellungen und füge neue Frames mit deinen eigenen Informationen hinzu (siehe nächster Abschnitt) + +``` +http://172.16.0.219:8087/getPlainValue/lametric.0.mydatadiy.obj/?json&user=lametric&pass=HhX7dZl3Fe +``` + +**Wichtig: Nutze das json-Flag des SimpleAPI Adapters (verfügbar seit Version 2.6.2)** + +**Stelle sicher, dass die IP, der Port, Benutzername und Passwort in der URL korrekt sind!** + +### Konfiguration (ohne Authentisierung) + +1. Installiere den [Simple API ioBroker Adapter](https://github.com/ioBroker/ioBroker.simple-api) +2. Installiere die App *My Data DIY* über den App-Store auf deiner *LaMetric Time* +3. Öffne die Einstellungen der *My Data (DIY)* App und konfiguriere die URL des Simple API Adapters (siehe unten) +4. Gehe in die Adaptereinstellungen und füge neue Frames mit deinen eigenen Informationen hinzu (siehe nächster Abschnitt) + +``` +http://172.16.0.219:8087/getPlainValue/lametric.0.mydatadiy.obj/?json +``` + +**Stelle sicher, dass die IP und der Port in der URL korrekt sind!** + +### Frame Konfiguration *(Version > 1.1.0)* + +- Füge mit dem Plus-Button so viele Frames hinzu, wie Du möchtest +- Symbol: Wähle ein Symbol von der [offiziellen Webseite](https://developer.lametric.com/icons) und füge die ID in das Feld ein. **Wichtig: Nutze ein i (für statische Sybole) oder ein a (für animierte Symbole) als Präfix der ID (Beispiel: `i3389`)** +- Text: Tippe einen beliebigen anzuzeigenden Text ein. Du kannst Informatioenn aus Datenpunkten abfragem, indem Du deren ID in geschweifte Klammern angibst. An dieser Stelle wird dann der aktuelle Wert der Datenpunkte eingesetzt. (Beispiel: `{youtube.0.channels.HausAutomatisierungCom.statistics.subscriberCount} Subscribers`) + +Beispielkonfiguration von 3 Frames: + +![example frame config](docs/myDataDIYConfig.png) + +## Spezielle Apps / Widgets *(Version > 1.1.2)* + +Einige Apps lassen sich mit Zusatzinformationen versehen oder steuern. + +### clock.clockface + +Gültige Werte sind + +- `weather`, `page_a_day`, `custom` oder `none` +- Eigene Icons im Format `data:image/png;base64,` oder `data:image/gif;base64,` + +Beispiel: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAOklEQVQYlWNUVFBgwAeYcEncv//gP04FMEmsCmCSiooKjHAFMEF0SRQTsEnCFcAE0SUZGBgYGAl5EwA+6RhuHb9bggAAAABJRU5ErkJggg==` + +### countdown.configure + +Erlaubte Werte: Zeit in Sekunden + +## Scripts + +Um Nachrichten/Notifications auf Deiner *LaMetric Time* anzuzeigen, sende eine Nachricht mit dem JavaScript Adapter (oder einem anderen Adapter) an die entsprechende Instanz: + +```JavaScript +sendTo( + "lametric.0", + "notification", + { + priority: "[info|warning|critical]", + iconType: "[none|info|alert]", + sound: "", + lifeTime: , + icon: "", + text: "", + cycles: + } +); +``` + +Beispiel einzelner Frame: + +```JavaScript +sendTo( + "lametric.0", + "notification", + { + priority: "info", + iconType: "none", + sound: "cat", + lifeTime: 5000, + icon: "i31820", + text: "test", + cycles: 1 + } +); +``` + +Beispiel mehrere Frames: + +```JavaScript +sendTo( + "lametric.0", + "notification", + { + priority: "info", + iconType: "none", + sound: "cat", + lifeTime: 5000, + icon: "i31820", + text: ["frame 1", "frame 2", "frame 3"], + cycles: 1 + } +); +``` + +Beispiel zyklische Informationen: + +```JavaScript +let i = 0; +function show() { + console.log('Show ' + i); + sendTo( + "lametric.0", + "notification", + { + priority: "info", + iconType: "info", + lifeTime: 5000, + icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAYdEVYdFNvZnR3YXJlAHBhaW50Lm5ldCA0LjEuNWRHWFIAAAAySURBVBhXY4AAYdcKk1lngCSUDwHIfAQbzgLqgDCgIqRLwFkQCYQoBAD5EATl4wQMDADhuxQzaDgX0gAAAABJRU5ErkJggg==", + text: "Hi " + i, + cycles: 1 + } + ); + i++; +} +setInterval(show, 10000); +show(); +``` \ No newline at end of file diff --git a/docs/en/basics.md b/docs/en/basics.md new file mode 100644 index 0000000..1ad1b21 --- /dev/null +++ b/docs/en/basics.md @@ -0,0 +1,184 @@ +![Logo](../../admin/lametric.png) + +# ioBroker.lametric + +## Requirements + +- *LaMetric Time* with firmware *2.2.2* (or later) + +## Configuration + +You can get your device API key [here](https://developer.lametric.com/user/devices). + +![api-key](docs/apiKey.png) + +## Features + +- Set display brightness (percent, auto-mode/manual-mode) +- Set audio volume (percent) +- Configure screensaver (enable/disable, time based, when dark) +- Activate/Deactivate bluetooth and change bluetooth name +- Switch between apps (next, previous, go to specific app) +- Send notifications with blockly (with configurable priority, sound, icons, text, ...) +- Control special apps like ``clock``, ``radio``, ``stopwatch`` or ``weather`` +- Use *My Data (DIY)* LaMetric App to display persistent information + +Features are limited by the [official API features](https://lametric-documentation.readthedocs.io/en/latest/reference-docs/lametric-time-reference.html). + +## Blockly Examples + +You can use a simple string as message, which will be shown as a single frame + +![single frame](docs/blockly1.png) + +To show multiple frames, you can also provide an array as message + +![multiple frames](docs/blockly2.png) + +If you want to use chart frames, you have to specify an array of numbers as a frame + +![chart data frames](docs/blockly3.png) + +## My Data (DIY) *(version > 1.1.0)* + +*LaMetric* offers an app (on the integrated app market) to poll custom data. This app is called [My Data DIY](https://apps.lametric.com/apps/my_data__diy_/8942). This adapter creates a new state in the required format. +You can use the Simple API Adapter to transfer the data to the LaMetric Time. + +```ioBroker LaMetric Adapter -> State with Frame information <- Simple API Adapter <- My Data DIY App <- LaMetric``` + +### Configuration (with authentication) + +1. Install the [Simple API ioBroker Adapter](https://github.com/ioBroker/ioBroker.simple-api) +2. Create a new ioBroker user called ``lametric`` with a custom password (e.g. ``HhX7dZl3Fe``) +3. Add the ``lametric`` user to the default group ``users`` +4. Install this *My Data DIY* App on your *LaMetric Time* (use Market) +5. Open the *My Data (DIY)* app settings and configure the simple api url (see below) +6. Go to the adapter configuration and configure the frames with your custom information (see next chapter) + +``` +http://172.16.0.219:8087/getPlainValue/lametric.0.mydatadiy.obj/?json&user=lametric&pass=HhX7dZl3Fe +``` + +**Important: use json flag of SimpleAPI Adapter (available since version 2.6.2)** + +**Ensure to update IP, port, user and password in the URL if necessary!** + +### Configuration (without authentication) + +1. Install the [Simple API ioBroker Adapter](https://github.com/ioBroker/ioBroker.simple-api) +2. Install this *My Data DIY* App on your LaMetric Time (use Market) +3. Open the *My Data (DIY)* app settings and configure the simple api url (see below) +4. Go to the adapter configuration and configure the frames with your custom information (see next chapter) + +``` +http://172.16.0.219:8087/getPlainValue/lametric.0.mydatadiy.obj/?json +``` + +**Ensure to update IP and port in the URL if necessary!** + +### Frame Configuration *(version > 1.1.0)* + +- Use the plus icon to add as many frames as you want +- Icon: Choose an icon from the [official website](https://developer.lametric.com/icons) and put the ID in the configuration field. **Important: Add an i (for static icons) or an a (for animated icons) as a prefix for that ID. (Example: `i3389`)** +- Text: Just type the text information for the frame. You can use states in curly braces. These information will be replaced with the corresponding value of the state. (Example: `{youtube.0.channels.HausAutomatisierungCom.statistics.subscriberCount} Subscribers`) + +Example configuration of 3 frames: + +![example frame config](docs/myDataDIYConfig.png) + +## Special Apps / Widgets *(version > 1.1.2)* + +You can control some apps with custom information. + +### clock.clockface + +Allowed values are: + +- one of `weather`, `page_a_day`, `custom` or `none` +- custom icon data in format `data:image/png;base64,` or `data:image/gif;base64,` + +Example: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAOklEQVQYlWNUVFBgwAeYcEncv//gP04FMEmsCmCSiooKjHAFMEF0SRQTsEnCFcAE0SUZGBgYGAl5EwA+6RhuHb9bggAAAABJRU5ErkJggg==` + +### countdown.configure + +Allowed value: Time in seconds + +## Scripts + +To show messages/notifications on your *LaMetric Time*, send a message to this instance with the JavaScript adapter (or any other): + +```JavaScript +sendTo( + "lametric.0", + "notification", + { + priority: "[info|warning|critical]", + iconType: "[none|info|alert]", + sound: "", + lifeTime: , + icon: "", + text: "", + cycles: + } +); +``` + +Example single frame: + +```JavaScript +sendTo( + "lametric.0", + "notification", + { + priority: "info", + iconType: "none", + sound: "cat", + lifeTime: 5000, + icon: "i31820", + text: "test", + cycles: 1 + } +); +``` + +Example multiple frames: + +```JavaScript +sendTo( + "lametric.0", + "notification", + { + priority: "info", + iconType: "none", + sound: "cat", + lifeTime: 5000, + icon: "i31820", + text: ["frame 1", "frame 2", "frame 3"], + cycles: 1 + } +); +``` + +Example to show some information cyclic: + +```JavaScript +let i = 0; +function show() { + console.log('Show ' + i); + sendTo( + "lametric.0", + "notification", + { + priority: "info", + iconType: "info", + lifeTime: 5000, + icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAYdEVYdFNvZnR3YXJlAHBhaW50Lm5ldCA0LjEuNWRHWFIAAAAySURBVBhXY4AAYdcKk1lngCSUDwHIfAQbzgLqgDCgIqRLwFkQCYQoBAD5EATl4wQMDADhuxQzaDgX0gAAAABJRU5ErkJggg==", + text: "Hi " + i, + cycles: 1 + } + ); + i++; +} +setInterval(show, 10000); +show(); +``` \ No newline at end of file diff --git a/io-package.json b/io-package.json index 0d8f582..84bedaf 100644 --- a/io-package.json +++ b/io-package.json @@ -140,6 +140,10 @@ "adminUI": { "config": "json" }, + "docs": { + "en": "docs/en/basics.md", + "de": "docs/de/basics.md" + }, "dependencies": [ { "js-controller": ">=3.3.0"