AudioControl Maestro

The audiocontrol_maestro driver controls AudioControl Maestro home-theater processors/receivers over TCP. It drives the main theater (Zone 1) and the secondary output (Zone 2): power, volume, mute, source selection, surround modes, HDMI output routing, and on-screen menu navigation. Control uses the Maestro's binary IP-control protocol — space-separated hex frames, each ending in a carriage return (0D).

note

This is a different product from the AudioControl Multi-Zone Amplifier (audiocontrol, telnet on port 23), which is a whole-house matrix amp that auto-creates a GEM zone per output. The Maestro is a two-zone home-theater processor; you create its zones by hand.

Prerequisites

• Maestro on the same LAN as GEM, reachable at a static IP or DHCP reservation.
• IP control enabled on the processor's front-panel setup menu, and the IP-control TCP port it is configured for. There is no fixed default — read the port off the unit's setup menu (it is often a high port such as 14999).

Setup

1. System → Devices → Add Device. Choose the AudioControl Maestro driver.

2. Fill in Processor IP and TCP Port. The port must match the IP-control port shown on the Maestro's setup menu — this is the most common reason a Maestro connects but never reports state. Optionally set Status Poll Interval (ms) (default 30000). Save and enable.

3. System → Zones → Add Zone. Create one zone with Address 1 for the main theater. If you use the second output, create a second zone with Address 2. The New Zone editor pre-selects the AV subsystem for this driver — leave it there so the zones surface in the AV routing screens.

   Subsystem placement

   The driver hints the AV subsystem, which is one of the subsystems GEM ships with, so the zone editor pre-selects AV automatically. Membership in AV is what makes these zones available in AV → AV Zones when you bind an AV Zone to an existing zone.

   The processor does not announce its zones — GEM never auto-creates them. Create the 1 (and optionally 2) zone rows yourself.

4. On connect the driver queries Zone 1 power → volume → mute → source once, then repeats that every Status Poll Interval, spacing the queries about a second apart so it doesn't flood the processor. If a zone with Address 2 exists it is polled the same way. The processor also pushes status on its own after power-on, source changes and key presses, so front-panel and remote changes show up without waiting for the poll. Values land on the device as the power_state, volume, mute_state and input attributes (Zone 2 with a zone_02_ prefix), and volume / mute_state are also written onto the zone row bound at that address.

Using the Maestro as an AV Zone

To drive the theater from an AV touchpanel:

1. AV → AV Zones → create (or bind) an AV Zone. In the Bind to existing zone picker choose the 1 zone you created above.
2. Set the AV Zone's Volume Device to the Maestro device. Its volume slider and mute button then drive the processor zone the bound zone's address names — 1 for the main theater, 2 for the second output.
3. Source selection from the touchpanel is done through the AV Zone's source on/off macros — put the matching source-select command (bd, sat, stb, cd, …) in each source's On Macro. There is no numeric routing command on this processor; you switch inputs with the named source buttons below.

Zone 2

The driver picks the processor zone from, in order: an explicit zone_number argument; the address of the zone the command was sent for, when that zone is bound to the Maestro; an explicit Address on the AV Zone; an address argument with no zone context; otherwise Zone 1. A zone owned by another device (a display that uses the Maestro as its volume device) does not pass its own address through — that address belongs to the display — so bind the AV Zone to the Maestro's 2 zone, or set the AV Zone Address to 2, to drive the second output from a touchpanel.

Zone 2 has its own set of remote keys on the processor. When a command targets Zone 2 the driver sends the Zone 2 key for power, mute, volume up/down and the source buttons that exist for Zone 2 (cd, bd, av, sat, stb, game, aux, net, fm, tuner, pvr). Keys with no Zone 2 equivalent (bt, uhd, arc, surround modes, menu navigation, HDMI output) always act on Zone 1.

Attributes

Device — required

Attribute	Type	Description
ip	string	LAN IP of the Maestro processor.
port	int	IP-control TCP port configured on the Maestro. No default — match the unit's setup menu.

Device — optional

Attribute	Type	Default	Description
monitor_interval	int (ms)	30000	How often to poll power / volume / mute / source. Zone 1 is always polled; Zone 2 is polled too when a zone with Address 2 is bound to the device.

Reflected device attributes

The driver writes live state onto the device. Zone 2 values use a zone_02_ prefix. volume and mute_state are additionally written onto the zone row bound at that address (1 or 2), which is where AV controls read them.

Attribute	Type	Values
power_state	string	on / off
volume	int	Current Zone 1 volume, decimal 0–99
mute_state	string	on / off
input	string	Current source name (see the source map below), or the raw hex code if unrecognized
zone_02_power_state	string	on / off
zone_02_volume	int	Zone 2 volume, 0–99
zone_02_mute_state	string	on / off
zone_02_input	string	Zone 2 source name

Zone

• Address required: yes.
• Address format: 1 for the main theater, 2 for the second output.

Commands

Send these from the Commands page, a macro, or a control. Commands that take zone_number accept 1 (main) or 2 (second output) and default to 1 when omitted (see the Zone 2 note above for how the zone is chosen when the argument is absent).

Power

Command	Args	Notes
power_on / power_off	zone_number	Discrete power on / off (standby).
power_standby	—	The Standby key — toggles between on and standby.

Volume & mute

