Russound smart home integration, free and open source
Russound multiroom controllers, local over RIO: zones, power, volume, mute, source, now playing.
Published by LM1LC3N7
- Devices
- Version 0.1.1
- Requires Gladys >=5.1.0
- ★ 0
Control from Gladys each zone of your Russound multiroom controllers with the RIO protocol on their network port (MCA-66, MCA-88, MCA-88X, MCA-C3, MCA-C5, MBX-PRE, MBX-AMP…), locally, without any cloud: power on, standby, volume (capped), mute, source and what is playing.
Important. This integration has never been tested with a real device: it was written from the
aiorussoundlibrary (the one Home Assistant uses) and tested against a fake controller only. Your feedback is welcome. Unofficial integration, not affiliated with Russound.
Installation
- Plug the controller into your network and give it a fixed IP address in your router (reserved DHCP lease).
- In Gladys, install the Russound integration, then open its configuration.
- Type the IP addresses of the controllers, separated by commas (for
example
192.168.1.40). The RIO port is 9621; for another one, add it:192.168.1.40:9622. One address is enough for controllers chained over RNET behind the first one. - Choose the volume cap (25 out of 50 by default).
- The zones appear in the Discovery tab (one per named zone): create the ones you want.
The integration keeps a connection open with each controller and watches every zone and source: what is changed on a keypad, a remote or the app shows at once in Gladys. The zones are also read again every minute.
Only the network port is supported: the RS-232 serial port is not (a Gladys integration runs in a container without access to the serial port), nor the RNET-only protocol of older models (CAV, CAM) without a RIO port.
What you get, for each zone
| Feature | Gladys type | Note |
|---|---|---|
| Power | binary state (read only) | 1 zone on, 0 off or controller unreachable |
| Power on | button | ZoneOn |
| Standby | button | ZoneOff |
| Volume | music / volume (0 to 100) | 100 % = the cap |
| Mute | button (television / mute) | each press reads the state, then sets the opposite |
| Source | dropdown | the named sources of the controller |
| Now playing | text (read only) | "artist - title", or the station; empty when zone off |
On purpose, no switch: an "everything off" or "everything on" of a voice assistant or a scene neither turns your zones on nor off.
Volume cap
Russound controllers count the volume from 0 to 50. In Gladys, the volume goes from 0 to 100 %: 100 % is the cap of the configuration (25 by default). Gladys (dashboard, scene, voice assistant) can never set a volume above the cap. The cap is read again just before sending: a new value saved applies at once.
The volume set on a keypad or a remote is not changed by the integration (above the cap, Gladys shows 100 %), except in the two cases where Gladys would make it heard:
- Unmute: when the volume of the zone is above the cap, it is first brought back to the cap, then the mute is removed. When the volume cannot be read, nothing is sent; when the controller does not confirm the lowering, the mute is kept.
- Power on: a zone turns on at its "turn-on volume"; above the cap, it is brought back to it, until the controller confirms a volume at or under the cap. When the zone is slow, the integration checks a few more times for about 15 seconds, and lowers a volume reported above the cap meanwhile.
Commands
A command succeeds only when the value read back from the controller is the one asked. Every command is answered within 4 seconds (Gladys waits 5 seconds). A command that left without confirmation is reported "sent, without confirmation"; a command that could not leave is reported "nothing sent". A burst of commands (a volume slider dragged) never closes the connection: the ones coming too late are refused without sending anything. Eight commands at most wait per zone.
The source is only chosen on a zone that is on (read just before): on a zone off, it is refused without sending anything, since choosing a source could turn the zone on at its turn-on volume, without the cap. Turn the zone on first.
Standby goes before every command waiting, cancels a Power on, a source or a volume still waiting (a command already running sends nothing after it), and stays possible right after a restart, before the first full read: when the connection waits for its next attempt, it is opened at once. A Standby not confirmed is read again and sent again up to three times within 15 seconds, unless a Power on is asked in Gladys meanwhile; a zone turned on again from a keypad during that time may thus be turned off again.
Mute uses the explicit ZoneMuteOn / ZoneMuteOff commands (RIO
1.09.00 or later); on an older firmware, which can only toggle the mute, it
is refused without sending anything.
Identity of the zones
Each zone is known by the address of the controller, the number of the
controller and the one of the zone (for example 192.168.1.40_c1_z3): keep
a fixed IP address. The MAC address of the controller, when it tells it, is
kept: when another controller answers at this address one day (DHCP swap),
its zones are neither read nor commanded and the status says so. If you
replaced the controller, remove its address from the configuration, delete
its zones in Gladys, then add it again. An unreadable MAC address is never
taken for another controller.
Reconnection
A controller that does not answer (off, unplugged) shows the power of its zones at 0 and is named in the integration status. The integration connects again after 10 s, then at intervals doubled after each failure, up to 5 minutes; a request without answer closes the connection, then the same spaced reconnection applies. The time of the last attempt is kept: a restart of the integration never asks the controller faster.
Configuration button
- Check the controllers: the connection, the RIO version, the MAC address and the number of zones of each controller, the state of each zone (power, volume out of 50, mute, source), and the cap in force.
Data and privacy
The integration asks for no account and no password: the RIO port has none.
It keeps in /data/russound.json the known zones (address, numbers, name,
sources), and for each address the MAC address of the controller, the time
of the last connection attempt and the number of failures. Nothing leaves
your local network.
Known limits
- No play / pause / next yet, no tuner presets, bass, treble, balance, loudness, party mode nor "do not disturb".
- The source list does not take into account the sources disabled for a zone.
- Limited use in France, Belgium and Switzerland: Russound is mostly installed in North America.
- Never tested with a real device: the real answers may differ.
Configuration settings
These are the settings Russound asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Russound controllers, on your local network | section | No | Each zone of a Russound controller with the RIO protocol on its network port (TCP 9621: MCA-66, MCA-88, MCA-C3, MCA-C5, MBX-PRE, MBX-AMP...) becomes a Gladys device: power on, standby, volume, mute, source and what is playing, without any cloud. The RS-232 serial port is not supported. Give each controller a fixed IP address in your router and type it below; the zones then appear in the Discovery tab. 100 % in Gladys is the volume cap below, never exceeded. Never tested with a real device. Unofficial integration, not affiliated with Russound. |
| IP addresses of the controllers | string | No | Separated by commas, for example 192.168.1.40, 192.168.1.41. Port 9621 by default; add :port for another one. One address per controller: the controllers chained to it (RNET) are found through it. |
| Volume cap (0 to 50) | number | No | The loudest volume Gladys may set, on the Russound scale shown by the keypads (from 1 to 50, 25 by default): it is 100 % in Gladys. A scene, a voice assistant or the dashboard can never go above it. A zone turned on by Gladys above it is brought back to it. |
How to install Russound in Gladys
- In Gladys, open Integrations: Russound appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-russound:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-russound.
Russound requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Russound is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation