Pepperdash.Essentials.Plugins.Bluesound.Api 1.0.0

Bluesound BluOS API Essentials Plugin (c) 2026

License

Provided under MIT license

Overview

PepperDash Essentials plugin for Bluesound BluOS network audio devices. Communicates with the BluOS Custom Integration API over HTTP (port 11000) to provide music service/input selection, preset/playlist management, transport controls, and volume control of the local zone.

Core feature set:

• Select service or physical input from /Browse root menu (paginated, up to 10/page)
• List and select saved presets/playlists (paginated, up to 10/page)
• Play, pause, next track, previous track
• Shuffle toggle with feedback
• Volume control — local zone (set, up, down with feedback)
• Now-playing feedback: track name, artist, album, album art URL
• Online/offline detection

Device type name: bluesoundapi

Minimum Essentials version: 2.24.0

Dependencies

• PepperDash Essentials ≥ 2.24.0 (referenced via NuGet as PepperDashEssentials)
• Target framework: .NET 4.7.2 (Crestron 4-Series)

Device Configuration

Add a device entry to your Essentials configuration JSON. The type must be bluesoundapi. The control object uses tcpIp method with the Bluesound device's IP address and port 11000.

{
  "key": "bluesound-1",
  "name": "Bluesound Node",
  "type": "bluesoundapi",
  "group": "audioPlayer",
  "properties": {
    "control": {
      "method": "tcpIp",
      "tcpSshProperties": {
        "address": "192.168.1.100",
        "port": 11000
      }
    },
    "pollTimeMs": 30000,
    "warningTimeoutMs": 60000,
    "errorTimeoutMs": 120000,
    "volumeStepPercent": 2
  }
}

Bridge Configuration

Add an EISC bridge entry and reference the device key.

{
  "key": "eisc-bluesound",
  "name": "EISC Bluesound",
  "type": "eiscApiAdvanced",
  "group": "api",
  "properties": {
    "control": {
      "method": "ipidTcp",
      "ipid": "A0",
      "tcpSshProperties": {
        "address": "127.0.0.2",
        "port": 0
      }
    },
    "devices": [
      {
        "deviceKey": "bluesound-1",
        "joinStart": 1
      }
    ]
  }
}

The joinStart value offsets all join numbers in the table below.
With joinStart: 1 the join numbers are as listed. With joinStart: 101 add 100 to each join number.

Join Map

Digital Joins

Analog Joins

Serial Joins

References

• BluOS Custom Integration API v1.7 — documents/BluOS-Custom-Integration-API_v1.7.pdf
• PepperDash Essentials framework — https://github.com/PepperDash/Essentials
• PepperDash plugin library — https://github.com/PepperDash
• pyblu reference client (endpoint mapping) — https://github.com/LouisChrist/pyblu
• Home Assistant Bluesound integration (reference architecture) — https://github.com/home-assistant/core/tree/dev/homeassistant/components/bluesound

Build

cd src
dotnet build epi-bluesound-api.4Series.csproj

The build outputs a .cplz package in /output/ ready for deployment to a 4-Series processor.

Generating NuGet Package

A NuGet package is automatically generated on build. To modify package metadata, edit the following in the .csproj:

1. PackageId — NuGet package name
2. PackageProjectUrl — should match this repo URL
3. AssemblyTitle — DLL file name shown on processor