homebridge-webos-tv puts an LG webOS TV into HomeKit

It is a Homebridge plugin, and the TV is an accessory

homebridge-webos-tv is a plugin for Homebridge which allows you to control your LG webOS TV from your Home app, and it should work with all TVs that support webOS2 and newer. The README is explicit about the audience nuance, saying that if you are already running a TV with native HomeKit integration you can still benefit from using this plugin by adding even more features and functionality to your TV. That distinction matters, because the plugin is not primarily a way to get a TV into HomeKit. It is a way to get more out of a TV that is already there. The package metadata backs the range, listing keyword support for webos2, webos3, webos4, webos5, webos6, webos22 and webos23, along with lgtv, homebridge and homekit. The implementation is an ES module with the main entry at index.js, a lib/ directory, a cli/ directory, a config.schema.json for editor validation, and a CHANGELOG.md.

The feature list is broader than a power switch

The features list is the reason to choose this plugin over the TV's own integration, and it is long. There is the HomeKit TV integration itself and HomeKit automations, then turn on and off, mute and unmute, volume control which can be exposed as a light bulb, as buttons or through the iOS remote app, changing sound output, switching inputs, opening apps, channel control, media control, showing notifications, emulating the remote control, running sequences of remote control button presses, turning the TV screen on and off separately from the device, reconfiguring the control center remote, switching picture mode, adjusting picture settings, switching sound mode, and showing the service menu or the ezAdjust menu. Two of those are unusual enough to be worth calling out. Turning the screen off while leaving the device on is the behaviour people actually want, since a TV in standby that cannot be woken is a TV you have to get up to switch on. And the remote remapping block lets you redefine what the arrow keys and select button do, per app, which is how you get a streaming app to behave the way it does on a native remote.

The configuration is one device object with optional button groups

Configuration lives in the Homebridge config.json under the webostv platform, with the TVs listed in a devices or tvs array, and the example in the README shows a single device with a name, an ip, a mac, a polling interval, and switches for volume control style, channel control, media control and the service menu button. The bulk of the file is a set of optional button groups, each of which becomes switches in HomeKit. The appButtons array gives an app id, a name, and optionally params, so a YouTube entry can point at a specific video URL. channelButtons is a list of channel numbers. notificationButtons carries a message, a name and optionally an app to open, which is how a motion notification appears on the television. soundOutputButtons lists output names such as tv_speaker, external_optical and headphone. pictureModeButtons and soundModeButtons are similar short lists of mode names, and remoteControlButtons lists raw remote key names such as HOME and EXIT. The remoteSequenceButtons entries hold a sequence of key presses with a name and an optional interval in milliseconds, which is how a screen share shortcut is scripted as HOME, RIGHT, RIGHT, RIGHT, ENTER.

Remapping the control center, and triggers

Two configuration blocks are more advanced than the rest. The ccRemoteRemap object renames what the HomeKit control center remote sends, mapping arrowup to VOLUMEUP, arrowdown to VOLUMEDOWN, arrowleft to CHANNELDOWN, arrowright to CHANNELUP, select to PROGRAM, back to BACK, playpause to YELLOW and information to TELETEXT, and it can be overridden per app with a key such as youtube.leanback.v4 that changes information to MUTE and select to HOME. The triggers object defines conditions, with a volume trigger using a threshold and a name so the switch shows up in Home as a named condition, and a backlight trigger with a threshold of 70. The named trigger is what makes the condition usable in a HomeKit automation, since a bare threshold switch is not much use on its own. A config.schema.json at the repository root means editors can validate this configuration as you type it, which matters given how many nested options there are.

Installation and the TV settings that must be changed

Installation is two global npm installs, one for Homebridge and one for the plugin:

sudo npm install -g homebridge

sudo npm install -g homebridge-webos-tv

Two settings on the television itself have to be changed, and the README says so plainly. You need to enable mobile TV on for the turn on feature to work correctly, which is under Settings, then General, then Mobile TV On. On newer TVs, LG Connect Apps under the network settings needs to be enabled as well. That second requirement is the sort of thing that makes a plugin work on one set and not another, since it depends on the model and the firmware. The README also covers the case where you are new to Homebridge by pointing at the Homebridge documentation, and mentions a tutorial in the Homebridge wiki for installing it on a Raspberry Pi. The package manifest pins the supported versions, with Node.js at ^18.20.4, ^20.15.1, ^22 or ^24, and Homebridge at ^1.6.0 or a 2.0.0 beta.

A TV is an external accessory, so it does not appear on its own

There is one HomeKit behaviour that catches people out, and the README explains it directly. Since HomeKit expects only one TV per bridge, they will be declared as external accessories and act as a bridge, which means that a TV will not appear in your Home app until you add it. The pairing steps follow the standard Home flow, opening the Home app, tapping the Home tab, then Add Accessory and selecting the option for not having a code or being unable to scan, then choosing the TV accessory to pair, and finally entering the Homebridge PIN. The PIN is under the QR code in the Homebridge user interface or in the Homebridge logs, and the alternative is to select Use Camera and scan the QR code again. The package also ships a small command line entry point, the webostv binary pointing at cli/index.js, and the dependency list gives a good picture of the implementation, with websocket for the webOS connection, wake_on_lan for the power on path, tcp-ping for reachability checks, persist-path for saved state, chalk for terminal output, and yargs for the CLI parsing.

Editorial conclusion

Adopt homebridge-webos-tv when you run Homebridge as your only bridge, you have an LG webOS television, and you want the TV in the Home app with controls for volume, inputs, apps and picture settings. Do not adopt it if your TVs already expose native HomeKit, where the plugin's value is the extra features rather than the integration itself. Verify first that your TV runs webOS2 or newer, that mobile TV on is enabled in the TV settings, that LG Connect Apps is enabled on newer sets, and that your Node.js and Homebridge versions fall inside the ranges the package manifest declares.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. merdok/homebridge-webos-tv on GitHub
4. README