homebridge-webos-tv

HomeKit integration for LG webOS TVs how it's supposed to be

homebridge-webos-tv is a plugin for homebridge which allows you to control your LG webOS TV from your Home app! It should work with all TVs that support webOS2 and newer.
If you are already running a TV with native Homekit integration then you can still benefit from using this plugin with adding even more features and functionality to your TV.

Features

HomeKit TV integration
HomeKit automations
Turn TV on/off
Mute/Unmute
Volume control (as light bulb, buttons or through iOS remote app)
Change sound output
Switch inputs
Open apps
Channel control
Media control
Show notifications
Emulate remote control
Run sequences of remote control button presses
Turn on/off the tv screen
Reconfigure control center remote
Switch picture mode
Adjust picture settings

Installation

If you are new to homebridge, please first read the homebridge documentation. If you are running on a Raspberry, you will find a tutorial in the homebridge wiki.

Install homebridge:

sudo npm install -g homebridge

Install homebridge-webos-tv:

sudo npm install -g homebridge-webos-tv

Configuration

Add the webostv platform in config.json in your home directory inside .homebridge.

Add your TV or multiply TVs in the devices or tvs array.

Example configuration:

{
  "platforms": [
    {
      "platform": "webostv",
      "devices": [
        {
          "name": "My webOS tv",
          "ip": "192.168.0.40",
          "mac": "ab💿ef:fe:dc:ba",
          "pollingInterval": 10,
          "volumeControl": "buttons",
          "channelControl": false,
          "mediaControl": false,
          "appButtons": [
            {
              "appId": "com.webos.app.livetv",
              "name": "Live TV"
            },
            {
              "appId": "com.webos.app.hdmi1",
              "name": "PS4"
            },
            {
              "appId": "youtube.leanback.v4",
              "name": "YouTube",
              "params": {
                "contentTarget": "https://www.youtube.com/tv?v=Bey4XXJAqS8"
              }
            }
          ],
          "channelButtons": [
            3,
            5,
            7
          ],
          "notificationButtons": [
            {
              "message": "Motion detected - living room",
              "name": "Living room motion",
              "appId": "com.webos.app.browser",
              "params": {
                "target": "https://www.google.com/"
              }
            },
            {
              "message": "Motion detected - kitchen",
              "name": "Kitchen motion"
            }
          ],
          "remoteControlButtons": [
            "HOME",
            "EXIT"
          ],
          "soundOutputButtons": [
            "tv_speaker",
            "external_optical",
            "headphone"
          ],
          "remoteSequenceButtons": [
            {
              "sequence": [
                "HOME",
                "RIGHT",
                "RIGHT",
                "RIGHT",
                "ENTER"
              ],
              "name": "screen_share_seq"
            },
            {
              "sequence": [
                "VOLUMEUP",
                "VOLUMEDOWN",
                "MUTE",
                "MUTE"
              ],
              "name": "volume_seq",
              "interval": 1000
            }
          ],
          "ccRemoteRemap": {
            "arrowup": "VOLUMEUP",
            "arrowdown": "VOLUMEDOWN",
            "arrowleft": "CHANNELDOWN",
            "arrowright": "CHANNELUP",
            "select": "PROGRAM",
            "back": "BACK",
            "playpause": "YELLOW",
            "information": "TELETEXT"
          },
          "pictureModeButtons": [
            "eco",
            "game",
            "cinema"
          ]
        }
      ]
    }
  ]
}

You also need to enable mobile TV on on your TV for the turn on feature to work correctly.

This is located on your TV under Settings > General > Mobile TV On

On newer TVs LG Connect Apps under the network settings needs to be enabled.

Adding the TV to the Home app

Since HomeKit expects only one TV per bridge they will be declared as external accessories and acts as a bridge.
This means that a TV will not appear in your Home app until you add it!

To add a TV to HomeKit follow this steps:

Open the Home app on your device.
Tap the Home tab, then tap .
Tap Add Accessory, and select I Don't Have a Code or Cannot Scan.
Select the tv accessory you want to pair.
Enter the Homebridge PIN, this can be found under the QR code in Homebridge UI or your Homebridge logs, alternatively you can select Use Camera and scan the QR code again.

For more info check the homebridge wiki Connecting Homebridge To HomeKit.

Inputs

Inputs and apps are automatically fetched from your TV. As default only Live TV and basic external inputs (HDMI1, HDMI2, etc) are enabled in the "inputs spinner". To add more apps to the spinner simply go on the accessory configuration in the Home app and check all the inputs which you would like to have in the spinner.

Parameters

Platform Configuration fields

platform [required] Should always be "webostv".
devices or tvs [required] A list of your TVs.

TV Configuration fields

