mwha2mqtt

Monoprice/McLELLAND whole-home audio amplifier serial to MQTT bridge controller.

The main component of this project is mwha2mqttd, a background daemon that communicates with various models of multi-zone whole-home audio amplifiers via RS232, enabling status enquiry and remote control of these amplifiers via MQTT.

mwha2mqttd periodically polls the connected amp(s) for zone status. When zone attributes (e.g., volume) change the new values are published to MQTT topics. Clients can adjust zone attributes by publishing values to MQTT topics. mwha2mqttd subscribes to these topics and will communicate with the amp to adjust the zone(s). See Topics below for details.

The project has been rewritten in Rust! The old Python version can be found on the python branch.

Features

• Zone attribute published and adjustable over MQTT.
• Communication via physical TTY or COM port (such as a USB<->RS232 adapter) or raw serial-over-TCP (RFC2217 not supported).
• Shairport Sync (AirPlay) volume control integration.

Features yet to be implemented

• A basic cli client tool (mwha-cli).
• A GUI mixer client.
• Automatic HomeKit and HomeAssistant integration.
• Automatic serial baud-rate detection and negotiation (for physical ports) (code is there, but doesn't work).
• MQTT SRV support.
• Example systemd service files.
• Packaging/install scripts for various distros.

Compatible Amplifiers

Manufacturer	Model	Compatibility	Notes
Monoprice	MPR-6ZHMAUT (10761)	Compatible	Equivalent to MAP-1200HD. Product Page, Manual
McLELLAND	MAP-1200HD	Unconfirmed	OEM. Product Page
McLELLAND	MAP-1200WE/MAP1200EW	Unconfirmed	OEM. Product Page
DaytonAudio	DAX66	Unconfirmed	Product Page, RS232 Commands
OSDAudio	NERO MAX12	Unconfirmed	Product Page
Texonic	A-M600	Unconfirmed	Product Page
Rave Technology	RMC-66A	Unconfirmed	Product Page, Manual
Soundavo	WS66i	Unconfirmed	Product Page, Manual

Amps listed as "unconfirmed" are those that haven't yet been validated as fully compatible with mwha2mqtt. These amps list RS232 control codes in their instruction manuals that match the MAP-1200HD and/or have a similar appearance (same chassis, ports and zone keypads). Pull requests to update this table would be appreciated once mwha2mqtt is confirmed working with these amps.

Configuration

mwha2mqttd has various settings that are set by a TOML configuration file.

The default config file shows all the available settings and documentation is provided as comments.

The location and name of this config file varies depending on how mwha2mqtt is installed.

Linux

On most Linux-based systems, packaged versions of mwha2mqttd reads its configuration from /etc/mwha2mqttd.conf.

Topics

The topic names below are shown with the prefix mwha/. This prefix can be changed in the mwha2mqttd configuration file (see the mqtt.url option)

In the topic names below <a> represents a placeholder for value a (the < and > characters are not present in the topic name). For example source/<i> where i = 1 results in a topic name source/1.

Messages sent on topics are JSON encoded. The JSON data type of the message clients should expect to send/receive on a particular topic is noted in the Data Type column. Integer is a JSON Number that only has an integer component.

Subscribe-only Topics

The following topics are for clients to receive metadata and updates about the configured amps, zones and sources.

Publishing messages to these topics is handled by mwha2mqttd. Any messages published by other clients will be ignored by mwha2mqttd

Messages published to these topics by mwha2mqttd will have their retain flag set. A message to each topic will be published once when mwha2mqttd starts, then whenever a zone attribute changes (after a successful status query to the amp).

Topic	Data Type	Description
mwha/connected	Integer	mwha2mqttd connected status. 0 = not connected/not running. 2 = connected to MQTT & serial.
mwha/status/amp/model	String	Amplifier model, as defined in the config.
mwha/status/amp/manufacturer	String	Amplifier manufacturer, as defined in the config.
mwha/status/amp/serial	String	Amplifier serial number, as defined in the config.
mwha/status/source/<source-id>/<attribute>	Various	Source status and metadata. See Source Attribute Topics below for details.
mwha/status/zones	String array	An array of configured zone IDs. Clients can use this to determine which zone topics are valid.
mwha/status/zone/<zone-id>/<attribute>	Various	Zone status and metadata. See Zone Attribute Topicsbelow for details.

Publish-only Topics

The following topics are for clients to alter the attributes of configured zones.

Publishing a message to topic for an unconfigured zone is a no-op. Invalid values will be logged but are otherwise a no-op.

Topic	Data Type	Description
mwha/set/zone/<zone-id>/<attribute>	Various	Zone adjustment. See Zone Attribute Topics below for details.

Source Attribute Topics

Source metadata and attribute updates are published by mwha2mqttd to the mwha/status/source/<source-id>/<attribute> topics.

source-id in the topic is the source ID. Valid source IDs are 1 through 6 (inclusive).

attribute in the topic is a source attribute name from the table below.

Attribute	Data Type	Description
name	String	Source name, as defined in the config.
enabled	Boolean	Source enabled state. Sources can be marked as disabled in the config. This is used as a hint to clients that the source isn't available. How clients reflect this is up to the client. All sources can always be selected from zone keypads.

Zone Attribute Topics

Zone metadata and attribute updates are published by mwha2mqttd to the mwha/status/zone/<zone-id>/<attribute> topics.

Clients can adjust certain zone attributes by publishing messages to the mwha/set/zone/<zone-id>/<attribute> topics.

For the meaning of <zone-id> and <attribute>, see Zone IDs and Zone Attributes.

Note: Zones must be first configured in the config file before mwha2mqttd will publish status and handle adjustments for them. Sending adjustments to an unconfigured zone is a no-op. The mwha/status/zones topic will contain a list of configured zone IDs. It is recommended that clients subscribe to this topic to discover the list of configured/active zones.

Zone IDs

<zone-id> in the topic is a 2-digit zone identifier in the format AZ.
The first digit A is the amplifier number, and valid values are 1 through 3 (inclusive), or 0 (see below).
The second digit Z is the zone number on amplifier A, and valid values are 1 through 6 (inclusive), or 0 (see below).

See the table below for a full list of valid zone IDs.

Zone IDs refer to physical zones unless their ID contains a 0 which instead refers to a virtual zone.

ID 00 is a virtual zone representing all zones (aka "the system"). No attribute status execpt name will be reported for this zone. However, adjustments sent to this zone will adjust all zones on every amp simultaniously.

IDs 10, 20, and 30 are virtual zones representing all zones on amp 1, 2 and 3 (respectively). No attribute status execpt name will be reported for these zones. However, adjustments sent to these zones will adjust all zones on amp A simultaniously.

ID	Zone Type	Attr. Status Updates	Description
11 .. 16	Physical	All attributes	Zones on amp 1 (Master position on the selector switch on the rear of the amp).
21 .. 26	Physical	All attributes	Zones on amp 2 (Slave 1 position on the selector switch on the rear of the amp).
31 .. 36	Physical	All attribute	Zones on amp 3 (Slave 2 position on the selector switch on the rear of the amp).
00	Virtual	name only	"System" zone. Adjusts all zones on all amps.
10	Virtual	name only	Amp 1 zone, adjusts all zones on amp 1.
20	Virtual	name only	Amp 2 zone, adjusts all zones on amp 2.
30	Virtual	name only	Amp 3 zone, adjusts all zones on amp 3.

Zone Attributes

<attribute> in the topic is a zone attribute name from the table below.

In the table below, attributes marked as RO cannot be adjusted. Updates for these attributes will be published on the status/ topic. However, trying to adjust them via the set/ topic is a no-op.

Attributed marked R/W can be adjusted via the set/ topic.

Attribute	Data Type		Details
name	String	RO	Zone name, as defined in the config.
public-announcement	Boolean	RO	Zone public announcement status. When a zone is in PA mode it will play audio from source 1. true = zone is in PA mode (the PA 12V trigger is pulled high). false = zone is normal.
power	Boolean	R/W	Zone power status. true = zone powered on. false = zone powered off.
mute	Boolean	R/W	Zone mute status. true = zone is muted. false = zone is un-muted.
do-not-disturb	Boolean	R/W	Zone do not disturb status. true = DND enabled. false = zone is un-muted.
volume	Integer	R/W	Zone volume. Value ranges from 0 to 38, inclusive.
treble	Integer	R/W	Zone treble adjustment. Value ranges from 0 to 14, inclusive. 0 = maximum treble reduction. 7 = flat (no adjustment). 14 = maximum treble boost.
bass	Integer	R/W	Zone bass adjustment. Value ranges from 0 to 14, inclusive. 0 = maximum bass reduction. 7 = flat (no adjustment). 14 = maximum bass boost.
balance	Integer	R/W	Zone balance adjustment. Value ranges from 0 to 20, inclusive 0 = 100% left. 7 = centre (no adjustment). 14 = 100% right.
source	Integer	R/W	Zone active source. Value ranges from 1 to 6, inclusive. This value can be mapped to the source metadata topics (source/<i>) for source info.
keypad-connected	Boolean	RO	Zone keypad connected status. true = zone keypad connected. false = zone keypad disconnected.

Shairport Sync Integration

mwha2mqttd can integrate with Shairport Sync via MQTT, which allows for volume control of zone(s) from AirPlay clients (such as iOS or macOS). When one or more zones are listening to a designated Shairport Sync source, volume control commands from AirPlay client(s) of that source change the volume of the zones listening to that source.

For example: a PC running Shairport Sync has its S/PDIF optical out connected to the Source 6 input on the back of the master amp, and this source is configured in the mwha2mqttd configuration as a Shairport Sync source (shairport.volume_topic is specified). Zones 1 and 4 are listening to Source 6 and an iOS client plays music over AirPlay to the Shairport Sync speaker, hence Zones 1 and 4 hear the music playing from the iOS device. The user adjusts the speaker volume on the iOS device and Shairport Sync publishes volume change metadata MQTT messages. mwha2mqttd receives these messages and adjusts the volume of Zones 1 and 4 to match the iOS clients' specified volume.

To use this feature, Shairport Sync must be compiled with MQTT support, and MQTT metadata must be enabled in the shairport-sync.conf configuration file. When enabled, Shairport Sync will publish metadata about the current AirPlay stream, including volume level, onto MQTT topics.

Basic Configuration Steps

1. Connect the hardware, so that the audio output of a device running Shairport Sync is connected to a source on the amp.

2. Compile Shairport Sync with MQTT support and configure it to publish metadata over MQTT.

   See the Shairport Sync MQTT documenation for more info.

   Either the publish_raw or publish_parsed (or both) option may be used in the Shairport Sync config, as the same volume metadata is published for either option, but note that the volume topic name differs. See below.

   Hint: It's recommened to set the Shairport Sync ignore_volume_control option to "yes" to disable the built-in software mixing and hardware audio device volume control. Explicitly set the hardware device volume to 100% (0 dB) and let the amp do the volume adjustment.

   Note: if you're running multiple instances of Shairport Sync, ensure that the topic configuration option is unique for each instance.

   Example partial shairport-sync.conf:

   general = {
       ⋮
       name = "Whole-home Audio (Source 6)";
       ignore_volume_control = "yes";
       ⋮
   }
   
   mqtt = {
       enabled = "yes";
       topic = "shairport-ch6"
       publish_parsed = "yes";
       ⋮
   }
   

3. Configure source(s) in mwha2mqttd.conf to have the appropriate shairport.volume_topic to match the Shairport and hardware configuration.

   When Shairport Sync is configured with:

   • publish_parsed = "yes", then the volume_topic should be of the form <shairport-topic>/volume.
   • publish_raw = "yes", then the volume_topic should be of the form <shairport-topic>/pvol.

   (where <shairport-topic> is the value of mqtt.topic in the Shairport config)

   Example partial mwha2mqttd.conf:

   [amp.sources]
   ⋮
   6 = { name = "AirPlay", shairport.volume_topic = "shairport-ch6/volume" }