WiiM Amp / Pro

Driver for WiiM network audio streamers and amplifiers — the WiiM Amp, WiiM Pro, Pro Plus, and their siblings. WiiM devices expose a Sonos-compatible UPnP control layer (the same RenderingControl and AVTransport services Sonos speakers use), so GEM controls them the same way it controls a Sonos speaker: each WiiM unit becomes an AV audio zone, and you drive its volume, mute, line-input selection, and power-off from the UI, a macro, or a touchpanel. The driver reads volume/mute/input back on a poll so the state you see in GEM tracks whatever someone changed in the WiiM Home app or on the unit.

This driver is derived from GEM's Sonos driver and shares its control model — if you have worked with Sonos in GEM, WiiM behaves the same, with a smaller command set (no queue, grouping, or music-library browse).

Discovery is not wired up in the current build

The step that finds WiiM units on the network and builds the live control handle to each one — the SSDP/UPnP discovery the Sonos driver runs on connect — is not yet present in this driver. As shipped, the device connects and reports online, but it does not enumerate WiiM units, does not auto-create zones, and cannot reach hardware, so the volume/mute/input/off commands below have nothing to act on until discovery is completed. Everything on this page describes the integration model and the exact command/attribute surface so the configuration is correct and ready the moment discovery lands. Nothing here requires you to change device firmware or network wiring in advance.

How WiiM is modeled in GEM

• One GEM device represents the WiiM integration for a subnet. It is intended to discover every WiiM unit on that subnet (the same one-device-many-zones pattern Sonos uses), not one GEM device per speaker.
• Each WiiM unit becomes a zone under the AV subsystem, addressed by the unit's UPnP UUID. The address is meant to be populated automatically during discovery — it is not something you type by hand.
• Zones are created on first connect only. A unit added to the network later does not retroactively appear; reload the device (or add its zone manually) to pick it up.
• The driver auto-creates the zone for each unit but does not also create the matching AV zone. To surface a WiiM unit inside AV routing (source selection, grouping views), add an AV zone for it yourself.

Prerequisites

• Set up each WiiM unit in the WiiM Home app first and confirm it plays audio. GEM controls an already-configured unit; it does not onboard it to Wi-Fi or your network.
• Put the WiiM unit(s) and the GEM controller on the same VLAN / subnet. Discovery relies on SSDP/UPnP multicast, which does not cross routers — a unit on a separate AV or IoT VLAN will not be found.

Setup

Open Devices

1. Go to System → Devices → Add Device and set:
   • Driver → WiiM Amp / Pro.
   • Type → an AV-class device type (the driver hints the AV subsystem for its zones).
2. Enable the device and save. On connect the driver is intended to discover the WiiM units on the subnet and create one AV zone per unit, with the zone Address set to the unit's UPnP UUID. (See the note above — this discovery step is not active in the current build, so no zones appear yet.)
3. Tune volume behavior per zone. On each WiiM zone you can set:
   • Volume Step (volume_increment) — how much volume_up / volume_down move the level. Falls back to the device-level step (default 3) if unset.
   • Min Volume (min_volume, default 0) and Max Volume (max_volume, default 100) — the floor and ceiling the up/down steps clamp to.

What you can control

Every command targets a WiiM zone. When you fire a command from a zone, GEM fills in the unit's UUID for you (the Address), so you never type it.

• Set an exact volume — volume sets the master volume directly (0–100).
• Nudge volume — volume_up / volume_down move by the zone's step and stop at Max Volume / Min Volume.
• Mute / unmute — mute_on and mute_off.
• Select a line input — input streams a WiiM unit's physical line-in as the source (see below).
• Turn the zone off — zone_off ungroups the unit and stops playback.

Selecting a line input

WiiM units, like Sonos, can stream one unit's physical line input (its analog or optical in) to another. GEM models that input as an AV source:

1. Create an AV source whose Address is the UUID of the WiiM unit whose line input you want to stream. Mark it Global if every room should be able to pick it, or assign it to a specific zone for a local-only source.
2. Selecting that source on a WiiM zone runs the input command, which streams the chosen unit's line-in to the zone and starts playback. Under the hood this uses the WiiM/Sonos line-in URI (x-rincon-stream:<UUID>); you only ever deal with the AV source, not the URI.

If the source resolves to no address, the command returns invalid av source — confirm the AV source's Address holds a real WiiM UUID.

