Skip to content
Introduction
Technical Reference
System Endpoints Documentation

System Endpoints Documentation

This document provides comprehensive documentation for the system management endpoints in the Bose SoundTouch Go client library.

Overview

The system endpoints provide access to device-level configuration and diagnostic information including:

  • Clock/Time Management: Device time settings and clock display configuration
  • Network Information: Network interfaces, connectivity status, and diagnostics

Clock/Time Management Endpoints

GET /clockTime

Retrieves the current device time with timezone and UTC timestamp information.

Response Structure:

<clockTime zone="America/New_York" utc="1609459200">2021-01-01 00:00:00</clockTime>

Go Usage:

clockTime, err := client.GetClockTime()
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Device time: %s\n", clockTime.GetTimeString())
fmt.Printf("UTC timestamp: %d\n", clockTime.GetUTC())
fmt.Printf("Timezone: %s\n", clockTime.GetZone())

CLI Usage:

soundtouch-cli -host 192.0.2.100 -clock-time

POST /clockTime

Sets the device time using either current system time or a specific UTC timestamp.

Request Structure:

<clockTime zone="UTC" utc="1609459200">2021-01-01 00:00:00</clockTime>

Go Usage:

// Set to current system time
err := client.SetClockTimeNow()

// Set to specific timestamp
request := models.NewClockTimeRequestUTC(1609459200)
err := client.SetClockTime(request)

// Set to specific time
t := time.Date(2021, 1, 1, 12, 0, 0, 0, time.UTC)
request := models.NewClockTimeRequest(t)
err := client.SetClockTime(request)

CLI Usage:

# Set to current system time
soundtouch-cli -host 192.0.2.100 -set-clock-time now

# Set to specific Unix timestamp
soundtouch-cli -host 192.0.2.100 -set-clock-time 1609459200

GET /clockDisplay

Retrieves clock display configuration including enabled state, format, brightness, and auto-dim settings.

Response Structure:

<clockDisplay deviceID="ABCD1234EFGH" enabled="true" format="24" brightness="75" autoDim="true" timeZone="America/New_York">Clock Display</clockDisplay>

Go Usage:

clockDisplay, err := client.GetClockDisplay()
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Enabled: %v\n", clockDisplay.IsEnabled())
fmt.Printf("Format: %s\n", clockDisplay.GetFormatDescription())
fmt.Printf("Brightness: %d%% (%s)\n", clockDisplay.GetBrightness(), clockDisplay.GetBrightnessLevel())
fmt.Printf("Auto-Dim: %v\n", clockDisplay.IsAutoDimEnabled())

CLI Usage:

soundtouch-cli -host 192.0.2.100 -clock-display

POST /clockDisplay

Configures clock display settings including enable/disable, format, brightness, and auto-dim behavior.

Request Structure:

<clockDisplay enabled="true" format="24" brightness="75" autoDim="false" timeZone="UTC"></clockDisplay>

Go Usage:

// Enable clock display
err := client.EnableClockDisplay()

// Disable clock display
err := client.DisableClockDisplay()

// Set brightness
err := client.SetClockDisplayBrightness(75)

// Set format
err := client.SetClockDisplayFormat(models.ClockFormat24Hour)

// Complex configuration
request := models.NewClockDisplayRequest().
    SetEnabled(true).
    SetFormat(models.ClockFormat24Hour).
    SetBrightness(75).
    SetAutoDim(false)
err := client.SetClockDisplay(request)

CLI Usage:

# Enable/disable clock display
soundtouch-cli -host 192.0.2.100 -enable-clock
soundtouch-cli -host 192.0.2.100 -disable-clock

# Set clock format (12, 24, auto)
soundtouch-cli -host 192.0.2.100 -clock-format 24

# Set brightness (0-100)
soundtouch-cli -host 192.0.2.10 -clock-brightness 75

Clock Formats:

  • 12: 12-hour format with AM/PM
  • 24: 24-hour format
  • auto: System default format

Brightness Levels:

  • 0: Off
  • 1-25: Low
  • 26-50: Medium
  • 51-75: High
  • 76-100: Maximum

Network Information Endpoints

GET /networkInfo

Retrieves comprehensive network information including interfaces, connectivity status, and statistics.

Response Structure:

WiFi Device Response (Real API) 

