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:

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:

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.

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:

proxy_hide_header etag;
add_header ETag $upstream_http_etag;

---

References

• SoundCork Issue #112: Enabling Remote Services
• SoundCork Issue #149: Debugging with Systemd/Gunicorn
• ÜberBöse API: Telemetry Documentation
• SoundCork Issue #129: ETag Case-Sensitivity & Preset Sync