Sennheiser Sound Control Protocol v2 (SSCv2)

For the EventSource specification only the parameters data and event are used. For the parameter event only the following events are used:

• open, at the start of a subscription.
• message, when sending resource updates. As it is there by default, it MAY be omitted in the event stream.
• close, when the SSCv2 client actively closes the subscription by sending DELETE to /api/ssc/state/subscriptions/{sessionUUID} or when the subscription is closed because the device is initiating a reboot.

A full EventSource-compatible update looks as follows:

event: <eventtype>\ndata: <updatejson>\n\n

where \n denotes the ASCII character for a linefeed.

To initiate a subscription:

• The subscription is initialized by the SSCv2 client by issuing a GET request to /api/ssc/state/subscriptions
• The SSCv2 server replies to the subscription request immediately either by acknowledging the request, or by sending an error reply.
  • The SSCv2 server sends an initial message to the client, containing:
    • The Content-Type set to text/event-stream
    • The Content-Location containing the path /api/ssc/state/subscriptions/{sessionUUID}
    • where SessionUUID is the ID generated for the subscription and associated with the HTTP session. It can be used later to modify the subscription.
    • The initial open event, with the following data:

{
  "path": "/api/ssc/state/subscriptions/{sessionUUID}",
  "sessionUUID": "{sessionUUID}"
}

• The SSCv2 subscription is initially empty without any subscribed resources, and the SSCv2 client must subscribe to resources using /api/ssc/state/subscriptions/{sessionUUID} and /api/ssc/state/subscriptions/{sessionUUID}/add, respectively.
• An SSCv2 client must not send further regular HTTP requests to the SSCv2 server via the connection used to request the subscription. After the initial subscription request the connection can only be used to receive events from the SSCv2 server.

The resource for starting subscription is provided in the OpenAPI snippet below.

/api/ssc/state/subscriptions:
  get:
    summary: Start a subscription
    description: An SSCv2 Command to start a subscription
    responses:
      '200':
        description: Successful request
        headers:
          Content-Location:
            description: Location of the resource to be used to change the subscribed resources
            schema:
              type: string
        content:
          text/event-stream:
            schema:
              type: string
              description: The initial subscription stream.
      '403':
        description: User is not authorized to subscribe to resources
      '500':
        description: SSCv2 Server encountered internal error

The SSCv2 client can request the subscription status:

• Send a GET request to /api/ssc/state/subscriptions/{sessionUUID} using the previously received sessionUUID.
• If the sessionUUID is incorrect, an error is returned.

OpenAPI snippet:

/api/ssc/state/subscriptions/{sessionUUID}:
  get:
    summary: Get the subscription list
    description: An SSCv2 Command to retrieve the list of subscriptions associated with the sessionUUID
    parameters:
        - in: path
          name: sessionUUID
          schema:
            type: string
          required: true
    responses:
      '200':
        description: Successful request
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: /api/device/site
      '403':
        description: User is not allowed to get subscription list for this sessionUUID
      '422':
        description: sessionUUID did not exist
      '500':
        description: SSCv2 Server encountered internal error

It is possible to either change the full set of resources of a subscription, or to add/remove resources from the currently subscribed set.

The SSCv2 client can only subscribe to resources specifying a GET request, otherwise an error is returned.

An SSCv2 client can end a subscription either implicitly or explicitly.

• To end a subscription implicitly, the SSCv2 client simply closes the connection that receives the subscription data.
• To end a subscription explicitly, an SSCv2 client sends a DELETE request to the resource /api/ssc/state/subscriptions/{sessionUUID}.
  • The SSCv2 server sends a close event to the subscription before it closes the connection.
  • The data sent in the close event is the same as in the open event.

The SSCv2 server terminates a subscription in the following cases:

• The subscribed client cancels the subscription explicitly.
• The SSCv2 client closes the connection.
• The transport layer of the SSCv2 connection signals a fatal communication error.

OpenAPI snippet

/api/ssc/state/subscriptions/{sessionUUID}:
  delete:
    summary: End an existing subscription
    description: An SSCv2 Command to end the subscription associated with the sessionUUID
    parameters:
        - in: path
          name: sessionUUID
          schema:
            type: string
          required: true
    responses:
      '200':
        description: Successful request
      '403':
        description: User is not allowed to end subscription for this sessionUUID
      '422':
        description: sessionUUID did not exist
      '500':
        description: SSCv2 Server encountered internal error

The SSCv2 client may request to subscribe to multiple resources in a single request.

• If the SSCv2 server is not able to successfully subscribe to even one of the resources, it sends an error and refuses all resources.
• If there are already subscribed resources present, the previous state of the subscription remains unchanged.

When the SSCv2 server refuses a request for a subscription or a set of subscriptions, it returns an object containing the first resource which was not subscribable and the reason for the error.

• 403 if subscribing to the resource is not allowed.
• 404 if the resource does not exist.

A subscription notification constitutes Server Sent Event (SSE) data in the form of a JSON object, using the resource that triggered the notification as the key and the entities of the resource wrapped in a JSON object as the value.

• An SSCv2 server may combine notifications for multiple resources in one JSON object, if the updates occur at the same time.
• Since a newly created subscription of multiple addresses must report the values of the resources, this may be combined into a larger JSON object.
• If this combination of the different resources is not supported, all notifications must be sent in the stream as individual JSON objects.

The following example shows a stream containing a notification after an initial subscription and a later notification of a name change:

{
	"/api/device/site":  
  {
		"name": "MyDevice",
		"location": "Chemistry Building 5, Room 15",
		"site": "Left side near the big pillar"
	}
}
{
  "/api/device/site":  
  {
    "name": "MyRenamedDevice",
    "location": "Chemistry Building 5, Room 15",
    "site": "Left side near the big pillar"
	}
}

The address /api/device/site was subscribed, the initial values were reported. After some time the name was changed and the resulting update was sent as a second JSON object.