mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-18 08:36:13 +00:00
Implement /requestToken API and fix clock time display
Major Features: • Implement complete /requestToken API endpoint for bearer token generation • Fix clock time parsing and display with comprehensive time information • Add comprehensive API documentation for 103 discovered endpoints /requestToken Implementation: • Add BearerToken model with full XML marshaling support • Add RequestToken() client method with proper error handling • Add 'soundtouch-cli token request' CLI command with security features • Token validation, formatting, and secure display (truncated for security) • Comprehensive unit tests and integration tests • Support for Authorization header formatting and raw token extraction Clock Time Fixes: • Fix ClockTime model to match actual device XML response structure • Add LocalTime component for nested time details • Support for utcTime, timeFormat, brightness, clockError attributes • Enhanced CLI display with comprehensive time information • Fixed month conversion (device uses 0-11, Go uses 1-12) Documentation Enhancements: • Add comprehensive /supportedURLs endpoint analysis (103 endpoints discovered) • Create detailed unimplemented endpoints documentation with examples • Update API coverage from 34% implemented to full endpoint catalog • Add SoundTouch End of Life notice with May 6, 2026 details • Enhanced endpoint descriptions with real device response examples Security: • All tests use generic token examples (no real tokens exposed) • Integration tests validate token properties without exposing values • Secure token display with truncation in CLI and string representations • Environment variable based testing for real devices Testing: • 15+ new test functions with comprehensive coverage • Real device validation on 192.168.178.28 and 192.168.178.35 • Mock server tests and XML marshaling validation • Integration tests with SOUNDTOUCH_TEST_HOST environment variable CLI Enhancements: • Enhanced clock time display with local time details and device settings • New token management commands with usage instructions • Improved error handling and user-friendly output formatting
This commit is contained in:
Tobias Gesellchen
+302
-11
@@ -58,6 +58,8 @@ Retrieves information about the currently playing music.
|
||||
### POST /key ✅ **Implemented**
|
||||
Sends key commands to the device.
|
||||
|
||||
**IMPORTANT - Key values, state, and sender attributes are CaSe-SeNsItIvE!**
|
||||
|
||||
**Important**: Proper key simulation requires sending both press and release states:
|
||||
|
||||
**Request XML (Press + Release):**
|
||||
@@ -66,6 +68,11 @@ Sends key commands to the device.
|
||||
<key state="release" sender="Gabbo">KEY_NAME</key>
|
||||
```
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<status>/key</status>
|
||||
```
|
||||
|
||||
**Available Keys:**
|
||||
|
||||
**Playback Controls:**
|
||||
@@ -74,11 +81,14 @@ Sends key commands to the device.
|
||||
- `STOP` - Stop current playback
|
||||
- `PREV_TRACK` - Go to previous track
|
||||
- `NEXT_TRACK` - Go to next track
|
||||
- `PLAY_PAUSE` - Toggles between play and pause for currently playing media
|
||||
|
||||
**Rating and Bookmark Controls:**
|
||||
- `THUMBS_UP` - Rate current content positively (Pandora, etc.)
|
||||
- `THUMBS_DOWN` - Rate current content negatively
|
||||
- `THUMBS_UP` - Rate current content positively (Pandora, Spotify, etc.)
|
||||
- `THUMBS_DOWN` - Rate current content negatively (Pandora, Spotify, etc.)
|
||||
- `BOOKMARK` - Bookmark current content
|
||||
- `ADD_FAVORITE` - Adds currently playing media to device favorites (Pandora, Spotify, etc.)
|
||||
- `REMOVE_FAVORITE` - Removes currently playing media from device favorites (Pandora, Spotify, etc.)
|
||||
|
||||
**Power and System Controls:**
|
||||
- `POWER` - Toggle device power state
|
||||
@@ -103,6 +113,19 @@ Sends key commands to the device.
|
||||
- `REPEAT_ONE` - Repeat current track
|
||||
- `REPEAT_ALL` - Repeat all tracks in playlist
|
||||
|
||||
**State Values:**
|
||||
- `press` - Indicates the key is pressed
|
||||
- `release` - Indicates the key is released
|
||||
- `repeat` - Indicates the key is repeated
|
||||
|
||||
**Sender Values:**
|
||||
- `Gabbo` - Default value for standard SoundTouch remote control device
|
||||
- `IrRemote` - IR remote control device
|
||||
- `Console` - Console device
|
||||
- `LightswitchRemote` - Lightswitch remote device
|
||||
- `BoselinkRemote` - Boselink remote device
|
||||
- `Etap` - Etap device
|
||||
|
||||
## Volume Control
|
||||
|
||||
### GET /volume ✅ **Implemented**
|
||||
@@ -139,13 +162,15 @@ Retrieves the current bass settings.
|
||||
```
|
||||
|
||||
### POST /bass ✅ **Implemented**
|
||||
Sets the bass settings (-9 to +9).
|
||||
Sets the bass settings. Range varies by device - check `/bassCapabilities` for supported range.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<bass>0</bass>
|
||||
```
|
||||
|
||||
**Note**: Value must be within the range specified by `bassMin` and `bassMax` from `/bassCapabilities` service.
|
||||
|
||||
## Source Management
|
||||
|
||||
### GET /sources ✅ **Implemented**
|
||||
@@ -221,20 +246,58 @@ Retrieves multiroom zone information.
|
||||
Configures multiroom zones.
|
||||
|
||||
### GET /balance ✅ **Implemented**
|
||||
Retrieves balance settings (stereo devices).
|
||||
Retrieves balance settings (stereo devices). Only works if device is configured as part of a stereo pair.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<balance deviceID="...">
|
||||
<balanceAvailable>true</balanceAvailable>
|
||||
<balanceMin>-7</balanceMin>
|
||||
<balanceMax>7</balanceMax>
|
||||
<balanceDefault>0</balanceDefault>
|
||||
<targetBalance>0</targetBalance>
|
||||
<actualBalance>0</actualBalance>
|
||||
</balance>
|
||||
```
|
||||
|
||||
### POST /balance ✅ **Implemented**
|
||||
Sets balance settings.
|
||||
Sets balance settings. Value must be within the range specified by `balanceMin` and `balanceMax`.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<balance>
|
||||
<targetBalance>0</targetBalance>
|
||||
</balance>
|
||||
```
|
||||
|
||||
**Range Examples:**
|
||||
- `-7` = left speaker
|
||||
- `0` = centered
|
||||
- `7` = right speaker
|
||||
|
||||
### GET /clockTime ✅ **Implemented**
|
||||
Retrieves the device time.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<clockTime utcTime="1701824606" cueMusic="0" timeFormat="TIME_FORMAT_12HOUR_ID" brightness="70" clockError="0" utcSyncTime="1701820350">
|
||||
<localTime year="2023" month="11" dayOfMonth="5" dayOfWeek="2" hour="19" minute="3" second="26" />
|
||||
</clockTime>
|
||||
```
|
||||
|
||||
### POST /clockTime ✅ **Implemented**
|
||||
Sets the device time.
|
||||
|
||||
### GET /clockDisplay ✅ **Implemented**
|
||||
Retrieves clock display settings.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<clockDisplay>
|
||||
<clockConfig timezoneInfo="America/Chicago" userEnable="false" timeFormat="TIME_FORMAT_12HOUR_ID" userOffsetMinute="0" brightnessLevel="70" userUtcTime="0" />
|
||||
</clockDisplay>
|
||||
```
|
||||
|
||||
### POST /clockDisplay ✅ **Implemented**
|
||||
Configures the clock display.
|
||||
|
||||
@@ -254,22 +317,39 @@ Establishes a persistent connection for live updates.
|
||||
### GET /networkInfo ✅ **Implemented**
|
||||
Retrieves network information.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<networkInfo wifiProfileCount="1">
|
||||
<interfaces>
|
||||
<interface type="WIFI_INTERFACE" name="wlan0" macAddress="..." ipAddress="192.168.1.131" ssid="network_name" frequencyKHz="2452000" state="NETWORK_WIFI_CONNECTED" signal="MARGINAL_SIGNAL" mode="STATION" />
|
||||
<interface type="WIFI_INTERFACE" name="wlan1" macAddress="..." state="NETWORK_WIFI_DISCONNECTED" />
|
||||
</interfaces>
|
||||
</networkInfo>
|
||||
```
|
||||
|
||||
### GET /capabilities ✅ **Implemented**
|
||||
Retrieves device capabilities.
|
||||
|
||||
### GET /name 🔍 **Extra**
|
||||
### GET /name 🔍 **Extra**
|
||||
Retrieves the device name.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<name>SoundTouch 10</name>
|
||||
```
|
||||
|
||||
**Note**: Official API only documents `POST /name` for setting device name. Our GET implementation appears to be an undocumented extension.
|
||||
|
||||
### POST /name ✅ **Implemented**
|
||||
Sets the device name via `SetName()` method.
|
||||
Sets the device name via `SetName()` method. If name is changed, the change will be detected immediately via ZeroConf services.
|
||||
|
||||
**Official Request Format:**
|
||||
**Request XML:**
|
||||
```xml
|
||||
<name>$STRING</name>
|
||||
<name>SoundTouch Living Room</name>
|
||||
```
|
||||
|
||||
**Response**: Returns same structure as `/info` endpoint with updated name.
|
||||
|
||||
### GET /bassCapabilities ✅ **Implemented**
|
||||
Checks if bass customization is supported on the device.
|
||||
|
||||
@@ -284,9 +364,18 @@ Checks if bass customization is supported on the device.
|
||||
```
|
||||
|
||||
### GET /trackInfo ✅ **Implemented**
|
||||
Gets track information (duplicate of `/now_playing` per official API).
|
||||
Gets extended track information for currently playing music service media.
|
||||
|
||||
**Status**: Fully implemented but times out on SoundTouch 10 & 20 test devices (AllegroWebserver timeout). May work on other SoundTouch models or firmware versions. Use `/now_playing` endpoint as reliable alternative.
|
||||
**Response XML:**
|
||||
```xml
|
||||
<trackInfo deviceID="...">Track Name;extended details;separated by semicolons;</trackInfo>
|
||||
```
|
||||
|
||||
**Important Notes:**
|
||||
- Only returns information if currently playing content is from a music service (PANDORA, SPOTIFY, etc.)
|
||||
- If playing non-music-service content (AIRPLAY, STORED_MUSIC, etc.), service becomes unresponsive for ~30 seconds until timeout
|
||||
- Extended details are delimited by semicolons (e.g., "Who You Are To Me (feat. Lady A);vocal duets;upbeat lyrics;")
|
||||
- Times out on some SoundTouch models - use `/now_playing` as reliable alternative
|
||||
|
||||
**Implementation**: Available via `GetTrackInfo()` method. Consider using `GetNowPlaying()` method for guaranteed compatibility.
|
||||
|
||||
@@ -342,6 +431,26 @@ These endpoints work with real hardware but are NOT in official API v1.0:
|
||||
|
||||
**Note**: Not documented in official API v1.0 but works with real devices.
|
||||
|
||||
### Token Management ✅ **Implemented**
|
||||
|
||||
#### GET /requestToken ✅ **Implemented**
|
||||
Generates a new bearer token from the device for authentication purposes.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<bearertoken value="Bearer vUApzBVT6Lh0nw1xVu/plr1UDRNdMYMEpe0cStm4wCH5mWSjrrtORnGGirMn3pspkJ8mNR1MFh/J4OcsbEikMplcDGJVeuZOnDPAskQALvDBCF0PW74qXRms2k1AfLJ/" />
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
- Tokens are generated per request and may have expiration times
|
||||
- Use for HTTP Authorization headers: `Authorization: Bearer <token>`
|
||||
- Store tokens securely and treat as passwords
|
||||
- Request new tokens when needed rather than reusing old ones
|
||||
|
||||
**Implementation**: Available via `RequestToken()` method
|
||||
|
||||
**Testing**: Integration tests available - run with `SOUNDTOUCH_TEST_HOST=<device-ip> go test ./pkg/client -run TestRequestToken_Integration` to validate real device token generation without exposing token values
|
||||
|
||||
## Coverage Summary
|
||||
|
||||
### Official API Coverage: 100%
|
||||
@@ -351,6 +460,13 @@ These endpoints work with real hardware but are NOT in official API v1.0:
|
||||
- **Device-Dependent**: 1 (5%) - GET /trackInfo times out on some models
|
||||
- **Excluded**: 1 endpoint (POST /presets officially N/A)
|
||||
|
||||
### Real Device Discovery: 103 Endpoints Found
|
||||
- **Total Discovered Endpoints**: 103 (from /supportedURLs)
|
||||
- **Currently Implemented**: ~35 (34%)
|
||||
- **Core Functionality**: 100% implemented
|
||||
- **Extended Features**: Many undocumented endpoints available
|
||||
- **Implementation Focus**: User-facing and essential system endpoints prioritized
|
||||
|
||||
### Feature Coverage: 100%
|
||||
- ✅ All available user functionality implemented
|
||||
- ✅ All functional device operations supported
|
||||
@@ -358,6 +474,7 @@ These endpoints work with real hardware but are NOT in official API v1.0:
|
||||
- ✅ Full multiroom capabilities
|
||||
- ✅ Complete advanced audio controls (where supported by device)
|
||||
- 🔍 Additional features beyond official specification
|
||||
- 🔍 68 additional undocumented endpoints discovered but not yet implemented
|
||||
|
||||
|
||||
## Error Handling
|
||||
@@ -407,6 +524,180 @@ func SendKey(deviceIP string, key string) error {
|
||||
4. **Rate Limiting**: No explicit limits documented, but moderate usage recommended
|
||||
5. **Device Discovery**: Devices can be found via UPnP on the local network
|
||||
|
||||
## Comprehensive Endpoint Discovery
|
||||
|
||||
### GET /supportedURLs ✅ **Implemented**
|
||||
Retrieves all supported endpoints for the specific device.
|
||||
|
||||
**Response XML Structure:**
|
||||
```xml
|
||||
<supportedURLs deviceID="...">
|
||||
<URL location="/info" />
|
||||
<URL location="/capabilities" />
|
||||
<!-- ... additional endpoints ... -->
|
||||
</supportedURLs>
|
||||
```
|
||||
|
||||
**Complete Endpoint List** (103 endpoints discovered from real devices):
|
||||
|
||||
**Core Device Information:**
|
||||
- `/info` ✅ - Device information
|
||||
- `/capabilities` ✅ - Device capabilities
|
||||
- `/supportedURLs` ✅ - This endpoint (self-reference)
|
||||
- `/networkInfo` ✅ - Network configuration
|
||||
- `/name` ✅ - Device name management
|
||||
- `/netStats` - Network statistics
|
||||
- `/powerManagement` - Power state and battery information
|
||||
- `/soundTouchConfigurationStatus` - Device configuration status
|
||||
|
||||
**Playback and Media Control:**
|
||||
- `/nowPlaying` ✅ - Current playback status
|
||||
- `/now_playing` ✅ - Alternative current playback endpoint
|
||||
- `/nowSelection` - Current selection details
|
||||
- `/key` ✅ - Send key commands
|
||||
- `/select` ✅ - Select source/content
|
||||
- `/playbackRequest` - Advanced playback requests
|
||||
- `/userPlayControl` - User play control interface (PAUSE_CONTROL, PLAY_CONTROL, etc.)
|
||||
- `/userTrackControl` - User track control interface
|
||||
- `/userRating` - User rating interface (UP/DOWN for Pandora, etc.)
|
||||
|
||||
**Volume and Audio:**
|
||||
- `/volume` ✅ - Volume control
|
||||
- `/bass` ✅ - Bass settings
|
||||
- `/bassCapabilities` ✅ - Bass capability info
|
||||
- `/balance` ✅ - Stereo balance
|
||||
- `/DSPMonoStereo` - DSP mono/stereo settings
|
||||
|
||||
**Sources and Content:**
|
||||
- `/sources` ✅ - Available sources
|
||||
- `/sourceDiscoveryStatus` - Source discovery status
|
||||
- `/nameSource` - Name/rename sources
|
||||
- `/selectLastSource` - Select last used source
|
||||
- `/selectLastWiFiSource` - Select last WiFi source
|
||||
- `/selectLastSoundTouchSource` - Select last SoundTouch source
|
||||
- `/selectLocalSource` - Select local source
|
||||
|
||||
**Presets and Favorites:**
|
||||
- `/presets` ✅ - Preset management
|
||||
- `/storePreset` - Store new preset (max 6 presets)
|
||||
- `/removePreset` - Remove existing preset
|
||||
- `/selectPreset` - Select preset by ID
|
||||
- `/recents` ✅ - Recently played content
|
||||
- `/bookmark` - Bookmark current content
|
||||
|
||||
**Music Services:**
|
||||
- `/setMusicServiceAccount` - Configure music service account (Pandora, Spotify, etc.)
|
||||
- `/setMusicServiceOAuthAccount` - OAuth account setup
|
||||
- `/removeMusicServiceAccount` - Remove music service account
|
||||
- `/serviceAvailability` - Check service availability
|
||||
- `/introspect` - Get introspect data for specific sources
|
||||
|
||||
**Station Management (Radio/Streaming):**
|
||||
- `/searchStation` - Search for stations (tested with Pandora)
|
||||
- `/addStation` - Add station to favorites (tested with Pandora)
|
||||
- `/removeStation` - Remove station from favorites (tested with Pandora)
|
||||
- `/genreStations` - Browse stations by genre
|
||||
- `/stationInfo` - Station information
|
||||
- `/trackInfo` ✅ - Extended track information with semicolon-delimited details
|
||||
|
||||
**Zone and Multiroom:**
|
||||
- `/getZone` ✅ - Get zone configuration
|
||||
- `/setZone` ✅ - Set zone configuration
|
||||
- `/addZoneSlave` ✅ - Add device to zone
|
||||
- `/removeZoneSlave` ✅ - Remove device from zone
|
||||
- `/addGroup` - Add to speaker group
|
||||
- `/removeGroup` - Remove from speaker group
|
||||
- `/getGroup` - Get group configuration
|
||||
- `/updateGroup` - Update group settings
|
||||
|
||||
**Clock and Display:**
|
||||
- `/clockDisplay` ✅ - Clock display settings
|
||||
- `/clockTime` ✅ - Device time management
|
||||
|
||||
**System and Configuration:**
|
||||
- `/powerManagement` - Power management settings
|
||||
- `/standby` - Standby mode control
|
||||
- `/lowPowerStandby` - Low power standby mode
|
||||
- `/systemtimeout` - System timeout settings
|
||||
- `/powersaving` - Power saving configuration
|
||||
- `/userActivity` - User activity tracking
|
||||
- `/language` - Language settings
|
||||
- `/speaker` - Speaker configuration
|
||||
|
||||
**Network and Connectivity:**
|
||||
- `/performWirelessSiteSurvey` - WiFi site survey (returns detected networks with signal strength)
|
||||
- `/addWirelessProfile` - Add WiFi profile (supports various security types)
|
||||
- `/getActiveWirelessProfile` - Get active WiFi profile
|
||||
- `/setWiFiRadio` - WiFi radio control
|
||||
|
||||
**Bluetooth:**
|
||||
- `/bluetoothInfo` ✅ - Bluetooth information and pairing status
|
||||
- `/enterBluetoothPairing` - Enter Bluetooth pairing mode (switches to BLUETOOTH source)
|
||||
- `/clearBluetoothPaired` - Clear all Bluetooth pairings (emits descending tone)
|
||||
|
||||
**Pairing and Setup:**
|
||||
- `/pairLightswitch` - Pair with lightswitch accessory
|
||||
- `/cancelPairLightswitch` - Cancel lightswitch pairing
|
||||
- `/clearPairedList` - Clear all pairings
|
||||
- `/enterPairingMode` - Enter general pairing mode
|
||||
- `/setPairedStatus` - Set pairing status
|
||||
- `/setPairingStatus` - Update pairing status
|
||||
- `/soundTouchConfigurationStatus` - Configuration status
|
||||
- `/setup` - Device setup interface
|
||||
|
||||
**Software Updates:**
|
||||
- `/swUpdateStart` - Start software update
|
||||
- `/swUpdateAbort` - Abort software update
|
||||
- `/swUpdateQuery` - Query update status
|
||||
- `/swUpdateCheck` - Check for updates
|
||||
|
||||
**Advanced Features:**
|
||||
- `/search` - Content search (music libraries with filter support)
|
||||
- `/navigate` - Content navigation (traverse music library containers)
|
||||
- `/listMediaServers` - List available UPnP/DLNA media servers
|
||||
- `/requestToken` ✅ - Bearer token generation
|
||||
- `/notification` - Notification management
|
||||
- `/playNotification` - Play notification beep (ST-10 series only)
|
||||
- `/speaker` - Play TTS messages or URL content (ST-10 series only)
|
||||
- `/test` - System test interface
|
||||
|
||||
**Internal/System:**
|
||||
- `/pdo` - Internal PDO operations
|
||||
- `/slaveMsg` - Slave device messaging
|
||||
- `/masterMsg` - Master device messaging
|
||||
- `/factoryDefault` - Factory reset
|
||||
- `/criticalError` - Critical error handling
|
||||
- `/netStats` - Network statistics and device interface details
|
||||
- `/rebroadcastlatencymode` - Rebroadcast latency mode configuration
|
||||
- `/systemtimeout` - System timeout settings
|
||||
- `/powersaving` - Power saving configuration
|
||||
|
||||
**Product Information:**
|
||||
- `/setProductSerialNumber` - Set product serial number
|
||||
- `/setProductSoftwareVersion` - Set software version
|
||||
- `/setComponentSoftwareVersion` - Set component versions
|
||||
|
||||
**Marge Integration (Bose Cloud Services):**
|
||||
- `/marge` - Marge service integration (Bose cloud services, EOL May 2026)
|
||||
- `/setMargeAccount` - Set Marge account (EOL May 2026)
|
||||
- `/pushCustomerSupportInfoToMarge` - Push support info to cloud (EOL May 2026)
|
||||
|
||||
**Reset and Control:**
|
||||
- `/getBCOReset` - Get BCO reset status
|
||||
- `/setBCOReset` - Set BCO reset
|
||||
|
||||
**Notes on Endpoint Discovery:**
|
||||
- Total discovered endpoints: **103**
|
||||
- Both test devices (192.168.178.28 and 192.168.178.35) support identical endpoint lists
|
||||
- Many endpoints are undocumented in official API v1.0 but functional on real hardware
|
||||
- Some endpoints may require specific device types or firmware versions
|
||||
- Endpoints marked ✅ are currently implemented in this Go library
|
||||
|
||||
**Implementation Priority:**
|
||||
1. **High**: Core functionality endpoints already implemented
|
||||
2. **Medium**: Music service integration, advanced zone management
|
||||
3. **Low**: Internal/diagnostic endpoints, factory operations
|
||||
|
||||
## Reference
|
||||
|
||||
Based on the official Bose SoundTouch Web API documentation:
|
||||
|
||||
@@ -0,0 +1,236 @@
|
||||
# SoundTouch supportedURLs Endpoint Analysis
|
||||
|
||||
This document provides a comprehensive analysis of the `/supportedURLs` endpoint response from real Bose SoundTouch devices and compares it with our current implementation.
|
||||
|
||||
## Discovery Summary
|
||||
|
||||
**Test Devices:**
|
||||
- Device 1: `192.168.178.28:8090` (deviceID: `08DF1F0BA325`)
|
||||
- Device 2: `192.168.178.35:8090` (deviceID: `A81B6A536A98`)
|
||||
|
||||
**Key Findings:**
|
||||
- Both devices return identical endpoint lists
|
||||
- **103 total endpoints** discovered
|
||||
- **~35 currently implemented** in this Go library (34%)
|
||||
- **68 additional endpoints** available for future implementation
|
||||
|
||||
## Endpoint Categories
|
||||
|
||||
### ✅ Fully Implemented (Core Functionality)
|
||||
|
||||
**Device Information (5/5):**
|
||||
- `/info` - Device information
|
||||
- `/capabilities` - Device capabilities
|
||||
- `/supportedURLs` - Supported endpoints list
|
||||
- `/networkInfo` - Network configuration
|
||||
- `/name` - Device name management
|
||||
|
||||
**Playback Control (3/3):**
|
||||
- `/nowPlaying` - Current playback status
|
||||
- `/now_playing` - Alternative current playback endpoint
|
||||
- `/key` - Send key commands
|
||||
|
||||
**Volume & Audio (4/4):**
|
||||
- `/volume` - Volume control
|
||||
- `/bass` - Bass settings
|
||||
- `/bassCapabilities` - Bass capability information
|
||||
- `/balance` - Stereo balance
|
||||
|
||||
**Source Management (2/2):**
|
||||
- `/sources` - Available sources
|
||||
- `/select` - Select source/content
|
||||
|
||||
**Preset Management (1/2):**
|
||||
- `/presets` - Get presets (POST officially N/A)
|
||||
|
||||
**Zone/Multiroom (4/4):**
|
||||
- `/getZone` - Get zone configuration
|
||||
- `/setZone` - Set zone configuration
|
||||
- `/addZoneSlave` - Add device to zone
|
||||
- `/removeZoneSlave` - Remove device from zone
|
||||
|
||||
**Clock & Display (2/2):**
|
||||
- `/clockDisplay` - Clock display settings
|
||||
- `/clockTime` - Device time management
|
||||
|
||||
**Advanced Audio (3/3):**
|
||||
- `/audiodspcontrols` - DSP settings (capability-dependent)
|
||||
- `/audioproducttonecontrols` - Advanced tone controls (capability-dependent)
|
||||
- `/audioproductlevelcontrols` - Speaker level controls (capability-dependent)
|
||||
|
||||
**System Info (3/3):**
|
||||
- `/trackInfo` - Track information
|
||||
- `/bluetoothInfo` - Bluetooth information
|
||||
- `/recents` - Recently played content
|
||||
|
||||
### 🔶 Partially Implemented/Different Approach
|
||||
|
||||
**Zone Management:**
|
||||
- `/addGroup` ⚠️ - We use `/setZone` for group management
|
||||
- `/removeGroup` ⚠️ - We use `/setZone` for group management
|
||||
- `/getGroup` ⚠️ - We use `/getZone` for group information
|
||||
- `/updateGroup` ⚠️ - We use `/setZone` for group updates
|
||||
|
||||
### ❌ Not Yet Implemented (High Priority)
|
||||
|
||||
**Enhanced Playback Control:**
|
||||
- `/nowSelection` - Current selection details
|
||||
- `/playbackRequest` - Advanced playback requests
|
||||
- `/userPlayControl` - User play control interface
|
||||
- `/userTrackControl` - User track control interface
|
||||
- `/selectPreset` - Select preset by ID
|
||||
|
||||
**Source Enhancement:**
|
||||
- `/sourceDiscoveryStatus` - Source discovery status
|
||||
- `/nameSource` - Name/rename sources
|
||||
- `/selectLastSource` - Select last used source
|
||||
- `/selectLastWiFiSource` - Select last WiFi source
|
||||
- `/selectLastSoundTouchSource` - Select last SoundTouch source
|
||||
- `/selectLocalSource` - Select local source
|
||||
|
||||
**Music Services Integration:**
|
||||
- `/setMusicServiceAccount` - Configure music service account
|
||||
- `/setMusicServiceOAuthAccount` - OAuth account setup
|
||||
- `/removeMusicServiceAccount` - Remove music service account
|
||||
- `/serviceAvailability` - Check service availability
|
||||
|
||||
**Enhanced Presets:**
|
||||
- `/storePreset` - Store new preset
|
||||
- `/removePreset` - Remove existing preset
|
||||
- `/bookmark` - Bookmark current content
|
||||
- `/userRating` - User rating for content
|
||||
|
||||
**Station/Radio Management:**
|
||||
- `/searchStation` - Search for stations
|
||||
- `/addStation` - Add station to favorites
|
||||
- `/removeStation` - Remove station from favorites
|
||||
- `/genreStations` - Browse stations by genre
|
||||
- `/stationInfo` - Station information
|
||||
|
||||
### ❌ Not Yet Implemented (Medium Priority)
|
||||
|
||||
**System Configuration:**
|
||||
- `/powerManagement` - Power management settings
|
||||
- `/standby` - Standby mode control
|
||||
- `/lowPowerStandby` - Low power standby mode
|
||||
- `/systemtimeout` - System timeout settings
|
||||
- `/powersaving` - Power saving configuration
|
||||
- `/language` - Language settings
|
||||
- `/speaker` - Speaker configuration
|
||||
|
||||
**Network & Connectivity:**
|
||||
- `/performWirelessSiteSurvey` - WiFi site survey
|
||||
- `/addWirelessProfile` - Add WiFi profile
|
||||
- `/getActiveWirelessProfile` - Get active WiFi profile
|
||||
- `/setWiFiRadio` - WiFi radio control
|
||||
|
||||
**Bluetooth Enhancement:**
|
||||
- `/enterBluetoothPairing` - Enter Bluetooth pairing mode
|
||||
- `/clearBluetoothPaired` - Clear Bluetooth pairings
|
||||
|
||||
**Content Discovery:**
|
||||
- `/search` - Content search
|
||||
- `/navigate` - Content navigation
|
||||
- `/listMediaServers` - List available media servers
|
||||
|
||||
### ❌ Not Yet Implemented (Low Priority)
|
||||
|
||||
**Pairing & Setup:**
|
||||
- `/pairLightswitch` - Pair with lightswitch accessory
|
||||
- `/cancelPairLightswitch` - Cancel lightswitch pairing
|
||||
- `/clearPairedList` - Clear all pairings
|
||||
- `/enterPairingMode` - Enter general pairing mode
|
||||
- `/setPairedStatus` - Set pairing status
|
||||
- `/setPairingStatus` - Update pairing status
|
||||
- `/soundTouchConfigurationStatus` - Configuration status
|
||||
- `/setup` - Device setup interface
|
||||
|
||||
**Software Updates:**
|
||||
- `/swUpdateStart` - Start software update
|
||||
- `/swUpdateAbort` - Abort software update
|
||||
- `/swUpdateQuery` - Query update status
|
||||
- `/swUpdateCheck` - Check for updates
|
||||
|
||||
**System Utilities:**
|
||||
- `/userActivity` - User activity tracking
|
||||
- `/requestToken` - Token management
|
||||
- `/notification` - Notification management
|
||||
- `/playNotification` - Play notification sound
|
||||
- `/introspect` - System introspection
|
||||
- `/test` - System test interface
|
||||
|
||||
**Internal/Advanced:**
|
||||
- `/pdo` - Internal PDO operations
|
||||
- `/slaveMsg` - Slave device messaging
|
||||
- `/masterMsg` - Master device messaging
|
||||
- `/factoryDefault` - Factory reset
|
||||
- `/criticalError` - Critical error handling
|
||||
- `/netStats` - Network statistics
|
||||
- `/rebroadcastlatencymode` - Rebroadcast latency mode
|
||||
- `/getBCOReset` - Get BCO reset status
|
||||
- `/setBCOReset` - Set BCO reset
|
||||
|
||||
**Product Management:**
|
||||
- `/setProductSerialNumber` - Set product serial number
|
||||
- `/setProductSoftwareVersion` - Set software version
|
||||
- `/setComponentSoftwareVersion` - Set component versions
|
||||
|
||||
**Cloud Integration (EOL May 2026):**
|
||||
- `/marge` - Marge service integration
|
||||
- `/setMargeAccount` - Set Marge account
|
||||
- `/pushCustomerSupportInfoToMarge` - Push support info to cloud
|
||||
|
||||
**Enhanced DSP (Device Dependent):**
|
||||
- `/DSPMonoStereo` - DSP mono/stereo settings
|
||||
|
||||
## Implementation Recommendations
|
||||
|
||||
### Phase 1: High-Value User Features
|
||||
1. **Enhanced Source Selection** - `/selectLast*` endpoints for better UX
|
||||
2. **Preset Management** - `/storePreset`, `/removePreset`, `/selectPreset`
|
||||
3. **Station Management** - Radio/streaming station operations
|
||||
4. **Music Service Integration** - Account management endpoints
|
||||
|
||||
### Phase 2: System Enhancement
|
||||
1. **Power Management** - Standby and power saving controls
|
||||
2. **Network Management** - WiFi profile and radio control
|
||||
3. **Content Discovery** - Search and navigation capabilities
|
||||
4. **Bluetooth Enhancement** - Pairing management
|
||||
|
||||
### Phase 3: Advanced Features
|
||||
1. **System Diagnostics** - Network stats, introspection
|
||||
2. **Update Management** - Software update control
|
||||
3. **Notification System** - Notification management
|
||||
4. **Advanced Setup** - Pairing and configuration tools
|
||||
|
||||
## Notes
|
||||
|
||||
1. **Device Consistency**: Both test devices expose identical endpoint lists, suggesting consistent firmware behavior across SoundTouch models.
|
||||
|
||||
2. **Official vs. Real**: The device exposes **84 additional endpoints** beyond the 19 documented in the official API v1.0, indicating significant undocumented functionality.
|
||||
|
||||
3. **Cloud Dependency**: Some endpoints (especially `/marge*`) may become non-functional after the May 2026 SoundTouch cloud EOL.
|
||||
|
||||
4. **Implementation Strategy**: Focus on user-facing functionality first, then system management, finally internal/diagnostic features.
|
||||
|
||||
5. **Testing Required**: Each new endpoint implementation should be tested against real hardware to verify functionality and response formats.
|
||||
|
||||
6. **Documentation Gap**: Many endpoints lack official documentation, requiring reverse engineering through testing.
|
||||
|
||||
## Raw Device Response
|
||||
|
||||
**Device Count:** 103 unique endpoints
|
||||
**Response Format:** XML with URL location attributes
|
||||
**Common Pattern:** Most endpoints support both GET (query) and POST (modify) operations
|
||||
|
||||
**Example Response Structure:**
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<supportedURLs deviceID="08DF1F0BA325">
|
||||
<URL location="/info" />
|
||||
<URL location="/capabilities" />
|
||||
<!-- ... 101 additional endpoints ... -->
|
||||
</supportedURLs>
|
||||
```
|
||||
|
||||
This analysis provides a roadmap for expanding the Go library's API coverage from 34% to potentially 100% of available device functionality.
|
||||
@@ -0,0 +1,785 @@
|
||||
# Unimplemented SoundTouch API Endpoints
|
||||
|
||||
This document provides detailed information about SoundTouch API endpoints that are supported by real hardware but not yet implemented in this Go library. The examples and XML structures are based on real device responses and the comprehensive [HomeAssistant SoundTouch Plus documentation](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API).
|
||||
|
||||
## High Priority Implementation Candidates
|
||||
|
||||
### Music Service Management
|
||||
|
||||
#### POST /setMusicServiceAccount
|
||||
Adds a music service account to the sources list.
|
||||
|
||||
**Request Examples:**
|
||||
|
||||
Pandora:
|
||||
```xml
|
||||
<credentials source="PANDORA" displayName="Pandora Music Service">
|
||||
<user>YourPandoraUserId</user>
|
||||
<pass>YourPandoraPassword$1pd</pass>
|
||||
</credentials>
|
||||
```
|
||||
|
||||
NAS Music Library:
|
||||
```xml
|
||||
<credentials source="STORED_MUSIC" displayName="My NAS Media Library:">
|
||||
<user>d09708a1-5953-44bc-a413-123456789012/0</user>
|
||||
<pass />
|
||||
</credentials>
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/setMusicServiceAccount</status>
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- UPnP media servers must be detected first (check `/listMediaServers`)
|
||||
- Note the `/0` suffix for STORED_MUSIC user names
|
||||
|
||||
#### POST /removeMusicServiceAccount
|
||||
Removes an existing music service account from the sources list.
|
||||
|
||||
**Request Examples:**
|
||||
|
||||
Remove Pandora:
|
||||
```xml
|
||||
<credentials source="PANDORA" displayName="Pandora Music Service">
|
||||
<user>YourPandoraUserId</user>
|
||||
<pass />
|
||||
</credentials>
|
||||
```
|
||||
|
||||
Remove NAS Library:
|
||||
```xml
|
||||
<credentials source="STORED_MUSIC" displayName="My NAS Media Library:">
|
||||
<user>d09708a1-5953-44bc-a413-123456789012/0</user>
|
||||
<pass />
|
||||
</credentials>
|
||||
```
|
||||
|
||||
### Enhanced Preset Management
|
||||
|
||||
#### POST /storePreset
|
||||
Stores a preset to the device (maximum 6 presets).
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<preset id="3" createdOn="1696133215" updatedOn="1696133215">
|
||||
<ContentItem source="TUNEIN" type="stationurl" location="/v1/playback/station/s309605" sourceAccount="" isPresetable="true">
|
||||
<itemName>K-LOVE 90s</itemName>
|
||||
<containerArt>http://cdn-profiles.tunein.com/s309605/images/logog.png</containerArt>
|
||||
</ContentItem>
|
||||
</preset>
|
||||
```
|
||||
|
||||
**Response:** Returns updated presets list
|
||||
|
||||
**Behavior:**
|
||||
- If preset ID exists, overlay existing preset
|
||||
- If content matches existing preset, move to specified slot
|
||||
- Generates `presetsUpdated` WebSocket event
|
||||
|
||||
#### POST /removePreset
|
||||
Removes an existing preset from the device.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<preset id="4"></preset>
|
||||
```
|
||||
|
||||
**Response:** Returns updated presets list
|
||||
**WebSocket Event:** `presetsUpdated`
|
||||
|
||||
#### GET /selectPreset
|
||||
Selects a preset by ID for playback.
|
||||
|
||||
**Usage:** Send preset ID to immediately play stored preset content.
|
||||
|
||||
### Station Management (Pandora Tested)
|
||||
|
||||
#### POST /searchStation
|
||||
Searches music service for stations that can be added.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<search source="PANDORA" sourceAccount="yourUserId">
|
||||
Zach Williams
|
||||
</search>
|
||||
```
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<results deviceID="..." source="PANDORA" sourceAccount="yourUserId">
|
||||
<songs>
|
||||
<searchResult source="PANDORA" sourceAccount="yourUserId" token="S88589974">
|
||||
<name>Cornerstone (Radio Edit) (feat. Zach Williams)</name>
|
||||
<artist>TobyMac</artist>
|
||||
<logo>http://mediaserver-cont-usc-mp1-1-v4v6.pandora.com/images/.../1080W_1080H.jpg</logo>
|
||||
</searchResult>
|
||||
<!-- More songs -->
|
||||
</songs>
|
||||
<artists>
|
||||
<searchResult source="PANDORA" sourceAccount="yourUserId" token="R324771">
|
||||
<name>Zach Williams</name>
|
||||
<logo>http://mediaserver-cont-dc6-2-v4v6.pandora.com/images/.../1080W_1080H.jpg</logo>
|
||||
</searchResult>
|
||||
<!-- More artists -->
|
||||
</artists>
|
||||
</results>
|
||||
```
|
||||
|
||||
#### POST /addStation
|
||||
Adds a station to music service collection.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<addStation source="PANDORA" sourceAccount="yourUserId" token="R4328162">
|
||||
<name>Zach Williams & Essential Worship</name>
|
||||
</addStation>
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/addStation</status>
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Station is immediately selected for playing
|
||||
- Use token from `/searchStation` results
|
||||
|
||||
#### POST /removeStation
|
||||
Removes a station from music service collection.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<ContentItem source="PANDORA" location="126740707481236361" sourceAccount="yourUserId" isPresetable="true">
|
||||
<itemName>Zach Williams Radio</itemName>
|
||||
</ContentItem>
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/removeStation</status>
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- If removed station is currently playing, playback stops and source becomes "INVALID_SOURCE"
|
||||
|
||||
### Enhanced User Controls
|
||||
|
||||
#### POST /userPlayControl
|
||||
Sends user play control commands.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<PlayControl>PLAY_CONTROL</PlayControl>
|
||||
```
|
||||
|
||||
**Valid Control Values:**
|
||||
- `PAUSE_CONTROL` - Pause currently playing content
|
||||
- `PLAY_CONTROL` - Play content that is paused/stopped
|
||||
- `PLAY_PAUSE_CONTROL` - Toggle play/pause state
|
||||
- `STOP_CONTROL` - Stop currently playing content
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/userPlayControl</status>
|
||||
```
|
||||
|
||||
#### POST /userRating
|
||||
Rates currently playing media (Pandora support confirmed).
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<Rating>UP</Rating>
|
||||
```
|
||||
|
||||
**Valid Rating Values:**
|
||||
- `UP` - Thumbs up rating
|
||||
- `DOWN` - Thumbs down rating (stops current track, advances to next)
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/userRating</status>
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Ratings stored in artist profile under "My Collection"
|
||||
- Currently only works with Pandora
|
||||
|
||||
## Medium Priority Implementation Candidates
|
||||
|
||||
### Content Discovery and Navigation
|
||||
|
||||
#### POST /navigate
|
||||
Returns child container items from music library containers.
|
||||
|
||||
**Request XML (Root Container):**
|
||||
```xml
|
||||
<navigate source="STORED_MUSIC" sourceAccount="d09708a1-5953-44bc-a413-123456789012/0">
|
||||
<startItem>1</startItem>
|
||||
<numItems>1000</numItems>
|
||||
</navigate>
|
||||
```
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<navigateResponse source="STORED_MUSIC" sourceAccount="...">
|
||||
<totalItems>4</totalItems>
|
||||
<items>
|
||||
<item Playable="1">
|
||||
<name>Music</name>
|
||||
<type>dir</type>
|
||||
<ContentItem source="STORED_MUSIC" location="1" sourceAccount="..." isPresetable="true">
|
||||
<itemName>Music</itemName>
|
||||
</ContentItem>
|
||||
</item>
|
||||
<item Playable="1">
|
||||
<name>Playlists</name>
|
||||
<type>dir</type>
|
||||
<ContentItem source="STORED_MUSIC" location="12" sourceAccount="..." isPresetable="true">
|
||||
<itemName>Playlists</itemName>
|
||||
</ContentItem>
|
||||
</item>
|
||||
</items>
|
||||
</navigateResponse>
|
||||
```
|
||||
|
||||
**Navigate Specific Container:**
|
||||
```xml
|
||||
<navigate source="STORED_MUSIC" sourceAccount="d09708a1-5953-44bc-a413-123456789012/0">
|
||||
<startItem>1</startItem>
|
||||
<numItems>1000</numItems>
|
||||
<item Playable="1">
|
||||
<name>Welcome to the New</name>
|
||||
<type>dir</type>
|
||||
<ContentItem source="STORED_MUSIC" location="7_114e8de9" sourceAccount="..." isPresetable="true">
|
||||
<itemName>Welcome to the New</itemName>
|
||||
</ContentItem>
|
||||
</item>
|
||||
</navigate>
|
||||
```
|
||||
|
||||
#### POST /search
|
||||
Searches specified music library container.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<search source="STORED_MUSIC" sourceAccount="d09708a1-5953-44bc-a413-123456789012/0">
|
||||
<startItem>1</startItem>
|
||||
<numItems>1000</numItems>
|
||||
<searchTerm filter="track">baby</searchTerm>
|
||||
<item>
|
||||
<name>Music Playlists</name>
|
||||
<type>dir</type>
|
||||
<ContentItem source="STORED_MUSIC" location="F" sourceAccount="..." isPresetable="true" />
|
||||
</item>
|
||||
</search>
|
||||
```
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<searchResponse source="STORED_MUSIC" sourceAccount="...">
|
||||
<totalItems>2</totalItems>
|
||||
<items>
|
||||
<item Playable="1">
|
||||
<name>Baby, It's Cold Outside</name>
|
||||
<type>track</type>
|
||||
<ContentItem source="STORED_MUSIC" location="F_a62301e2-7788 TRACK" sourceAccount="..." isPresetable="true">
|
||||
<itemName>Baby, It's Cold Outside</itemName>
|
||||
</ContentItem>
|
||||
<artistName>Anne Murray</artistName>
|
||||
<albumName>Christmas Album</albumName>
|
||||
</item>
|
||||
</items>
|
||||
</searchResponse>
|
||||
```
|
||||
|
||||
**Valid Filters:**
|
||||
- `track` - Search track names
|
||||
- `artist` - Search artist names
|
||||
- `album` - Search album names
|
||||
|
||||
### Power Management
|
||||
|
||||
#### GET /powerManagement
|
||||
Returns power state and battery capability information.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<powerManagementResponse>
|
||||
<powerState>FullPower</powerState>
|
||||
<battery>
|
||||
<capable>false</capable>
|
||||
</battery>
|
||||
</powerManagementResponse>
|
||||
```
|
||||
|
||||
#### GET /standby
|
||||
Places device into standby (power-saving) mode.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/standby</status>
|
||||
```
|
||||
|
||||
**WebSocket Event:**
|
||||
```xml
|
||||
<updates deviceID="...">
|
||||
<nowPlayingUpdated>
|
||||
<nowPlaying deviceID="..." source="STANDBY">
|
||||
<ContentItem source="STANDBY" isPresetable="false" />
|
||||
</nowPlaying>
|
||||
</nowPlayingUpdated>
|
||||
</updates>
|
||||
```
|
||||
|
||||
#### GET /lowPowerStandby
|
||||
Places device into low-power mode (device becomes unresponsive until physical power button pressed).
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/lowPowerStandby</status>
|
||||
```
|
||||
|
||||
**Warning:** Device will not respond to any commands after this until physically powered on.
|
||||
|
||||
### Language and Configuration
|
||||
|
||||
#### GET /language
|
||||
Returns current language configuration.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<sysLanguage>3</sysLanguage>
|
||||
```
|
||||
|
||||
#### POST /language
|
||||
Sets device language.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<sysLanguage>3</sysLanguage>
|
||||
```
|
||||
|
||||
**Language Codes:**
|
||||
- 1 = DANISH
|
||||
- 2 = GERMAN
|
||||
- 3 = ENGLISH
|
||||
- 4 = SPANISH
|
||||
- 5 = FRENCH
|
||||
- 6 = ITALIAN
|
||||
- 7 = DUTCH
|
||||
- 8 = SWEDISH
|
||||
- 9 = JAPANESE
|
||||
- 10 = SIMPLIFIED_CHINESE
|
||||
- 11 = TRADITIONAL_CHINESE
|
||||
- 12 = KOREAN
|
||||
- 13 = THAI
|
||||
- 15 = CZECH
|
||||
- 16 = FINNISH
|
||||
- 17 = GREEK
|
||||
- 18 = NORWEGIAN
|
||||
- 19 = POLISH
|
||||
- 20 = PORTUGUESE
|
||||
- 21 = ROMANIAN
|
||||
- 22 = RUSSIAN
|
||||
- 23 = SLOVENIAN
|
||||
- 24 = TURKISH
|
||||
- 25 = HUNGARIAN
|
||||
|
||||
### System Information and Status
|
||||
|
||||
#### GET /soundTouchConfigurationStatus
|
||||
Returns current SoundTouch configuration status.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<SoundTouchConfigurationStatus status="SOUNDTOUCH_CONFIGURED" />
|
||||
```
|
||||
|
||||
**Valid Status Values:**
|
||||
- `SOUNDTOUCH_CONFIGURED` - Device configuration complete
|
||||
- `SOUNDTOUCH_NOT_CONFIGURED` - Device not configured
|
||||
- `SOUNDTOUCH_CONFIGURING` - Configuration in progress
|
||||
|
||||
#### GET /serviceAvailability
|
||||
Returns information about which source services are currently available.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<serviceAvailability>
|
||||
<services>
|
||||
<service type="AIRPLAY" isAvailable="true" />
|
||||
<service type="ALEXA" isAvailable="false" />
|
||||
<service type="AMAZON" isAvailable="true" />
|
||||
<service type="BLUETOOTH" isAvailable="false" reason="INVALID_SOURCE_TYPE" />
|
||||
<service type="SPOTIFY" isAvailable="true" />
|
||||
<service type="TUNEIN" isAvailable="true" />
|
||||
<!-- More services -->
|
||||
</services>
|
||||
</serviceAvailability>
|
||||
```
|
||||
|
||||
#### GET /listMediaServers
|
||||
Returns information about detected UPnP/DLNA media servers.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<ListMediaServersResponse>
|
||||
<media_server id="d09708a1-5953-44bc-a413-123456789012" mac="S-1-5-21-240303764-901663538-1234567890-1001" ip="192.168.1.5" manufacturer="Microsoft Corporation" model_name="Windows Media Player Sharing" friendly_name="My NAS Media Library" model_description="" location="http://192.168.1.5:2869/upnphost/udhisapi.dll?..." />
|
||||
</ListMediaServersResponse>
|
||||
```
|
||||
|
||||
#### GET /requestToken ✅ **Implemented**
|
||||
Returns a new bearer token generated by the device.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<bearertoken value="Bearer vUApzBVT6Lh0nw1xVu/plr1UDRNdMYMEpe0cStm4wCH5mWSjrrtORnGGirMn3pspkJ8mNR1MFh/J4OcsbEikMplcDGJVeuZOnDPAskQALvDBCF0PW74qXRms2k1AfLJ/" />
|
||||
```
|
||||
|
||||
**Implementation**: Available via `RequestToken()` client method and `soundtouch-cli token request` command.
|
||||
|
||||
### Software Updates
|
||||
|
||||
#### GET /swUpdateCheck
|
||||
Gets latest available software update release information.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<swUpdateCheckResponse deviceID="..." indexFileUrl="https://worldwide.bose.com/updates/soundtouch">
|
||||
<release revision="27.0.6.46330.5043500" />
|
||||
</swUpdateCheckResponse>
|
||||
```
|
||||
|
||||
#### GET /swUpdateQuery
|
||||
Gets status of a SoundTouch software update.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<swUpdateQueryResponse deviceID="...">
|
||||
<state>IDLE</state>
|
||||
<percentComplete>0</percentComplete>
|
||||
<canAbort>false</canAbort>
|
||||
</swUpdateQueryResponse>
|
||||
```
|
||||
|
||||
## Low Priority / Specialized Endpoints
|
||||
|
||||
### Notification System (ST-10 Series Only)
|
||||
|
||||
#### POST /playNotification
|
||||
Plays a notification beep on the device.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/playNotification</status>
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Pauses current media
|
||||
- Emits double beep sound
|
||||
- Resumes media playback
|
||||
|
||||
**Note:** Only works on ST-10 series. ST-300 and other models do not support this.
|
||||
|
||||
#### POST /speaker
|
||||
Plays TTS messages or URL content (ST-10 Series Only).
|
||||
|
||||
**TTS Example:**
|
||||
```xml
|
||||
<play_info>
|
||||
<url>http://translate.google.com/translate_tts?ie=UTF-8&tl=EN&client=tw-ob&q=a.There%20is%20activity%20at%20the%20front%20door.</url>
|
||||
<app_key>YourAppKey</app_key>
|
||||
<service>TTS Notification</service>
|
||||
<message>Google TTS</message>
|
||||
<reason>a.There is activity at the front door.</reason>
|
||||
<volume>70</volume>
|
||||
</play_info>
|
||||
```
|
||||
|
||||
**URL Content Example:**
|
||||
```xml
|
||||
<play_info>
|
||||
<url>https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_1MB_MP3.mp3</url>
|
||||
<app_key>YourAppKey</app_key>
|
||||
<service>FreeTestData.com</service>
|
||||
<message>MP3 Test Data</message>
|
||||
<reason>Free_Test_Data_1MB_MP3</reason>
|
||||
</play_info>
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Only ST-10 series supported
|
||||
- Pauses current content during notification
|
||||
- Volume restored after notification completes
|
||||
- SoundTouch device limits volume range 10-70
|
||||
|
||||
### WiFi Management
|
||||
|
||||
#### POST /performWirelessSiteSurvey
|
||||
Gets list of wireless networks detected by device.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<PerformWirelessSiteSurveyResponse error="none">
|
||||
<items>
|
||||
<item ssid="my_wireless_ssid" signalStrength="-58" secure="true">
|
||||
<securityTypes>
|
||||
<type>wpa_or_wpa2</type>
|
||||
</securityTypes>
|
||||
</item>
|
||||
<item ssid="NETGEAR07" signalStrength="-83" secure="true">
|
||||
<securityTypes>
|
||||
<type>wpa_or_wpa2</type>
|
||||
</securityTypes>
|
||||
</item>
|
||||
</items>
|
||||
</PerformWirelessSiteSurveyResponse>
|
||||
```
|
||||
|
||||
#### POST /addWirelessProfile
|
||||
Adds wireless profile configuration to device.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<addWirelessProfile timeout="30">
|
||||
<profile ssid="YourSSIDName" password="YourSSIDPassword" securityType="wpa_or_wpa2"></profile>
|
||||
</addWirelessProfile>
|
||||
```
|
||||
|
||||
**Security Types:**
|
||||
- `none` - No security
|
||||
- `wep` - WEP
|
||||
- `wpatkip` - WPA/TKIP
|
||||
- `wpaaes` - WPA/AES
|
||||
- `wpa2tkip` - WPA2/TKIP
|
||||
- `wpa2aes` - WPA2/AES
|
||||
- `wpa_or_wpa2` - WPA/WPA2 (recommended)
|
||||
|
||||
**Setup Process:**
|
||||
1. Connect to device WiFi (default IP: 192.0.2.1)
|
||||
2. Add wireless profile
|
||||
3. End setup: POST to `/setup` with `<setupState state="SETUP_WIFI_LEAVE" />`
|
||||
|
||||
#### GET /getActiveWirelessProfile
|
||||
Gets current wireless profile configuration.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<GetActiveWirelessProfileResponse>
|
||||
<ssid>my_wireless_ssid</ssid>
|
||||
</GetActiveWirelessProfileResponse>
|
||||
```
|
||||
|
||||
### Bluetooth Management
|
||||
|
||||
#### POST /enterBluetoothPairing
|
||||
Enters Bluetooth pairing mode and waits for device to pair.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/enterBluetoothPairing</status>
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Device enters pairing mode
|
||||
- Bluetooth indicator turns blue
|
||||
- Emits ascending tone when pairing complete
|
||||
- Source immediately switches to BLUETOOTH
|
||||
|
||||
#### POST /clearBluetoothPaired
|
||||
Clears all existing Bluetooth pairings.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<BluetoothInfo BluetoothMACAddress="34:15:13:45:2f:93" />
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- All existing pairings removed
|
||||
- Devices need to re-pair
|
||||
- Emits descending tone
|
||||
|
||||
### Source Selection Shortcuts
|
||||
|
||||
#### GET /selectLastSource
|
||||
Selects the last source that was selected.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/selectLastSource</status>
|
||||
```
|
||||
|
||||
#### GET /selectLastSoundTouchSource
|
||||
Selects the last SoundTouch source that was selected.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/selectLastSoundTouchSource</status>
|
||||
```
|
||||
|
||||
#### GET /selectLastWiFiSource
|
||||
Selects the last WiFi source that was selected.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/selectLastWiFiSource</status>
|
||||
```
|
||||
|
||||
#### GET /selectLocalSource
|
||||
Selects the LOCAL source (for devices where this is the only way to select LOCAL).
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<status>/selectLocalSource</status>
|
||||
```
|
||||
|
||||
### Group Management (ST-10 Stereo Pairs Only)
|
||||
|
||||
The ST-10 is the only SoundTouch product that supports stereo pair groups (different from zones).
|
||||
|
||||
#### GET /getGroup
|
||||
Gets current left/right stereo pair configuration.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<group id="1115893">
|
||||
<name>Bose-ST10-1 + Bose-ST10-4</name>
|
||||
<masterDeviceId>9070658C9D4A</masterDeviceId>
|
||||
<roles>
|
||||
<groupRole>
|
||||
<deviceId>9070658C9D4A</deviceId>
|
||||
<role>LEFT</role>
|
||||
<ipAddress>192.168.1.131</ipAddress>
|
||||
</groupRole>
|
||||
<groupRole>
|
||||
<deviceId>F45EAB3115DA</deviceId>
|
||||
<role>RIGHT</role>
|
||||
<ipAddress>192.168.1.134</ipAddress>
|
||||
</groupRole>
|
||||
</roles>
|
||||
<senderIPAddress>192.168.1.131</senderIPAddress>
|
||||
<status>GROUP_OK</status>
|
||||
</group>
|
||||
```
|
||||
|
||||
#### POST /addGroup
|
||||
Creates new left/right stereo pair speaker group.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<group>
|
||||
<name>Bose-ST10-1 + Bose-ST10-4</name>
|
||||
<masterDeviceId>9070658C9D4A</masterDeviceId>
|
||||
<roles>
|
||||
<groupRole>
|
||||
<deviceId>9070658C9D4A</deviceId>
|
||||
<role>LEFT</role>
|
||||
<ipAddress>192.168.1.131</ipAddress>
|
||||
</groupRole>
|
||||
<groupRole>
|
||||
<deviceId>F45EAB3115DA</deviceId>
|
||||
<role>RIGHT</role>
|
||||
<ipAddress>192.168.1.134</ipAddress>
|
||||
</groupRole>
|
||||
</roles>
|
||||
</group>
|
||||
```
|
||||
|
||||
**WebSocket Event:** `groupUpdated` sent to both devices
|
||||
|
||||
#### GET /removeGroup
|
||||
Removes existing stereo pair group.
|
||||
|
||||
**Response:**
|
||||
```xml
|
||||
<group />
|
||||
```
|
||||
|
||||
#### POST /updateGroup
|
||||
Updates name of stereo pair group.
|
||||
|
||||
**Request XML:**
|
||||
```xml
|
||||
<group id="1116267">
|
||||
<name>Updated Group Name</name>
|
||||
<masterDeviceId>9070658C9D4A</masterDeviceId>
|
||||
<roles>
|
||||
<groupRole>
|
||||
<deviceId>9070658C9D4A</deviceId>
|
||||
<role>LEFT</role>
|
||||
<ipAddress>192.168.1.131</ipAddress>
|
||||
</groupRole>
|
||||
<groupRole>
|
||||
<deviceId>F45EAB3115DA</deviceId>
|
||||
<role>RIGHT</role>
|
||||
<ipAddress>192.168.1.134</ipAddress>
|
||||
</groupRole>
|
||||
</roles>
|
||||
</group>
|
||||
```
|
||||
|
||||
### Advanced System Configuration
|
||||
|
||||
#### GET /systemtimeout
|
||||
Gets current system timeout configuration.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<systemtimeout>
|
||||
<powersaving_enabled>true</powersaving_enabled>
|
||||
</systemtimeout>
|
||||
```
|
||||
|
||||
#### GET /rebroadcastlatencymode
|
||||
Gets current rebroadcast latency mode configuration.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<rebroadcastlatencymode mode="SYNC_TO_ZONE" controllable="true" />
|
||||
```
|
||||
|
||||
#### GET /DSPMonoStereo
|
||||
Gets current digital signal processor configuration.
|
||||
|
||||
**Response XML:**
|
||||
```xml
|
||||
<DSPMonoStereo deviceID="...">
|
||||
<mono enable="false" />
|
||||
</DSPMonoStereo>
|
||||
```
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Device Compatibility
|
||||
- Many endpoints work on specific device models only
|
||||
- Always check `/supportedURLs` before implementing
|
||||
- Test with real hardware when possible
|
||||
|
||||
### Error Handling
|
||||
- Services may return timeout errors on unsupported devices
|
||||
- Some endpoints appear in `/supportedURLs` but still don't work
|
||||
- Graceful degradation recommended
|
||||
|
||||
### WebSocket Events
|
||||
Many POST operations generate corresponding WebSocket events:
|
||||
- `presetsUpdated` - Preset changes
|
||||
- `groupUpdated` - Group changes
|
||||
- `volumeUpdated` - Volume changes
|
||||
- `nowPlayingUpdated` - Source/playback changes
|
||||
- `zoneUpdated` - Zone changes
|
||||
|
||||
### Security Considerations
|
||||
- `/speaker` endpoint requires app_key parameter
|
||||
- Token-based authentication available via `/requestToken` ✅ **Implemented**
|
||||
- Some operations require device to be in specific states
|
||||
|
||||
### Music Service Specifics
|
||||
- Pandora: Confirmed working for station management, ratings
|
||||
- Spotify: Requires PREMIUM account for most operations
|
||||
- STORED_MUSIC: Requires UPnP/DLNA server setup
|
||||
- LOCAL_MUSIC: Requires SoundTouch App Media Server running
|
||||
|
||||
This documentation provides the foundation for implementing these endpoints in the Go library, with real-world examples and detailed XML structures verified against actual SoundTouch hardware.
|
||||
Reference in New Issue
Block a user