Maxx Control REST: Device grouping

Maxx Control REST: create device groups, assign channels, then mute, solo, and set group volume on one amplifier.
Tags:
Categories:

Use the Maxx Control REST API to group channels on one amplifier, then mute, solo, or trim volume for that set. This is the same grouping Maxx Control’s GROUPS page uses.

These are device groups (16 slots on the amp). They are not Maxx Remote project groups. For rooms across many amplifiers, use Maxx Remote.

How grouping applies

A group only affects audio when enable is true. Then:

ControlEffect on assigned channels
MuteMutes every assigned channel (on top of channel mute).
VolumeAdds to each assigned channel. If a channel is in several enabled groups, those group volumes sum.
SoloKeeps assigned channels open and mutes other channels that belong to some enabled group. Channels that are in no group stay untouched.

assign_id is the amplifier channel number (1…channel count). group_id is 1…16.

Writes need the token header (see REST API overview).

Base URL on the device is /rest-api (OpenAPI servers). Paths below are from /settings/device/grouping in the on-device schema.

Complete example

Create group 1 as Foyer, assign channels 1 and 2, enable it, then drop group volume by 6 dB and mute it:

IP="${IP:-10.77.150.42}"
TOKEN="f4005bf8507999192162d989d5a60823"
BASE="http://${IP}/rest-api"

# Allowed group_id range: {"group_id":[1,16,1,""]}
curl -s -X OPTIONS "${BASE}/settings/device/grouping/groups"

# Configure group 1 in one PUT (array of SettingsGroup)
curl -s -X PUT "${BASE}/settings/device/grouping/groups" \
  -H "Content-Type: application/json" \
  -H "token: ${TOKEN}" \
  -d '[
    {
      "group_id": 1,
      "name": { "value": "Foyer" },
      "enable": { "value": true },
      "mute": { "value": false },
      "solo": { "value": false },
      "volume": { "value": -6.0 },
      "assign": [
        { "assign_id": 1, "value": true },
        { "assign_id": 2, "value": true }
      ]
    }
  ]'

# Day-to-day leaf calls
curl -s -X PUT "${BASE}/settings/device/grouping/groups/1/mute" \
  -H "Content-Type: application/json" \
  -H "token: ${TOKEN}" \
  -d '{"value": true}'

curl -s -X PUT "${BASE}/settings/device/grouping/groups/1/mute" \
  -H "Content-Type: application/json" \
  -H "token: ${TOKEN}" \
  -d '{"value": false}'

curl -s -X PUT "${BASE}/settings/device/grouping/groups/1/volume" \
  -H "Content-Type: application/json" \
  -H "token: ${TOKEN}" \
  -d '{"value": -10.0}'

List all groups

Read the full grouping tree (soloautoclear plus all 16 groups):

curl -X 'GET' http://${IP}/rest-api/settings/device/grouping
{
  "soloautoclear": { "value": true },
  "groups": [
    {
      "group_id": 1,
      "assign": [
        { "assign_id": 1, "value": true },
        { "assign_id": 2, "value": true },
        { "assign_id": 3, "value": false }
      ],
      "enable": { "value": true },
      "name": { "value": "Foyer" },
      "solo": { "value": false },
      "mute": { "value": false },
      "volume": { "value": -6.0 }
    }
  ]
}

GET /settings/device/grouping/groups returns only the groups array. OPTIONS on that path reports the group-id range:

curl -X 'OPTIONS' http://${IP}/rest-api/settings/device/grouping/groups
{
  "group_id": [1, 16, 1, ""]
}

Get one group

curl -X 'GET' http://${IP}/rest-api/settings/device/grouping/groups/1
{
  "group_id": 1,
  "assign": [
    { "assign_id": 1, "value": true },
    { "assign_id": 2, "value": true }
  ],
  "enable": { "value": true },
  "name": { "value": "Foyer" },
  "solo": { "value": false },
  "mute": { "value": false },
  "volume": { "value": -6.0 }
}

There is no PUT on /groups/{group_id}. Write a leaf (/mute, /volume, …) or PUT an array to /groups.

Name a group

Names are limited to 256 characters. OPTIONS on the name leaf returns { "length": 256 } (MAX_GROUP_NAME in firmware).

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/name \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": "Foyer"
}'
curl -X 'OPTIONS' http://${IP}/rest-api/settings/device/grouping/groups/1/name

Assign channels to a group

assign_id is the channel. value: true adds the channel; false removes it. OPTIONS on /assign reports [MIN, MAX, STEP, UNIT] for assign_id (max is the device channel count).

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/assign \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '[
  { "assign_id": 1, "value": true },
  { "assign_id": 2, "value": true },
  { "assign_id": 3, "value": false }
]'
[
  { "assign_id": 1, "value": true },
  { "assign_id": 2, "value": true },
  { "assign_id": 3, "value": false }
]

Read a single assignment with GET /settings/device/grouping/groups/1/assign/1 → { "assign_id": 1, "value": true }. Assignment is write-only on the collection path — there is no PUT on /assign/{assign_id}.

Enable the group

Mute, solo, and group volume are ignored until the group is enabled:

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/enable \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": true
}'
curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/enable \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": false
}'

Mute a group

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/mute \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": true
}'
curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/mute \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": false
}'

The resulting mute on a channel (group mute plus solo) is readable, GET-only:

curl -X 'GET' http://${IP}/rest-api/settings/channel/1/dsp/groupmute

That is separate from the channel’s own mute.

Set group volume

Group volume uses the same range as channel volume: -72.0 dB to +24.0 dB, step 0.1 dB. It adds to each assigned channel; it does not replace channel volume.

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/volume \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": -6.0
}'
curl -X 'OPTIONS' http://${IP}/rest-api/settings/device/grouping/groups/1/volume

OPTIONS response: { "value": [-72.0, 24.0, 0.1, "dB"] }.

Solo and solo auto-clear

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/solo \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": true
}'
curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups/1/solo \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": false
}'

When solo auto-clear is on, enabling solo on one group clears solo on the others (same as the GROUPS page SOLO AUTO CLEAR button):

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/soloautoclear \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '{
  "value": true
}'

Configure a group in one PUT

Partial updates work on /settings/device/grouping/groups: send only the groups and fields you want to change.

curl -X 'PUT' http://${IP}/rest-api/settings/device/grouping/groups \
-H 'Content-Type: application/json' \
-H 'token: f4005bf8507999192162d989d5a60823' \
-d '[
  {
    "group_id": 1,
    "name": { "value": "Foyer" },
    "enable": { "value": true },
    "mute": { "value": false },
    "solo": { "value": false },
    "volume": { "value": -6.0 },
    "assign": [
      { "assign_id": 1, "value": true },
      { "assign_id": 2, "value": true }
    ]
  }
]'
[
  {
    "group_id": 1,
    "name": { "value": "Foyer" },
    "enable": { "value": true },
    "mute": { "value": false },
    "solo": { "value": false },
    "volume": { "value": -6.0 },
    "assign": [
      { "assign_id": 1, "value": true },
      { "assign_id": 2, "value": true }
    ]
  }
]

You can PUT several groups in that same array (for example a Foyer group and an All Subs group).