Skip to content

Commit

Permalink
[lgtvserial] Update documentation and fix labels/descriptions (#18253)
Browse files Browse the repository at this point in the history 
Signed-off-by: Michael Lobstein <[email protected]>
  • Loading branch information
@mlobstein
mlobstein authored Feb 12, 2025
1 parent 2a7a76f commit e95fb3c
Show file tree
Hide file tree
Showing 7 changed files with 85 additions and 71 deletions.
104 changes: 59 additions & 45 deletions bundles/org.openhab.binding.lgtvserial/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,79 @@
# LG TV Serial Binding

This binding can send some commands typically used by LG LCD TVs (and some used by projectors).
This binding controls LG TVs, monitors and projectors that have an RS-232C control port.

See below for a list of supported channels.

## Supported Things

Supports one TV or projector per thing, also corresponding to a unique serial port.
Supports one TV, monitor or projector per thing, also corresponding to a unique serial port.
The protocol supports daisy-chaining of serial devices.

The LG serial command set appears to be similar on many models ([1], [5]), but not all commands will work on all models.

Some TVs may have an alternative port type instead of a standard DB9 connector, and may thus require an adapter.
The control port on most TVs is a male DE-9 connector that requires a "Null modem" cable to connect to a serial port or USB to serial adapter.

The serial port may be marked "Service only".
Some TVs have a 3.5 mm phone jack for the control port instead of a DE-9 connector, and may thus require the use of an adapter cable.

Tested and developed with :
The 3.5 mm phone jack may work with a generic 3.5 mm TRS phone plug to DE-9 cable or possibly LG part # EAD62707901 or EAD62707902 (3.5 mm TRRS to DE-9).

- LG 55UF772V (with [this cable adapter](https://www.ebay.com/itm/DB9-9-Pin-Female-To-TRS-3-5mm-Male-Stereo-Serial-Data-Converter-Cable-1-8M-6Ft-/291541959764?)).
- LG 47LK520 with a [serial hat](https://www.buyapi.ca/product/serial-hat-rs232/) on a Raspberry Pi
The control port may be marked "Service Only".

Tested and developed with:

- LG 55UF772V with a generic 3.5 mm TRS phone plug to DE-9 cable
- LG 47LK520 with a [serial hat](https://www.pishop.ca/product/serial-hat-rs232/) on a Raspberry Pi

## Discovery

No discovery supported, manual configuration is required.
No discovery supported; manual configuration is required.

## Thing Configuration

It is necessary to specify the serial port device used for communication.
The thing has the following configuration parameters:

| Parameter Label | Parameter ID | Description | Accepted values |
|------------------------|----------------------|---------------------------------------------------------------------------------|------------------|
| Serial Port | port | Serial port to use for connecting to TV/monitor/projector. | Serial port name |
| Set ID | setId | Set ID configured in the TV. If 0, will send the commands to every chained TV. | 0-99; default 1 |

It is necessary to specify the serial port used for communication.
On Linux systems, this will usually be either `/dev/ttyS0`, `/dev/ttyUSB0` or `/dev/ttyACM0` (or a higher number than `0` if multiple devices are present).
On Windows it will be `COM1`, `COM2`, etc.

The set id can also be specified when using daisy-chaining.
That allows you to have a thing that will handle a particular device (with set id other than 0), and another to send command on all devices (with set id equals 0).
However, the item values for the thing with set id 0 will never display the right values as it receives responses from many devices.
The Set ID can also be specified when using daisy-chaining.
This allows you to have a Thing that will handle a particular device (with Set ID other than 0), and another to send commands to all devices (with Set equals 0).
However, the item values for the Thing with Set ID 0 will never display the right values as it receives responses from many devices.

## Channels

The following channels are common to most TV through the serial or service port, taken from [4].
The following channels are common to most TVs, taken from [4].

| Channel type id | Command | Item type | Description |
| Channel ID | Command | Item Type | Description |
|-----------------|---------|-----------|--------------------------------------------------|
| aspect-ratio | k c | String | Adjust screen format, at least 4:3, 16:9 formats |
| power | k a | Switch | Turns the device on or off |
| volume | k f | Dimmer | Sets the volume, values are from 0 to 100 |
| volume-mute | k e | Switch | Set mute on or off |

As for others, please refer to the documentation of your device in the section named "Controlling the multiple product", "External control" or any section that refers to RS-232, the names of the channels map the command names.
As for others, please refer to the documentation of your device in the section named "Controlling the multiple product", "External control" or any section that refers to RS-232.
If your device documentation doesn't give such information, you can look at the "LG protocol references" below and use the "Generic LG TV" thing which should contain all the different possible channels/commands.

Note: Devices might not respond or return an error to some command when the device is powered off which will make your items look in a wrong state until the TV turns on.
Note: Devices might not respond or return an error to some command when the device is powered off which can put items in an incorrect state until the device is turned on.
For instance, getting the volume status when the device is off makes no sense.

## All channel type ids

Here's a list of all the LG TV commands added to the binding, in channel type id alphabetic order
Here is the list of all the LG TV commands added to the binding, in channel type id alphabetic order:

| Channel type id | Command | Item type | Description |
| Channel ID | Command | Item Type | Description |
|--------------------|---------|-----------|-----------------------------------------------------|
| 3d | x t | String | To change 3D mode for tv |
| 2d-extended | x v | String | To change 3D options for tv |
| 3d | x t | String | To change the 3D mode |
| 3d-extended | x v | String | To change the 3D options |
| aspect-ratio | k c | String | To adjust the screen format |
| auto-sleep | f g | Switch | Set Auto Sleep |
| auto-volume | d u | Switch | Automatically adjust the volume level |
| speaker | d v | Switch | Turn the speaker on or off |
| auto-sleep | f g | Switch | To set the Auto Sleep function |
| auto-volume | d u | Switch | To set the Auto Volume adjustment function |
| speaker | d v | Switch | To turn the speaker on or off |
| backlight | m g | Dimmer | To adjust screen backlight |
| balance | k t | Dimmer | To adjust balance, from 0 to 100 |
| bass | k s | Dimmer | To adjust bass, from 0 to 100 |
Expand All @@ -71,33 +82,32 @@ Here's a list of all the LG TV commands added to the binding, in channel type id
| color-temperature | k u | String | To adjust the screen color temperature |
| color-temperature2 | x u | Dimmer | To adjust color temperature, from 0 to 100 |
| contrast | k g | Dimmer | To adjust screen contrast, from 0 to 100 |
| dpm | f j | Switch | Set the DPM (Display Power Management) function |
| dpm | f j | Switch | To set the DPM (Display Power Management) function |
| energy-saving | j q | String | To control the energy saving function |
| fan-fault-check | d w | Switch | To check the Fan fault of the TV |
| fan-fault-check | d w | Switch | To read the Fan fault status of the device |
| elapsed-time | d l | String | To read the elapsed time |
| h-position | f q | Dimmer | To set the Horizontal position, from 0 to 100 |
| h-size | f s | Dimmer | To set the Horizontal size, from 0 to 100 |
| input | k b | String | To select input source for the Set |
| input2 | x b | String | To select input source for set |
| input | k b | String | To select the current input source for the device |
| input2 | x b | String | To select the current input source for the device |
| ism-method | j p | String | To avoid having a fixed image remain on screen |
| ir-key-code | m c | String | To send IR remote key code |
| lamp-fault-check | d p | Switch | To check lamp fault |
| power | k a | Switch | To control Power On/Off of the set |
| osd-select | k l | Switch | To select OSD (On Screen Display) on/off |
| osd-language | f i | String | Set the OSD language |
| ir-key-code | m c | String | To send an IR remote key code |
| lamp-fault-check | d p | Switch | To read the lamp fault status of the device |
| power | k a | Switch | To turn the device on or off |
| osd-select | k l | Switch | To select OSD (On Screen Display) on or off |
| osd-language | f i | String | To set the OSD language |
| natural-mode | d j | Switch | To assign the Tile Natural mode for Tiling function |
| picture-mode | d x | String | To adjust the picture mode |
| power-indicator | f o | Switch | To set the LED for Power Indicator |
| power-saving | f l | Switch | To set the Power saving mode |
| screen-mute | k d | String | To select screen mute on/off |
| screen-mute | k d | String | To select screen mute on or off |
| serial-number | f y | String | To read the serial numbers |
| software-version | f z | String | Check the software version |
| software-version | f z | String | To read the software version |
| sharpness | k k | Dimmer | To adjust screen sharpness, from 0 to 100 |
| sleep-time | f f | String | Set sleep time |
| sleep-time | f f | String | To set the sleep timer |
| sound-mode | d y | String | To adjust the Sound mode |
| speaker | d v | Switch | Turn the speaker on or off |
| speaker | d v | Switch | To turn the speaker on or off |
| temperature-value | d n | String | To read the inside temperature value |
| tile-mode | d d | String | Change a Tile mode |
| tile | d d | String | To change the Tile mode |
| tile-h-position | d e | Dimmer | To set the Horizontal position, from 0 to 100 |
| tile-h-size | d g | Dimmer | To set the Horizontal size, from 0 to 100 |
| tile-id-set | d i | Dimmer | To assign the Tile ID for Tiling function, 0 to 25 |
Expand All @@ -106,15 +116,17 @@ Here's a list of all the LG TV commands added to the binding, in channel type id
| tint | k j | Dimmer | To adjust screen tint, from 0 to 100 |
| treble | k r | Dimmer | To adjust treble, from 0 to 100 |
| volume | k f | Dimmer | To adjust volume, from 0 to 100 |
| volume-mute | k e | Switch | Set mute on or off |
| volume-mute | k e | Switch | To set mute on or off |
| v-position | f r | Dimmer | To set the Vertical position, from 0 to 100 |
| v-size | f t | Dimmer | To set the Vertical size, from 0 to 100 |
| raw **(advanced)** | | String | To send a raw command directly to the device(s) |

## Not added or linked commands

## Not added or linked command
The following commands/channels are not currently implemented in the binding but the commands could be sent via the `raw` channel.

| Channel type id | Command | Description
| Channel ID | Command | Description
|--------------------|---------|------------------------------------------------------------------------------------------------------------|
| abnormal-state | k z | Used to Read the power off status when Stand-by mode |
| abnormal-state | k z | Used to read the power off status when in Stand-by mode |
| auto-configuration | j u | To adjust picture position and minimize image shaking automatically. it works only in RGB(PC) mode. |
| power-on-delay | f h | Set the schedule delay when the power is turned on (Unit: second) |
| remote-lock | k m | To control Remote Lock on/off to the set. Locks the remote control and the local keys. |
Expand All @@ -125,17 +137,19 @@ Here's a list of all the LG TV commands added to the binding, in channel type id
| off-timer-on-off | f c | Set days for Off Timer |
| on-timer-time | f d | Set On Timer |
| off-timer-time | f e | Set Off Timer |
| h-size | f s | Set the Horizontal size, from 0 to 100 |
| v-size | f t | Set the Vertical size, from 0 to 100 |

## LG protocol references

[1] <https://www.lg.com/us/commercial/documents/m6503ccba-owner-manual.pdf>
[1] Manual for M6503C monitor <https://gscs-b2c.lge.com/downloadFile?fileId=KROWM000237239.pdf>

[2] <https://sites.google.com/site/brendanrobert/projects/bits-and-pieces/lg-tv-hacks>

[3] <https://code.google.com/archive/p/lg-tv-command/source/default/source>

[4] <https://github.com/suan/libLGTV_serial>

[5] Manual LV series, LK series, PW series and PZ series <https://gscs-b2c.lge.com/downloadFile?fileId=ujpO8yH69djwNZzwuavqpQ>
[5] Manual for LV series, LK series, PW series and PZ series <https://gscs-b2c.lge.com/downloadFile?fileId=ujpO8yH69djwNZzwuavqpQ>

[6] Manual for LD series, LE series, LX series and PK series <https://gscs-b2c.lge.com/downloadFile?fileId=76If0tKDLOUizuoXikllgQ>
2 changes: 1 addition & 1 deletion bundles/org.openhab.binding.lgtvserial/src/main/resources/OH-INF/addon/addon.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

<type>binding</type>
<name>LG TV Serial Binding</name>
<description>Controlling LG TVs using serial (RS232C) protocol</description>
<description>Controls LG TVs that have an RS-232C control port</description>
<connection>local</connection>

</addon:addon>
2 changes: 1 addition & 1 deletion bundles/org.openhab.binding.lgtvserial/src/main/resources/OH-INF/config/config.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
</parameter>
<parameter name="setId" type="integer" required="true">
<label>Set ID</label>
<description>Set ID configured in the TV. If 0, this will send a command to every chained TV.</description>
<description>Set ID configured in the TV. If 0, will send the commands to every chained TV.</description>
<default>1</default>
</parameter>
</config-description>
Expand Down
Loading

0 comments on commit e95fb3c

Please sign in to comment.