AVPro Edge AC-MAX

The avpro_acmax driver controls the AVPro Edge AC-MAX audio matrix / distribution amplifier. It speaks the AVPro ASCII IP control protocol over TCP — plain text commands such as SET OUT1 VOL 45, \r\n terminated in both directions, no login. The AC-MAX routes any input to any output and gives each output its own volume, mute, and on/off, so in GEM it is a controller: one device drives many zone outputs and switches between many source inputs.

You bind each output to an AV zone and each input to an AV source. Once an AV zone's Volume Device points at the AC-MAX, the zone's volume/mute controls dispatch to that output and the matrix mirrors the output's state back onto the zone.

Prerequisites

• The AC-MAX on the same LAN as GEM, with a static IP or a DHCP reservation.
• IP control enabled in the AC-MAX web UI. Note the control port shown there — you enter it when you create the device.
• A list of which physical OUT number feeds each room and which IN number each source is wired to. AVPro numbers OUT/IN ports 1-based; confirm the numbering printed on the chassis matches the labels in your rack drawings before you start.

Addressing

Throughout GEM, an AC-MAX AV zone address is the output (OUT) number and an AV source address is the input (IN) number — both 1-based integers that match the chassis. The query OUT0 is a wildcard the driver uses internally to read all outputs at once; you never enter 0 as a real zone address.

Setup

1. System → Devices → Add Device: choose driver AVPro Edge AC-MAX (avpro_acmax). Set ip to the matrix's LAN address and port to the IP control port from the AC-MAX web UI. Set Enabled to Yes and save. On connect the driver reads every output's volume, mute, routed input, and on/off state once (a wildcard OUT0 sweep), so the current matrix state populates immediately.

2. AV → AV Zones → Add — create one AV zone per output you want to control:

   • AV Type — audio (use video only if you are mapping a video output).
   • Volume Device — the Device that controls volume for this zone picker. Set it to the AC-MAX. This is what makes the zone's volume and mute controls reach the matrix output.
   • Address — the OUT number for this room (e.g. 3 for OUT3). If you use the Advanced addressing toggle instead, put the output number in the Audio Routing field; the driver reads the audio routing address first, then the plain Address.

3. AV → AV Sources → Add — create one AV source per input:

   • Device — the physical source feeding that input (cable box, streamer, media server).
   • AV Type, Label — required; the label is what users see when they pick the source.
   • Address — the IN number this source is wired to (e.g. 5 for IN5).
   • On Macro — the route command (see Routing a source to a zone below).

4. On a touchpanel, selecting a source for the zone runs that source's On Macro to route the input to the zone's output; the zone's volume/mute controls drive the output directly.

Routing a source to a zone

GEM does not auto-route a matrix — a source is routed by its On Macro. Build one Run Command macro and reuse it for every AC-MAX source:

1. Automation → Macros → Add a macro, e.g. Route AC-MAX.
2. Add a step that sends the AC-MAX input command (wire: SET OUT[address] AS IN[input]).
3. Leave its argument pickers on the AV defaults — address resolves to the AV zone's output address and input resolves to the AV source's input address. GEM fills both in at run time from whichever zone and source are involved, so the single macro works for all of them.
4. Set this macro as the On Macro on each AC-MAX AV source.

When a user picks that source in a zone, GEM substitutes the zone's OUT and the source's IN and sends SET OUT<out> AS IN<in>. The driver then reports the new routing back, and the zone's input attribute updates.

Volume vs. source — two separate paths

Volume and mute flow automatically through the zone's Volume Device binding — no macro needed. Source routing is the On Macro above. Note the driver tracks the routed hardware input in the zone's input attribute; it never writes the zone's source field, which GEM manages from your AV source selection.

Attributes

Device — required

Attribute	Type	Description
ip	string	LAN IP of the AC-MAX.
port	int	IP control (TCP) port shown in the AC-MAX web UI.

Device — optional

Attribute	Type	Default	Description
command_throttle	int (ms)	200	Minimum spacing between commands sent to the matrix. Raise it if rapidly issued commands are dropped.
response_terminator	string	\r\n	Line terminator the matrix uses. Leave it unless a non-standard firmware ships with a bare \r — in that case responses buffer forever and the driver never updates.

Status reads happen on connect, not on a timer

The AC-MAX reads all outputs once when GEM connects (and again after any reconnect); it does not poll on a cycle. After that, the displayed state stays current because the driver applies the matrix's own confirmations to every command it sends. A change made outside GEM — at the AC-MAX web UI or front panel — shows up the next time GEM reconnects to the matrix, not immediately. If you need a manual refresh, run get_global_status or the per-output get_volume / get_mute_state / get_input queries.

Reflected zone attributes

The driver writes these onto the bound AV zone as the matrix confirms each command and during the connect sweep:

Attribute	Type	Notes
volume	int	Output volume, 0-100.
mute_state	string	Output mute, on / off.
input	int	The IN number currently routed to this output.
power_state	string	Output enable state, on (EN) / off (DIS).

These names are cataloged, so they appear in the Attribute editor's name picker and can drive attribute triggers — for example, alert when an output is muted (mute_state = on) or when input changes.

Zone / AV zone

• Address required: yes — the output (OUT) number, 1-based. Set it in the AV zone's Address field, or in Audio Routing under Advanced addressing. A zone whose Volume Device is the AC-MAX is what the driver tracks per output.

AV source

• Address: the input (IN) number, 1-based, in the AV source Address field. The source's On Macro routes this input to the chosen zone output.

Commands

get_* commands take an output (address) or input (input) argument and return current state; the rest are control commands. The address argument is an AV zone (output) address and input is an AV source (input) address — the pickers offer your real zones and sources.

