diff --git a/tellstick/DOCS.md b/tellstick/DOCS.md new file mode 100644 index 0000000..b66478c --- /dev/null +++ b/tellstick/DOCS.md @@ -0,0 +1,167 @@ +# Home Assistant Add-on: TellStick + +## Installation + +Follow these steps to get the add-on installed on your system: + +1. Navigate in your Home Assistant frontend to **Supervisor** -> **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: + +```yaml +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 separator 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 easier 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 a bug, please [open an issue on our GitHub][issue]. + +[conf]: http://developer.telldus.com/wiki/TellStick_conf +[discord]: https://discord.gg/c5DvZ4e +[forum]: https://community.home-assistant.io +[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/README.md b/tellstick/README.md index 8eab488..24b498b 100644 --- a/tellstick/README.md +++ b/tellstick/README.md @@ -16,173 +16,9 @@ work with TellStick. For more details, please check the TellStick [protocol list][protocol-list]. -## Installation - -Follow these steps to get the add-on installed on your system: - -1. Navigate in your Home Assistant frontend to **Supervisor** -> **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: - -```yaml -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 separator 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 easier 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 a 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]: http://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 +[i386-shield]: https://img.shields.io/badge/i386-yes-green.svg \ No newline at end of file