tellstick: Split documentation (#1300)
This commit is contained in:
Joakim Sørensen
167
tellstick/DOCS.md
Normal file
167
tellstick/DOCS.md
Normal file
@@ -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:
|
||||||
|
|
||||||
|
<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:
|
||||||
|
|
||||||
|
```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
|
||||||
@@ -16,173 +16,9 @@ work with TellStick.
|
|||||||
|
|
||||||
For more details, please check the TellStick [protocol list][protocol-list].
|
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:
|
|
||||||
|
|
||||||
<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:
|
|
||||||
|
|
||||||
```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
|
[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
|
||||||
[amd64-shield]: https://img.shields.io/badge/amd64-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
|
[armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg
|
||||||
[armv7-shield]: https://img.shields.io/badge/armv7-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
|
[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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user