Exposing Sonos to HomeKit

Accessories

To deal with the static nature of the HomeKit configuration, homebridge-zp exposes accessories, services, and characteristics per zone, linking these dynamically to the zone group coordinator. This way, changes to zone groups won't result in HomeKit configuration changes.

To deal with the limited HomeKit support, the accessory, service, and characteristic types used by homebridge-zp can be configured in config.json.

The following table gives an overview of the accessories and services exposed by homebridge-zp:

Accessory	Service Name	Service Type	Description
Sonos			Bridged accessory per visible zone player (i.e. per visible zone). When leds is set in config.json: invisible zone players are also exposed, with only a LED service.
Sonos	Sonos	Switch*	Linked to the AVTransport, GroupRenderingControl, GroupManagement, and ContentDirectory services of the zone group coordinator.
Sonos	Speakers	Switch*	Linked to the RenderingControl and GroupManagement services of the zone master. When speakers is set in config.json.
Sonos	LED	Lightbulb	Linked to the DeviceProperties service of the zone player. When leds is set in config.json.
Sonos	Alarm #	Switch	Linked to the AlarmClock service of the zone master. When alarms is set in config.json.
Sonos TV			Non-bridged accessory per visible zone player (i.e. per zone). When tv is set in config.json.
Sonos TV	TV	Television	Linked to the AVTransport service of the zone group coordinator. When tv is set in config.json.
Sonos TV	TV Speaker	TelevisionSpeaker	Linked to the GroupRenderingControl service of the zone group coordinator. When tv is set in config.json.
Sonos TV	TV Input #	InputSource	Fixed number (20), linked to the GroupManagement and ContentDirectory services of the zone group coordinator. When tv is set in config.json.

*) Depending on the service setting in config.json, this can be a Switch, Speaker, Lightbulb, or Fan.

Sonos Accessory

The Sonos accessory is a bridged SPEAKER accessory, exposed through Homebridge's HAP server. The AccessoryInformation service exposes the following characteristics:

Characteristic	RW	Description
Name	R-	Based on the zone name, e.g. Living Room Sonos. Can be changed by setting nameScheme in config.json.
Manufacturer	R-	From the device description, e.g. Sonos
Model	R-	From the device description, e.g. Playbar (S9)
Firmware	R-	From the device description, e.g. 10.3
SerialNumber	R-	Device unique ID, e.g. RINCON_xxxxxxxxxxxx01400.

As homebridge-zp uses the dynamic platform accessory model, bridged accessories are persisted across Homebridge restarts in ~/.homebridge/accessories/cachedAccessories. To clear the cached accessories, delete this file (which will delete the cached accessories by all plugins), or run homebridge -R while preventing Homebridge form loading homebridge-zp, by excluding it from the plugins section in config.json, or by uninstalling homebridge-zp. Note that this will remove the accessory from HomeKit, losing any association to HomeKit rooms, scenes, and automations.

Sonos TV Accessory

The Sonos TV accessory is a standalone TELEVISION accessory, with its own HAP server, which needs to be paired separately. As this accessory contains a Television service, HomeKit hides it from other HomeKit apps. The AccessoryInformation service exposes the following characteristics:

Characteristic	RW	Description
Name	R-	Based on the zone name, e.g. Living Room Sonos. Can be changed by setting nameScheme in config.json.
Manufacturer	R-	From the device description, e.g. Sonos
Model	R-	From the device description, e.g. Playbar (S9)
Firmware	R-	From the device description, e.g. 10.3
SerialNumber	R-	Based on the device unique ID, e.g. TV_xxxxxxxxxxxx01400. Can be changed by setting tvIdPrefix in config.json.

Note that the "mac address" (username) and service name suffix of the TV accessory's HAP server are generated from the SerialNumber value. These need to be unique on your network, or Homebridge will crash because of a conflicting Bonjour announcement. If you want to run multiple instances of homebridge-zp on the same network (e.g. for testing), be sure to set tvIdPrefix to a different value in the config.json of each instance.

The port that Homebridge uses for the TV accessory's HAP server can be specified in config.json, see Homebridge's example config.json

Unlike bridged accessories, standalone accessories are not persisted in ~/.homebridge/accessories/cachedAccessories.

Services

Sonos Service

Speakers Service

Alarm Service

LED Service

TV Service

TV Speaker Service

TV Input Service

Challenge

HomeKit Configuration

While Sonos is brilliantly dynamic, up to the rendering of the controls by their app, HomeKit doesn't like configuration changes at all. When a bridged accessory is no longer exposed, HomeKit removes it, including any association to HomeKit rooms, scenes, and automations. Note that these HomeKit objects are not exposed over HAP, so the accessory (or Homebridge plugin) has no knowledge of these. When the accessory is re-exposed to HomeKit, it's treated as a new accessory, and you have to re-create the associations to HomeKit rooms, scenes, and automations.

HomeKit synchronises its configuration between iDevices over iCloud. This synchronisation can takes a considerable amount of time, up to half an hour or more. Accessories tend to be Unavailable during this synchronisation, or behave erratically. Simply put: changing accessory properties (services, characteristics, characteristic properties), whether dynamically, or by restarting Homebridge, is a bad idea.

HomeKit Support

While Apple does a brilliant job marketing HomeKit, the technical implementation differs significantly:

• Speakers and televisions supporting AirPlay 2 (including the Apple TV and Airport Express) can be accessed through Apple's Home app and through Siri, but this has nothing to do with HomeKit. The Home app and Siri use the Airplay 2 protocol to communicate with these devices. Other HomeKit apps cannot access these devices. Homebridge uses the HomeKit Accessory Protocol (HAP) and cannot expose AirPlay 2 speakers nor televisions. As far as I know, there are no open source implementations of AirPlay 2.
• The standard HomeKit Speaker service and corresponding Volume and Mute characteristics are defined for video doorbell accessories. Neither Siri nor Apple's Home app support these otherwise, but other HomeKit apps typically do.
• Televisions supporting HomeKit can be accessed through Apple's Home app, through Siri, and through the Remote Widget. While these televisions are exposed as regular HomeKit accessories using the HAP protocol, HomeKit hides these from other HomeKit apps. Also, a television accessory cannot be bridged. It needs to be exposed as a standalone accessory, which needs to be paired to HomeKit separately.