name [required] Name of your TV.
ip [required] ip address of your TV.
mac [required] Mac address of your TV.
broadcastAdr [optional] If homebridge runs on a host with more than one network interface use this to specify the broadcast address.
keyFile [optional] Specify a custom file path to store the permission token for the TV. If the file doesn't exist it'll be created. Don't specify a directory or you'll get an EISDIR error. Default: "~/.homebridge/.webosTv/keyFile_xxx"
prefsDir [optional] The directory where TV model info should be saved. Default: "~/.homebridge/.webosTv"
pollingInterval [optional] The TV state background polling interval in seconds. Default: 5
deepDebugLog [optional] Enables additional more detailed debug log. Useful when trying to figure out issues with the plugin. Default: false
hideTvService [optional] Whether to hide the TV service. This is recommended if your TV supports native HomeKit integration, since the TV accessory already exists. Default: false
volumeLimit [optional] The max allowed volume which can be set using the TV. Range 1-100. Default: 100
volumeControl [optional] Whether the volume control service is enabled. Default: "both"
- Available values:
  - "both" or true - slider and buttons
  - "none" or false - no volume control
  - "slider" - just slider
  - "buttons" - just buttons
- The slider volume control is not supported for ARC sound outputs
channelControl [optional] Whether the channel control service is enabled. Default: true
mediaControl [optional] Whether the media control service is enabled. Buttons: play, pause, stop, rewind, fast forward. Default: false
screenControl [optional] Whether the screen control service is enabled. Shows a button which allows to turn on/off the tv screen, while the content is still playing. Default: false
screenSaverControl [optional] Whether the screen saver control service is enabled. Shows a button which allows to instantly activate the screen saver on the TV. Can be used only when no content is playing on the tv. Default: false
backlightControl [optional] Whether the backlight control service is enabled. Allows to control the backlight picture setting of the TV. Default: false
brightnessControl [optional] Whether the brightness control service is enabled. Allows to control the brightness picture setting of the TV. Default: false
colorControl [optional] Whether the color control service is enabled. Allows to control the color picture setting of the TV. Default: false
contrastControl [optional] Whether the contrast control service is enabled. Allows to control the contrast picture setting of the TV. Default: false
ccRemoteRemap [optional] Allows to remap the control center remote buttons. For possible values, see section below. Default: no remap
- Set an object with the following properties: arrowup, arrowdown, arrowleft, arrowright, select, back, playpause, information
- See example above on how the property should look like
appButtons [optional] Dedicated app buttons which will appear for the TV. Can be used to trigger automations and can be controlled by Siri. Default: "" (disabled)
- Set an array of app IDs or objects as the value. An object needs to have the appId and name property
- You can optionally specifiy the params property as key/value object to launch the application with the specified parameters
- To get the app ID simply open an app on your TV and check the homebridge console. The app ID of the opened app will be printed
- App buttons can also be used when the TV is off, in that case an attempt to power on the TV and open the chosen app will be made
channelButtons [optional] Whether the channel buttons service is enabled. This allows to create buttons for the channels of your choice. This way you can quickly switch between favorite channels. Default: "" (disabled)
- Set an array of channel numbers as the value
- You can also set an array of objects as the value. An object can have the following properties:
  - channelNumber - [required] the channel number,
  - channelId - [optional] the channel id,
  - name - [optional] the channel name,
- Channel buttons can also be used when the TV is off, in that case an attempt to power on the TV and afterwards open the chosen channel will be made.
- Some webos TVs require the channelId in order to be able to switch channels, in that case this property needs to be specified. To get the channelId simply change a channel on your TV and check the homebridge console. The channelId of the current channel will be printed.
notificationButtons [optional] Whether the notification buttons service is enabled. This allows to create buttons which when pressed display the specified text on the TV screen in a toast. Useful for HomeKit automations or to display text on TV for viewers. Default: "" (disabled)
- Set an array of notification texts as the value
- You can also set an array of objects as the value. An object can have the following properties:
  - message - [required] the message to display in the notification
  - name - [optional] the notification name
  - appId - [optional] when specified, clicking on the toast will open the app
  - params - [optional] parameters to be used for the app when clicking on the toast
  - file - [optional] when specified, the content of the file will be used for the notification message. Specify a file name (will be read from the prefs dir) or full file path
remoteControlButtons [optional] Whether the remote control buttons service is enabled. This allows to emulate remote control buttons. Default: "" (disabled)
- For possible values, see section below.
- Set an array of commands as the value.
- You can also set an array of objects as the value. An object can have the following properties:
  - action - [required] one of the action specified above,
  - name - [optional] the remote control button name
remoteSequenceButtons [optional] Whether the remote sequence buttons service is enabled. This allows to run a sequence of remote control button presses. Default: "" (disabled)
- Set an array of objects as the value. An object can have the following properties:
  - sequence - [required] an array of remote control keys. For possible values see remoteControlButtons above,
  - name - [optional] the sequence name,
  - interval - [optional] the interval between sequence actions. Can be a single value or an array of values. Default is 500ms
soundOutputButtons [optional] Whether the sound output buttons service is enabled. This allows to switch between sound outputs on the TV. Default: "" (disabled)
- Set an array of sound outputs as the value. Example values are:
  - tv_speaker - internal tv speaker,
  - external_optical - optical audio,
  - external_arc - hdmi arc,
  - lineout - line out,
  - headphone - headphones,
  - external_speaker - audio out (optical/hdmi arc),
  - tv_external_speaker - tv speaker and optical,
  - tv_speaker_headphone - tv speaker and headphones
  - bt_soundbar - bluetooth soundbar and bluetooth devices
