MRAD Communications on MAS
- Michele Masiello
- Jonathan Simon
Overview
When a Mirage Media Streamer (MMS) and a Mirage Amplifier or Mirage Amplifiers are paired together, they become a Mirage Audio System (MAS). As with MMS control, the API is fairly simple. We strongly recommend using XML mode for all list browsing. With this API, you can control a MAS's Zones, Sources, and Zone Groups.
In all examples, --> indicates a messages to the server and <-- indicates a response. XML responses will be formatted for readability although they will be transmitted compressed to a single line in real communications
Establishing a Connection
In most scenarios, MRAD communication is done through port 5006 on the server over a TCP socket. We recommend setting a number of options and settings to improve the experience and to configure the communications between your client and the server.
On A series servers, you have to switch protocol modes using the * command and this command should be the first command you send. However, this command is safe to send to e series servers with no ill effect.
The SetClientType command takes an arbitrary string argument that sets the connection's type. This allows the MMS to react to different client types if necessary.
As described elsewhere, you'll want all lists to be sent as XML, so send the SetXmlMode Lists command.
You can also set the encoding of the communications. Most control systems are UTF-8 compatible, so we recommend sending SetEncoding 65001.
To be sure the MMS knows which address you accessed it through, be sure to use the SetHost command, sending the address you connected to. For example: SetHost 192.168.0.53 or SetHost foo.homeowner.com
To be sure the MMS notifies you of any status changes during your connection's lifetime, be sure to use some form of SubscribeEvents. This command is described below in the Events section.
To be sure you have the current state of the server, be sure to send GetStatus. This command is also described below in the Events section.
We recommend requesting Sources, Zones, and Zone Groups upon your initial connection by sending BrowseSources, BrowseZones, and BrowseZoneGroups. These commands are described below in the Browsing Zones, Sources, and Zone Groups section.
A full preamble example:
--> *
--> SetClientType DemoClient
--> SetEncoding 65001
--> SetXMLMode Lists
--> SetHost 192.168.0.53
--> SubscribeEvents Smart
--> GetStatus
--> BrowseSources
--> BrowseZones
--> BrowseZoneGroups
The Relationship Between 5004 and 5006
When connected to an instance on port 5004, events will be published that will instruct the control client where to go for MRAD. These events are MRADServer and MRADSource. MRADServer tells the client the IP and port to connect to for MRAD control. MRADSource tells the client which source in MRAD represents the current MMS instance. On port 5006, events (described in detail below in the Events section) MCSControl, MCSInstance, and MCSWebPort describe the inverse relationship.
Single Socket Communications
On all modern MMS firmware (5.35.x.x and higher), it is possible to make a single connection to the MMS control port (5004) and use that socket for both MMS control and MRAD control. To utilize this functionality, make your connection normally, then send SetOption Supports_SingleSocket=True. Subsequently, the MMS will proxy commands and feedback to and from MRAD. Any commands sent that are prepended with MRAD. will be handled by MRAD and any events MRAD sends will be prepended with MRAD.. Browse responses will not be prepended as they are unique to MRAD and therefore can not be confused as MMS responses.
Setting this option is not necessary on eSeries MMSs. The firmware will automatically configure the connection in this mode the first time a command prepended with MRAD. is recevied.
Definition of Terms
Zone: a physical output on the amplifier, after the matrix. A zone selects sources. There are some special cases where a zone is pre-matrix output and can't be grouped with other zones.
Source: an output of the MMS. This can be one physical output, many physical outputs, and/or a network stream (eAudioCast). A source is selected into a zone or zones.
Zone Group: a set of zones that have the same source selected. There are two types of zone groups, hard groups and soft groups.
Hard Group: a set of zones that are grouped on the amplifier for at least their selected source and optionally power and volume.
Soft Group: a set of zones that are grouped by virtue of having the same source selected. A soft group can contain a hard group or hard groups.
Events
As with MMS control, MRAD control offers an event driven and asynchronous communications protocol. Events about the currently selected zone and source are pushed to the control client if configured to do so. Data about other zones is also pushed, but more information is available for the currently selected zone. To request that events be pushed to you, use the SubscribeEvents command. This command takes 1 to n comma delimited arguments. If you pass true or false, event subscription will be enabled or disabled for all events. If you pass a comma delimited list of named events, you'll be subscribed to those events only. For example, if you only care about volume and power events, you could do SubscribeEvents Power,Volume. It's important to note that the the list of events does not have spaces in it. Events will always be sent in one of these two formats:
StateChanged <EventSource> <EventName>=<EventValue>ReportState <EventSource> <EventName>=<EventValue>
If you're communicating to the MRAD system through an MMS connection and the Single Socket option, all events will be prepended with MRAD. (as described above) like so:
MRAD.StateChanged <EventSource> <EventName>=<EventValue>
Examples of both formats:
ReportState Zone_1 Volume=3orStateChanged Zone_1 Volume=3MRAD.ReportState Zone_1 Volume=3orMRAD.StateChanged Zone_1 Volume=3
To request a full status report, use GetStatus command (MRAD.GetStatus in Single Socket mode). The response will simply be a set of events pushed to you all at once.
It's important to keep track of these System events:
ActiveSource: which source is does theActiveZonehave selected.ActiveZone: which zone is currently selected by this control client.
It's important to keep track of these Zone events. Events are available for every zone unless otherwise noted.
MaxVolume: the maximum volume for theActiveZone. This event is only available for theActiveZone.MinVolume: the minimum volume for theActiveZone. This event is only available for theActiveZone.Mute:Trueif the zone indicated by the event is muted,Falseotherwise.PowerOn:Trueif the zone indicated by the event is powered on,Falseotherwise.SourceId: an integer value indicating which source is selected byActiveZone. This event is only available for theActiveZone.VolumeZoneGroupId: the guid of the ZoneGroup that containsActiveZone. This event is only available for theActiveZone.ZoneGuid: the guid ofActiveZoneitself. This event is only available for theActiveZone.ZoneId: the integer id ofActiveZoneitself. This corresponds to the numbered output on the physical amplifier. This event is only available for theActiveZone.ZoneName: the string name ofActiveZoneitself. This corresponds to the output on the physical amplifier. This event is only available for theActiveZone.
It's important to keep track of these Source events. These events are only available for the ActiveSource:
MCSControl: this event tells you the IP and port to connect to in order to control the MMS instance that corresponds to this MRAD source, if one exists. For example,192.168.0.53:5004. Not relevant if using single socket mode.MCSInstance: this event tells you what to set as the MMS instance in order to control the MMS instance that corresponds to this MRAD source, if one exists.MCSWebPort: this events tells what IP and port to use as the host for any HTTP requests to MMS.NuVoSmartSource:Trueif the source is an MMS instance,Falseotherwise.SourceGuid: the guid of the Source itself.SourceId: the integer id ofActiveSourceitself. OnAseries servers, this corresponds to the physical input on the amp that is selected. Oneseries servers, this value has a more complex meaning. If the MMS instance is wired physically to an input on the Mirage Amplifier, this event's value has the same meaning as onAseries servers. Otherwise, the source ID indicates both which source on the amplifier and which eSeries device, ordinally positioned in the System, the source resides on.
Browsing Zones, Sources, and Zone Groups
MRAD browse commands function similarly to MMS browse commands. BrowseZones, BrowseSources, and BrowseZoneGroups all take either 0 or 2 arguments. However, given the relatively low number of items in any one response, it's safe to request all items by making an argument-less request. Always use SetXmlMode Lists if your environment supports XML processing as the responses will carry far more information. As with MMS browse commands, limit the response to a subset of items by specifying start and count. For example, BrowseZones 1 2. All XML responses are sent as one single line of data. We've formatted them here for readability.
Zones
BrowseZones returns the list of zones available to the MMS. If all zones have the default names, all zones will be listed. If any zone has a non-default name, then zones with non-default names will be listed. On e series, there is an additional command to see all zones regardless of name: BrowseAllZones. It functions identically to BrowseZones except that it always returns all zones.
--> BrowseZones
<-- <Zones total="4" start="1" more="false" art="false" alpha="false" displayAs="List">
<Zone guid="00010000-a259-4cda-a715-94915436337e" name="Oficina" dna="name" button="0" id="Zone_1" isOn="True" sourceId="7" sourceName="Main" gId="00000000-0007-0000-0000-000000000000" gName="ZG_1" gPwr="0" gVol="0" gSrc="1" sId="7" sGuid="00000007-a259-4cda-a715-94915436337e" m1="Pandora: Tool Radio" m2="Tool" m3="10,000 Days" m4="Right In Two" mArt="http://192.168.0.53:5005/GetArt?instance=alsa_output.pci-0000_00_1b.0.digital-stereo_MultiChannel@root@00-00-00-00-00-00&ticks=636174188433893670&guid=70c762d5-f24c-5b74-dcc1-a68531576204" />
<Zone guid="00020000-a259-4cda-a715-94915436337e" name="Gimnasio" dna="name" button="0" id="Zone_2" isOn="False" sourceId="0" sourceName="" gId="00000002-0000-0000-0000-000000000000" gName="ZG_2" gPwr="0" gVol="0" gSrc="0" sId="0" sGuid="00000000-0000-0000-0000-000000000000" m1="" m2="" m3="" m4="" mArt="" />
<Zone guid="00030000-a259-4cda-a715-94915436337e" name="Bar" dna="name" button="0" id="Zone_3" isOn="False" sourceId="0" sourceName="" gId="00000003-0000-0000-0000-000000000000" gName="ZG_3" gPwr="0" gVol="0" gSrc="0" sId="0" sGuid="00000000-0000-0000-0000-000000000000" m1="" m2="" m3="" m4="" mArt="" />
<Zone guid="00070000-a259-4cda-a715-94915436337e" name="Auriculares" dna="name" button="0" id="Zone_7" isOn="False" sourceId="7" sourceName="Main" gId="00000001-0000-0000-d762-484700000000" gName="ZG_4" gPwr="0" gVol="0" gSrc="1" sId="7" sGuid="00000007-a259-4cda-a715-94915436337e" m1="Pandora: Tool Radio" m2="Tool" m3="10,000 Days" m4="Right In Two" mArt="http://192.168.0.53:5005/GetArt?instance=alsa_output.pci-0000_00_1b.0.digital-stereo_MultiChannel@root@00-00-00-00-00-00&ticks=636174188433893670&guid=70c762d5-f24c-5b74-dcc1-a68531576204" />
</Zones>Sources
BrowseSources returns the list of sources available to the currently selected zone. If all sources have the default names, all sources will be listed. If any source has a non-default name, then sources with non-default names will be listed. On e series, there is an additional command to see all sources regardless of name: BrowseAllSources. It functions identically to BrowseSources except that it always returns all sources.
--> BrowseSources
<-- <Sources total="8" start="1" more="false" art="false" alpha="false" displayAs="List">
<Source guid="00000001-a259-4cda-a715-94915436337e" name="WIN B" dna="name" button="0" smart="0" nnet="0" znCount="0" znList="" sId="1" sGuid="00000001-a259-4cda-a715-94915436337e" m1="" m2="" m3="" m4="" mArt="" />
<Source guid="00000002-a259-4cda-a715-94915436337e" name="Player A" dna="name" button="0" smart="1" nnet="0" znCount="0" znList="" sId="2" sGuid="00000002-a259-4cda-a715-94915436337e" m1="" m2="" m3="" m4="" mArt="" />
<Source guid="00000003-a259-4cda-a715-94915436337e" name="Player B" dna="name" button="0" smart="1" nnet="0" znCount="0" znList="" sId="3" sGuid="00000003-a259-4cda-a715-94915436337e" m1="" m2="" m3="" m4="" mArt="" />
<Source guid="00000004-a259-4cda-a715-94915436337e" name="1e" dna="name" button="0" smart="0" nnet="0" znCount="0" znList="" sId="4" sGuid="00000004-a259-4cda-a715-94915436337e" m1="" m2="" m3="" m4="" mArt="" />
<Source guid="00000005-a259-4cda-a715-94915436337e" name="AUX" dna="name" button="0" smart="0" nnet="0" znCount="0" znList="" sId="5" sGuid="00000005-a259-4cda-a715-94915436337e" m1="" m2="" m3="" m4="" mArt="" />
<Source guid="00000006-a259-4cda-a715-94915436337e" name="AUX 2" dna="name" button="0" smart="0" nnet="0" znCount="0" znList="" sId="6" sGuid="00000006-a259-4cda-a715-94915436337e" m1="" m2="" m3="" m4="" mArt="" />
<Source guid="00000007-a259-4cda-a715-94915436337e" name="Main" dna="name" button="0" smart="1" nnet="0" znCount="2" znList="Oficina,Auriculares" sId="7" sGuid="00000007-a259-4cda-a715-94915436337e" m1="Pandora: Tool Radio" m2="Rage Against The Machine" m3="The Battle Of Los Angeles (Explicit)" m4="Calm Like A Bomb" mArt="http://192.168.0.53:5005/GetArt?instance=alsa_output.pci-0000_00_1b.0.digital-stereo_MultiChannel@root@00-00-00-00-00-00&ticks=636174193843003290&guid=70c762d5-f24c-5b74-dcc1-a68531576204" />
<Source guid="00000008-a259-4cda-a715-94915436337e" name="WIN MAIN" dna="name" button="0" smart="0" nnet="0" znCount="0" znList="" sId="8" sGuid="00000008-a259-4cda-a715-94915436337e" m1="" m2="" m3="" m4="" mArt="" />
</Sources>Zone Groups
BrowseZonesGroups returns the list of zone groups (adhering to the definition above) on the MMS. Once browsed once an active connection, it is not necessary to ask again. Any changes to this list will be pushed to you as they occur. If the connection closes for any reason, re-requesting this list once will reinitiate that process. You'll notice that this response has a few extra attributes in the root node.
srceAvail:0if no unused MMS source is available,1if an unused MMS source is availablesrceId: the guid of the available MMS source, if available.srceMmsAddr: the IP and port of the MMS the source resides.srceMmsInst: a unique name for the MMS instance that the source represents.
Setting Current Zone and Source
Setting Current Zone
To set your connection's current zone, use the SetZone command. This command takes a single argument. This argument can be the Id or Guid or Name of the target zone. After setting your zone, it's recommended that you do a GetStatus to ensure you have the latest information regarding that zone.
For example:
Setting Current Source
To set your current zone's source, use the SetSource command. This command takes a single argument but the valid options for that argument are different on A series and e series. On A series, this command takes the Id or Guid or Name of a source. On e series, this command takes the Guid of a source only. After setting your source, it's recommended that you do a GetStatus to ensure you have the latest information regarding that source.
For example:
Setting Zone Volume and Mute
To set the volume of your currently selected zone, send Volume <vol> where <vol> is an integer between MinVolume and MaxVolume. To set the volume of another zone, use the same command, appending the target zone's Id, Guid, or Name.
For example:
OR
To do a volume up on your currently selected zone, send VolumeUp. To do a volume up on another zone, use the same command, appending the target zone's Id, Guid, or Name.
For example:
OR
To do a volume down on your currently selected zone, send VolumeDown. To do a volume down on another zone, use the same command, appending the target zone's Id, Guid, or Name.
For example:
OR
To set the mute state on your currently selected zone, send Mute <state> where <state> is true, or false, or toggle. To set the mute state of another zone, use the same command, appending the target zone's Id, Guid, or Name.
For example:
OR
Working with Zone Groups
Building or modifying Zone Groups
As described above, a Zone Group is a set of zones that have the same Source selected. There are several ways to configure a zone group. The simplest way to to simply set more than one zone to the same source. However, there is a SetZoneGroup command that takes a comma delimited list of zones, among other things. This command has a few different formats for arguments, taking either 2 or 3 arguments.
If constructing a new zone group, you'll need to specify a source by GUID. In this case, the command will take three arguments: SetZoneGroup guidOfFirstZoneInGroup memberZone1,memberZone2,memberZoneN sourceGuid. The source guid is the srceId value from the root node of the BrowseZoneGroups response or push.
For example:
If modifying an existing zone group, use 2 arguments instead, where the first argument is the guid of the zone group itself and the second argument is the new list of zones it should contain.
For example:
Setting Zone Group Volume and Mute
Setting zone group volume and mute state functions identically to doing so for an individual zone except that the zone group's Guid is substituted for the second argument in the command.
For example: