diff --git a/docs/guides/DEVICE-INITIAL-SETUP.md b/docs/guides/DEVICE-INITIAL-SETUP.md index 6729b39..35473a8 100644 --- a/docs/guides/DEVICE-INITIAL-SETUP.md +++ b/docs/guides/DEVICE-INITIAL-SETUP.md @@ -25,13 +25,17 @@ Used by most modern SoundTouch devices (ST-10, ST-20/30 Series III, SoundTouch 3 The classic "failover" or "alternate" setup method. - **Mechanism**: The device creates its own Wi-Fi network (SSID: `Bose SoundTouch ...` or `Bose Home Speaker ...`). -- **IP Address**: Typically `192.168.1.1` or `10.0.0.1` (device-side). +- **IP Address**: Typically `192.0.2.1` (device-side, verified on ST10). - **Web Interface**: The device hosts a web server on port 80. - **Process**: 1. Connect a PC/Phone to the device's Wi-Fi. - 2. Open a browser to `http://192.168.1.1`. - 3. The device serves `setup.html`, which redirects to a setup wizard (`setup/index.html`). - 4. Use the Wi-Fi setup form to select a network and enter credentials (calls `POST http://192.0.2.1:8090/addWirelessProfile` via the SoundTouch API — see §6.3). + 2. Open a browser to `http://192.0.2.1`. + 3. The device serves a Wi-Fi setup form — enter your home network SSID and password and click Submit. + 4. The device disconnects from AP mode and joins your home network within ~15–30 seconds. + +![Speaker AP mode Wi-Fi setup page at 192.0.2.1](../images/speaker-ap-wifi-setup.png) + +For command-line provisioning (without a browser), see §6 below. --- diff --git a/docs/guides/MIGRATION-GUIDE.md b/docs/guides/MIGRATION-GUIDE.md index 13e9836..1f15f84 100644 --- a/docs/guides/MIGRATION-GUIDE.md +++ b/docs/guides/MIGRATION-GUIDE.md @@ -60,9 +60,11 @@ See [Raspberry Pi Setup](RASPBERRY-PI.md) and the [SoundTouch Service Guide](SOU Open `http://:8000` and go to the **Settings** tab. -Set the **Server URL** to the address your speakers can reach — for example `http://soundtouch.fritz.box:8000` or `http://192.168.1.100:8000`. This must be the host's address on your local network, not `localhost`. +![AfterTouch Settings tab](../images/ui-settings.png) -If you plan to use DNS/DHCP redirect (which requires HTTPS), also set the **HTTPS Server URL** (e.g. `https://soundtouch.fritz.box:8443`). +Set the **Target Domain** to the address your speakers can reach — for example `https://soundtouch.fritz.box` or `http://192.168.1.100:8000`. This must be the host's address on your local network, not `localhost`. + +If you plan to use DNS/DHCP redirect, enable the **DNS Discovery Server** and set the **DNS Bind Address** to `:53`. The upstream DNS should be your router's IP, not the service's own address. > **Tip**: If you change settings and they don't seem to take effect, check `data/settings.json` — settings saved in the UI take precedence over environment variables. @@ -86,11 +88,15 @@ You only need to do this once per speaker. SSH can remain enabled for future mai ### Discover -The service scans for SoundTouch devices automatically every few minutes. Check the **Devices** tab in the web UI. If your speaker doesn't appear, click **Discover Devices** to trigger an immediate scan, or add it manually by IP address. +The service scans for SoundTouch devices automatically every few minutes. Check the **Devices** tab in the web UI. If your speaker doesn't appear, click **Scan Again** to trigger an immediate scan, or enter the IP address manually and click **Add Device**. + +![AfterTouch Devices tab showing discovered speakers](../images/ui-devices.png) ### Sync -Once the speaker appears, click **Sync**. This connects to the speaker and pulls its current presets, recently played items, and configured sources into the local service's datastore. It also creates an off-device backup of the speaker's configuration. +Once the speaker appears, click **Sync Data**. This connects to the speaker and pulls its current presets, recently played items, and configured sources into the local service's datastore. It also creates an off-device backup of the speaker's configuration. + +![Data Sync tab showing a successful sync](../images/ui-sync.png) If the Bose cloud is still running, Sync also fetches your account data from Bose's servers. This is your preservation step — do it before the cloud shuts down. @@ -98,7 +104,11 @@ If the Bose cloud is still running, Sync also fetches your account data from Bos ## Step 5: Migrate -The **Migration** tab in the web UI walks you through the redirect. Two methods are available: +Click **Migrate** next to a device on the Devices tab to open the Migration tab. It shows SSH status, CA trust status, and connection test results before letting you apply the redirect. + +![Migration tab showing HTTPS and DNS connection tests](../images/ui-migration.png) + +Two redirect methods are available: ### XML redirect (recommended for first-time / testing) diff --git a/docs/images/README.md b/docs/images/README.md index f50e49d..eec1e91 100644 --- a/docs/images/README.md +++ b/docs/images/README.md @@ -1,90 +1,17 @@ -# Images for Migration Guide +# docs/images -This directory contains images, screenshots, and diagrams referenced in the migration guide and other documentation. +Screenshots and diagrams referenced by the documentation. -## Required Images for Migration Guide +## Current screenshots -The following images need to be created to complete the migration guide: +| File | Shows | Used in | +|------|-------|---------| +| `ui-settings.png` | AfterTouch web UI — Settings tab (Target Domain, DNS Discovery, Mirroring) | Migration Guide | +| `ui-devices.png` | AfterTouch web UI — Devices tab (discovered speakers with Sync/Migrate actions) | Migration Guide | +| `ui-sync.png` | AfterTouch web UI — Data Sync tab (successful sync result) | Migration Guide | +| `ui-migration.png` | AfterTouch web UI — Migration tab (HTTPS test, DNS test, method selector) | Migration Guide | +| `speaker-ap-wifi-setup.png` | Speaker AP mode Wi-Fi setup page at `http://192.0.2.1` | Device Initial Setup | -### Dashboard Screenshots -- **dashboard-home.png** - Main SoundTouch Service dashboard homepage -- **account-creation.png** - Account creation form with fields filled -- **account-dashboard.png** - Fresh account dashboard showing ready state -- **device-discovery.png** - Device discovery page showing found speakers -- **device-registration.png** - Device registration dialog with options -- **migration-setup.png** - Migration configuration dialog -- **migration-progress.png** - Migration progress tracker showing phases -- **migration-health.png** - Migration health monitoring dashboard -- **account-migration.png** - Account-wide migration progress overview -- **migration-complete.png** - Completed migration dashboard view -- **backup-setup.png** - Backup configuration settings page +## Adding new screenshots -### Setup and Preparation -- **usb-remote-services.png** - USB drive setup showing file structure -- **raspberry-pi-setup.png** - Raspberry Pi with connected cables (optional) - -### Process Diagrams -- **migration-flow-diagram.png** - Flow chart showing migration phases -- **network-topology.png** - Network diagram showing Pi, router, speakers -- **data-flow-diagram.png** - How data flows between components - -## Image Requirements - -### Technical Specifications -- **Format**: PNG preferred for screenshots, SVG for diagrams -- **Resolution**: Minimum 1200px width for screenshots -- **File Size**: Keep under 500KB when possible for fast loading -- **Naming**: Use descriptive kebab-case names as shown above - -### Content Guidelines -- **Clean Interface**: Show realistic but clean interface states -- **Consistent Styling**: Use consistent colors and styling across images -- **Readable Text**: Ensure all text in screenshots is legible -- **Example Data**: Use realistic example data (Living Room Speaker, etc.) -- **Status Indicators**: Show clear success/error states with appropriate colors - -### Placeholder Content -Until real screenshots are available, consider: -- **Mockups**: Create simple mockups showing the expected interface -- **Wireframes**: Basic wireframes indicating layout and content -- **Diagrams**: Technical diagrams can be created immediately -- **Text Placeholders**: Use `[Image: Description]` in documentation - -## Creating the Images - -### For Dashboard Screenshots -1. Set up the enhanced SoundTouch service -2. Create sample account and register devices -3. Take screenshots at key points in the migration process -4. Edit for clarity (highlight important elements, add annotations) - -### For Diagrams -1. Use tools like Lucidchart, draw.io, or similar -2. Follow consistent color scheme: - - Blue: SoundTouch Service components - - Green: Healthy/successful states - - Orange: Warning/in-progress states - - Red: Error/problematic states - - Gray: External/third-party components - -### For Physical Setup -1. Take photos of actual hardware setup -2. Show USB drive preparation process -3. Demonstrate network connections if helpful - -## Alternative Text Requirements - -Each image should have appropriate alt text for accessibility: - -```markdown -![Alt text describing the image content](../images/image-name.png) -*Caption: Additional context or explanation* -``` - -## Future Enhancements - -Consider adding: -- **Video Walkthroughs**: Screen recordings of key processes -- **Interactive Demos**: Web-based interactive guides -- **Troubleshooting Screenshots**: Common error states and solutions -- **Mobile Views**: How to access from mobile devices \ No newline at end of file +PNG format, 1200 px or wider. Use descriptive kebab-case names. Update this README when adding files. \ No newline at end of file diff --git a/docs/images/speaker-ap-wifi-setup.png b/docs/images/speaker-ap-wifi-setup.png new file mode 100644 index 0000000..e149d8c Binary files /dev/null and b/docs/images/speaker-ap-wifi-setup.png differ diff --git a/docs/images/ui-devices.png b/docs/images/ui-devices.png new file mode 100644 index 0000000..a04753e Binary files /dev/null and b/docs/images/ui-devices.png differ diff --git a/docs/images/ui-migration.png b/docs/images/ui-migration.png new file mode 100644 index 0000000..2e09a3d Binary files /dev/null and b/docs/images/ui-migration.png differ diff --git a/docs/images/ui-settings.png b/docs/images/ui-settings.png new file mode 100644 index 0000000..10bdfb9 Binary files /dev/null and b/docs/images/ui-settings.png differ diff --git a/docs/images/ui-sync.png b/docs/images/ui-sync.png new file mode 100644 index 0000000..51a2009 Binary files /dev/null and b/docs/images/ui-sync.png differ