Atlona AT-OME / AT-UHD Matrix

Drives Atlona OmniStream / OME presentation switchers and HDR-capable UHD matrix switchers — including the AT-OME-MS52W, AT-OME-PS62, AT-OME-PS63, AT-OME-MH21, AT-UHD-CLSO-824, AT-HDR-CAT-8 family — over Telnet ASCII on port 23. Each matrix output is exposed as a GEM zone with input routing, output mute, and (where the model supports it) HDBaseT/HDMI output volume.

Not Velocity. Atlona Velocity is Atlona's separate room-control product and speaks its own REST API. This driver talks to the matrix hardware directly. The two coexist — point Velocity at one set of credentials and GEM at another.

Prerequisites

• Atlona AT-OME or AT-UHD unit on the LAN with Telnet enabled (factory default; check System → Network in the web UI).
• If Telnet authentication is enabled on the unit (default on modern AT-OME-PS firmware), a control username + password.
• TCP/23 reachable from the GEM controller to the matrix.

Setup

1. Enable / verify Telnet. From the matrix web UI, System → Network → Telnet. Confirm it's enabled and note whether authentication is required.
2. Create or look up a control user if auth is required. A dedicated account beats reusing admin in production.
3. Add the device. In GEM, create a Device with driver atlona_atome. Set ip to the matrix IP; leave port on 23.
4. Set credentials (if needed). When Telnet auth is on, set username and password on the device row. Leave both blank when auth is off — the driver does not assume auth and will not get stuck on a missing prompt.
5. Set the matrix shape. output_count defaults to 8 and is used as the upper bound for status polling. Set input_count to match the unit (used to validate set_source requests).
6. Create one GEM zone per output. zone.address is the plain integer output number matching the matrix's port labelling (1, 2, ...).
7. (Optional) Wire AV sources. Define an AV Source per matrix input so the picker shows friendly names in the UI instead of bare integers.

Device attributes

Attribute	Required	Default	Description
ip	yes	—	LAN IP or hostname of the matrix.
port	no	23	Telnet port.
username	no	—	Required only when Telnet auth is enabled on the unit.
password	no	—	Required only when Telnet auth is enabled (stored as a secure attribute).
output_count	no	8	Number of outputs on the matrix. Bounds the status poll loop.
input_count	no	8	Number of inputs on the matrix. Validates set_source arguments.
status_interval	no	30000	Poll interval (ms).
command_throttle	no	100	Minimum gap between outbound commands.

Zone attributes

Attribute	Required	Description
address	yes	Output number as a plain integer matching the matrix port labelling.

The driver writes the following onto each zone as state arrives from the matrix:

• zone.input — currently routed input number for this output.
• zone.volume — output level 0–100 (mapped from Atlona's −80 .. 0 dB; only meaningful on models with output volume).
• zone.mute_state — on / off.

Commands

• on / off — matrix power, where supported.
• set_source / route — accepts address (output) and source (input number). Wire format is xMAVxN — input M to output N.
• mute_on / mute_off / mute_toggle — per-output mute.
• set_volume — 0–100 scaled to −80 .. 0 dB.
• volume_up / volume_down — single-step adjustment.
• get_zone_status — force a re-read for one output.
• get_outputs — re-poll every output up to output_count.
• get_version — read firmware version (smoke test).

Zone address format

Plain integer matching the matrix output number:

1, 2, 3, ...

There is no special prefix or zero-padding.

Known limitations

• No input enumeration over Telnet. Atlona does not expose a query for "list available inputs" on the AT-OME protocol; the integrator must configure AV Sources (or simply use the integer in the UI). input_count lets the driver validate set_source requests but does not fetch input metadata.
• Volume varies by model. Entry-level AT-OME and AT-HDR units have no output volume control; set_volume returns Command FAILED on those models. The driver does not pre-validate model capabilities.
• No native mute toggle. mute_toggle is resolved client-side from the cached zone.mute_state — if the cache is stale (no recent poll), the toggle may target the wrong direction once before correcting.
• Routing is one-way wire syntax. The Atlona web UI shows routes as "output ← input" in some screens; the protocol always uses xMAVxN (input M, then output N). The driver respects the wire format.
• Velocity not addressed. If the install uses Atlona Velocity as the central controller, GEM still drives the matrix directly. There's no need to integrate with Velocity for matrix control.

Troubleshooting

Symptom	Check
every command returns Command FAILED	Telnet auth is enabled but credentials are wrong/missing. Set username / password on the device row, or disable Telnet auth in the matrix web UI.
connect succeeds but outputs never report state	output_count is set too high — the driver polls 1..output_count each interval and an oversized count floods the parser with errors. Match it to the unit.
routes succeed but mute does nothing	Legacy AT-UHD firmware accepts only lowercase verbs (mute1). Upgrade — every AT-OME firmware since 2020 accepts both cases.
connection drops after a single command	A second Telnet session is open from another control system (Atlona admits multiple but treats the most recent as authoritative). Close the other session or rotate the credential.
auth prompt loop	The unit is asking for credentials the driver doesn't have. Either disable Telnet auth or set username and password on the device row.