Lightware LW3

Controls Lightware video matrices, extenders and presentation switchers that speak LW3, the open line-based control protocol Lightware serves on TCP port 6107. Covers the MMX2 family, MMX6x2, UMX-TPS, Taurus UCX, HDMI20-OPTC extender pairs and the VINX / UBEX control planes.

Each matrix destination (output) becomes a GEM zone. The driver subscribes to the crosspoint, so a route changed from the front panel, from Lightware Device Controller, or by another control system shows up in GEM within a few hundred milliseconds — it is not poll-only.

Driver name: lightware_lw3
Transport: ASCII lines over TCP
Default port: 6107
Category: AV matrix

Prerequisites

An LW3-capable device. LW3 is standard on everything from roughly the MX2 generation onward. Older MX-series frames speak LW2 on port 10001 and are not supported here — if a GET on 6107 returns nothing, the unit is LW2.
TCP/6107 reachable from the GEM server.
A static IP or DHCP reservation on the device.
Nothing needs to be released first — LW3 permits several concurrent sessions, so Lightware Device Controller can stay open while GEM is connected.

danger

LW3 on port 6107 is unauthenticated. Anything that can open a socket to that port can re-route the matrix, mute outputs, and read the device configuration. That is a property of the protocol, not of this driver. Keep Lightware devices on a closed control VLAN and do not expose 6107 beyond it.

Setup steps

Verify the device answers LW3. From the GEM server:
```
telnet <device-ip> 6107
GET /MEDIA/VIDEO/XP.DestinationConnectionList
```
A healthy device replies with a line like pr /MEDIA/VIDEO/XP.DestinationConnectionList=I1;I2;I1;O1.
In GEM go to /admin/devices, add a device, and pick driver Lightware LW3. Enter the device IP; leave the port at 6107.
Save. The driver reads the product name, serial number and firmware version, opens a subscription on the crosspoint, and reads the current routing.

Run the get_outputs command to see the crosspoint size and current routes:

{
  "input_count": 8,
  "output_count": 4,
  "routes": [
    {"destination": 1, "input": 3},
    {"destination": 2, "input": 1}
  ]
}

Create one GEM zone per destination. Set zone.address to the destination number as labelled on the device — 1, 2, 3. The LW3 form (O1) is accepted as well.
Optional: define AV Sources keyed to the input numbers so the UI shows "Apple TV" rather than "input 3".
Optional: on a model with a separate audio crosspoint, set audio_breakaway to enable set_audio_input and audio-route reporting.

Attribute reference

Device attributes

Attribute	Required	Default	What it does
`ip`	yes	—	LAN IP or hostname of the Lightware device.
`port`	no	`6107`	LW3 control port.
`audio_breakaway`	no	`false`	Poll and expose `/MEDIA/AUDIO/XP`. Leave off on video-follows-audio models — the node does not exist and every poll would log an error.
`input_count`	no	read from device	Number of sources. Read from `SourcePortCount` at connect; set manually only to override. Out-of-range routes are rejected against it.
`output_count`	no	read from device	Number of destinations, from `DestinationPortCount`.
`status_interval`	no	`15000`	Backstop crosspoint poll in ms. The subscription does the real work; this catches anything it missed.
`command_throttle`	no	`80`	Minimum spacing between outbound LW3 lines, in ms.

The driver also writes model, serial_number, firmware_version and part_number onto the device row from the root node at connect.

Zone attributes written by the driver

Attribute	Meaning
`input`	Crosspoint source currently routed to this destination. `0` means nothing is connected.
`audio_input`	Audio crosspoint source, when `audio_breakaway` is enabled.
`mute_state`	`on` / `off`, decoded from `DestinationPortStatus`.
`port_locked`	`true` when the destination is locked against route changes.
`port_status`	The raw `DestinationPortStatus` entry for this destination, verbatim.

note

The driver never writes zone.source. That attribute is GEM's foreign key into the av_source table and belongs to the AV routing macros. The matrix's physical input number goes in zone.input.

Zone address format

Form	Meaning
`1`	Destination (output) 1
`O1`	The same destination in LW3 notation

Whatever form you use, the driver normalises it to O<n> on the wire.

Commands

