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].
|
||||
|
||||
## 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
|
||||
[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
|
||||
Reference in New Issue
Block a user