- You can also set an array of objects as the value. An object can have the following properties:
  - soundOutput - [required] one of the sound outputs specified above,
  - name - [optional] the sound output button name
- Depending on the TV and connected devices to the TV there might also be other values. In that case just switch sound outputs on the TV and check the homebridge log.
pictureModeButtons [optional] Whether the picture mode buttons service is enabled. This allows to switch between picture modes on the TV. Default: "" (disabled)
- Set an array of picture modes as the value. Available values are below.
- You can also set an array of objects as the value. An object can have the following properties:
  - pictureMode - [required] one of the picture modes specified below,
  - name - [optional] the picture mode button name
- Not all picture modes might be available for all TVs.

Remote control values

1, 2, 3, 4, 5, 6, 7, 8, 9, 0, LIST, AD, DASH,
MUTE, VOLUMEUP, VOLUMEDOWN, CHANNELUP, CHANNELDOWN, HOME, MENU,
UP, DOWN, LEFT, RIGHT, CLICK, BACK, EXIT, PROGRAM, ENTER, INFO,
RED, GREEN, YELLOW, BLUE, LIVE_ZOOM, CC, PLAY, PAUSE, REWIND, FASTFORWARD,
POWER, FAVORITES, RECORD, FLASHBACK, QMENU, GOTOPREV,
GOTONEXT, 3D_MODE, SAP, ASPECT_RATIO, EJECT, MYAPPS, RECENT,
BS, BS_NUM_1, BS_NUM_2, BS_NUM_3, BS_NUM_4, BS_NUM_5, BS_NUM_6, BS_NUM_7, BS_NUM_8,
BS_NUM_9, BS_NUM_10, BS_NUM_11, BS_NUM_12, CS1, CS1_NUM_1, CS1_NUM_2, CS1_NUM_3, CS1_NUM_4,
CS1_NUM_5, CS1_NUM_6, CS1_NUM_7, CS1_NUM_8, CS1_NUM_9, CS1_NUM_10, CS1_NUM_11, CS1_NUM_12,
CS2, CS2_NUM_1, CS2_NUM_2, CS2_NUM_3, CS2_NUM_4, CS2_NUM_5, CS2_NUM_6, CS2_NUM_7, CS2_NUM_8,
CS2_NUM_9, CS2_NUM_10, CS2_NUM_11, CS2_NUM_12, TER, TER_NUM_1, TER_NUM_2, TER_NUM_3, TER_NUM_4,
TER_NUM_5, TER_NUM_6, TER_NUM_7, TER_NUM_8, TER_NUM_9, TER_NUM_10, TER_NUM_11, TER_NUM_12,
3DIGIT_INPUT, BML_DATA, JAPAN_DISPLAY, TELETEXT, TEXTOPTION, MAGNIFIER_ZOOM, SCREEN_REMOT

Picture modes

cinema, eco, expert1, expert2, game, normal, photo, sports, technicolor,
vivid, hdrEffect, hdrCinema, hdrCinemaBright, hdrExternal, hdrGame,
hdrStandard, hdrTechnicolor, hdrVivid, dolbyHdrCinema,dolbyHdrCinemaBright,
dolbyHdrDarkAmazon, dolbyHdrGame, dolbyHdrStandard, dolbyHdrVivid, dolbyStandard

Troubleshooting

If you have any issues with the plugin or TV services then you can run homebridge in debug mode, which will provide some additional information. This might be useful for debugging issues.

Homebridge debug mode:

homebridge -D

Deep debug log, add the following to your config.json:

"deepDebugLog": true

This will enable additional extra log which might be helpful to debug all kind of issues. Just be aware that this will produce a lot of log information so it is recommended to use a service like https://pastebin.com/ when providing the log for inspection.

Fixes to known issues

‘Connecting to TV’ when adding the TV to HomeKit

Most probably the ports assigned to your tv accessory are not open in your firewall.

To fix that you need to first update the config.json with a fixed range of ports like this:

...
  "bridge": {
      "name": "Homebridge",
      "username": "**:**:**:**:**:**",
      "pin": "***-**-***",
      "port": 51283
  },
  "ports": {
      "start": 52100,
      "end": 52150
  },
...

After that make sure that the specified range of ports is open in your firewall to allow connections.

TV not visible when trying to add to HomeKit

When you try to add your TV to the HomeKit app but it is not visbile even when in the homebridge UI it appears, then it most probably is a homebridge cache issue.

Homebridge Config UI X

Go to Homebridge Settings and click on Unpair Bridges / Cameras / TVs / External Accessories and remove the TV from the list. After that try to add your TV to the HomeKit app.

HOOBS

Use the Reset Connection button and after that try to add your TV to the HomeKit app.

Special thanks

lgtv2 - the Node.js remote control module for LG WebOS smart TVs.

HAP-NodeJS & homebridge - for making this possible.

homebridge-webos-tvHomebridge plugin for LG webOS TVs