Unfolded Circle Integration StormAudio

This repository contains the source code for the Unfolded Circle Remote Two/3 integration driver for StormAudio devices. The Focal Astral 16 and Bryston SP4 should work, too.

The integration is based on the amazing work of JackJPowell's ucapi-framework.

Table of contents

1. Supported entity types
2. Installation instructions
3. Update instructions
4. Versioning
5. Changelog
6. Development
7. Resources
8. License

Supported entity types

• Media player
• Remote
• Selects
• Sensors

Media Player entity

The Media Player entity implements the following features:

• ON_OFF: Provides dedicated on/off commands
• DPAD: Enables navigating your ISPs front panel (for supported models)
• TOGGLE: Provides the power toggle
• VOLUME: Enables adjusting the volume slider via the Remote 3's touch slider
• VOLUME_UP_DOWN: Provides dedicated volume up/down commands
• HOME: Provides the home and back commands. Both commands are mapped to the back command, as there is no home command for the ISPs
• MUTE: Mutes the device
• UNMUTE: Unmutes the device
• MUTE_TOGGLE: Toggles the mute state of the device
• SELECT_SOUND_MODE: Provides a dropdown of available sound modes (Upmixers)
• SELECT_SOURCE: Provides a dropdown of available sources

The entity doesn't provide any of the playback features, though, as the StormAudio API doesn't provide any of those commands (they would only be active for Roon anyway).

Furthermore, the Media Player entity implements all the Simple-Commands provided by the Remote entity, too.

Remote entity

The Media Player entity implements the following features:

• ON_OFF: Provides dedicated on/off commands
• TOGGLE: Provides the power toggle
• SEND_CMD: Allows sending a (custom) command to the device
• SEND_CMD_SEQUENCE: Allows sending a (custom) command sequence to the device

Furthermore, it implements many Simple-Commands.

The commands SEND_CMD and SEND_CMD_SEQUENCE allow the user to send any of your StormAudio's supported TCP commands (see https://www.stormaudio.com/tools-guides/ → Drivers Packages → TCP/IP API for reference).

Additionally, you can send the following custom commands for the send_cmd and send_cmd_sequence commands:

1. PRESET_<YourPresetName> --> This will select the given preset on your device.
2. SOURCE_<YourSourceName> --> This will select the given source on your device.
3. VOLUME_<YourVolumeLevel> --> This will set the volume level on your device to the given value (i.e. VOLUME_45 will result in -55dB in your ISP).

Select entity

This integration provides the following Select-Types:

• Auro-Matic presets
• Auro-Matic strength
• Presets
• Sound mode (aka Upmixers)

Sensor entity

This integration provides the following sensors:

• Current Volume
• Muted Status
• Current Audio-Stream-Info (Stream (like PCM, DTS, etc.), input channel configuration and Samplerate)
• Current Auro-Matic Preset
• Current Auro-Matic Strength
• Current Dolby Mode
• Current Dolby Center Spread Setting
• Current Dolby Virtualizer Setting
• Current Loudness Setting
• Current Preset
• Current Source
• Current Upmixer
• StormXT Status
• Tone controls (Bass, Treble, Brightness, Center enhancement, Surround enhancement, LFE enhancement)

Installation instructions

1. Download the integration package (tar.gz file) from the Releases page
2. Upload the archive via the Remote's web configurator: "Integrations" → "Install custom"
3. Configure your device through the setup wizard

Update instructions

1. Download the integration package (tar.gz file) from the Releases page
2. Remove the existing integration from the Remote (twice) → no worries, all your configured activity settings will still be there.
3. Upload the archive via the Remote's web configurator: "Integrations" → "Install custom"
4. Configure your device through the setup wizard

Versioning

We use SemVer for versioning. For the versions available, see the tags and releases in this repository.

Changelog

The major changes found in each new release are listed in the changelog and under the GitHub releases.

Development

Project Structure

├── driver.json              # Integration metadata and configuration
├── uc_intg_stormaudio/      # Main integration code
│   ├── __init__.py          # Main entry point
│   ├── config.py            # device configuration dataclass
│   ├── const.py             # Constants
│   ├── device.py            # Device communication and state management
│   ├── device_attributes.py # Contains the device attributes, i.e. the state of the StormAudio ISP
│   ├── discover.py          # Network device discovery
│   ├── helpers.py           # Common used helper files
│   ├── media_player.py      # Media player entity
│   ├── remote.py            # Remote entity
│   ├── select_entity.py     # Select entity
│   ├── sensor.py            # Sensor entity
│   ├── setup.py             # Setup flow and user configuration
│   └── stormaudio.py        # The basic TCP-/Telnet-client for communicating with StormAudio devices
├── config/                  # Runtime configuration storage
├── Dockerfile               # Container build configuration
└── requirements.txt         # Python dependencies

Prerequisites

• Python 3.11+
• uv
• Docker, Docker Compose

Running the integration

1. Prepare the environment:

   uv venv

2. Install dependencies:

   uv sync

3. Install the git-hooks:

   uv run pre-commit install

4. Run the integration either locally or via a Compose environment:

   1. Locally:

      uv run python3 uc_intg_stormaudio

   2. via Compose:

      docker compose up --remove-orphans --build --watch --pull=always

Adding and removing dependencies

Adding dependencies

uv add <dependency>
uv export --format requirements.txt --output-file requirements.txt --no-annotate --no-header --no-hashes --no-dev

Removing dependencies

uv remove <dependency>
uv export --format requirements.txt --output-file requirements.txt --no-annotate --no-header --no-hashes --no-dev

Updating a single dependency

uv lock --upgrade-package <dependency>
uv export --format requirements.txt --output-file requirements.txt --no-annotate --no-header --no-hashes --no-dev

Updating all dependencies

uv lock --upgrade
uv export --format requirements.txt --output-file requirements.txt --no-annotate --no-header --no-hashes --no-dev

Environment Variables

Variable	Description	Default
UC_LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	DEBUG
UC_CONFIG_HOME	Configuration directory path	/config
UC_INTEGRATION_INTERFACE	Network interface to bind	0.0.0.0
UC_INTEGRATION_HTTP_PORT	HTTP port for the integration	9090
UC_DISABLE_MDNS_PUBLISH	Disable mDNS advertisement	false

Resources

• UC Integration Python Library
• UCAPI Framework
• Unfolded Circle Developer Documentation

License

Mozilla Public License Version 2.0 – see LICENSE for details.