- Overview
- Structure
- App flow and navigation
- Preconditions
- Settings of the Widget
- Icon List
- Troubleshooting
- Open Tasks
- License
This widget for garmin watches is a UI or visualization for your ioBroker instance. So you can visualize:
- Information as text like e.g. a temperature
- States as colored text or colored icons
- Switches as icons to see if something is on or off and to change the state
- Buttons as icons to trigger something
The UI is separated in so called Spaces. A Space can be a room or a device or what ever you want to cluster your states. The Space has an icon, so you can identify it, e.g. a couch for the living room. Each Space exists of at least one Object or at most eight Objects (more would overload the little screen of your garmin device). An Object is a visual representation of a state from your ioBroker e.g. the on/off state of a bulb.
First of all the widget try to connect to your ioBroker instance. On an error the widget shows the ioBroker icon framed with a red circle and the error description and/or code. On success the widget shows the first configured Space.
If you have configured switches or buttons you can interact with the related Objects by tapping on them. By Tapping on the Space icon you can refresh the view to get updated states. Wiping up and down you can navigate through the Spaces (it's the standard navigation on garmin devices to navigate to the next or previous page).
To navigate through the Spaces use the buttons Up and Down. You can refresh the view by pressing the button Enter. To interact with the Objects you must use the menu (see next passage).
You can interact with the Objects by using the menu. For devices without touch screen this is the only way to change the state of an Object. To open the menu simply press the button Menu. The upcoming menu shows you a list of the Objects from the current selected Space. To change the state of an Object navigate (button Up or Down) to the menu item and select (button Enter) it. With the button Back you can navigate back to the Space.
Of course you need an ioBroker instance / server. Additionally you need:
- A simple-api adapter instance
- A secured (https) signed connection to your server i.e. simple-api instance
- An object with the configuration for the visualization
Your simple-api instance needs in each case the setting for HTTPS. Use appropriate certificates for that. You can find some hints in the Connection details.
Recommendation: Activate also the option Authentication and configure a fitting user with password for your use case.
You need somewhere an object with a special configuration. Currently you have to create it manually.
Recommendation: Create it under
0_userdata.0, e.g.0_userdata.0.garminas typedevice. Be sure that your used user for the simple-api has the authorizations to read this object.
After the creation you have to modify the object. At the object data tab you can see the object configuration in json format. You must create or modify the attribute native:
{
"common": {
"name": "...",
},
"native": {
}
}As already described, the UI is separated into Spaces, so you must define first those in an Array:
"native": {
"spaces": [
{
"icon": "star",
"color": "#FFAA00",
"name": "Favorite",
}
]
}Each Space has three attributes for visualization. The icon, a color and a name. See the available icons in the list below. You can specify the color in hexadecimal format with a leading #. The icon is mandatory. If you do not specify the color the widget takes yellow as default. The widget uses the name as title for the menu.
As you know a Space exists of Objects, so you have to specify them too inside:
"native": {
"spaces": [
{
"icon": "star",
"name": "Favorite",
"objects": [
{
"type": "<icon>|text|state",
"name": "My State",
}
]
}
]
}An Object has always a type. The type could be an icon (see list below), a simple text or a state. For any type you can specify a color like at the Space. The type text has white as default color and the others has blue. Additionally you can specify a name for your Object, which the widget uses as label for the menu item.
The type text needs the additional attribute get, where you must specify the state in your ioBroker object list, which has to be read. Additionally you can specify a unit as postfix and a precision of the decimal places for numbers (rounded).
Example: Show the temperature -> 21.5°C
{ "type": "text", "name": "Temperature", "get": "adapter.0.channel.device.temperature", "unit": "°C", "precision": "1" }
The type icon you can use as simple showing indicator, as switch (showing the sate and change it) or as simple command (activate something). The indicator and the switch work only with boolean or similar states. You can control the usage by specifying the attributes get and set or even not. As switch it needs both attributes, as indicator it needs only get and as command it needs only set. Depending on the usage you should choose a fitting icon (see list below). A switch as well as an indicator should have an icon with the usage switch and a command can have any icon (consider the restrictions described at the icon list).
If you have a similar state to a boolean state, you must configure a mapping. Therefore you have the attributes true and false. At true put in the value for the truly value and at false the value for the falsely.
The command needs additionally the attribute value. This attribute contains the value, which has to be sent to the state in ioBroker.
Example: Switch for a bulb (where the state has the values
onandoff) and Command to start a timer[ { "type": "bulb", "color": "#FF9900", "name": "Lights", "get": "adapter.0.channel.device.state", "set": "adapter.0.channel.device.state", "true": "on", "false": "off" }, { "type": "play", "name": "Start Timer", "set": "adapter.0.channel.device.timer", "value": "start" } ]
The type state is a little bit more complex. You need in any case the attributes get and scopes. The attribute get contains - as you already know - the state in your ioBroker, whose value you want to read. The attribute scopes is again an Array with several elements; you can even say the characteristics of the state. So depending on the value of your specified state, one of the Scopes will be shown. Each Scope is more or less like an Object. So you must define the attribute type here too. This time you have only the choice between a simple text and an icon as indicator (no switch and no command). You can specifiy also a color for a Scope. Additionally you need at least one of the attributes value, min or max. With value you can specify a concrete value of your sate, where the Scope should be active. It overrules the other both attributes, so they are superfluous if you sepcify value. With the attributes min and max you can specify ranges (for numerical values). If one of them is missing, it will be interpreted as endless.
Consider: The widget checks the Scopes in the specified order; first come, first serve. So if you have an overlap the first fitting Scope wins.
Example: Show temperature as colored text or icon, if it is too cold or too hot
{ "type": "state", "name": "Temperature", "get": "adapter.0.channel.device.temperature", "scopes": [ { // show snow icon if the temperature is -5 or less "type": "snow", "color": "#FFFFFF", "max": "-5" }, { // show zero in white (must come first due to overlap with next scope) "type": "text", "unit": "°C", "precision": "0", "color": "#FFFFFF", "value": "0" }, { // show temperature in blue if it is between -5 and 10 "type": "text", "unit": "°C", "precision": "1", "color": "#0000FF", "min": "-5", "max": "10" }, { // show temperature in grey if it is between 10 and 20 "type": "text", "unit": "°C", "precision": "1", "color": "#999999", "min": "10", "max": "20" }, { // show temperature in green if it is between 20 and 30 "type": "text", "unit": "°C", "precision": "1", "color": "#00FF00", "min": "20", "max": "30" }, { // show temperature in orange if it is between 30 and 40 "type": "text", "unit": "°C", "precision": "1", "color": "#FF5500", "min": "30", "max": "40" }, { // show alert icon if temperature is higher than 40 "type": "alert", "color": "#FF0000", "min": "40" } ] }
Why do you need a secured signed connection?
Due to some restrictions on the garmin device, you must use https. Otherwise the device refueses the connection. This is a good thing in general to secure the communication between the garmin device, the garmin Connect Mobile App and your ioBroker server. Especially when using an authorization concept. But, the connection or in better words the security certificate must be signed from an official organization. You cannot import self signed certificates on the garmin device.
How can you manage this if your ioBroker is in the local network?
If your IP address from outside is changing periodically (most cases), you need a dynamic DNS to solve this problem. So you have a static URL redirecting to your network at home. In the standard case your internet router is addressed this way. So you have to manage there a port forwarding. In the easiest way you simply forward the same port as your simple-api adapter is listening to and of course you must address there your ioBroker server.
How does it work with the signed certificate?
As already explained you need an official signed certificate. You can use some paid offers to get a certificate or you can use Let's Encrypt. Also ioBroker supports Let's Encrypt. At the generation of the certificates you must consider to use the correct URL, e.g. the URL from your dynamic DNS provider, and that the PC where you use Let's Encrypt from is reachable by this URL (usually on web port: 80). Maybe you need again port forwarding for this. Finally you have the needed certificates you must provide them to your simple-api instance. You need the private key certificate, the public key certificate and maybe also the full chain certificate. Consider also, that the certificates must be updated periodically. Using the guide on the Let's Encrypt web page and using the ioBroker server, where the certificates will be generated, the update process should be no problem.
There are four or five settings you can configure in the Garmin Connect Mobile App. The fields with * are mandatory:
-
URL*
Put in the URL (incl. port) to your simple-api instance of your ioBroker server, e.g.
https://ioBroker.mydomain.xyz:8088As default the setting has the URL
http://www.example.com. This URL triggers a demo setting of Spaces so you can get a look & feel. -
Definition Object*
Specify the object, where you have configured your Spaces, e.g.
0_userdata.0.garmin -
User
Type in a user for authorization (if you have set up your simple-api instance with authorization)
-
Password
Provide the password for the user
-
Greeting
This setting is available only on devices with a Glance List. Specify here a greeting (or description) for the item of this Widget in the list.
As default the setting has the phrase
ioBrokerVis
Take a look in the separate document with the icon list.
Please check your configuration, if you have specified a valid icon as type.
Check the associated get attribute, if you have specified a valid ioBroker state id. Take a look at the object tree in your ioBroker instance. Check also, if the chosen user has the authorization to read the state.
Check if the chosen user has the authorization to write to the state.
Please check your configuration, if you have specified the name attribute at the Space (for title) or at the Object (for label).
- Adapter in ioBroker to create the object with the configuration with a user friendly UI
MIT License
Copyright (c) 2021 Armin Junge
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.