LG TV (webOS)

Controls LG webOS TVs (2019 and later) for navigation, inputs, transport, and app launching. It connects over the TV’s SSAP WebSocket.

Connection

Network, over WebSocket: secure wss on port 3001, or plain ws on port 3000. The first connection triggers a pairing prompt on the TV; accepting it yields a client-key, stored as a managed secret.

Power-on is handled by Wake-on-LAN, which needs the TV’s MAC address — read off the set itself the first time the hub connects to it, so nobody has to go and find one.

Setup

• Host — the TV’s address.
• Port — 3001 for wss (2019 and later), 3000 for plain ws.
• MAC address — needed for Wake-on-LAN power-on, and filled in automatically: the driver asks the TV for the MAC of whichever interface it is reachable on, every time it connects. Type one in only if the hub can’t reach the set at all. A MAC you type is never overwritten.
• Pairing — run pair_begin, then accept the prompt on the TV to obtain the client-key.

An LG set announces itself over SSDP, not mDNS, so it appears in the discovered list on its own — the hub searches for urn:lge-com:service:webos-second-screen:1. A TV that never shows up there is either switched off or on a network the hub can’t send multicast to.

What it can do

Command	What it does
pair_begin	Start pairing (accept the prompt on the TV)
power_on (WoL) / power_off	Power the TV on or off
volume_up / volume_down / set_volume	Adjust or set the volume
mute_on / mute_off	Mute or unmute
channel_up / channel_down	Change channel
set_input (e.g. HDMI_1) / input_hdmi1–input_hdmi4	Select an input
launch_app	Launch an app by webOS app id
transport	Play, pause, and related transport control
toast	Show an on-screen message

Reports state and implements input-source discovery, so it exposes the TV’s real input list. It also lists apps: unlike some drivers, it enumerates the live installed apps, with artwork. It ships a remote template.

Notes

Note

Power-on relies on Wake-on-LAN, so the TV needs a MAC address before power_on can work. You don’t have to find one: the driver asks the television for it on every connection and keeps the address of whichever interface the set is actually reachable on. So Power On starts working once the TV has been reached at least once while it was on.

The TV also has to be told to allow it — All Settings → General → Devices → External Devices → TV On With Mobile → Turn on via Wi-Fi. Despite the name it’s needed on a wired set too, and it’s the one half of this the hub can’t do for you.

Pairing fails immediately

A pair_begin that fails in a few milliseconds never reached the TV — a connection that is refused comes straight back, where a TV that is genuinely unreachable takes seconds. The failure names the address and port it tried and says which of these it was:

• Nothing listening on that port. The set has to be on — standby closes both 3000 and 3001. If the other port answers, the message says so; change Port to the one it names.
• The name didn’t resolve. Put the IP address in instead of a hostname.
• No route from the hub. The TV is on a network the hub can’t reach.
• The secure handshake failed. The port is open but its TLS was refused; try port 3000, which webOS also serves in the clear.