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
This commit is contained in:
Franck Nijhof
committed by
Pascal Vizeli
Pascal Vizeli
parent
adcbd24d6f
commit
81a49a8ec2
195
tellstick/README.md
Normal file
195
tellstick/README.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user