Bose SoundTouch Toolkit

Documentation for controlling and preserving Bose SoundTouch devices

View the Project on GitHub gesellix/Bose-SoundTouch

SoundTouch Device Discovery

This document describes the various methods available for discovering Bose SoundTouch devices on your network.

Overview

The SoundTouch library supports multiple discovery methods to find devices on your network:

  1. Configuration-based discovery - Manually configured devices in .env file
  2. UPnP/SSDP discovery - Automatic discovery using Universal Plug and Play protocol
  3. mDNS/Bonjour discovery - Automatic discovery using multicast DNS

Discovery Methods

1. Configuration-based Discovery

You can manually configure known devices in your .env file:

PREFERRED_DEVICES=Living Room:192.168.1.100:8090,Kitchen:192.168.1.101:8090

This method is:

2. UPnP/SSDP Discovery

Uses the Universal Plug and Play protocol to discover devices automatically. This is enabled by default.

Configuration:

UPNP_ENABLED=true  # Default: true

This method is:

3. mDNS/Bonjour Discovery

Uses multicast DNS to discover devices advertising the _soundtouch._tcp service.

Configuration:

MDNS_ENABLED=true  # Default: true

This method is:

Configuration Options

Environment Variables

# Discovery timeouts
DISCOVERY_TIMEOUT=5s        # How long to wait for discovery

# Protocol enablement
UPNP_ENABLED=true          # Enable UPnP/SSDP discovery
MDNS_ENABLED=true          # Enable mDNS/Bonjour discovery

# Caching
CACHE_ENABLED=true         # Enable discovery result caching
CACHE_TTL=30s             # How long to cache results

# Manual device configuration
PREFERRED_DEVICES=Name:IP:Port,Name2:IP2:Port2

.env File Example

# Discovery settings
DISCOVERY_TIMEOUT=10s
UPNP_ENABLED=true
MDNS_ENABLED=true

# Cache settings
CACHE_ENABLED=true
CACHE_TTL=60s

# Known devices (fastest method)
PREFERRED_DEVICES=Living Room:192.168.1.100:8090,Kitchen:192.168.1.101:8090,Bedroom:192.168.1.102

Usage Examples

CLI Discovery

# Discover all devices using all methods
./soundtouch-cli -discover

# Discover with custom timeout
./soundtouch-cli -discover -timeout 10s

# Show detailed device information
./soundtouch-cli -discover-all

Programmatic Usage

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/gesellix/bose-soundtouch/pkg/config"
    "github.com/gesellix/bose-soundtouch/pkg/discovery"
)

func main() {
    // Load configuration
    cfg, err := config.LoadFromEnv()
    if err != nil {
        cfg = config.DefaultConfig()
    }

    // Create unified discovery service
    discoveryService := discovery.NewUnifiedDiscoveryService(cfg)

    // Discover devices
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    devices, err := discoveryService.DiscoverDevices(ctx)
    if err != nil {
        fmt.Printf("Discovery failed: %v\n", err)
        return
    }

    // Print results
    for _, device := range devices {
        fmt.Printf("Found: %s at %s:%d\n", device.Name, device.Host, device.Port)
    }
}

mDNS-only Discovery

package main

import (
    "context"
    "time"

    "github.com/gesellix/bose-soundtouch/pkg/discovery"
)

func main() {
    // Create mDNS-only discovery service
    mdnsService := discovery.NewMDNSDiscoveryService(5 * time.Second)

    ctx := context.Background()
    devices, err := mdnsService.DiscoverDevices(ctx)
    
    // Handle results...
}

Troubleshooting

No devices found

  1. Check network connectivity: Ensure devices are on the same network
  2. Verify multicast support: Some corporate networks block multicast traffic
  3. Try configuration-based discovery: Add devices manually to .env file
  4. Increase timeout: Some networks may be slow
  5. Check firewall settings: Ensure UDP multicast is allowed

Slow discovery

  1. Enable caching: Set CACHE_ENABLED=true
  2. Use manual configuration: Fastest method for known devices
  3. Disable unused protocols: Turn off UPnP or mDNS if not needed
  4. Reduce timeout: If you know devices respond quickly

mDNS specific issues

mDNS discovery may fail if:

UPnP specific issues

UPnP discovery may fail if:

Discovery Flow

The unified discovery service uses this flow:

  1. Check cache (if enabled and not expired)
  2. Load configured devices from environment/config
  3. Start parallel discovery:
    • UPnP/SSDP discovery (if enabled)
    • mDNS discovery (if enabled)
  4. Merge results (removing duplicates by IP)
  5. Update cache for future requests
  6. Return combined device list

Device Information

Each discovered device includes:

Performance Considerations

Security Notes

API Reference

Core Types

type DiscoveredDevice struct {
    Name     string
    Host     string
    Port     int
    Location string
    LastSeen time.Time
}

Services

Methods