From 0186fead6e536edf12bedbc908086b8cccb8fbe6 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Thu, 12 Feb 2026 21:55:02 +0100 Subject: [PATCH] docs: add comprehensive documentation for SoundTouch device redirection, logging, and cloud analysis --- .gitignore | 1 + README.md | 5 + docs/DEVICE-INITIAL-SETUP.md | 80 ++++++++++ docs/DEVICE-LOGGING.md | 107 +++++++++++++ docs/DEVICE-REDIRECT-METHODS.md | 191 ++++++++++++++++++++++++ docs/UNDOCUMENTED-COMMUNITY-FEATURES.md | 45 ++++++ docs/UPSTREAM-URLS-ANALYSIS.md | 84 +++++++++++ 7 files changed, 513 insertions(+) create mode 100644 docs/DEVICE-INITIAL-SETUP.md create mode 100644 docs/DEVICE-LOGGING.md create mode 100644 docs/DEVICE-REDIRECT-METHODS.md create mode 100644 docs/UNDOCUMENTED-COMMUNITY-FEATURES.md create mode 100644 docs/UPSTREAM-URLS-ANALYSIS.md diff --git a/.gitignore b/.gitignore index fae6071..d5ebe10 100644 --- a/.gitignore +++ b/.gitignore @@ -60,6 +60,7 @@ Thumbs.db *.pid *.seed *.pid.lock +.output.txt # Runtime data pids diff --git a/README.md b/README.md index 29fa596..38d75e5 100644 --- a/README.md +++ b/README.md @@ -616,6 +616,11 @@ If you discover new endpoints, features, or improvements through this library, p - 💡 **Feature Requests**: [Start a discussion](https://github.com/gesellix/bose-soundtouch/discussions) - ❓ **Questions**: Check [existing discussions](https://github.com/gesellix/bose-soundtouch/discussions) - 📖 **Documentation**: Browse the [docs/](docs/) directory +- 🔍 **New Discoveries**: See [Undocumented Community Features](docs/UNDOCUMENTED-COMMUNITY-FEATURES.md) for advanced API research +- 🌐 **Upstream Analysis**: [Upstream URLs & Domains](docs/UPSTREAM-URLS-ANALYSIS.md) for cloud dependency research +- 🔧 **Redirection Guide**: [Device Redirect Methods](docs/DEVICE-REDIRECT-METHODS.md) for custom service setup +- 🐣 **Initial Setup**: [Device Initial Setup Variants](docs/DEVICE-INITIAL-SETUP.md) for out-of-the-box configuration +- 📜 **Logging & Debugging**: [Device Logging Guide](docs/DEVICE-LOGGING.md) for accessing system and traffic logs --- diff --git a/docs/DEVICE-INITIAL-SETUP.md b/docs/DEVICE-INITIAL-SETUP.md new file mode 100644 index 0000000..f100aa6 --- /dev/null +++ b/docs/DEVICE-INITIAL-SETUP.md @@ -0,0 +1,80 @@ +# SoundTouch Device Initial Setup Variants + +Based on community research from the **SoundCork** and **ÜberBöse API** projects, as well as analysis of the Stockholm firmware (`firmware/Stockholm/.../setup/`), this document outlines the methods used for the "out-of-the-box" setup of SoundTouch devices. + +## Setup Overview + +Initial setup is the process of connecting a new or factory-reset device to a local Wi-Fi network and a Bose (or custom) account. This is distinct from the "Migration" process (handled by `soundtouch-service`), which redirects an already-configured device to a new server. + +--- + +## 1. Bluetooth Low Energy (BLE) Setup +Used by most modern SoundTouch devices (ST-10, ST-20/30 Series III, SoundTouch 300). + +- **Mechanism**: The SoundTouch app communicates with the device over BLE to exchange Wi-Fi credentials. +- **Protocol**: Internal research refers to this as the **Gabbo** protocol (see `gabbo_setup_bco.js` in firmware). +- **Process**: + 1. Put the device in setup mode (usually by holding the '2' and '-' buttons). + 2. The app discovers the device via BLE. + 3. The app sends the Wi-Fi SSID and Password to the device. + 4. The device connects to Wi-Fi and disables BLE setup. + +--- + +## 2. Access Point (AP) Mode / Web Setup +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). +- **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 `gabbo_wifi` form to select a network and enter credentials. + +--- + +## 3. Wireless Accessory Configuration (WAC) +Specific to Apple iOS devices. + +- **Mechanism**: Uses Apple's MFi/WAC protocol to pass Wi-Fi settings from an iPhone/iPad directly to the device without manual password entry. +- **Status**: Detected automatically by iOS when a new SoundTouch device is in setup mode. + +--- + +## 4. USB Setup (Legacy) +Primarily used for older SoundTouch Series I and II devices or as a last resort. + +- **Mechanism**: Physical connection via Micro-USB to a computer running the SoundTouch Setup application. +- **Process**: + 1. Connect USB cable. + 2. The desktop app communicates via a proprietary HID or Serial-over-USB protocol. + 3. The app pushes Wi-Fi credentials. + 4. References to this exist in the firmware as `lost_USB_connection` and `connect_device` (see `setup_wizard.xml`). + +--- + +## Technical Details: The "Gabbo" Protocol +The Stockholm firmware contains references to a communication layer called **Gabbo**. +- **File**: `setup/js/gabbo_setup_bco.js` +- **Function**: Handles the state machine for Wi-Fi connection, account pairing, and error handling during setup. +- **Relationship**: It appears to be an internal wrapper for the messages sent between the setup client (App or Browser) and the device firmware. + +## Redirection during Setup +While the `soundtouch-service` focuses on migrating existing devices, a truly "clean" setup to a custom service would require: +1. Intercepting the initial account pairing request. +2. Providing a mock "Marge" service that accepts any credentials. +3. Patching the `SoundTouchSdkPrivateCfg.xml` during or immediately after the Wi-Fi connection phase. + +--- + +## Comparison: Initial Setup vs. Migration + +| Feature | Initial Setup | Migration (soundtouch-service) | +| :--- | :--- | :--- | +| **Connectivity** | BLE, AP Mode, USB, WAC | Ethernet/Wi-Fi (existing) | +| **Credentials** | Required (SSID/Pass) | Not required (uses existing) | +| **Access** | Web UI / App protocol | SSH (root) | +| **Primary File** | `setup/index.html` | `SoundTouchSdkPrivateCfg.xml` | +| **Use Case** | Out-of-the-box / Reset | Redirecting active devices | diff --git a/docs/DEVICE-LOGGING.md b/docs/DEVICE-LOGGING.md new file mode 100644 index 0000000..ad0f939 --- /dev/null +++ b/docs/DEVICE-LOGGING.md @@ -0,0 +1,107 @@ +# Device Logging & Troubleshooting + +Accessing logs from SoundTouch devices is critical for debugging custom service integrations and understanding internal device behavior. This document outlines the methods for collecting logs, as discovered by the **SoundCork** and **ÜberBöse API** communities. + +## Log Types + +1. **System Logs**: Internal OS logs (Linux-based) including `dmesg`, `syslog`, and process-specific logs. +2. **Traffic Logs**: Real-time HTTP/HTTPS requests sent by the device to cloud or local services. +3. **Proxy Logs**: Logs generated by the `soundtouch-service` when it acts as a man-in-the-middle. + +--- + +## 1. Accessing System Logs (Requires Root) + +Most SoundTouch devices run a modified Linux distribution. Accessing these logs requires root SSH or Telnet access. + +### Enabling Root Access (Remote Services) + +Community research (SoundCork Issue #112) has identified a "backdoor" to enable developer services: + +1. **USB Method**: + - Format a USB stick to **FAT32**. + - Create an empty file named `remote_services` (no extension) in the root of the USB stick. + - Insert the stick into the SoundTouch device. + - Reboot the device (power cycle). + - On some models, you may need to hold **4** and **Volume -** on the device while powering on to force a USB check. +2. **TAP Command (Legacy)**: + - On older firmware versions, you can connect to port 17000 via Telnet and issue the command: `remote_services on`. + +### Making Root Access Persistent +Once you have logged in as `root` (usually no password or a well-known community password), you can make the access survive reboots without the USB stick: +```bash +touch /mnt/nv/remote_services +/etc/init.d/sshd start +``` + +### Viewing Logs +Once inside via SSH: +- **Kernel Logs**: `dmesg` +- **System Logs**: `cat /var/log/messages` or `tail -f /tmp/soundtouch.log` (paths vary by firmware). +- **Real-time Monitoring**: `logread -f` +- **Process List**: `ps w` + +#### Pro-Tip: Filtered Real-time Monitoring +To focus on cloud service and preset interactions (Marge), use the following command on the device: +```bash +logread -f | grep -Ei '(marge|preset)' +``` +This is particularly useful for debugging preset synchronization and service redirection issues. + +--- + +## 2. Traffic Logging & Interception + +If you cannot or do not want to root the device, you can monitor its outbound traffic by redirecting it to a proxy. + +### Via `soundtouch-service` +The `soundtouch-service` included in this repository includes a built-in proxy. When a device is migrated to use this service, all of its cloud-bound traffic is logged to the service console. + +**Key Traffic to Monitor**: +- `POST /v1/scmudc/{deviceId}`: Real-time telemetry events. +- `GET /marge/...`: Account and streaming configuration requests. +- `POST /streaming/support/power_on`: Boot-time diagnostics. + +### Via Packet Sniffing (Advanced) +If you have a managed switch or a router capable of port mirroring, you can use **Wireshark** or `tcpdump` to capture traffic. +- **Filter**: `tcp port 80 or tcp port 443` +- **Target**: The IP address of your SoundTouch device. + +--- + +## 3. Troubleshooting Common Issues + +### "IsItBose" Validation Failures +If the device fails to connect to your custom service despite correct configuration, it may be failing the internal `IsItBose` regex check. +- **Evidence**: Look for SSL handshake failures or "Unauthorized" errors in your service logs. +- **Solution**: See the [Binary Patching section in DEVICE-REDIRECT-METHODS.md](DEVICE-REDIRECT-METHODS.md#method-3-binary-patching). + +### Disappearing Sources (TuneIn/Local Radio) +If `TUNEIN` or `LOCAL_INTERNET_RADIO` sources disappear after a reboot in an offline environment. +- **Cause**: These sources are validated against the cloud only during the initial boot sequence. +- **Solution**: Ensure your emulated service is reachable and responding correctly to `/streaming/support/power_on` and `/streaming/sourceproviders` during the device's boot-up. + +--- + +## 4. HTTP Protocol Quirks + +### ETag Case-Sensitivity +Research in **SoundCork Issue #129** revealed a significant bug in the SoundTouch device firmware regarding HTTP `ETag` headers. + +- **The Issue**: The device firmware expects the `ETag` header to be exactly title-cased (`ETag`). Many modern web servers or frameworks (like FastAPI/Uvicorn) return headers in all lowercase (`etag`) per HTTP/2 or standard case-insensitive conventions. +- **The Symptom**: If the server returns a lowercase `etag`, the device fails to recognize it. Consequently, the device will never send an `If-None-Match` header in subsequent requests, breaking preset synchronization and efficient caching. +- **The Workaround**: If you are using a custom service, you may need to use a reverse proxy (like **Nginx**) or a middleware to force the header casing to `ETag`. + +**Example Nginx Fix**: +```nginx +proxy_hide_header etag; +add_header ETag $upstream_http_etag; +``` + +--- + +## References +- [SoundCork Issue #112: Enabling Remote Services](https://github.com/deborahgu/soundcork/issues/112) +- [SoundCork Issue #149: Debugging with Systemd/Gunicorn](https://github.com/deborahgu/soundcork/issues/149) +- [ÜberBöse API: Telemetry Documentation](https://github.com/julius-d/ueberboese-api) +- [SoundCork Issue #129: ETag Case-Sensitivity & Preset Sync](https://github.com/deborahgu/soundcork/issues/129) diff --git a/docs/DEVICE-REDIRECT-METHODS.md b/docs/DEVICE-REDIRECT-METHODS.md new file mode 100644 index 0000000..0dcbaed --- /dev/null +++ b/docs/DEVICE-REDIRECT-METHODS.md @@ -0,0 +1,191 @@ +# Device Redirect Methods & Custom Service Setup + +To enable offline operation or use custom services like **SoundCork** or **ÜberBöse API**, SoundTouch devices must be redirected from Bose's official cloud endpoints to a local or custom server. This document outlines the three known methods to achieve this, gathered from community reverse-engineering efforts in the **SoundCork** and **ÜberBöse API** projects. + +## Overview of Redirection Targets + +SoundTouch devices primarily communicate with the following domains: +- `streaming.bose.com`: Marge (Account and streaming services) +- `updates.bose.com`: Software updates +- `stats.bose.com`: Telemetry and analytics +- `bmx.bose.com`: Bose Media eXchange registry + +--- + +## Method 1: XML Configuration Modification (Recommended) + +The most robust and granular method involves modifying the device's private configuration file. This is the primary method used by **SoundCork**'s migration logic to redirect devices to a local service instance. + +### Technical Details +- **File Path**: `/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml` +- **Mechanism**: The device firmware reads this XML file at boot to determine service URLs. +- **Fields to Modify**: + - ``: Redirects account/streaming calls. + - ``: Redirects telemetry. + - ``: Redirects update checks. + - ``: Redirects service discovery. + +### Implementation +Requires SSH access to the device. +```xml + + http://192.168.1.10:8000/marge + http://192.168.1.10:8000 + http://192.168.1.10:8000/updates/soundtouch + http://192.168.1.10:8000/bmx/registry/v1/services + +``` + +### Pros & Cons +| Pros | Cons | +| :--- | :--- | +| **Granular Control**: Redirect specific services while leaving others (e.g., updates) intact. | **Requires SSH**: Must have root/SSH access to the device. | +| **Persistent**: Survives software updates (usually). | **Syntax Sensitive**: Errors in XML can cause boot issues or service failures. | +| **Native**: Uses the device's built-in configuration mechanism. | | + +--- + +## Method 2: `/etc/hosts` DNS Override + +This method uses the standard Linux hosts file to redirect traffic at the network level within the device. It is often used as a quick alternative in the **ÜberBöse API** community for global redirection. + +### Technical Details +- **File Path**: `/etc/hosts` +- **Mechanism**: Overrides DNS resolution for Bose domains to point to a local IP. + +### Implementation +Requires SSH access. Add entries for the target domains: +```text +192.168.1.10 streaming.bose.com +192.168.1.10 updates.bose.com +192.168.1.10 stats.bose.com +``` + +### Pros & Cons +| Pros | Cons | +| :--- | :--- | +| **Simple**: Easy to understand and implement. | **Requires SSH**: Must have root access. | +| **Universal**: Affects all processes on the device attempting to reach those domains. | **HTTPS Issues**: Redirecting HTTPS domains to a local IP will cause SSL certificate errors unless the device is patched to skip verification or trust a custom CA. | +| | **Brittle**: Some firmware versions may overwrite `/etc/hosts` on reboot. | + +--- + +## Method 3: Binary Patching + +A low-level approach where the actual compiled binaries (e.g., `BoseApp`, `IoT`) are modified to change hardcoded URL patterns. Research into these patterns has been documented in both **SoundCork** (Issue #128) and **ÜberBöse API** research. + +### Technical Details +- **Target Binaries**: `/opt/Bose/BoseApp`, `/opt/Bose/IoT`, `/opt/Bose/lib/libBmxAccountHsm.so` +- **Mechanism**: + - **URL Replacement**: Using a hex editor to search for string patterns like `https://streaming.bose.com` and replacing them with a custom URL of the **exact same length**. + - **Regex Neutralization**: Some libraries (like `libBmxAccountHsm.so`) perform a validation check called `IsItBose` using a hardcoded regex. This regex prevents the device from connecting to non-Bose domains even if the URL is changed in the configuration. + +#### The `IsItBose` Regex Patch +Research in the **SoundCork** community (Issue #62) identified a specific regex in `libBmxAccountHsm.so` that enforces Bose/Apigee domain usage: +`^https:\/\/bose-[a-zA-Z0-9\.\_\-\$\%]\+\.apigee\.net\/` + +By patching this regex to be more "lax", the device can be made to accept any custom domain. + +**Example Patch**: +Using `sed` to replace the strict regex with a broad match while preserving the original string length: +```bash +sed "s#\^https:....bose.\+apigee..net..#http[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]*#g" \ +< libBmxAccountHsm.so.orig > libBmxAccountHsm.so.patched +``` + +### Implementation +1. Copy the target binary or library from the device to a PC. +2. Use a hex editor or `sed` to locate and patch the URL strings or regex patterns. +3. Copy the patched file back to the device. +4. Restore execution permissions and reboot. + +### Pros & Cons +| Pros | Cons | +| :--- | :--- | +| **Bypass Config**: Works even if the firmware ignores XML settings. | **High Risk**: Modifying binaries can lead to permanent bricks or boot loops. | +| **Hardcoded Redirects**: Can catch URLs that aren't exposed in configuration files. | **Length Constraint**: Custom URLs must fit within the space of the original strings. | +| | **Firmware Specific**: Patches must be reapplied after every software update. | +| | **Complexity**: Requires understanding of binary structures and potential checksums. | + +--- + +## Comparison & Usage Strategy + +### Summary Table + +| Method | Primary Use Case | Ease | Safety | Persistence | Granularity | +| :--- | :--- | :---: | :---: | :---: | :---: | +| **XML Config** | Logical service redirection | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | +| **`/etc/hosts`** | Quick global DNS override | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ | +| **Binary Patch** | Bypassing hardcoded checks | ⭐ | ⭐ | ⭐ | ⭐⭐⭐ | + +--- + +## Combining Methods: When is one not enough? + +A common question is whether these methods can be used in isolation or if they must be combined. The answer depends on your specific firmware version and the target service. + +### Scenario A: XML Config Only (The Ideal Case) +If your firmware does not strictly enforce the `IsItBose` check for the specific URLs you are changing, **Method 1 (XML)** is sufficient. This is the cleanest approach and is used by the `soundtouch-service` migration tool. + +### Scenario B: XML Config + Binary Patching (The "Locked" Case) +On some newer firmware versions, even if you change the `` in the XML to `http://192.168.1.10`, the internal library (`libBmxAccountHsm.so`) will validate the string against the hardcoded Bose regex. +* **Symptom**: The device ignores the XML setting or fails to connect despite the correct URL being present. +* **Solution**: You **must** apply the **Binary Patch (Method 3)** to neutralize the `IsItBose` check *in addition* to the XML change. + +### Scenario C: `/etc/hosts` + Custom CA (The "Clean Deep Redirect") +If you use `/etc/hosts` to point `streaming.bose.com` to a local IP and want to avoid binary patching. +* **Requirement 1**: Your local server must handle HTTPS (port 443). +* **Requirement 2**: You must inject your Root CA into the device's trust store (see [Option 1](#option-1-custom-ca-certificate-recommended) below). +* **Benefit**: Maintains system integrity (no binary changes) and full end-to-end encryption. + +### Scenario D: `/etc/hosts` + Binary Patching (The "Legacy Deep Redirect") +If you cannot or do not want to manage certificates, but still use `/etc/hosts` for DNS redirection. +* **Requirement 1**: Your local server must handle HTTPS (port 443). +* **Requirement 2**: Since the certificate will be invalid (mismatched domain/CA), you must patch the binary to **skip SSL verification** (see [Option 2](#option-2-ssl-verification-bypass) below). +* **Risk**: Less secure and higher risk of bricking due to binary modification. + +### Scenario E: The Triple-Threat (Total Control) +For developers creating a completely isolated "dark" environment (no internet at all): +1. **XML**: Point all URLs to local services. +2. **Binary Patch**: Neutralize `IsItBose` to allow non-Bose domains/IPs. +3. **`/etc/hosts`**: Redirect hardcoded domains that aren't exposed in the XML (like analytics or NTP) to prevent leakage to the real Bose cloud. + +--- + +## Handling HTTPS & SSL Certificates + +When redirecting HTTPS traffic to a custom service, SoundTouch devices will fail the SSL handshake because they do not trust your local server's certificate. + +### Option 1: Custom CA Certificate (Recommended) + +As suggested by community members, you can configure the device to trust your own Root CA. This allows for secure HTTPS communication without patching binaries. + +**Technical Steps**: +1. **Generate a Root CA** and issue a certificate for the target domain (e.g., `streaming.bose.com`). +2. **SSH into the device** and copy your `rootCA.crt` to `/usr/share/ca-certificates/custom/`. +3. **Update the Trust Store**: + - **Method A (Append to Bundle)**: `cat /usr/share/ca-certificates/custom/rootCA.crt >> /etc/pki/tls/certs/ca-bundle.crt` + - **Method B (Symlinks)**: Add the certificate to `/etc/ssl/certs/` and create a hash symlink using `c_rehash` (if available) or manual mapping. + +**Pros & Cons**: +| Pros | Cons | +| :--- | :--- | +| **Secure**: Maintains end-to-end encryption. | **Requires SSH**: Must have root access to modify the trust store. | +| **Clean**: No binary patching required for SSL bypass. | **Update Risk**: Firmware updates might overwrite the `ca-bundle.crt`. | + +### Option 2: SSL Verification Bypass + +If you cannot or do not want to manage certificates, you can patch the binary to skip certificate verification. + +**Target**: `libBmxAccountHsm.so` or `BoseApp` +**Mechanism**: Locating the SSL verification function (often in the internal curl-based or openssl-based logic) and forcing it to return "Success" regardless of the certificate status. + +--- + +## Recommendation + +1. **Start with Method 1 (XML Modification)**. It is the least invasive and most likely to work across different models. +2. **Verify connectivity**. If the device refuses to connect to your custom endpoint, check logs for "IsItBose" or validation failures. +3. **Apply Method 3 (Binary Patching)** only if Method 1 is being actively blocked by the firmware's validation logic. +4. **Avoid Method 2 (`/etc/hosts`)** unless you are prepared to handle SSL certificate complexities or are performing quick temporary tests. diff --git a/docs/UNDOCUMENTED-COMMUNITY-FEATURES.md b/docs/UNDOCUMENTED-COMMUNITY-FEATURES.md new file mode 100644 index 0000000..6655b37 --- /dev/null +++ b/docs/UNDOCUMENTED-COMMUNITY-FEATURES.md @@ -0,0 +1,45 @@ +# Undocumented Community Features & API Discoveries +This document captures advanced API endpoints and device behaviors discovered by the SoundTouch community through reverse engineering projects like **SoundCork** and **ÜberBöse API**. These features are not documented in the official Bose SoundTouch Web API v1.0 but are crucial for full device emulation and offline operation. +## Cloud Emulation (Marge/BMX) Discoveries +While the local `/8090` API is well-documented, the cloud-side service emulation reveals deeper device integration points. +### 1. Stereo Pairing & Cloud-Side Grouping +SoundCork has pioneered the emulation of "Marge" group endpoints, which differ from the local `/getGroup` API. These are primarily used for persistent configurations like **Stereo Pairs** (e.g., two ST-10s). +- **GET** `/marge/streaming/account/{account}/device/{device}/group` + Returns `` if ungrouped, or full group configuration for stereo pairs. +- **POST** `/marge/streaming/account/{account}/group` + Creates a new group (returns a 7-digit group ID). Used for initial pairing. +- **DELETE** `/marge/streaming/account/{account}/group/{group}` + Dissolves a group configuration. +### 2. Device Analytics & Event Reporting +Devices report real-time telemetry to the cloud. Intercepting these provides a window into device usage without polling. +- **Endpoint**: `POST /v1/scmudc/{deviceId}` +- **Function**: Submits event data including `play-state-changed`, `preset-pressed`, `power-pressed`, `source-state-changed`, and `art-changed` (Metadata updates). This endpoint was first extensively documented in the **ÜberBöse API** specification. +### 3. Power-On Lifecycle +When a SoundTouch device boots or "powers on" (distinct from waking from standby), it contacts specific support endpoints. +- **Endpoint**: `POST /streaming/support/power_on` +- **Behavior**: Reports device serial number, IP address, and diagnostic data. +- **Critical Finding**: SoundTouch devices fetch `TUNEIN` and `LOCAL_INTERNET_RADIO` source availability from the cloud **ONLY at boot time**. If the cloud is unreachable during a hard reboot (power cycle), these sources will disappear from the device's `/sources` list and become unavailable, even if the local API is working. This behavior was analyzed and reported by the **ÜberBöse API** project (Issue #3). +### 4. OAuth & Service Tokens +Integration with music services (Spotify, Pandora, etc.) involves specific token management endpoints. +- **Endpoint**: `POST /oauth/device/{deviceId}/music/musicprovider/{providerId}/token/{tokenType}` +- **Usage**: Used to refresh or validate session tokens for cloud-based music providers. +## Community-Driven Extensions +The community is working on extending SoundTouch functionality beyond its original design. +### 1. Radio-Browser.info Integration +There is an active effort to add `radio-browser.info` as a native `sourceprovider`. This would allow devices to browse a massive directory of thousands of stations without relying on the TuneIn cloud service. +- **Status**: Research phase in SoundCork (Issue #150). +- **Implementation**: Requires adding a new source provider entry in the emulated `/streaming/sourceproviders` response. +### 2. Stockholm Internal App Analysis +Deep analysis of the Stockholm (device firmware) internal web application reveals a set of internal AJAX/XML calls used by the device's own control interface. +- **Internal Domains**: `Marge` (XML-based) and `Gabbo` (App-send based). +- **Reference**: See SoundCork Issue #128 for a comprehensive list of internal JS controllers and their functions. +### 3. ETag Case-Sensitivity Bug +The SoundTouch device firmware has a case-sensitivity bug regarding HTTP `ETag` headers. +- **Discovery**: SoundCork Issue #129. +- **Detail**: The device expects the `ETag` header to be exactly title-cased. If a server returns `etag` (lowercase), the device fails to use it for `If-None-Match` requests, breaking efficient preset synchronization. +- **Solution**: Force title-casing of the header via a reverse proxy like Nginx or mitmproxy. +## References +- [SoundCork GitHub Repo](https://github.com/deborahgu/soundcork) +- [ÜberBöse API Spec](https://github.com/julius-d/ueberboese-api) +- [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) +- [IsItBose Regex Research](https://github.com/deborahgu/soundcork/issues/62#issuecomment-3610563908) diff --git a/docs/UPSTREAM-URLS-ANALYSIS.md b/docs/UPSTREAM-URLS-ANALYSIS.md new file mode 100644 index 0000000..94ecb70 --- /dev/null +++ b/docs/UPSTREAM-URLS-ANALYSIS.md @@ -0,0 +1,84 @@ +# Upstream URLs & Domains Analysis + +This document provides a comprehensive overview of the upstream Bose cloud services and domains that SoundTouch devices communicate with. These details were gathered from firmware analysis of ST10/ST20 devices, binary string extraction, and community research from the **SoundCork** project (Issue #128). + +## Core Service Domains + +SoundTouch devices use a set of primary domains for their operation. These are often configurable via the `SoundTouchSdkPrivateCfg.xml` file. + +| Service | Primary Domain | Purpose | +| :--- | :--- | :--- | +| **Marge** | `streaming.bose.com` | Account management, streaming source providers, and preset sync. | +| **BMX Registry** | `content.api.bose.io` | Bose Media eXchange service discovery and registry. | +| **Stats/Analytics** | `events.api.bosecm.com` | Telemetry, device events, and usage statistics. | +| **Software Update** | `worldwide.bose.com` | Firmware update checks and downloads (path: `/updates/soundtouch`). | +| **Voice/Alexa** | `voice.api.bose.io` | Token management for Amazon Alexa integration. | + +## Internal & Development Domains + +Analysis of device binaries (`BoseApp`, `IoT`) and community findings revealed several internal, integration, and development domains used by Bose. + +### Marge & Auth Proxies +- `bose-test.apigee.net/margeproxy` (Integration/Test proxy) +- `bose-test.apigee.net/margeproxyefe` +- `streamingstg.bose.com` (Staging) +- `streamingintoauth.bose.com` (Internal Auth) +- `streamingefeintoauth.bose.com` (Internal EFE Auth) +- `streamingefeint.bose.com` + +### BMX & Content Registry +- `test.content.api.bose.io` +- `content.api.bose.io/bmx/registry/v1/services` +- `test.content.api.bose.io/bmx/int-registry/v1/services` +- `test.content.api.bose.io/bmx/efe-registry/v1/services` + +### Stats & Analytics +- `eventsdev.api.bosecm.com` +- `eventsefe.api.bosecm.com` +- `eventsdev.bosecm.com` + +### Software Updates +- `worldwide.bose.com/updates/soundtouch-int` +- `worldwide.bose.com/updates/soundtouch-efe` + +## Third-Party Services + +Devices also communicate directly with third-party providers for specific features. + +- **Pandora**: + - `device-tuner.pandora.com` + - `device-tuner-beta.savagebeast.com` +- **Amazon AVS**: + - `avs.na.amazonalexa.com` + +## Hardcoded Validation (IsItBose) + +As documented in [DEVICE-REDIRECT-METHODS.md](DEVICE-REDIRECT-METHODS.md#method-3-binary-patching), the `libBmxAccountHsm.so` library contains a hardcoded regex to validate these URLs: + +`^https:\/\/bose-[a-zA-Z0-9\.\_\-\$\%]\+\.apigee\.net\/` + +This regex ensures that certain critical services must reside on the `apigee.net` domain under a `bose-` prefix, unless patched. + +## Configuration File References + +On-device, these URLs are primarily managed in the following files: + +1. **`/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml`**: + * `` + * `` + * `` + * `` +2. **`/opt/Bose/etc/Voice.xml`**: + * `` (Points to `voice.api.bose.io`) +3. **`/opt/Bose/etc/HandCraftedWebServer-SoundTouch.xml`**: + * Contains internal local API mapping. + +## Conclusion for Offline Operation + +To achieve full offline operation or redirection to a custom service (like `soundtouch-service`), all of the above domains must either be redirected via DNS (`/etc/hosts`) or updated in the device's XML configuration files. For domains not exposed in XML, binary patching or DNS-level redirection is the only option. + +--- + +## References +- [SoundCork Issue #128: Endpoint and URL Listing](https://github.com/deborahgu/soundcork/issues/128#issuecomment-3892933337) +- [Bose SoundTouch Web API v1.0 Specification](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf)