LG webOS TV

LG webOS smart TVs (any WiFi/LAN model running webOS) are controlled over LG's webOS WebSocket API on port 3000 — the same protocol the LG mobile remote app uses. One TV becomes one GEM device, and commands target that device directly (this driver creates no zones).

Two things to know before you start:

• Pairing, not a password. The first time GEM connects, the TV pops a pairing prompt on screen and someone must press OK with the remote. GEM stores the resulting pairing token automatically — you never type it in.
• Power-on is Wake-on-LAN. webOS has no "turn on" command while the TV is off, so GEM powers the TV on by sending a Wake-on-LAN packet to its MAC address. That only works if Wake-on-LAN is enabled on the TV, which is why the MAC address is a required field.

What's controlled

• Power — on (via Wake-on-LAN) and off.
• Volume and mute — volume up/down, mute on/off. (See "Volume, mute, and the TV's own speakers" for how mute-toggle and a fixed volume level work through an AV zone.)
• Inputs — switch the TV to any HDMI/external input by its webOS input id.
• Apps — launch or close any installed app by its webOS app id, open a web URL, and list what's installed.
• Channels — channel up/down and tune a specific channel (for the TV's own tuner).
• Media transport — play, pause, stop, rewind, fast-forward.
• On-screen notifications — pop a text toast on the TV.
• Sound output — switch where the TV sends audio (internal speakers, ARC/optical, Bluetooth soundbar, etc.).
• Live status feedback — GEM polls the TV a few times a minute and reports the current volume, mute state, and the app currently on screen, so a touchpanel and triggers stay in sync.

Prerequisites

• An LG webOS TV on the same LAN as GEM, reachable by IP (no NAT between them). Give it a static IP or DHCP reservation so its address never moves.
• LG Connect Apps / mobile-app control enabled on the TV (the setting that lets the LG remote app and third-party controllers connect). On most models this is on by default.
• Wake-on-LAN enabled if you want power_on to work while the TV is off. On the TV this is usually Settings → General → Devices → External Devices → Mobile TV On / Turn on via WiFi (the exact path varies by model year). Without it, GEM can control the TV when it's on but cannot wake it.
• The TV's MAC address — printed on the TV or shown under the TV's network settings.

Setup

1. Open Devices, add a device, and choose the LG webOS TV driver. It suggests the AV subsystem and a display device type — accept those.
2. Fill in the two required fields:
   • TV IP Address — the TV's LAN IP.
   • TV MAC Address — used for Wake-on-LAN power-on, e.g. AA:BB:CC:DD:EE:FF.
3. Save and enable the device.
4. Approve the pairing prompt on the TV. On the first connect the TV shows a pairing request on screen — press OK with the TV remote. GEM stores the pairing token in the read-only Client Key attribute automatically; you should not have to pair again unless the token is cleared or a firmware update invalidates it.

Once paired, GEM stays connected and begins polling the TV for volume, mute, and the foreground app.

Power on, and the Wake-on-LAN limitation

power_on sends a Wake-on-LAN "magic packet" to the TV's MAC address — there is no other way to wake a webOS TV that is fully off. Keep these realities in mind when commissioning:

• If the MAC address is wrong or blank, or Wake-on-LAN ("Mobile TV On") is disabled on the TV, power_on does nothing.
• Wake-on-LAN is a broadcast on the local subnet — the TV and GEM must be on the same network segment (no router between them blocking broadcast).
• The ~10-minute window. Many webOS models stop answering Wake-on-LAN after roughly ten minutes of being off (the network interface goes fully to sleep). Past that point the TV can only be woken with the remote. If reliable cold power-on matters on the job, the standard workaround is a network-attached IR blaster sending the TV's IR power code as a fallback.

power_off is a normal webOS command and works any time the TV is on and connected.

Volume, mute, and the TV's own speakers

The driver exposes volume_up, volume_down, mute_on, and mute_off. There is no native webOS "set volume to N" and no native mute-toggle — so:

• If the room's audio comes out of the TV's own speakers, make this TV the AV zone's volume device: open AV Zones, edit the zone, and set the Volume Device field to this TV. Volume and mute commands for that zone then route to the TV.
• Mute-toggle is handled for you in that case. When the TV is an AV zone's Volume Device and a mute-toggle is requested, GEM looks at the TV's last-known mute state and sends mute_on or mute_off accordingly — you do not need a separate mute-toggle command on the TV.
• If the room audio comes from a receiver, amp, or soundbar instead, leave that device as the AV zone's Volume Device and set the TV's own sound output away from its speakers (see "Sound output" below) so you are not controlling two volumes at once.

note

Sending mute_toggle straight to the TV device (for example from a plain UI button wired to the device, not through an AV zone) won't toggle — the driver only has mute_on / mute_off. The automatic toggle behavior is the AV-zone volume path described above. On a button, bind it to the AV zone's mute, or alternate mute_on / mute_off yourself.

Inputs, apps, and sound output

webOS identifies inputs, apps, and sound outputs by internal ids, not by the friendly names you see on screen. Discover the real ids on the actual TV rather than guessing:

• Inputs. Run get_inputs to list the TV's external inputs and their ids, then pass one to the input command's input argument. Ids look like HDMI_1, HDMI_2, HDMI_3, depending on the model.
• Apps. Run get_apps (or get_launch_points) to list installed apps with their ids, then pass an id to launch_app's app_id argument. The app id is not the on-screen name — Netflix, for instance, is netflix, not "Netflix".
• Sound output. Run get_sound_output to read the current setting, then pass a webOS output value to set_sound_output's output argument. Common values are tv_speaker (internal speakers), external_arc (HDMI ARC), external_optical, and bt_soundbar. Use the value get_sound_output reports as your reference for what this TV accepts.

Status feedback

While connected, GEM polls the TV on a short interval (default 2 seconds, set by the optional status_interval attribute in milliseconds) and updates three device attributes when they change:

• volume — the TV's current volume level.
• mute_state — on or off.
• input — derived from the app currently in the foreground, so you can see and trigger on what's on screen.

These are what keep a touchpanel's now-playing and volume readout live, and they can be used as trigger conditions (for example, fire a macro when a specific app comes to the foreground). See Triggers.

Attributes

Device — required

Attribute	Type	Description
ip	string	The TV's LAN IP address.
mac_address	string	The TV's MAC address. Required for Wake-on-LAN power_on.

Device — optional

Attribute	Type	Default	Description
client_key	string (secure, read-only)	—	webOS pairing token. Stored automatically after you approve the on-TV pairing prompt; you don't enter it. Clear it to force re-pairing.
status_interval	int	2000	How often (ms) GEM polls the TV for volume, mute, and foreground app.

note

LG webOS TVs have no entries in the attribute autocomplete catalog, so when you reference these names in triggers or macros, type them exactly as shown.

Commands

Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons.

Power

Command	Action
power_on	Wake the TV via Wake-on-LAN to its MAC address.
power_off	Turn the TV off.

Volume and mute

Command	Action
volume_up / volume_down	Step the TV volume up / down.
mute_on / mute_off	Mute / unmute. (Mute-toggle is emulated through the AV-zone volume path — see above.)
get_volume	Read the current volume.
get_audio_status	Read volume and mute together.

Inputs and sound output

Command	Action
input (arg input)	Switch to an input by its webOS input id (e.g. HDMI_1).
get_inputs	List external inputs and their ids.
set_sound_output (arg output)	Set where the TV sends audio (e.g. tv_speaker, external_arc).
get_sound_output	Read the current sound output.

Channels

Command	Action
channel_up / channel_down	Tuner channel up / down.
channel (arg channel)	Tune a specific channel id.
get_channel	Read the current channel.

Apps and web

Command	Action
launch_app (arg app_id)	Launch an installed app by its webOS app id.
close_app (arg app_id)	Close an app by its id.
get_apps	List installed apps (id and name).
get_launch_points	List app launch points (an alternate app listing).
get_foreground_app	Report the app currently on screen.
open_url (arg url)	Open the TV web browser at a URL.
get_services	List webOS services.
get_system_info	Read TV model / system information.

Media transport

Command	Action
play pause stop	Transport control.
fast_forward / rewind	Scan forward / back.

Notifications

Command	Action
send_notification (arg message)	Pop a text toast on the TV screen.

Known limitations

• Power-on is Wake-on-LAN only, with the ~10-minute sleep limitation above. There is no protocol "turn on" once the TV is fully asleep — use an IR blaster as a fallback if cold power-on must be reliable.
• No native set-volume-to-N and no native mute-toggle. Volume is stepped with volume_up / volume_down; mute-toggle is emulated through the AV-zone volume path.
• First connect always requires the on-TV pairing prompt — someone must press OK with the remote during commissioning. After that the stored token is reused.
• Single device, no zones. An LG TV is one GEM device; it creates no zones. Group rooms and multi-room behavior at the AV-zone / macro layer.

Troubleshooting

Symptom	Check
Pairing prompt never appears / can't pair	Confirm LG Connect Apps / mobile-app control is enabled on the TV, the TV IP is correct, and GEM is on the same LAN with no NAT.
Commands time out after a TV firmware update	webOS pairing tokens occasionally invalidate after a firmware update. Clear the Client Key attribute and re-pair (approve the new on-TV prompt).
power_on does nothing	Confirm the MAC Address is set correctly and Wake-on-LAN ("Mobile TV On" / "Turn on via WiFi") is enabled on the TV. Confirm the TV and GEM share the same subnet, and that you're inside the ~10-minute wake window.
launch_app reports no app id / launches nothing	Run get_apps to enumerate installed app ids — the user-visible name (e.g. "Netflix") is not the app id.
input does nothing	Run get_inputs to get the exact input ids; pass one of those to input rather than a friendly name.
Volume readout or now-playing is stale	Confirm the device is enabled and connected; status polling runs on status_interval (default 2 s).

See also

• AV Zones — make the TV a zone's Volume Device so volume and mute route to it.
• Devices — adding and configuring devices.
• Commands — running and scripting device commands.
• Triggers — fire automations on the TV's app/volume/mute state.