<networkInfo wifiProfileCount="2">
<interfaces>
<interface type="WIFI_INTERFACE" name="wlan0" macAddress="AA:BB:CC:DD:EE:FF" ipAddress="192.0.2.10" ssid="MyHomeNetwork" frequencyKHz="5500000" state="NETWORK_WIFI_CONNECTED" signal="EXCELLENT_SIGNAL" mode="STATION"/>
<interface type="WIFI_INTERFACE" name="wlan1" macAddress="AA:BB:CC:DD:EE:01" state="NETWORK_WIFI_DISCONNECTED"/>
</interfaces>
</networkInfo>

Ethernet Device Response (Real API) 

<networkInfo wifiProfileCount="3">
<interfaces>
<interface type="ETHERNET_INTERFACE" name="eth0" macAddress="AA:BB:CC:DD:EE:FF" ipAddress="192.0.2.10" state="NETWORK_ETHERNET_CONNECTED"/>
</interfaces>
</networkInfo>

Go Usage:

networkInfo, err := client.GetNetworkInfo()
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Device ID: %s\n", networkInfo.GetDeviceID())
fmt.Printf("Interfaces: %d\n", len(networkInfo.GetInterfaces()))

// Check connectivity
if networkInfo.HasWiFi() {
    fmt.Println("WiFi available")
}
if networkInfo.HasEthernet() {
    fmt.Println("Ethernet available")
}

// Iterate through interfaces
for i, iface := range networkInfo.GetInterfaces() {
    fmt.Printf("Interface %d:\n", i+1)
    fmt.Printf("  Type: %s\n", iface.GetType())
    fmt.Printf("  MAC: %s\n", iface.GetMacAddress())
    fmt.Printf("  IP: %s\n", iface.GetIPAddress())
    fmt.Printf("  Active: %v\n", iface.IsActive())
}

// WiFi profile information (if available)
if profile := networkInfo.GetWiFiProfile(); profile != nil {
    fmt.Printf("WiFi SSID: %s\n", profile.GetSSID())
    fmt.Printf("Security: %s\n", profile.GetSecurity())
    fmt.Printf("Signal: %d%% (%s)\n", profile.GetSignalStrength(), profile.GetSignalLevel())
}

// Network statistics (if available)
if stats := networkInfo.GetStatistics(); stats != nil {
    sent, received := stats.GetFormattedBytes()
    fmt.Printf("Data: %s sent, %s received\n", sent, received)
}

CLI Usage:

soundtouch-cli -host 192.0.2.100 -network-info

CLI Output Example (WiFi Device):

Network Information:
  WiFi Profiles: 2
  Total Interfaces: 2
  Active Interfaces: 1

Interface 1:
  • Type: WIFI_INTERFACE (wlan0)
  • MAC Address: AA:BB:CC:DD:EE:FF
  • IP Address: 192.0.2.10
  • State: WiFi Connected ✓
  • SSID: MyHomeNetwork
  • Signal: Excellent (90%)
  • Frequency: 5.5 GHz (5GHz)
  • Mode: Station (Client)
  • Summary: MyHomeNetwork (Excellent, 5GHz)

Interface 2:
  • Type: WIFI_INTERFACE (wlan1)
  • MAC Address: AA:BB:CC:DD:EE:01
  • State: WiFi Disconnected
  • Summary: Disconnected

Active WiFi Connection:
  • Network: MyHomeNetwork (Excellent, 5GHz)
  • Interface: wlan0
  • IP Address: 192.0.2.10

Connectivity Summary:
  ✓ WiFi Available (Connected)
  ✗ No Ethernet

Interface Types

Real SoundTouch Types

  • WIFI_INTERFACE: WiFi network interfaces with SSID, signal strength, and frequency data
  • ETHERNET_INTERFACE: Wired Ethernet network interfaces

Interface States

  • NETWORK_WIFI_CONNECTED: WiFi interface is connected to a network
  • NETWORK_WIFI_DISCONNECTED: WiFi interface is not connected
  • NETWORK_ETHERNET_CONNECTED: Ethernet interface is connected
  • NETWORK_ETHERNET_DISCONNECTED: Ethernet interface is not connected

Signal Levels

  • EXCELLENT_SIGNAL: 90% quality
  • GOOD_SIGNAL: 70% quality
  • FAIR_SIGNAL: 50% quality
  • POOR_SIGNAL: 30% quality
  • virtual: Virtual network interface

Data Models

ClockTime 

type ClockTime struct {
    XMLName xml.Name `xml:"clockTime"`
    Zone    string   `xml:"zone,attr,omitempty"`
    UTC     int64    `xml:"utc,attr,omitempty"`
    Value   string   `xml:",chardata"`
}

