Bose-SoundTouch/docs/guides/MIGRATION-GUIDE.md

THIS IS A PLANNED TO BE THE MIGRATION GUIDE

This migration guide is not finalized, yet. We're using it as an orientation for the required implementation.

---

Complete Migration Guide - From Bose Cloud to Local SoundTouch Service

Overview

This guide will walk you through migrating your Bose SoundTouch speakers from Bose's cloud services to your own local SoundTouch service. By the end of this process, your speakers will be completely independent of Bose's servers while retaining all their functionality.

💡 Why Migrate? Bose announced the shutdown of their SoundTouch cloud services in May 2026. This migration ensures your speakers continue working indefinitely with enhanced local control and monitoring.

What You'll Need

Hardware Requirements

• Raspberry Pi 4 or similar (minimum: Raspberry Pi Zero 2W)
• MicroSD card (16GB or larger)
• USB drive (for device preparation)
• Network connection for your Raspberry Pi

Before You Start

• List all your SoundTouch devices and their current locations
• Note your current presets and favorites (they will be preserved)
• Ensure devices are on the same network as your future SoundTouch service
• Basic computer skills (following instructions, using a web browser)

Time Estimate

• Setup: 30-60 minutes for the service installation
• Per Device: 10-15 minutes for each speaker migration
• Total: 1-3 hours depending on number of devices

Step 1: Install SoundTouch Service

Option A: Raspberry Pi Installation (Recommended)

1.1 Prepare Your Raspberry Pi

1. Flash Raspberry Pi OS to your SD card using Raspberry Pi Imager (see the raspberrypi.com documentation)
2. Enable SSH during imaging or create an empty ssh file on the boot partition
3. Boot your Pi and connect it to your network
4. Find your Pi's IP address (check your router or use ping raspberrypi.local)

1.2 Install SoundTouch Service

Connect to your Pi via SSH and run:

# Download and install
curl -sSL https://github.com/gesellix/Bose-SoundTouch/releases/latest/download/install.sh | bash

# Start the service
sudo systemctl enable soundtouch-service
sudo systemctl start soundtouch-service

1.3 Verify Installation

1. Open your web browser
2. Go to http://[PI_IP_ADDRESS]:8000 (replace with your Pi's IP)
3. You should see the SoundTouch Service Dashboard

Example: SoundTouch Service main dashboard

Option B: Docker Installation

If you prefer Docker, run:

docker run -d \
  --name soundtouch-service \
  --restart unless-stopped \
  -p 8000:8000 \
  -p 8443:8443 \
  -v soundtouch-data:/data \
  gesellix/soundtouch-service:latest

Step 2: Create Your Account

2.1 Initial Setup

1. Open the dashboard at http://[SERVICE_IP]:8000
2. Click "Create New Account"
3. Fill in your details:
   • Account Name: My Home Audio
   • Email: your@email.com (optional, for notifications)
   • Migration Strategy: Gradual (recommended)

Example: Account creation form

2.2 Account Configuration

After creation, you'll see your Account Dashboard:

• Account ID: Unique identifier (e.g., acc_home_audio_001)
• Status: Active - Ready for Migration
• Device Count: Initially 0
• Migration Status: Prepared

Example: Fresh account dashboard ready for device migration

Step 3: Prepare Your Devices

⚠️ Important: This step temporarily enables SSH access on your speakers. SSH will be automatically disabled after migration unless you choose to keep it enabled.

3.1 Enable Remote Services

For each SoundTouch device:

1. Prepare a USB drive:

   • Format as FAT32
   • Create a file named remote_services (no extension)
   • Content of file: enable

2. Insert USB drive into your SoundTouch speaker

3. Power cycle the device (unplug for 10 seconds, then reconnect)

Example: USB drive setup for enabling remote services

3.2 Verify Remote Access

In your SoundTouch Service dashboard:

1. Go to "Device Discovery" tab
2. Click "Scan Network"
3. Your devices should appear with SSH Status: Enabled

Example: Discovered devices with remote access enabled

Step 4: Discover and Register Devices

4.1 Automatic Discovery

The service automatically scans for SoundTouch devices every 5 minutes. To trigger immediate discovery:

1. Dashboard → "Devices" → "Discover Devices"
2. Wait 30-60 seconds for scan completion
3. Review discovered devices in the list

4.2 Register Devices to Your Account

For each discovered device:

1. Click device name in the discovery list

2. Verify device information:

   • Name: Living Room Speaker
   • Model: SoundTouch 30
   • MAC Address: A8:1B:6A:53:6A:98
   • IP Address: 192.168.1.100
   • Status: Discovered - Ready for Registration

3. Click "Register to Account"

4. Choose registration type:

   • Fresh Setup: For new or factory-reset devices
   • Migrate from Bose: For devices with existing Bose account (recommended)

Example: Device registration dialog with migration options

4.3 Device Registration Results

After registration, you'll see:

• Device Status: Registered - Active
• Account Association: Your account name
• Lifecycle State: Active
• Data Sources: Mirror Primary (initially uses Bose, falls back to local)

Step 5: Migrate Individual Devices

🔄 Migration Strategy: We recommend "gradual migration" where devices continue using Bose services while building local data, then switch to local-only when ready.

5.1 Start Device Migration

1. Dashboard → "Devices" → Select your device
2. Click "Migrate Device"
3. Configure migration:
   • Migration Method: Gradual (recommended)
   • Preserve Data: ✅ Yes
   • Backup Current State: ✅ Yes
   • Test Period: 7 days

Example: Migration configuration dialog

5.2 Migration Process

The migration happens in phases:

Phase 1: Data Collection (Days 1-3)

• Device continues using Bose services
• Local service mirrors all requests/responses
• Builds local database of presets, recents, sources
• Status: Migrating - Data Collection

Phase 2: Testing (Days 4-6)

• Device uses local services for some requests
• Falls back to Bose if issues occur
• Validates local data completeness
• Status: Migrating - Testing

Phase 3: Full Local (Day 7+)

• Device uses only local services
• Bose services disabled for this device
• Full independence achieved
• Status: Active - Local Only

Example: Migration progress tracking

5.3 Monitor Migration Health

During migration, monitor:

Device Health Dashboard:

• Connectivity: Should remain Online throughout
• Response Time: Should be similar or better than before
• Error Rate: Should remain low (<1%)
• Data Completeness: Shows percentage of data successfully migrated

Example: Migration health monitoring

Data Verification:

• Presets: Verify all presets work correctly
• Recent History: Check recent play history is preserved
• Source Configuration: Ensure all configured sources (Spotify, etc.) work
• Multiroom: Test zone functionality if applicable

Step 6: Complete Account Migration

6.1 Migrate All Devices

Repeat Step 5 for each of your SoundTouch devices. You can migrate multiple devices simultaneously, but we recommend doing 1-2 at a time to monitor progress.

Migration Dashboard shows overall progress:

• Devices Migrated: 2 of 4 completed
• Currently Migrating: Living Room Speaker, Kitchen Speaker
• Pending Migration: Bedroom Speaker, Office Speaker
• Estimated Completion: 3 days remaining

Example: Account-wide migration progress

6.2 Verify Complete Migration

When all devices are migrated:

1. Account Status: Active - Fully Migrated
2. Bose Dependency: None
3. Local Control: 100%
4. Device Health: All devices show Healthy - Local Only

Example: Completed migration dashboard

Step 7: Post-Migration Setup

7.1 Disable Remote Services (Optional)

For enhanced security, disable SSH on migrated devices:

1. Dashboard → "Device Management"
2. Select device → "Security Settings"
3. Click "Disable Remote Services"
4. Confirm to disable SSH access

7.2 Configure Backups

Set up automatic backups of your device configurations:

1. Dashboard → "Settings" → "Backup"
2. Enable Automatic Backups: ✅
3. Backup Schedule: Daily at 2 AM
4. Retention: Keep 30 days
5. Export Location: /data/backups or external storage

Example: Backup configuration settings

7.3 Set Up Monitoring Alerts (Optional)

Configure notifications for important events:

1. Dashboard → "Settings" → "Notifications"
2. Email Notifications: Enter your email
3. Alert Types:
   • ✅ Device goes offline
   • ✅ Migration failures
   • ✅ Service errors
   • ✅ Daily health summary

