github/Bose-SoundTouch
1
0
Fork 0
mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-18 08:36:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(group): add ST-10 stereo-pair support end-to-end

Browse Source 
Implements the speaker-side group API surface (path 1 of the two
approaches gmuth outlined in issue #252): clients form, rename, and
dissolve stereo pairs directly on the device, and the resulting
GroupService.xml persists on disk in the same shape the device emits
over /getGroup.

What landed:

- pkg/models/group.go: Status field + IsEmpty() helper, matching the
  GET /getGroup response shape (id-attr, masterDeviceId, roles,
  senderIPAddress).
- pkg/client/client.go: GetGroup, AddGroup, UpdateGroup, RemoveGroup.
  The endpoint name is /getGroup (not /group, despite some wiki docs)
  — confirmed against a real ST-10's /supportedURLs. RemoveGroup uses
  GET per the wire spec.
- cmd/soundtouch-cli/cmd_group.go + main.go: new `group` subcommand
  with status / create --left --right [--name] / rename / remove,
  mirroring gmuth's group.sh recipe.

WebSocket notifications:

- pkg/models/websocket.go: EventTypeGroupUpdated +
  GroupUpdatedEvent + dispatch helpers. The device fans this out to
  both LEFT and RIGHT speakers on every group mutation, including
  empty-group teardowns; the parse test covers both shapes.
- pkg/client/websocket.go: OnGroupUpdated registration and dispatch.
- cmd/soundtouch-cli/cmd_events.go: `group` filter +
  handleGroupEvent formatter.

WebSocket observability (came up while validating the above against
a real device):

- New RawMessageHandler type + OnRawMessage hook that fires for every
  incoming frame before parsing, with the parse error alongside.
- New --debug flag on `events subscribe` with modes all / unknown /
  errors. Raw output goes to stderr so it composes cleanly with
  shell redirects.

The pkg/client refactor in this commit also adopts speaker.HTTPPort
(introduced in the previous refactor) — the unexported
defaultSoundTouchPort and three hard-coded 8090 literals are gone.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
2026-05-11 23:18:08 +02:00
co-authored by Claude Opus 4.7
parent c8c38b78e6
commit cbbbaa9707
9 changed files with 875 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/models/group.go
+9
View File
@@ -10,6 +10,15 @@ type Group struct {
MasterDeviceID string `xml:"masterDeviceId"`
Roles GroupRoles `xml:"roles"`
SenderIPAddress string `xml:"senderIPAddress,omitempty"`
// Status is populated by the device on GET /group (e.g. "GROUP_OK")
// and omitted from requests we send back.
Status string `xml:"status,omitempty"`
}
// IsEmpty reports whether the device returned an empty <group/> element,
// which is the speaker's way of saying "no stereo pair configured".
func (g *Group) IsEmpty() bool {
return g.ID == "" && g.MasterDeviceID == "" && len(g.Roles.Roles) == 0
}
// GroupRoles contains the role assignments for devices in a group.
pkg/models/websocket.go
+43
View File
@@ -21,6 +21,10 @@ const (
EventTypePresetUpdated WebSocketEventType = "presetsUpdated"
// EventTypeZoneUpdated indicates a zone configuration change
EventTypeZoneUpdated WebSocketEventType = "zoneUpdated"
// EventTypeGroupUpdated is emitted to both ROLE devices when an ST-10
// stereo pair is created, renamed, or removed via /addGroup,
// /updateGroup, or /removeGroup.
EventTypeGroupUpdated WebSocketEventType = "groupUpdated"
// EventTypeBassUpdated indicates a bass level change
EventTypeBassUpdated WebSocketEventType = "bassUpdated"
// EventTypeClockTimeUpdated indicates a clock time change
@@ -56,6 +60,8 @@ func (e WebSocketEventType) String() string {
return "Preset Updated"
case EventTypeZoneUpdated:
return "Zone Updated"
case EventTypeGroupUpdated:
return "Stereo Pair Updated"
case EventTypeBassUpdated:
return "Bass Updated"
case EventTypeClockTimeUpdated:
@@ -88,6 +94,7 @@ type WebSocketEvent struct {
ConnectionStateUpdated *ConnectionStateUpdatedEvent `xml:"connectionStateUpdated,omitempty"`
PresetUpdated *PresetUpdatedEvent `xml:"presetsUpdated,omitempty"`
ZoneUpdated *ZoneUpdatedEvent `xml:"zoneUpdated,omitempty"`
GroupUpdated *GroupUpdatedEvent `xml:"groupUpdated,omitempty"`
BassUpdated *BassUpdatedEvent `xml:"bassUpdated,omitempty"`
ClockTimeUpdated *ClockTimeUpdatedEvent `xml:"clockTimeUpdated,omitempty"`
ClockDisplayUpdated *ClockDisplayUpdatedEvent `xml:"clockDisplayUpdated,omitempty"`
@@ -122,6 +129,10 @@ func (e *WebSocketEvent) GetEvents() []interface{} {
events = append(events, e.ZoneUpdated)
}
if e.GroupUpdated != nil {
events = append(events, e.GroupUpdated)
}
if e.BassUpdated != nil {
events = append(events, e.BassUpdated)
}
@@ -215,6 +226,16 @@ type ZoneUpdatedEvent struct {
Zone Zone `xml:"zone"`
}
// GroupUpdatedEvent represents an ST-10 stereo-pair update notification.
// The device fans this event out to both LEFT and RIGHT speakers whenever
// the pair is created, renamed, or removed. Group will be the zero value
// for a teardown notification — see (*Group).IsEmpty.
type GroupUpdatedEvent struct {
XMLName xml.Name `xml:"groupUpdated"`
DeviceID string `xml:"deviceID,attr"`
Group Group `xml:"group"`
}
// Zone represents multiroom zone information
type Zone struct {
XMLName xml.Name `xml:"zone"`
@@ -373,6 +394,7 @@ type WebSocketEventHandlers struct {
OnConnectionState TypedEventHandler[*ConnectionStateUpdatedEvent]
OnPresetUpdated TypedEventHandler[*PresetUpdatedEvent]
OnZoneUpdated TypedEventHandler[*ZoneUpdatedEvent]
OnGroupUpdated TypedEventHandler[*GroupUpdatedEvent]
OnBassUpdated TypedEventHandler[*BassUpdatedEvent]
OnClockTimeUpdated TypedEventHandler[*ClockTimeUpdatedEvent]
OnClockDisplayUpdated TypedEventHandler[*ClockDisplayUpdatedEvent]
@@ -382,8 +404,19 @@ type WebSocketEventHandlers struct {
OnLanguageUpdated TypedEventHandler[*LanguageUpdatedEvent]
OnUnknownEvent EventHandler
OnSpecialMessage SpecialMessageHandler
// OnRawMessage fires for every received frame before any parsing
// happens. Use it for debug/observability tooling that wants to see
// exactly what the device sent on the wire — the typed handlers
// above still run afterwards, independently. parseErr is the result
// of the XML parse: nil for messages that decoded cleanly, non-nil
// for malformed payloads. The slice is owned by the caller; copy
// before retaining.
OnRawMessage RawMessageHandler
}
// RawMessageHandler defines the signature for raw-frame handlers.
type RawMessageHandler func(data []byte, parseErr error)
// ParseWebSocketEvent attempts to parse a WebSocket message into a specific event type
func ParseWebSocketEvent(data []byte) (*WebSocketEvent, error) {
var event WebSocketEvent
@@ -411,6 +444,8 @@ func (e *WebSocketEvent) getFieldByEventType(eventType WebSocketEventType) inter
field = e.PresetUpdated
case EventTypeZoneUpdated:
field = e.ZoneUpdated
case EventTypeGroupUpdated:
field = e.GroupUpdated
case EventTypeBassUpdated:
field = e.BassUpdated
case EventTypeClockTimeUpdated:
@@ -462,6 +497,8 @@ func isNil(i interface{}) bool {
return v == nil
case *ZoneUpdatedEvent:
return v == nil
case *GroupUpdatedEvent:
return v == nil
case *BassUpdatedEvent:
return v == nil
case *ClockTimeUpdatedEvent:
@@ -508,6 +545,8 @@ func (e *WebSocketEvent) HasEventType(eventType WebSocketEventType) bool {
return e.PresetUpdated != nil
case EventTypeZoneUpdated:
return e.ZoneUpdated != nil
case EventTypeGroupUpdated:
return e.GroupUpdated != nil
case EventTypeBassUpdated:
return e.BassUpdated != nil
case EventTypeClockTimeUpdated:
@@ -551,6 +590,10 @@ func (e *WebSocketEvent) GetEventTypes() []WebSocketEventType {
types = append(types, EventTypeZoneUpdated)
}
if e.GroupUpdated != nil {
types = append(types, EventTypeGroupUpdated)
}
if e.BassUpdated != nil {
types = append(types, EventTypeBassUpdated)
}
pkg/models/websocket_test.go
+84
View File
@@ -16,6 +16,7 @@ func TestWebSocketEventType_String(t *testing.T) {
{"ConnectionState", EventTypeConnectionState, "Connection State Updated"},
{"PresetUpdated", EventTypePresetUpdated, "Preset Updated"},
{"ZoneUpdated", EventTypeZoneUpdated, "Zone Updated"},
{"GroupUpdated", EventTypeGroupUpdated, "Stereo Pair Updated"},
{"BassUpdated", EventTypeBassUpdated, "Bass Updated"},
{"ClockTimeUpdated", EventTypeClockTimeUpdated, "Clock Time Updated"},
{"ClockDisplayUpdated", EventTypeClockDisplayUpdated, "Clock Display Updated"},
@@ -187,6 +188,89 @@ func TestParseWebSocketEvent(t *testing.T) {
t.Error("Expected error for invalid XML, got nil")
}
})
t.Run("ValidGroupUpdatedEvent", func(t *testing.T) {
// The device fans this out to both ROLE devices when a stereo
// pair is created via POST /addGroup.
xmlData := `<?xml version="1.0" encoding="UTF-8" ?>
<updates deviceID="9070658C9D4A">
<groupUpdated deviceID="9070658C9D4A">
<group id="1234567">
<name>Living Room Pair</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>
<status>GROUP_OK</status>
</group>
</groupUpdated>
</updates>`
event, err := ParseWebSocketEvent([]byte(xmlData))
if err != nil {
t.Fatalf("ParseWebSocketEvent: %v", err)
}
if !event.HasEventType(EventTypeGroupUpdated) {
t.Fatal("HasEventType(EventTypeGroupUpdated) = false, want true")
}
if event.GroupUpdated == nil {
t.Fatal("GroupUpdated is nil")
}
g := event.GroupUpdated.Group
if g.ID != "1234567" {
t.Errorf("group ID = %q, want 1234567", g.ID)
}
if g.MasterDeviceID != "9070658C9D4A" {
t.Errorf("MasterDeviceID = %q", g.MasterDeviceID)
}
if len(g.Roles.Roles) != 2 || g.Roles.Roles[0].Role != "LEFT" || g.Roles.Roles[1].Role != "RIGHT" {
t.Errorf("roles not parsed as LEFT/RIGHT: %+v", g.Roles.Roles)
}
if g.Status != "GROUP_OK" {
t.Errorf("status = %q, want GROUP_OK", g.Status)
}
})
t.Run("GroupUpdatedTeardown", func(t *testing.T) {
// On /removeGroup, the device emits a groupUpdated with an empty
// <group/> body. Parsing must surface that as IsEmpty=true so the
// UI can render "pair dissolved" cleanly.
xmlData := `<?xml version="1.0" encoding="UTF-8" ?>
<updates deviceID="9070658C9D4A">
<groupUpdated deviceID="9070658C9D4A">
<group/>
</groupUpdated>
</updates>`
event, err := ParseWebSocketEvent([]byte(xmlData))
if err != nil {
t.Fatalf("ParseWebSocketEvent: %v", err)
}
if event.GroupUpdated == nil {
t.Fatal("GroupUpdated is nil")
}
if !event.GroupUpdated.Group.IsEmpty() {
t.Errorf("Group.IsEmpty() = false on teardown; got %+v", event.GroupUpdated.Group)
}
})
}
func TestWebSocketEvent_HasEventType(t *testing.T) {