diff --git a/tellstick/CHANGELOG.md b/tellstick/CHANGELOG.md index 5e53003..527317d 100644 --- a/tellstick/CHANGELOG.md +++ b/tellstick/CHANGELOG.md @@ -1,10 +1,18 @@ # 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 + protocols: comen, fineoffset, mandolyn, oregon + models: temperature, temperaturehumidity - Created changelog diff --git a/tellstick/Dockerfile b/tellstick/Dockerfile index a301a77..13a71d7 100644 --- a/tellstick/Dockerfile +++ b/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 "/\/a \#include \" 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 \ + && sed -i \ + "/\/a \#include \" \ + 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 \ diff --git a/tellstick/README.md b/tellstick/README.md new file mode 100644 index 0000000..44e00cb --- /dev/null +++ b/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: + + + +## 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 diff --git a/tellstick/config.json b/tellstick/config.json index c43dfa7..a871f5d 100644 --- a/tellstick/config.json +++ b/tellstick/config.json @@ -1,32 +1,40 @@ { "name": "TellStick", - "version": "1.0", + "version": "2.0", "slug": "tellstick", - "description": "TellStick and TellStick Duo service.", - "url": "https://home-assistant.io/addons/tellstick/", - "arch": ["armhf", "armv7", "aarch64", "amd64", "i386"], + "description": "TellStick and TellStick Duo service", + "url": "https://github.com/home-assistant/hassio-addons/tree/master/tellstick", + "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": [ - { - "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" - } + { + "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" + } ] }, "schema": { diff --git a/tellstick/run.sh b/tellstick/run.sh index 1250355..65ff3db 100755 --- a/tellstick/run.sh +++ b/tellstick/run.sh @@ -1,62 +1,61 @@ -#!/bin/bash +#!/usr/bin/env bashio set -e -CONFIG_PATH=/data/options.json -DEVICES=$(jq --raw-output '.devices | length' $CONFIG_PATH) - -echo "[Info] Initialize the tellstick configuration" +CONFIG="/etc/tellstick.conf" +bashio::log.info "Initialize the tellstick configuration..." # User access -echo "user = \"root\"" > /etc/tellstick.conf -echo "group = \"plugdev\"" >> /etc/tellstick.conf -echo "ignoreControllerConfirmation = \"false\"" >> /etc/tellstick.conf +{ + echo "user = \"root\"" + echo "group = \"plugdev\"" + echo "ignoreControllerConfirmation = \"false\"" +} > "${CONFIG}" # devices -for (( i=0; i < "$DEVICES"; i++ )); do - DEV_ID=$(jq --raw-output ".devices[$i].id" $CONFIG_PATH) - DEV_NAME=$(jq --raw-output ".devices[$i].name" $CONFIG_PATH) - DEV_PROTO=$(jq --raw-output ".devices[$i].protocol" $CONFIG_PATH) - DEV_MODEL=$(jq --raw-output ".devices[$i].model // empty" $CONFIG_PATH) - ATTR_HOUSE=$(jq --raw-output ".devices[$i].house // empty" $CONFIG_PATH) - ATTR_CODE=$(jq --raw-output ".devices[$i].code // empty" $CONFIG_PATH) - ATTR_UNIT=$(jq --raw-output ".devices[$i].unit // empty" $CONFIG_PATH) - ATTR_FADE=$(jq --raw-output ".devices[$i].fade // empty" $CONFIG_PATH) +for device in $(bashio::config 'devices|keys'); do + DEV_ID=$(bashio::config "devices[${device}].id") + DEV_NAME=$(bashio::config "devices[${device}].name") + DEV_PROTO=$(bashio::config "devices[${device}].protocol") + DEV_MODEL=$(bashio::config "devices[${device}].model") + ATTR_HOUSE=$(bashio::config "devices[${device}].house") + ATTR_CODE=$(bashio::config "devices[${device}].code") + ATTR_UNIT=$(bashio::config "devices[${device}].unit") + ATTR_FADE=$(bashio::config "devices[${device}].fade") ( echo "" echo "device {" - echo " id = $DEV_ID" - echo " name = \"$DEV_NAME\"" - echo " protocol = \"$DEV_PROTO\"" + echo " id = ${DEV_ID}" + echo " name = \"${DEV_NAME}\"" + echo " protocol = \"${DEV_PROTO}\"" - if [ -n "$DEV_MODEL" ]; then - echo " model = \"$DEV_MODEL\"" - fi + bashio::var.has_value "${DEV_MODEL}" \ + && echo " model = \"${DEV_MODEL}\"" - 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 - echo " house = \"$ATTR_HOUSE\"" - fi - if [ -n "$ATTR_CODE" ]; then - echo " code = \"$ATTR_CODE\"" - fi - if [ -n "$ATTR_UNIT" ]; then - echo " unit = \"$ATTR_UNIT\"" - fi - if [ -n "$ATTR_FADE" ]; then - echo " fade = \"$ATTR_FADE\"" - fi + + bashio::var.has_value "${ATTR_HOUSE}" \ + && echo " house = \"${ATTR_HOUSE}\"" + + bashio::var.has_value "${ATTR_CODE}" \ + && echo " code = \"${ATTR_CODE}\"" + + bashio::var.has_value "${ATTR_UNIT}" \ + && echo " unit = \"${ATTR_UNIT}\"" + + bashio::var.has_value "${ATTR_FADE}" \ + && echo " fade = \"${ATTR_FADE}\"" 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')" - devid="$(echo "$input" | jq --raw-output '.device // empty')" - echo "[Info] Read $funct / $devid" - - if ! msg="$(tdtool "--$funct" "$devid")"; then - echo "[Error] TellStick $funct fails -> $msg" + funct=$(bashio::jq "${input}" '.function') + devid=$(bashio::jq "${input}" '.device // empty') + bashio::log.info "Read ${funct} / ${devid}" + + if ! msg="$(tdtool "--${funct}" "${devid}")"; then + bashio::log.error "TellStick ${funct} fails -> ${msg}" else - echo "[Info] TellStick $funct success -> $msg" + bashio::log.info "TellStick ${funct} success -> ${msg}" fi done