Troubleshooting Common Issues

Device Not Discovered

Problem: Device doesn't appear in discovery scan

Solutions:

1. Check network: Ensure device and service are on same network
2. Verify USB setup: Confirm remote_services file was processed
3. Power cycle: Unplug device for 30 seconds, reconnect
4. Manual add: Dashboard → "Devices" → "Add Manually" with IP address

Migration Stuck

Problem: Device stuck in "Migrating" status

Solutions:

1. Check device health: Dashboard → Device → "Health Status"
2. Review logs: Dashboard → Device → "View Logs"
3. Restart migration: Device → "Migration" → "Restart Process"
4. Rollback: Device → "Migration" → "Rollback to Bose"

Presets Not Working

Problem: Saved presets don't work after migration

Solutions:

1. Verify sources: Check configured sources are still available
2. Re-authenticate: Re-login to music services (Spotify, etc.)
3. Rebuild presets: Dashboard → Device → "Presets" → "Rebuild from Backup"

Service Unreachable

Problem: Cannot access SoundTouch Service dashboard

Solutions:

1. Check service status: sudo systemctl status soundtouch-service
2. Restart service: sudo systemctl restart soundtouch-service
3. Check network: Verify Pi is connected and accessible
4. Check ports: Ensure ports 8000 and 8443 are not blocked

Advanced Features

Multi-Zone Management

After migration, your multi-zone setups work seamlessly:

1. Dashboard → "Zones"
2. Create Zone: Select primary device and slaves
3. Zone Control: Play, pause, volume control for entire zone
4. Individual Control: Override individual speakers in zone

Custom Sources

Add custom streaming sources:

1. Dashboard → "Sources" → "Add Custom"
2. Configure:
   • Name: Local Radio Station
   • Stream URL: http://stream.example.com:8000
   • Image URL: http://example.com/logo.png
3. Assign to devices: Select which devices can access this source

API Access

For developers and advanced users:

• REST API: http://[SERVICE_IP]:8000/api/v1/
• Documentation: http://[SERVICE_IP]:8000/docs
• WebSocket Events: Real-time device status updates
• Export Data: JSON/XML export of all device configurations

Maintenance and Monitoring

Daily Monitoring

Check your Dashboard Summary:

• All Devices Online: ✅ Green indicators
• Response Times: < 100ms average
• Error Rate: < 1%
• Storage Usage: Monitor disk space

Weekly Tasks

1. Review Health Reports: Check weekly device health summaries
2. Update Service: Check for SoundTouch service updates
3. Backup Verification: Ensure backups are completing successfully
4. Log Review: Check for any recurring issues or warnings

Monthly Tasks

1. Full System Backup: Export complete account and device data
2. Performance Review: Analyze response times and error patterns
3. Security Update: Update Raspberry Pi OS and service
4. Capacity Planning: Monitor storage and consider expansion

Getting Help

Documentation Resources

• Technical Reference: /docs/reference/ - Detailed API and configuration docs
• Troubleshooting Guide: /docs/guides/TROUBLESHOOTING.md - Common issues and solutions
• Community Forum: GitHub Discussions for community support

Diagnostic Information

When seeking help, provide:

1. System Information: Dashboard → "System" → "Download Diagnostic Report"
2. Device Logs: Dashboard → Device → "Export Logs"
3. Migration History: Dashboard → "Migration" → "Export Timeline"
4. Current Status: Screenshot of main dashboard

Support Channels

• GitHub Issues: Technical bugs and feature requests
• Community Discussions: User questions and experiences
• Documentation Updates: Corrections and improvements

---

Summary

Congratulations! 🎉 You've successfully migrated your SoundTouch speakers to local control. Your devices are now:

• ✅ Independent of Bose cloud services
• ✅ Fully functional with all original features preserved
• ✅ Enhanced with better monitoring and control
• ✅ Future-proof against service shutdowns

What's Next?

• Enjoy your music with enhanced local control
• Monitor your system through the dashboard
• Share your experience with the community
• Explore advanced features as you become more comfortable

Your SoundTouch speakers will now continue working indefinitely, regardless of external service availability. Welcome to true audio independence! 🔊