Command	Args	Notes
volume	zone_number, volume	Set an absolute level. volume is a decimal 0–99 — the driver converts it to the processor's hex encoding. Values outside 0–99 are clamped.
volume_up / volume_down	zone_number	Step up/down one increment. Safest for touchpanel binding because they need no scaled value.
mute_on / mute_off	zone_number	Mute / unmute.
mute_toggle	zone_number	Native mute toggle — GEM sends it directly, no state emulation.

Status queries

Command	Args	Notes
get_power	zone_number	Refreshes power_state.
get_volume	zone_number	Refreshes volume.
get_mute	zone_number	Refreshes mute_state.
get_source	zone_number	Refreshes input (decoded via the source map).
get_direct_mode	—	Query direct-mode state (Zone 1).

Source selection

There is no numeric route command. Pick a source with its named button; GEM reports the current source back through get_source / the input attribute.

Command	Notes
cd bd av sat stb game aux net fm pvr tuner	Select the corresponding input. Take zone_number; with 2 the Zone 2 key is sent.
bt arc uhd	Select Bluetooth, the Display (HDMI ARC) input, or UHD. Zone 1 only.
multi_channel	The Multi Channel listening mode key — not an input selection.

tuner and fm are the same input on the processor (both report as fm). net is refused with "command invalid at this time" on units that have no network source.

The processor reports its current source with these codes (used to fill the input attribute):

Code	Source	Code	Source
00	follow_zone_1	0B	fm
01	cd	0C	dab_europe
02	bd	0E	net
03	av	0F	usb
04	sat	10	stb
05	pvr	11	game
06	uhd	12	bt
08	aux
09	display_arc

Audio / video routing

Command	Args	Notes
set_audio_input	zone_number, audio_source	Choose the audio source type: analog, digital, hdmi (or request to query).
set_video_output	output	Route HDMI output: hdmi_1, hdmi_2, hdmi_1_2 (both), or request.
hdmi_out_1 / hdmi_out_2 / hdmi_out_1_2	—	Discrete HDMI-output selection.
set_osd	zone_number, status	On-screen display: on, off, or request.

Surround / listening modes

Command	Notes
direct_mode_on / direct_mode_off	Direct mode (bypass audio processing) on / off. discrete_on / discrete_off are older names for the same two keys — they were never power commands.
stereo / 5_7_stereo	Two-channel / all-channel stereo.
auto_matic	Auto surround selection.
dolby_surround / dolby_digital_ex	Dolby modes.
dolby_volume_toggle	Toggle Dolby Volume.
dts_neo6_cinema / dts_neo6_music	DTS Neo:6 cinema / music.
dts_neuralx / dts_virtualx	DTS Neural:X / Virtual:X.

Menu navigation & display

Command	Notes
up down left right select menu home	On-screen menu navigation.
display_off	Turn the front-panel display off.
display_brightness_toggle	Cycle front-panel brightness.
cycle_output_resolution	Step the HDMI output resolution.
cycle_vfd_info	Cycle the front-panel info readout.
zone_toggle	Change which zone the front panel and remote control (the processor's "next zone" key). It does not power Zone 2 on or off — use power_on / power_off with zone_number 2.

IR passthrough

Command	Args	Notes
ir_command	zone_number, system_code, command	Simulate a raw RC5 key: system code 10 for Zone 1 keys, 17 for Zone 2 keys, plus the key's command code, both as two hex digits.

Known quirks

• Every frame is hex ending in 0D. Volume is encoded 00–63 on the wire; in GEM you enter and read it as decimal 0–99.
• Mute status is 00 for muted, 01 for not muted on the wire. The driver reports it as mute_state on / off.
• Status arrives in bursts. After power-on and every source change the processor sends twenty-odd status frames packed into one or two packets; the driver reassembles them by the frame length byte, so state is complete right after the burst rather than after the next poll.
• Zone 2 keys are acknowledged as "invalid". The processor answers Zone 2 remote keys with answer code 85 and then executes them anyway, pushing the Zone 2 status frame. The driver ignores those acknowledgements.
• Most keys are refused in standby. mute_on, source keys and the like answer 85 ("command invalid at this time") until the zone is powered on.
• No source-routing number. Sources are chosen with the named buttons (bd, sat, …), not a channel/input index.
• Unrecognized source codes are reported as the raw hex value in input rather than a friendly name.

Troubleshooting

Symptom	Check
Connects but no state ever updates	The TCP Port almost certainly doesn't match the IP-control port on the Maestro's front-panel setup menu.
Volume reads look wrong	Volume is decimal 0–99. Make sure nothing else is sending raw values to the same port.
Zone 2 never refreshes	Zone 2 is polled only when a zone with Address 2 is bound to the Maestro device. Create that zone, or query it explicitly with get_power / get_volume / get_mute / get_source and zone_number 2.
Touchpanel mute drives the wrong zone	The AV Zone's bound zone belongs to another device, so its address is not used. Bind the AV Zone to the Maestro's own 1 or 2 zone, or set the AV Zone Address to the processor zone.
A source key logs "query refused" or does nothing	The processor refuses keys for inputs it doesn't have (net without a network module) and most keys while in standby. Power the zone on first.

Related

• Devices
• Zones
• Subsystems
• Commands
• AV Zones
• AV Sources
• AudioControl Multi-Zone Amplifier