Key Methods:

  • GetTime() (time.Time, error): Parse time value
  • GetTimeString() string: Formatted time string
  • IsEmpty() bool: Check if time data is available

ClockDisplay 

type ClockDisplay struct {
    XMLName    xml.Name `xml:"clockDisplay"`
    DeviceID   string   `xml:"deviceID,attr,omitempty"`
    Enabled    bool     `xml:"enabled,attr,omitempty"`
    Format     string   `xml:"format,attr,omitempty"`
    Brightness int      `xml:"brightness,attr,omitempty"`
    AutoDim    bool     `xml:"autoDim,attr,omitempty"`
    TimeZone   string   `xml:"timeZone,attr,omitempty"`
    Value      string   `xml:",chardata"`
}

Key Methods:

  • IsEnabled() bool: Check if clock display is enabled
  • GetFormat() string: Get format (12/24/auto)
  • GetBrightness() int: Get brightness (0-100)
  • GetBrightnessLevel() string: Get descriptive level

NetworkInformation 

type NetworkInformation struct {
    XMLName          xml.Name          `xml:"networkInfo"`
    WifiProfileCount int               `xml:"wifiProfileCount,attr,omitempty"`
    Interfaces       NetworkInterfaces `xml:"interfaces"`
}

type NetworkInterfaces struct {
    XMLName    xml.Name           `xml:"interfaces"`
    Interfaces []NetworkInterface `xml:"interface"`
}

Key Methods:

  • GetWifiProfileCount() int: Get number of WiFi profiles
  • GetInterfaces() []NetworkInterface: Get all interfaces
  • GetActiveInterfaces() []NetworkInterface: Get connected interfaces only
  • GetConnectedWiFiInterface() *NetworkInterface: Get active WiFi interface
  • GetConnectedEthernetInterface() *NetworkInterface: Get active Ethernet interface
  • HasWiFi() bool: Check WiFi availability
  • HasEthernet() bool: Check Ethernet availability

NetworkInterface 

type NetworkInterface struct {
    XMLName      xml.Name `xml:"interface"`
    Type         string   `xml:"type,attr"`
    Name         string   `xml:"name,attr,omitempty"`
    MacAddress   string   `xml:"macAddress,attr,omitempty"`
    IPAddress    string   `xml:"ipAddress,attr,omitempty"`
    SSID         string   `xml:"ssid,attr,omitempty"`
    FrequencyKHz int      `xml:"frequencyKHz,attr,omitempty"`
    State        string   `xml:"state,attr,omitempty"`
    Signal       string   `xml:"signal,attr,omitempty"`
    Mode         string   `xml:"mode,attr,omitempty"`
}

Key Methods:

  • IsConnected() bool: Check if interface is connected
  • IsWiFi() bool: Check if WiFi interface (WIFI_INTERFACE)
  • IsEthernet() bool: Check if Ethernet interface (ETHERNET_INTERFACE)
  • GetFrequencyGHz() float64: Get WiFi frequency in GHz
  • GetFrequencyBand() string: Get frequency band (2.4GHz/5GHz)
  • GetSignalQuality() int: Get signal strength percentage (0-100)
  • GetSignalDescription() string: Get readable signal level
  • GetNetworkSummary() string: Get connection summary
  • ValidateIP() bool: Validate IP address format
  • ValidateMAC() bool: Validate MAC address format

Error Handling

All system endpoints include comprehensive error handling:

Common Error Cases

  • Network errors: Connection timeouts, unreachable device
  • HTTP errors: 404 (endpoint not found), 500 (server error)
  • Validation errors: Invalid input parameters
  • XML parsing errors: Malformed responses

Error Response Format 

type APIError struct {
    XMLName xml.Name `xml:"error"`
    Code    int      `xml:"code,attr"`
    Message string   `xml:",chardata"`
}

Best Practices

  1. Always check for errors before using response data
  2. Use validation methods for input parameters
  3. Handle network timeouts gracefully
  4. Log detailed error information for debugging

Validation and Safety Features

Clock Time Validation

  • UTC timestamps must be between year 2000 and 2100
  • Time formats are automatically validated and parsed
  • Timezone information is preserved when available

Clock Display Validation

  • Brightness values are clamped to 0-100 range
  • Format values are validated (12/24/auto only)
  • Configuration changes require at least one parameter

Network Info Safety

  • IP and MAC address validation methods provided
  • Interface status checking with multiple criteria
  • Graceful handling of missing optional fields

Integration Examples

Complete Device Setup 

func setupDevice(host string) error {
    client := client.NewClientFromHost(host)
    
    // Set device time to current time
    if err := client.SetClockTimeNow(); err != nil {
        return fmt.Errorf("failed to set time: %w", err)
    }
    
    // Configure clock display
    err := client.SetClockDisplayFormat(models.ClockFormat24Hour)
    if err != nil {
        return fmt.Errorf("failed to set clock format: %w", err)
    }
    
    err = client.SetClockDisplayBrightness(50)
    if err != nil {
        return fmt.Errorf("failed to set brightness: %w", err)
    }
    
    err = client.EnableClockDisplay()
    if err != nil {
        return fmt.Errorf("failed to enable clock: %w", err)
    }
    
    // Check network connectivity
    networkInfo, err := client.GetNetworkInfo()
    if err != nil {
        return fmt.Errorf("failed to get network info: %w", err)
    }
    
    activeInterfaces := networkInfo.GetActiveInterfaces()
    if len(activeInterfaces) == 0 {
        return fmt.Errorf("no active network interfaces found")
    }
    
    log.Printf("Device setup complete with %d active network interfaces", len(activeInterfaces))
    return nil
}

Network Diagnostics 

func diagnoseNetwork(host string) error {
    client := client.NewClientFromHost(host)
    
    networkInfo, err := client.GetNetworkInfo()
    if err != nil {
        return fmt.Errorf("failed to get network info: %w", err)
    }
    
    fmt.Printf("Network Diagnostics for %s:\n", networkInfo.GetDeviceID())
    
    interfaces := networkInfo.GetInterfaces()
    activeCount := len(networkInfo.GetActiveInterfaces())
    
    fmt.Printf("Total Interfaces: %d\n", len(interfaces))
    fmt.Printf("Active Interfaces: %d\n", activeCount)
    
    if activeCount == 0 {
        fmt.Println("⚠️  WARNING: No active network interfaces")
        return nil
    }
    
    for i, iface := range interfaces {
        fmt.Printf("\nInterface %d:\n", i+1)
        fmt.Printf("  Type: %s\n", iface.GetType())
        fmt.Printf("  MAC: %s", iface.GetMacAddress())
        if !iface.ValidateMAC() {
            fmt.Printf(" ❌ Invalid")
        }
        fmt.Printf("\n")
        
        fmt.Printf("  IP: %s", iface.GetIPAddress())
        if !iface.ValidateIP() {
            fmt.Printf(" ❌ Invalid")
        }
        fmt.Printf("\n")
        
        fmt.Printf("  Status: %s", iface.GetStatus())
        if iface.IsActive() {
            fmt.Printf(" ✅ Active")
        } else {
            fmt.Printf(" ❌ Inactive")
        }
        fmt.Printf("\n")
    }
    
    return nil
}

CLI Integration

All system endpoints are fully integrated into the CLI tool with comprehensive help and examples:

# View all system commands
soundtouch-cli -help

# Device time management
soundtouch-cli -host 192.0.2.100 -clock-time
soundtouch-cli -host 192.0.2.100 -set-clock-time now

# Clock display configuration  
soundtouch-cli -host 192.0.2.100 -clock-display
soundtouch-cli -host 192.0.2.100 -enable-clock
soundtouch-cli -host 192.0.2.100 -clock-format 24
soundtouch-cli -host 192.0.2.100 -clock-brightness 75

# Network diagnostics
soundtouch-cli -host 192.0.2.100 -network-info

Testing

Comprehensive test coverage includes:

  • Unit Tests: All models and validation logic
  • Integration Tests: HTTP client behavior with mock servers
  • Real Device Tests: Verified against actual SoundTouch hardware
  • Edge Case Tests: Error conditions and invalid inputs
  • CLI Tests: Command parsing and output formatting

API Compatibility

The system endpoints implementation is designed to be:

  • Backward Compatible: No breaking changes to existing APIs
  • Forward Compatible: Extensible for future SoundTouch features
  • Robust: Graceful handling of missing or unknown fields
  • Realistic: Based on actual device response structures

The implementation supports both the basic SoundTouch response format (SCM/SMSC interfaces) and potential enhanced formats with additional network details.

Last updated on
Spotify Account Addition Technical ReferenceVolume Control Implementation