tellstick: Refactor of add-on (#596)

* tellstick: Code formatting

* tellstick: Rewrite add-on onto Bashio

* tellstick: Adds README to add-on repository

* tellstick: Bump version to 2.0, added README

tellstick/CHANGELOG.md

@@ -1,9 +1,17 @@
 # Changelog
 
+## 2.0
+
+- Rewrites add-on onto Bashio
+- Added documentation to the add-on repository
+- Code formatting
+
 ## 1.0
+
 - Update base image
 
 ## 0.5
+
 - Added possibility for config options:
   protocols: comen, fineoffset, mandolyn, oregon
   models: temperature, temperaturehumidity

tellstick/Dockerfile

@@ -5,16 +5,34 @@ ENV LANG C.UTF-8
 
 # Install Telldus library for TellStick (using same approach as in hassio docker installation)
 RUN apk add --no-cache \
-        confuse libftdi1 libstdc++ socat \
+        confuse \
+        libftdi1 \
+        libstdc++ \
+        socat \
     && apk add --no-cache --virtual .build-dependencies \
-        cmake build-base gcc doxygen confuse-dev argp-standalone libftdi1-dev git \
+        argp-standalone \
+        build-base \
+        cmake \
+        confuse-dev \
+        doxygen \
+        gcc \
+        git \
+        libftdi1-dev \
     && ln -s /usr/include/libftdi1/ftdi.h /usr/include/ftdi.h \
     && mkdir -p /usr/src \
     && cd /usr/src \
     && git clone -b master --depth 1 https://github.com/telldus/telldus \
     && cd telldus/telldus-core \
-    && sed -i "/\<sys\/socket.h\>/a \#include \<sys\/select.h\>" common/Socket_unix.cpp \
+    && sed -i \
-    && cmake . -DBUILD_LIBTELLDUS-CORE=ON -DBUILD_TDADMIN=OFF -DBUILD_TDTOOL=ON -DGENERATE_MAN=OFF -DFORCE_COMPILE_FROM_TRUNK=ON -DFTDI_LIBRARY=/usr/lib/libftdi1.so \
+        "/\<sys\/socket.h\>/a \#include \<sys\/select.h\>" \
+        common/Socket_unix.cpp \
+    && cmake . \
+        -DBUILD_LIBTELLDUS-CORE=ON \
+        -DBUILD_TDADMIN=OFF \
+        -DBUILD_TDTOOL=ON \
+        -DGENERATE_MAN=OFF \
+        -DFORCE_COMPILE_FROM_TRUNK=ON \
+        -DFTDI_LIBRARY=/usr/lib/libftdi1.so \
     && make \
     && make install \
     && apk del .build-dependencies \

tellstick/README.md

@@ -0,0 +1,195 @@
+# Hass.io Core Add-on: TellStick
+
+TellStick and TellStick Duo service.
+
+![Supports aarch64 Architecture][aarch64-shield] ![Supports amd64 Architecture][amd64-shield] ![Supports armhf Architecture][armhf-shield] ![Supports armv7 Architecture][armv7-shield] ![Supports i386 Architecture][i386-shield]
+
+## About
+
+This add-on wraps around the `telldus-core` package to expose a service
+for your TellStick and TellStick Duo.
+
+This integration allows users to add switches, lights, and sensors which are
+communicating with 433 MHz. There are a number of vendors (Capidi Elro,
+Intertechno, Nexa, Proove, Sartano, and Viking) who are selling products that
+work with TellStick.
+
+For more details, please check the TellStick [protocol list][protocol-list].
+
+## Installation
+
+The installation of this add-on is straightforward and easy to do.
+
+1. Navigate in your Home Assistant frontend to **Hass.io** -> **Add-on Store**.
+2. Find the "TellStick" add-on and click it.
+3. Click on the "INSTALL" button.
+
+## How to use
+
+### Starting the add-on
+
+After installation you are presented with a default and example configuration,
+to alter this you must follow both the JSON format and also be aligned with
+the [valid parameters for Tellstick configuration file (tellstick.conf)][conf].
+
+1. Adjust the add-on configuration to match your devices. See the add-on
+   configuration options below for more details.
+2. Save the add-on configuration by clicking the "SAVE" button.
+3. Start the add-on.
+
+### Home Assistant integration
+
+You will need to add internal communication details to the `configuration.yaml`
+file to enable the integration with the add-on.
+
+```yaml
+# Example configuration.yaml entry
+tellstick:
+    host: core-tellstick
+    port: [50800, 50801]
+```
+
+To add lights, sensors and switches to Home Assistant, you need to follow the
+guidelines for each type individually that is described for Home Assistant.
+
+For more information, check the Home Assistant documentation:
+
+<https://www.home-assistant.io/components/tellstick/>
+
+## Configuration
+
+After installation you are presented with a default and example configuration,
+to alter this you must follow both the JSON format and also be aligned with
+the [valid parameters for Tellstick configuration file (tellstick.conf)][conf].
+
+Example add-on configuration:
+
+```json
+{
+  "devices": [
+    {
+      "id": 1,
+      "name": "Example device",
+      "protocol": "everflourish",
+      "model": "selflearning-switch",
+      "house": "A",
+      "unit": "1"
+    },
+    {
+      "id": 2,
+      "name": "Example device two",
+      "protocol": "everflourish",
+      "model": "selflearning-switch",
+      "house": "A",
+      "unit": "2"
+    }
+  ]
+}
+```
+
+Please note: After any changes have been made to the configuration,
+you need to restart the add-on for the changes to take effect.
+
+### Option: `devices` (required)
+
+Add one or more devices entries to the add-on configuration for each
+device you'd like to add. Please note the comma seperator between each
+device (see example above).
+
+#### Option: `devices` -> `id` (required)
+
+A unique number / identifier that must be unique for each device.
+
+#### Option: `devices` -> `name` (required)
+
+A name for your device, making it easy to identify it.
+
+#### Option: `devices` -> `protocol` (required)
+
+This is the protocol the device uses. For a full list of supported protocols
+(and thus valid values for this configuration option), check the
+TellStick [protocol list][protocol-list].
+
+#### Option: `devices` -> `model` (optional)
+
+The model parameter is only used by some protocols where there exists different
+types of devices using the same protocol. This can be dimmers versus non-dimmers,
+codeswitch versus self-learning, etc.
+
+#### Option: `devices` -> `house` (optional)
+
+Depending on protocol the values here can vary a lot to identify
+or group per house or type.
+
+#### Option: `devices` -> `unit` (optional)
+
+Unit identifier, in most cases a value between 1 to 16 and often used in
+combination with the house.
+
+#### Option: `devices` -> `fade` (optional)
+
+Fade is either `true` or `false` and tells a dimmer if it should fade smooth
+or instant between values (only for IKEA protocol as it seems).
+
+#### Option: `devices` -> `code` (optional)
+
+A number series based on ones and zeroes often used for dip-switch based devices.
+
+## Service calls
+
+If you wish to teach a self-learning device in your TellStick configuration:
+
+Go to Home Assistant service call in Developer tools and select:
+
+- Service: `hassio.addon_stdin`
+- Enter service Data:
+  `{"addon":"core_tellstick","input":{"function":"learn","device":"1"}}`
+
+Replace `1` with the corresponding ID of the device in your TellStick configuration.
+
+You can also use this to list devices or sensors and read the output in the
+add-on log: `{"addon":"core_tellstick","input":{"function":"list-sensors"}}`
+
+### Supported service commands
+
+- `"function":"list"`
+  List currently configured devices with name and device id and all discovered sensors.
+  
+- `"function":"list-sensors"`
+  
+- `"function":"list-devices"`
+  Alternative devices/sensors listing: Shows devices and/or sensors using key=value
+  format (with tabs as separators, one device/sensor per line, no header lines.)
+
+- `"function":"on","device":"x"`
+  Turns on device. ’x’ could either be an integer of the device-id,
+  or the name of the device.
+
+- `"function":"off","device":"x"`
+  Turns off device. ’x’ could either be an integer of the device-id,
+  or the name of the device.
+
+## Support
+
+Got questions?
+
+You have several options to get them answered:
+
+- The [Home Assistant Discord Chat Server][discord].
+- The Home Assistant [Community Forum][forum].
+- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit]
+
+In case you've found an bug, please [open an issue on our GitHub][issue].
+
+[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
+[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
+[armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg
+[armv7-shield]: https://img.shields.io/badge/armv7-yes-green.svg
+[conf]: https://developer.telldus.com/wiki/TellStick_conf
+[discord]: https://discord.gg/c5DvZ4e
+[forum]: https://community.home-assistant.io
+[i386-shield]: https://img.shields.io/badge/i386-yes-green.svg
+[issue]: https://github.com/home-assistant/hassio-addons/issues
+[protocol-list]: http://developer.telldus.com/wiki/TellStick_conf
+[reddit]: https://reddit.com/r/homeassistant
+[repository]: https://github.com/hassio-addons/repository

tellstick/config.json

@@ -1,14 +1,22 @@
 {
   "name": "TellStick",
-  "version": "1.0",
+  "version": "2.0",
   "slug": "tellstick",
-  "description": "TellStick and TellStick Duo service.",
+  "description": "TellStick and TellStick Duo service",
-  "url": "https://home-assistant.io/addons/tellstick/",
+  "url": "https://github.com/home-assistant/hassio-addons/tree/master/tellstick",
-  "arch": ["armhf", "armv7", "aarch64", "amd64", "i386"],
+  "arch": [
+    "armhf",
+    "armv7",
+    "aarch64",
+    "amd64",
+    "i386"
+  ],
   "startup": "system",
   "stdin": true,
   "boot": "auto",
-  "devices": ["/dev/bus/usb:/dev/bus/usb:rwm"],
+  "devices": [
+    "/dev/bus/usb:/dev/bus/usb:rwm"
+  ],
   "options": {
     "devices": [
       {

tellstick/run.sh

@@ -1,62 +1,61 @@
-#!/bin/bash
+#!/usr/bin/env bashio
 set -e
 
-CONFIG_PATH=/data/options.json
+CONFIG="/etc/tellstick.conf"
-DEVICES=$(jq --raw-output '.devices | length' $CONFIG_PATH)
-
-echo "[Info] Initialize the tellstick configuration"
 
+bashio::log.info "Initialize the tellstick configuration..."
 # User access
-echo "user = \"root\"" > /etc/tellstick.conf
+{
-echo "group = \"plugdev\"" >> /etc/tellstick.conf
+    echo "user = \"root\""
-echo "ignoreControllerConfirmation = \"false\"" >> /etc/tellstick.conf
+    echo "group = \"plugdev\""
+    echo "ignoreControllerConfirmation = \"false\"" 
+} > "${CONFIG}"
 
 # devices
-for (( i=0; i < "$DEVICES"; i++ )); do
+for device in $(bashio::config 'devices|keys'); do
-    DEV_ID=$(jq --raw-output ".devices[$i].id" $CONFIG_PATH)
+    DEV_ID=$(bashio::config "devices[${device}].id")
-    DEV_NAME=$(jq --raw-output ".devices[$i].name" $CONFIG_PATH)
+    DEV_NAME=$(bashio::config "devices[${device}].name")
-    DEV_PROTO=$(jq --raw-output ".devices[$i].protocol" $CONFIG_PATH)
+    DEV_PROTO=$(bashio::config "devices[${device}].protocol")
-    DEV_MODEL=$(jq --raw-output ".devices[$i].model // empty" $CONFIG_PATH)
+    DEV_MODEL=$(bashio::config "devices[${device}].model")
-    ATTR_HOUSE=$(jq --raw-output ".devices[$i].house // empty" $CONFIG_PATH)
+    ATTR_HOUSE=$(bashio::config "devices[${device}].house")
-    ATTR_CODE=$(jq --raw-output ".devices[$i].code // empty" $CONFIG_PATH)
+    ATTR_CODE=$(bashio::config "devices[${device}].code")
-    ATTR_UNIT=$(jq --raw-output ".devices[$i].unit // empty" $CONFIG_PATH)
+    ATTR_UNIT=$(bashio::config "devices[${device}].unit")
-    ATTR_FADE=$(jq --raw-output ".devices[$i].fade // empty" $CONFIG_PATH)
+    ATTR_FADE=$(bashio::config "devices[${device}].fade")
   
     (
         echo ""
         echo "device {"
-        echo "  id = $DEV_ID"
+        echo "  id = ${DEV_ID}"
-        echo "  name = \"$DEV_NAME\""
+        echo "  name = \"${DEV_NAME}\""
-        echo "  protocol = \"$DEV_PROTO\""
+        echo "  protocol = \"${DEV_PROTO}\""
         
-        if [ -n "$DEV_MODEL" ]; then
+        bashio::var.has_value "${DEV_MODEL}" \
-            echo "  model = \"$DEV_MODEL\""
+            && echo "  model = \"${DEV_MODEL}\""
-        fi
         
-        if [ -n "$ATTR_HOUSE" ] || [ -n "$ATTR_CODE" ] || [ -n "$ATTR_UNIT" ] || [ -n "$ATTR_FADE" ]; then
+        if bashio::var.has_value "${ATTR_HOUSE}${ATTR_CODE}${ATTR_UNIT}${ATTR_FADE}";
+        then
             echo "  parameters {"
 
-            if [ -n "$ATTR_HOUSE" ]; then
+            bashio::var.has_value "${ATTR_HOUSE}" \
-                echo "    house = \"$ATTR_HOUSE\""
+                && echo "    house = \"${ATTR_HOUSE}\""
-            fi
+
-            if [ -n "$ATTR_CODE" ]; then
+            bashio::var.has_value "${ATTR_CODE}" \
-                echo "    code = \"$ATTR_CODE\""
+                && echo "    code = \"${ATTR_CODE}\""
-            fi
+
-            if [ -n "$ATTR_UNIT" ]; then
+            bashio::var.has_value "${ATTR_UNIT}" \
-                echo "    unit = \"$ATTR_UNIT\""
+                && echo "    unit = \"${ATTR_UNIT}\""
-            fi
+
-            if [ -n "$ATTR_FADE" ]; then
+            bashio::var.has_value "${ATTR_FADE}" \
-                echo "    fade = \"$ATTR_FADE\""
+                && echo "    fade = \"${ATTR_FADE}\""
-            fi
             
             echo "  }"
         fi
         
         echo "}"
-    ) >> /etc/tellstick.conf
+    ) >> "${CONFIG}"
 done
 
-echo "[Info] Exposing sockets and loading service"
+bashio::log.info "Exposing sockets and loading service..."
 
 # Expose the unix socket to internal network
 socat TCP-LISTEN:50800,reuseaddr,fork UNIX-CONNECT:/tmp/TelldusClient &
@@ -66,16 +65,16 @@ socat TCP-LISTEN:50801,reuseaddr,fork UNIX-CONNECT:/tmp/TelldusEvents &
 /usr/local/sbin/telldusd --nodaemon < /dev/null &
 
 # Listen for input to tdtool
-echo "[Info] Starting event listener"
+bashio::log.info "Starting event listener..."
 while read -r input; do
     # parse JSON value
-    funct="$(echo "$input" | jq --raw-output '.function')"
+    funct=$(bashio::jq "${input}" '.function')
-    devid="$(echo "$input" | jq --raw-output '.device // empty')"
+    devid=$(bashio::jq "${input}" '.device // empty')
-    echo "[Info] Read $funct / $devid"
+    bashio::log.info "Read ${funct} / ${devid}"
 
-    if ! msg="$(tdtool "--$funct" "$devid")"; then
+    if ! msg="$(tdtool "--${funct}" "${devid}")"; then
-    	echo "[Error] TellStick $funct fails -> $msg"
+        bashio::log.error "TellStick ${funct} fails -> ${msg}"
     else
-        echo "[Info] TellStick $funct success -> $msg"
+        bashio::log.info "TellStick ${funct} success -> ${msg}"
     fi
 done