[vizio] Vizio TV binding - Initial contribution (#13309)
Signed-off-by: Michael Lobstein <michael.lobstein@gmail.com>
This commit is contained in:
mlobstein
GitHub
181
bundles/org.openhab.binding.vizio/README.md
Normal file
181
bundles/org.openhab.binding.vizio/README.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Vizio Binding
|
||||
|
||||
This binding connects Vizio TVs to openHAB.
|
||||
The TV must support the Vizio SmartCast API that is found on 2016 and later models.
|
||||
|
||||
## Supported Things
|
||||
|
||||
There is currently only one supported thing type, which represents a Vizio TV using the `vizio_tv` id.
|
||||
Multiple Things can be added if more than one Vizio TV is to be controlled.
|
||||
|
||||
## Discovery
|
||||
|
||||
Auto-discovery is supported if the Vizio TV can be located on the local network using mDNS.
|
||||
Otherwise the thing must be manually added.
|
||||
When the TV is discovered, a pairing process to obtain an authentication token from the TV must be completed using the openHAB console. See below for details.
|
||||
|
||||
## Thing Configuration
|
||||
|
||||
The thing has a few configuration parameters:
|
||||
|
||||
| Parameter | Description |
|
||||
|-------------|--------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| hostName | The host name or IP address of the Vizio TV. Mandatory. |
|
||||
| port | The port on the Vizio TV that listens for https connections. Default 7345; Use 9000 for older model TVs. |
|
||||
| authToken | The token that is used to authenticate all commands sent to the TV. See below for instructions to obtain via the openHAB console. |
|
||||
| appListJson | A JSON string that defines the apps that are available in the `activeApp` channel drop down. See below for instructions for editing. |
|
||||
|
||||
### Console Commands for Pairing:
|
||||
|
||||
To obtain an authorization token that enables openHAB to authenticate with the TV, the following console commands must be used while the TV is turned on.
|
||||
The first command will send a pairing start request to the TV. This triggers the TV to display a 4-digit pairing code on screen that must be sent with the second command.
|
||||
|
||||
Start Pairing:
|
||||
|
||||
```
|
||||
openhab:vizio <thingUID> start_pairing <deviceName>
|
||||
```
|
||||
|
||||
Substitute `<thingUID>` with thing's id, ie: `vizio_tv:00bc3e711660`
|
||||
Substitute `<deviceName>` the desired device name that will appear in the TV's settings, under Mobile Devices, ie: `Vizio-openHAB`
|
||||
|
||||
Submit Pairing Code:
|
||||
|
||||
```
|
||||
openhab:vizio <thingUID> submit_code <pairingCode>
|
||||
```
|
||||
|
||||
Substitute `<thingUID>` with the same thing id used above
|
||||
Substitute `<pairingCode>` with the 4-digit pairing code displayed on the TV, ie: `1234`
|
||||
|
||||
The console should then indicate that pairing was successful (token will be displayed) and that the token was saved to the thing configuration.
|
||||
If using file-based provisioning of the thing, the authorization token must be added to the thing configuration manually.
|
||||
With an authorization token in place, the binding can now control the TV.
|
||||
|
||||
The authorization token text can be re-used in the event that it becomes necessary to setup the binding again.
|
||||
By simply adding the token that is already recognized by the TV to the thing configuration, the pairing process can be bypassed.
|
||||
|
||||
## Channels
|
||||
|
||||
The following channels are available:
|
||||
|
||||
| Channel ID | Item Type | Description |
|
||||
|-------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| power | Switch | Turn the power on the TV on or off. Note: TV may not turn on if power is switched off and the TV is configured for Eco mode. |
|
||||
| volume | Dimmer | Control the volume on the TV (0-100%). |
|
||||
| mute | Switch | Mute or unmute the volume on the TV. |
|
||||
| source | String | Select the source input on the TV. The dropdown list is automatically populated from the TV. |
|
||||
| activeApp | String | A dropdown containing a list of streaming apps defined by the `appListJson` config option that can be launched by the binding. An app started via remote control is automatically selected. |
|
||||
| control | Player | Control Playback e.g. Play/Pause/Next/Previous/FForward/Rewind |
|
||||
| button | String | Sends a remote control command the TV. See list of available commands below. |
|
||||
|
||||
### List of available button commands for Vizio TVs:
|
||||
|
||||
PowerOn
|
||||
PowerOff
|
||||
PowerToggle
|
||||
VolumeUp
|
||||
VolumeDown
|
||||
MuteOn **(may only work as a toggle)**
|
||||
MuteOff **(may only work as a toggle)**
|
||||
MuteToggle
|
||||
ChannelUp
|
||||
ChannelDown
|
||||
PreviousCh
|
||||
InputToggle
|
||||
SeekFwd
|
||||
SeekBack
|
||||
Play
|
||||
Pause
|
||||
Up
|
||||
Down
|
||||
Left
|
||||
Right
|
||||
Ok
|
||||
Back
|
||||
Info
|
||||
Menu
|
||||
Home
|
||||
Exit
|
||||
Smartcast
|
||||
ccToggle
|
||||
PictureMode
|
||||
WideMode
|
||||
WideToggle
|
||||
|
||||
### App List Configuration:
|
||||
|
||||
The Vizio API to launch and identify currently running apps on the TV is very complex.
|
||||
To handle this, the binding maintains a JSON database of applications and their associated metadata in order to populate the `activeApp` dropdown with available apps.
|
||||
|
||||
When the thing is started for the first time, this JSON database is saved into the `appListJson` configuration parameter.
|
||||
This list of apps can be edited via the script editor on the thing configuration.
|
||||
By editing the JSON, apps that are not desired can be removed from the `activeApp` dropdown and newly discovered apps can be added.
|
||||
|
||||
An entry for an application has a `name` element and a `config` element containing `APP_ID`, `NAME_SPACE` and `MESSAGE` (null for most apps):
|
||||
|
||||
```
|
||||
{
|
||||
"name": "Crackle",
|
||||
"config": {
|
||||
"APP_ID": "5",
|
||||
"NAME_SPACE": 4,
|
||||
"MESSAGE": null
|
||||
}
|
||||
},
|
||||
|
||||
```
|
||||
|
||||
If an app is running that is not currently recognized by the binding, the `activeApp` channel will display a message that contains the `APP_ID` and `NAME_SPACE` which can be used to create the missing record for that app in the JSON.
|
||||
|
||||
If an app that is in the JSON database fails to start when selected, try adjusting the `NAME_SPACE` value for that app.
|
||||
`NAME_SPACE` seems to be a version number and adjusting the number up or down may correct the mismatch between the TV and the binding.
|
||||
|
||||
A current list of `APP_ID`'s can be found at http://hometest.buddytv.netdna-cdn.com/appservice/vizio_apps_prod.json
|
||||
and `NAME_SPACE` & `MESSAGE` values needed can be found at http://hometest.buddytv.netdna-cdn.com/appservice/app_availability_prod.json
|
||||
|
||||
If there is an error in the user supplied `appListJson`, the thing will fail to start and display a CONFIGURATION_PENDING message.
|
||||
If all text in `appListJson` is removed (set to null) and the thing configuration saved, the binding will restore `appListJson` from the binding's JSON db.
|
||||
|
||||
## Full Example
|
||||
|
||||
vizio.things:
|
||||
|
||||
```
|
||||
// Vizio TV
|
||||
vizio:vizio_tv:mytv1 "My Vizio TV" [ hostName="192.168.10.1", port=7345, authToken="idspisp0pd" ]
|
||||
|
||||
```
|
||||
|
||||
vizio.items:
|
||||
|
||||
```
|
||||
// Vizio TV items:
|
||||
|
||||
Switch TV_Power "Power" { channel="vizio:vizio_tv:mytv1:power" }
|
||||
Dimmer TV_Volume "Volume [%d %%]" { channel="vizio:vizio_tv:mytv1:volume" }
|
||||
Switch TV_Mute "Mute" { channel="vizio:vizio_tv:mytv1:mute" }
|
||||
String TV_Source "Source Input [%s]" { channel="vizio:vizio_tv:mytv1:source" }
|
||||
String TV_ActiveApp "Current App: [%s]" { channel="vizio:vizio_tv:mytv1:activeApp" }
|
||||
Player TV_Control "Playback Control" { channel="vizio:vizio_tv:mytv1:control" }
|
||||
String TV_Button "Send Command to TV" { channel="vizio:vizio_tv:mytv1:button" }
|
||||
|
||||
```
|
||||
|
||||
vizio.sitemap:
|
||||
|
||||
```
|
||||
sitemap vizio label="Vizio" {
|
||||
Frame label="My Vizio TV" {
|
||||
Switch item=TV_Power
|
||||
// Volume can be a Setpoint also
|
||||
Slider item=TV_Volume minValue=0 maxValue=100 step=1 icon="soundvolume"
|
||||
Switch item=TV_Mute icon="soundvolume_mute"
|
||||
Selection item=TV_Source icon="screen"
|
||||
Selection item=TV_ActiveApp icon="screen"
|
||||
Default item=TV_Control
|
||||
Selection item=TV_Button
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user