Yamaha MTX / MRX / XMV

Commercial installation DSP driver for the Yamaha MTX3, MTX5-D and MRX7-D processors and the XMV series amplifiers. The driver speaks Yamaha's plain-text remote control protocol over TCP port 49280 — the same interface the third-party control modules for these units use.

This is the driver for Yamaha's installation line. The residential network receivers (RX-V / Aventage) speak a completely different protocol and are covered by yamaha_ynca.md and yamaha_musiccast.md.

How this driver is different: the project file owns the parameter names

An MTX/MRX is a blank DSP until an integrator builds a project in MTX-MRX Editor and syncs it to the hardware. There is no fixed "zone 3 volume" command the way there is on a matrix amplifier — what exists is whatever the project defines, addressed by a parameter path plus two index numbers.

The protocol has no way to enumerate those paths. That means:

• The driver deliberately ships no default parameter paths. You supply them from your project.
• Zone discovery is manual: you create one GEM zone per output and set its address to the parameter indices.
• Once configured, everything else behaves like any other multi-zone audio device in GEM — state, volume, mute_state and source land on the zone and the normal zone tiles work.

note

If you are commissioning a system somebody else programmed, open the project in MTX-MRX Editor and use the parameter list to read off the paths and index columns. Guessing them is not viable — a wrong path returns a protocol ERROR line rather than doing anything visible.

Prerequisites

• An MTX/MRX/XMV unit on the LAN with its project already synced from MTX-MRX Editor.
• TCP port 49280 reachable from the GEM controller (no auth — restrict at the network layer if the DSP shares a VLAN with untrusted devices).
• The parameter paths for output level and mute, plus the index pair for each output, taken from the project.
• A static IP or DHCP reservation on the DSP.

Setup

1. Confirm the link by hand first. From a workstation on the same VLAN, telnet <dsp-ip> 49280 and send devinfo productname followed by Enter. A healthy unit answers with an OK devinfo productname "…" line naming the model. If the socket opens and nothing comes back, another controller most likely holds the session.
2. Add the device. In /admin/devices create a device with driver yamaha_mtx:
   • ip — the DSP address
   • port — leave at 49280
   • level_address — the output fader parameter path from your project
   • mute_address — the output mute parameter path
   • source_address — only if your project has a per-zone source selector
3. Set the level window. min_level_db / max_level_db define the dB range that GEM's 0-100 scale maps into. The defaults (-60 dB to 0 dB) are a safe starting point; if the project already sets gain structure downstream, cap max_level_db lower so a 100% zone cannot overdrive the amplifier.
4. Create one zone per output. Set zone.address to the index pair for that output — "0:0", "1:0", and so on. See Zone address format.
5. Verify. Run get_device_info on the device (product name, serial and firmware land as read-only attributes), then get_zone_status on one zone. The zone's volume and mute_state should populate within a second.

Attribute reference

Device

Attribute	Required	Default	Description
ip	yes	—	LAN address of the DSP
port	no	49280	Remote control protocol port
level_address	no	—	Parameter path driven by set_level / volume. Zone level commands are refused while empty.
mute_address	no	—	Parameter path driven by on / off / the mute commands
source_address	no	—	Parameter path driven by set_source, for projects with a per-zone selector
min_level_db	no	-60	dB value mapped to zone level 1
max_level_db	no	0	dB value mapped to zone level 100
level_step	no	5	Increment used by volume_up / volume_down when no step arg is given
poll_interval	no	30000	Backstop re-read interval per zone, in ms
product_name	read-only	—	From devinfo productname
device_label	read-only	—	Unit name set in MTX-MRX Editor
serial_number	read-only	—	From devinfo serialno
firmware_version	read-only	—	From devinfo version
run_mode	read-only	—	From devstatus runmode — normal while the unit is running its project

Zone

The driver writes volume (0-100), mute_state (on/off), state (on/off, mirrored from mute) and — when source_address is set — source. No zone attributes need to be set by hand beyond the address.

Zone address format

zone.address is the parameter index pair, written indexA:indexB. A bare indexA is accepted and indexB defaults to 0.

These are the two index columns shown beside the parameter in the MTX-MRX Editor parameter list. For most projects indexA is the zero-based output/zone number and indexB is 0, so a five-zone system is 0:0 through 4:0 — but confirm against the project rather than assuming.

Address	Meaning
0:0	First output, sub-index 0
3	Fourth output, sub-index 0 (shorthand)
2:1	Third output, sub-index 1

Levels

The protocol carries fader values in hundredths of a dB: -1000 is -10.00 dB, 0 is unity, and -32768 is -∞.

GEM's 0-100 zone scale maps linearly into the min_level_db..max_level_db window, with level 0 special-cased to -∞ so an off zone is genuinely silent rather than sitting at the bottom of the window. This is a linear-in-dB taper, which tracks perceived loudness better than a linear-in-voltage one — expect the midpoint of a -60..0 dB window to sound like a moderate listening level rather than "half".

Commands

Command	Args	Notes
on / off	address	Unmute / mute. A DSP output has no power rail.
set_level	address, level	0-100
volume	address, volume	Alias of set_level for AV zones
volume_up / volume_down	address, step	Read-modify-write from the cached fader value
mute_on / mute_off / mute_toggle	address	Toggle resolves from the cached mute state
set_source	address, source	Requires source_address
get_zone_status	address	Re-reads level and mute for one zone
get_zones	—	Lists bound zones with the parameter paths and cached values
get_device_info	—	devinfo + devstatus runmode
get_parameter	parameter, index_a, index_b	Raw get — works against any parameter in the project
set_parameter	parameter, index_a, index_b, value	Raw set. Fader values are 1/100 dB.
recall_preset	preset	Not implemented — see below

The raw get_parameter / set_parameter pair is the escape hatch. Anything the project exposes — matrix crosspoints, room-combine states, priority ducker thresholds — can be driven through it from a macro without a driver change.

Known limitations

• Preset recall is not implemented. recall_preset is listed so it is discoverable, but it returns not yet implemented rather than guessing a wire format that was not verifiable against Yamaha's protocol document. Recalling a preset from a macro today means using set_parameter against whatever the project exposes.
• No parameter discovery. Covered above — this is a protocol limitation, not a driver gap.
• Unsolicited change notifications are applied if the unit sends them, but the driver does not depend on them. State stays correct through the polling loop either way; if your firmware does push NOTIFY lines you simply get faster feedback.
• No auth. The protocol has none. Treat network reachability as the access control.
• Not validated against physical hardware. The protocol framing and command set follow Yamaha's published remote control protocol, but this driver has not yet been run against a live MTX/MRX. Commission it with get_device_info and a single zone before rolling out a whole system.

Troubleshooting

Symptom	Check
Socket connects, every command returns an error	The parameter path is wrong for this project. Re-read level_address / mute_address from the MTX-MRX Editor parameter list. Watch the device log — the driver prints the full ERROR line the unit returned.
Socket connects then immediately drops	Another control system already holds the session slot, or the unit is in update/emergency mode. Check run_mode on the device.
Zone volume jumps to full, or barely moves	min_level_db / max_level_db do not match the project's gain structure.
set_source refused	source_address is empty. It is optional and has no default.
volume_up returns "no cached level"	The driver has not read that zone's fader yet. Run get_zone_status on the zone, or wait one poll interval.
Nothing at all on 49280	Some units ship with the remote control port disabled until a project is synced. Sync from MTX-MRX Editor first.