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. Go to System → Devices → Add Device and pick the Atlona AT-OME / AT-UHD Matrix driver (key atlona_atome). Set the Matrix IP to the unit's address; leave Telnet Port on 23.
4. Set credentials (if needed). When Telnet auth is on, fill in Username and Password on the device. 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 bounds the status poll loop; set it to the unit's real output count. Set Input Count to match the unit — it validates set_source requests. Both fields accept 1–32.
6. Create one GEM zone per output. Outputs are not auto-discovered: the Atlona protocol has no "list outputs/inputs" query, so the driver only writes state onto zones you create by hand and bind to this device. For each output, add a Zone whose Address is the plain integer output number matching the matrix's port labelling (1, 2, ...). Put them in the AV subsystem (see note below).
7. (Optional) Expose inputs as named sources. For an on-screen, name-based source picker, bind the output zones on the AV → AV Zones screen and define one AV Source per matrix input, with the source's address set to that input number. Picking a source on the touch panel then routes through the source's macros. For plain control you can skip this entirely and route directly with the set_source command, passing the bare input number.

Subsystem placement

Atlona output zones belong in the AV subsystem. The driver hints av, which matches GEM's default-seeded AV subsystem, so the New Zone editor pre-selects AV for you — just confirm it. These are ordinary zones (they appear under System → Zones); placing them in AV is also what surfaces them in the Bind to existing zone picker on the AV → AV Zones screen, since that picker lists AV-subsystem zones only.

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.

These three names are cataloged, so they autocomplete in the Attribute editor's name picker and can drive attribute triggers — for example, alert when a critical display's input changes, or when mute_state flips to on.

State refreshes two ways. The driver re-polls every output once per status_interval (default 30 s), and it also updates a zone the moment a route, mute, or volume change for that output is echoed back. So changes GEM makes appear as soon as the matrix acknowledges them, while changes made from the unit's own web UI or another controller surface at the next poll. A Version keepalive goes out every 45 s to hold the Telnet session open between polls.

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.
connection drops when idle	The driver already sends a Version keepalive every 45 s. If a firewall or NAT still idles the socket, add a ping_interval attribute (ms) on the device and lower it.
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.

Related documentation

• Zones — create one zone per matrix output (place them in the AV subsystem).
• Subsystems — the AV subsystem these output zones belong to.
• Devices — add and configure the matrix.
• Commands — the command grid and Test runner for set_source, set_volume, and the mute verbs.
• AV Zones and AV Sources — bind output zones and name matrix inputs for a touch-panel source picker.