Bose-SoundTouch/docs/DEVICE-LOGGING.md

# 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.

For HTTPS / connection-refused debugging (e.g. `Curl 7, http 0`), drop the speaker's loopback chatter so only outbound calls remain visible:
```bash
logread -f | grep -v '127.0.0.1'
```
The speaker generates a steady stream of localhost-to-localhost HTTP traffic between its internal services; filtering it out makes the actual cloud / AfterTouch attempts (the ones that matter when diagnosing redirect or TLS issues) easy to read in real time.

---

## 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](analysis/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)