Optoma Projector

Control any Optoma commercial installation or home-cinema projector that exposes the RS-232 command surface over LAN (which covers virtually every model shipped since 2015 — ZH / ZK / EH / UHD / GT / HD series and most of the commercial ProAV lineup).

The driver speaks the standard Optoma text command protocol (~00<cmd> <val>\r) directly to the projector on TCP port 23. No cloud, no vendor SDK, no license required.

Prerequisites

• Network Standby enabled. In the projector OSD: Setup → Power → Network Standby → On. Without this, the projector's LAN port powers down when the projector is off, and control is only possible while it is already on.
• LAN control enabled. In the projector OSD: Setup → Network → LAN Control — pick the option that mentions "RS232 by IP" or "Extron IP" (label varies by firmware). This exposes the RS-232 command surface on the network port.
• Static IP or DHCP reservation on the projector. Note the address from Setup → Network → LAN Settings.
• Confirmed control port. Most models ship on TCP 23. Some ZK / UHD installation models use 3023. The setup screen usually shows the current value.

Setup steps

1. Enter the projector menu and enable Network Standby and LAN control per Prerequisites.
2. Note the projector's IP address and confirm the control port under Setup → Network.
3. In GEM, go to Admin → Devices and add a new device.
4. Choose driver optoma_projector.
5. Fill in:
   • Projector IP — the LAN IP from the projector's Network Settings.
   • Control Port — leave 23 unless the projector's Network menu says otherwise.
6. Save. Within a few seconds the device should show as connected and populate model_name, firmware_version, lamp_hours, power_state, and input.

Attribute reference

Required

Attribute	Type	Description
ip	string	LAN IP of the projector.

Optional (connection & tuning)

Attribute	Type	Default	Description
port	int	23	TCP port. Some installation-series models use 3023 — confirm in the projector's Network menu.
projector_id	string	00	Two-digit projector address. 00 is the wildcard and matches any projector. Only change when multiple projectors share a single RS-232 link and each has been assigned a unique ID via the OSD. A single digit is padded (7 becomes 07); a value that is not digits is refused, and commands return an error until it is corrected.
volume_max	int	100	The projector's native maximum volume value. Installation-series units use 0-100 natively; entry-level home projectors use 0-32. When set to 32, GEM's 0-100 volume slider scales down to the 0-32 wire range.
status_interval	int	30000	Milliseconds between status polls. A blank, zero or negative value uses 30000; values under 1000 are raised to 1000. A poll that is still running when the next one is due is not doubled up.

Diagnostic (populated by the driver)

Attribute	Type	Description
model_name	string	Auto-populated from the model-name query on first connect.
firmware_version	string	Auto-populated from the firmware query on first connect.
lamp_hours	int	Cumulative lamp / light-source hours reported by the projector. History-enabled so long-term wear is tracked.
power_state	string	on / off — reflects the projector's own report, not just GEM's last command.
input	string	Current input keyword (e.g. hdmi1, hdbaset).
mute_state	string	on / off — the last mute the driver sent (the projector does not report mute), so mute_toggle alternates. A mute the projector refuses during warm-up, or one made with the remote, is not reflected.

Zone address

Not used. Each device row is a single projector. If you want to link volume / mute to an AV zone, set volume_device_id on the AV zone to the projector device's id — volume and mute commands for that zone go to the projector, and the driver copies the projector's reported input onto the zone's input attribute.

Commands

Power: power_on, power_off, get_power.

Source: set_input (with input arg — a named input, or a raw Optoma source code of one or two digits), plus one-shot shortcuts hdmi1, hdmi2, hdmi3, hdbaset, displayport, vga1, vga2, and get_input.

Audio: volume (0-100; values outside the range are clamped; level is accepted when volume is absent; a missing, blank or non-numeric value is refused with an error rather than sent as 0), volume_up, volume_down, mute_on, mute_off, mute_toggle.

Image: blank_on / blank_off (AV mute — blanks video, leaves audio alone), freeze_on / freeze_off, brightness, contrast (level 0-100, clamped; a missing level sends 0, an unparseable one is refused), set_aspect (4:3, 16:9, 16:10, ltbx, native, auto).

OSD & diagnostics: menu_toggle, get_lamp_hours, get_model, get_firmware.

Known limitations

• Warm-up window. Optoma projectors reject control commands during the 30-90 s power-on cycle with an F (fail) reply. The driver logs a warning and picks the state back up on the next status poll — expect a brief mismatch between commanded and reported state after power_on.
• Response ambiguity. Optoma projectors reply to queries with just Ok<value> — the query code is not echoed. The driver maintains a FIFO of pending queries to bind each response back to its query. If the projector volunteers unsolicited data (rare), the FIFO stays consistent because unmatched responses are dropped. A query that gets no Ok reply within 10 seconds of being sent is dropped from the FIFO, and the FIFO is cleared on every reconnect, so one unanswered query cannot shift later replies onto the wrong attribute.
• AV mute vs audio mute. blank_on uses the projector's video mute (command 30). It stops the picture but leaves audio active. Use mute_on if you want silence.
• Input coverage. The source list covers HDMI 1/2/3, HDBaseT, DisplayPort, VGA 1/2, Video, S-Video, BNC, DVI, and Component. Newer specialty inputs (Wi-Fi display, USB reader) are model-specific and not exposed as named shortcuts yet — send the raw source code via set_input if you need one.
• No test-pattern controls. The driver does not expose pattern, keystone, or color-temp commands. These are model-specific and best driven from the OSD.

Troubleshooting

Connection refused / drops the moment the projector goes into standby. Network Standby is off. Enable it under Setup → Power → Network Standby → On. Some models call it "Direct Power On" or bury it under Setup → Options → Standby Mode → Eco/Active.

Commands succeed, but power/source status stays empty. The projector may be on a non-standard port (3023 vs 23) or need the LAN Control mode set to RS232 by IP specifically. Toggle both and disconnect / reconnect the device row.

Set commands return F while the projector is warming up. Expected. Optoma rejects control during the 30-90 s warm-up. The driver picks state back up on the next poll.

Volume slider jumps in large steps. volume_max defaults to 100 but your model uses 0-32 native. Set volume_max = 32 in the device attributes and the driver will scale 0-100 GEM values into the 0-32 wire range.

Multiple projectors on the same link (RS-232 daisy chain). Set each projector's Projector ID in the OSD (Advanced → Projector ID), then set the corresponding projector_id attribute on each GEM device row so commands don't broadcast.