Routing & output power

Command	Args	Wire	Notes
input	address, input	SET OUT[address] AS IN[input]	Route an input to an output. Used by AV source On Macros.
zone_on	address	SET OUT[address] EN	Enable (power on) the output.
zone_off	address	SET OUT[address] DIS	Disable (power off) the output.
set_output_state	state (EN/DIS), address	SET OUT[address] [state]	Same as zone_on/zone_off with an explicit state.

Volume & mute (per output)

Command	Args	Wire	Notes
volume	address, volume (0-100)	SET OUT[address] VOL [volume]	Set output volume.
volume_up	address	SET OUT[address] VOL+	Step volume up.
volume_down	address	SET OUT[address] VOL-	Step volume down.
mute_on	address	SET OUT[address] MUTE	Mute the output.
mute_off	address	SET OUT[address] UNMUTE	Unmute the output.

Output tuning

Command	Args	Wire	Notes
set_output_balance	address, balance	SET OUT[address] BAL[balance]	Set the left/right balance for the output (range per AVPro documentation).
set_output_channel_config	address, mode (0-3)	SET OUT[address] CH CONFIG [mode]	Set the output channel configuration; mode values per AVPro documentation.
set_output_follow	address, mode (0-3), leader	SET OUT[address] FOLLOW [mode] OUT[leader]	Make an output follow a leader output so they track together.

Input controls

Command	Args	Wire	Notes
set_input_volume	input, volume	SET IN[input] VOLUME [volume]	Trim the input gain.
set_input_state	input, state (EN/DIS)	SET IN[input] [state]	Enable / disable an input.

Chime / paging

Command	Args	Wire	Notes
play_chime	config (1-5)	PLAY CHIME [config] EN	Start a built-in chime configuration.
stop_chime	config (1-5)	PLAY CHIME [config] DIS	Stop a chime configuration.
play_chime_in_zones	config, zones, duration, volume, file	—	Play a chime through specific zones with auto-restore (see below).

play_chime_in_zones is the doorbell / paging helper. Call it from a macro Send Command step (or a trigger) against the AC-MAX device with these args:

• zones — an array of AV zone ids to chime (a comma-separated list is also accepted).
• config — chime configuration 1-5 (default 1).
• file — chime file 1-5 (default 1).
• duration — milliseconds the chime plays (default 5000).
• volume — chime volume 0-100 (default 40).

The driver enables any listed output that is currently off and unmutes any that is muted (a muted output would play no chime), plays the chime through all of them, waits duration, then restores exactly what it changed — re-muting the outputs that were muted and turning back off only the outputs it had to turn on. Outputs that were already playing are left running. This makes it safe as a doorbell or page that does not disturb whatever the rooms were doing.

The sequence is drop-resilient: the AC-MAX can silently kill an idle control session, which used to swallow chimes whose enable/play lines raced the reconnect. The driver now keeps the link warm with a keepalive query (GET OUT1 EN every 30 s when idle) and, if any line of the chime sequence still hits a dead socket, waits for the reconnect, redoes the whole prep phase (enables and unmutes — both idempotent), and plays — logging avpro acmax chime interrupted by socket drop when that happens. A chime that could not be delivered returns an error instead of pretending it played.

Queries

Command	Args	Wire
get_volume	address	GET OUT[address] VOL
get_mute_state	address	GET OUT[address] MUTE
get_input	address	GET OUT[address] AS
get_output_state	address	GET OUT[address] EN
get_output_follow	address	GET OUT[address] FOLLOW
get_input_state	input	GET IN[input] EN
get_input_volume	input	GET IN[input] VOLUME
get_input_signal_status	input	GET IN[input] SIG STA
get_global_status	—	STA
get_system_status	—	GET STA
get_config	—	GET CONFIG
get_dhcp_state	—	GET DHCP
get_mac_address	—	GET MAC

System

Command	Args	Wire	Notes
reboot	—	SET RBT	Reboot the matrix.
help	—	H	Device help / command list.
passthrough	command	[command]	Send a raw protocol command verbatim — the escape hatch for anything not modeled above.

Known quirks

• OUT/IN numbers are 1-based and must match the chassis labels. OUT0 is an internal all-outputs query, never a real zone address.
• Status is read on connect, not on a poll. Changes made directly at the AC-MAX (web UI or front panel) appear after GEM's next reconnect. Run a get_* query for an on-demand refresh.
• Terminator sensitivity. The driver expects \r\n. Firmware that replies with a bare \r makes the driver buffer responses indefinitely — set the response_terminator attribute to match in that rare case.
• An output can follow another. If a room never changes volume independently, check get_output_follow — set_output_follow may have it tracking a leader output.

Troubleshooting

Symptom	Check
Volume or mute does nothing for a zone	Confirm the AV zone's Volume Device is set to the AC-MAX and the zone Address is the correct OUT number.
Source select does not switch the input	The source needs an On Macro that runs the input command (see Routing a source to a zone). Confirm the source Address is the right IN number.
Output appears stuck off	The output may be disabled (get_output_state returns DIS) or following another output (get_output_follow). Send zone_on, or clear the follow with set_output_follow.
State never updates after a route change	Confirm response_terminator is \r\n; some firmware ships with a bare \r and the driver will buffer responses indefinitely.
Reported state is stale after a web-UI change	Status is read on connect, not polled. Reconnect the device, or run get_global_status / the per-output queries.

Related documentation

• AV Zones — bind each output as a zone's Volume Device.
• AV Sources — define the inputs and their routing macros.
• Macros — build the source On Macro and the paging chime.
• Devices — add and configure the matrix.
• Commands — the command grid and the Test runner.