Attribute reference

Device

Attribute	Type	Default	Description
volume_increment	int	3	Volume change per volume_up / volume_down. A per-zone Volume Step overrides it.
status_interval	int	5000	How often (ms) the driver polls each zone's volume, mute, and current input.

Zone

Attribute	Type	Default	Description
address	string	—	The WiiM unit's UPnP UUID. Populated automatically during discovery — do not enter it by hand.
volume_increment	int	(device value)	Per-zone Volume Step override.
min_volume	int	0	Floor that volume_down clamps to.
max_volume	int	100	Ceiling that volume_up clamps to.

State the driver reports back

On its poll the driver writes these zone attributes so GEM reflects the unit's live state (and they can drive triggers and UI):

Attribute	Type	Meaning
volume	int	Current master volume (0–100).
mute_state	string	on when muted, off when not.
input	string	UUID of the line input currently streaming, or blank when the unit is not on a line-in.
input_device	string	Name of the source unit feeding the current line input.
input_device_id	int	Id of the source unit feeding the current line input.

Commands

These are the commands the driver declares. Driver command rows are rewritten on every boot — add commands of your own, but do not hand-edit the args below; they are overwritten on restart.

Command	Args	What it does
volume	volume, address	Set the master volume to an exact value (0–100).
volume_up	address	Raise volume by the zone's step, clamped to Max Volume.
volume_down	address	Lower volume by the zone's step, clamped to Min Volume.
mute_on	address	Mute the unit.
mute_off	address	Unmute the unit.
zone_off	address	Ungroup the unit and stop playback.
input	device_id, address	Stream the selected AV source's WiiM line input to this zone.
get_volume	address	Placeholder — see the note below.
get_mute	address	Placeholder — see the note below.
get_input	address	Placeholder — see the note below.

note

The get_* commands are placeholders

get_volume, get_mute, and get_input are listed for completeness but perform no action when called — they return nothing. The driver keeps volume, mute, and input current on its own status poll (status_interval, default 5000 ms) rather than on demand, so you never need to call them to refresh state.

Known limitations

• Discovery is not wired up in this build (see the note near the top). Until the SSDP/UPnP discovery step lands, no WiiM units are found, no zones are auto-created, and the commands cannot reach hardware.
• Zones auto-create on first connect only (intended behavior). A unit added later needs a device reload, or add its zone by hand with the unit's UUID as the Address.
• The AV zone is not auto-created. The driver creates a plain zone per unit; add the AV zone yourself to place the unit in AV routing.
• Shared Sonos heritage. Because the driver is derived from the Sonos driver, some internal log lines read sonos. That is cosmetic — it does not change what the driver does.
• No transport, grouping, queue, or library browse. Unlike the full Sonos driver, this covers volume, mute, line-input selection, and power-off only. Playback source selection beyond line-in is done in the WiiM Home app or by a streaming source feeding the unit.

Troubleshooting

Symptom	Check
No zones appear after enabling the device	Expected in the current build — discovery is not wired up yet (see the note near the top). When discovery is present, this instead points to SSDP multicast being blocked: confirm the WiiM unit and GEM are on the same VLAN/subnet and that the unit is visible in the WiiM Home app.
A command returns invalid zone	The address did not match a WiiM zone. From a zone context GEM fills the Address in for you; if you are calling the command directly, pass the unit's UUID as address.
A command returns invalid av source or missing av source address	The input command could not resolve a source for this zone/device pair, or the resolved AV source has no Address. Set the AV source's Address to the UUID of the WiiM unit whose line input you want to stream.
Volume drifts out of the range you expect	Check the zone's Min Volume / Max Volume — volume_up / volume_down clamp to them. volume sets an exact value and is not clamped.
GEM state lags a change made on the unit or in the app	State reconciles on the poll; lower Status Poll Interval (status_interval) on the device for faster catch-up.

Related documentation

• Sonos — the driver this one is derived from; the same UPnP control model and line-in pass-through, with the full playback/grouping/browse command set.
• Devices — add the WiiM device and reload it to pick up new units.
• Zones — the per-unit AV zones addressed by the WiiM UUID.
• AV Zones — surface a WiiM unit inside AV routing.
• AV Sources — define the line-input source the input command selects.
• Commands — where volume / mute_on / input appear and can be tested.
• Subsystems — the AV subsystem the WiiM zones live under.