Command	Args	LW3 sent
`set_input` / `route`	`address`, `input`	`CALL /MEDIA/VIDEO/XP:switch(I<in>:O<out>)`
`set_audio_input`	`address`, `input`	`CALL /MEDIA/AUDIO/XP:switch(...)` — needs `audio_breakaway`
`mute_on`	`address`	`CALL /MEDIA/VIDEO/XP:muteDestination(O<out>)`
`mute_off`	`address`	`CALL /MEDIA/VIDEO/XP:unmuteDestination(O<out>)`
`mute_toggle`	`address`	Resolved from the last reported port status, then `mute_on` / `mute_off`
`lock_output`	`address`	`CALL /MEDIA/VIDEO/XP:lockDestination(O<out>)`
`unlock_output`	`address`	`CALL /MEDIA/VIDEO/XP:unlockDestination(O<out>)`
`get_outputs`	—	Reads port counts and the connection list
`get_status`	—	Forces a crosspoint poll
`get_device_info`	—	Re-reads the root-node identity properties
`recall_preset`	`preset`	Not implemented — see limitations
`raw_lw3`	`command`	Sends one raw LW3 line

Every route, mute and lock command is followed by a read-back of the relevant property rather than an optimistic state write, because a locked destination accepts the call and then refuses the switch. GEM shows what the device reports, not what was asked for.

Understanding the protocol responses

Useful when reading the device log or using raw_lw3:

Prefix	Meaning
`pw`	Writable property value
`pr`	Read-only property value
`mO`	Method call succeeded
`mF`	Method call failed
`pE` / `nE` / `mE`	Property / node / method error
`n-`	Node listing entry
`o-`	Subscription opened
`CHG`	Unsolicited change on a subscribed node

CHG and pr are handled identically by the driver, which is exactly why a front-panel route change propagates into GEM.

Known limitations

Preset recall is not implemented. The preset node path differs between product families and could not be verified against hardware, so recall_preset returns not yet implemented rather than guessing a path and appearing to work. Use raw_lw3 with the path from your model's LW3 reference until it is wired up properly.
DestinationPortStatus is only partly decoded. The first character carries mute and lock state — T neither, M muted, L locked, U both — and the driver decodes that. The remaining characters are model-specific signal bits and are stored verbatim in port_status rather than interpreted. Check them against your model's LW3 reference before building automation on them.
No LW3 command signatures. The driver does not use the {signature} bracketing that lets a client correlate a reply to a specific request. Responses are matched by node path instead. The practical effect is that the driver cannot tell "this is the answer to my GET" from "someone else just changed this" — and it treats both as truth, which is the desired behaviour here.
Audio is off by default. With audio_breakaway disabled, the audio crosspoint is never touched. That is correct for a switcher where audio follows video.
LW2 devices are out of scope. Older MX frames on port 10001 need a separate driver.
No EDID management, no signal analysis, no test-pattern generation. Those live under other LW3 node trees and are reachable through raw_lw3 if needed.

Troubleshooting

Device connects but no routes ever appear The unit is probably LW2. Confirm with a manual GET /MEDIA/VIDEO/XP.DestinationConnectionList on port 6107 — silence or a closed socket means LW2 on 10001.

set_input returns ok but the route does not change The destination is locked. Check the zone's port_locked attribute and send unlock_output. This is exactly why the driver reads back instead of writing state optimistically.

Route changes work, mute state never updates The model's DestinationPortStatus string starts with a character outside T/M/L/U. The raw value is still recorded in port_status — read it and open a note so the decode table can be extended.

nE errors in the log mentioning /MEDIA/AUDIO/XP audio_breakaway is enabled on a model with no separate audio crosspoint. Turn it off.

Errors on GET /.ProductName at connect Harmless. Not every product exposes all four root identity properties; the driver probes them and ignores the ones that are missing. The device stays connected.

Connection drops and reconnects repeatedly Something else is resetting the session, or the device is being rebooted by a PoE/power schedule. LW3 permits concurrent sessions, so another controller connecting is not the cause. Check for a power or network interruption on the device.

AV Zones — binding matrix destinations to AV zones.
AV Sources — naming inputs so the UI shows sources, not numbers.
Devices — adding and configuring device rows.

Prerequisites​

Setup steps​

Attribute reference​

Device attributes​

Zone attributes written by the driver​

Zone address format​

Commands​

Understanding the protocol responses​

Known limitations​

Troubleshooting​

Related​