Sennheiser Sound Control Protocol (SSC) versatile command, control, and configuration for networked audio systems Developer‘s guide for evolution wireless D1 Sennheiser electronic GmbH & Co. KG Am Labor 1, 30900 Wedemark, Germany, www.sennheiser.com TI 1093 v2.
Table of Contents 1.... Introduction.........................................................................................................................................6 2... Open Sound Control Overview.......................................................................................................... 7 2.1....... JavaScript Object Notation Overview.........................................................................................7 3... Conventions........................................
6.6...... IEEE 802.15.4 / ZigBee / DECT................................................................................................. 29 6.7...... Low-bandwidth serial infrared link........................................................................................... 29 6.8...... Byte-stream connections (serial interface etc.)...................................................................... 29 6.9...... Unidirectional low-bandwidth monitoring..................................................
8.39.... /rx1/pair....................................................................................................................................... 43 8.40.... /rx1/rf_quality............................................................................................................................. 44 8.41..... /rx1/rf_stack_active................................................................................................................... 44 8.42.... /rx1/walktest............................
9.4.6..... 408 Request Timeout........................................................................................................... 54 9.4.7...... 409 Conflict........................................................................................................................... 55 9.4.8..... 410 Gone................................................................................................................................ 55 9.4.9..... 413 Request Entity Too Large...........................
Introduction 1. Introduction Modern professional audio devices are designed as building blocks for large, complex systems.
Open Sound Control Overview 2. Open Sound Control Overview Open Sound Control (OSC) is a protocol developed at The Center For New Music and Audio Technology (CNMAT) at University of California, Berkeley. The OSC specification Version 1.1 is available from the Open Sound Control website at: http://www.opensoundcontrol.org/ . The OSC Schema defined by MicroOSC at: http://cnmat.berkeley.
Conventions 3. Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP14/RFC 2119, "Key words for use in RFCs to Indicate Requirement Levels". 3.
SSC Data Structure Specification 4. SSC Data Structure Specification 4.1 Applying JSON to the OSC device model OSC models the controlled device as a tree-shaped hierarchy of methods, with the method addresses constructed from the names of all the nodes in the hierarchy, written like a file path.
SSC Data Structure Specification 4.2 JSON Message Transaction Syntax The SSC Message exchange is described here as transaction using the following syntax: Prefix"TX:" indicates an SSC Message that an SSC Client is sending to an SSC Server. Prefix "RX:" indicates an SSC Message that the SSC Server will send back to the Client. An SSC-Message is written verbatim, enclosed by curly brackets { }.
SSC Data Structure Specification • string => boolean: Any non-empty string is true, an empty string is false. • number => string: a string representation of the number suitable for interpretation by strtod() is used. • number => boolean: Number zero is false, everything else is true. • boolean => string: true results in "true", false in an empty string "". • boolean => number: true is 1, false is 0. 4.3.2 SSC Messages A Message is the protocol unit of transmission.
SSC Data Structure Specification to other SSC Methods; the JSON syntax of hierarchical objects SHOULD be used instead. SSC Methods MAY be overloaded with respect to their arguments: the SSC Server may execute the method in different ways depending on the arguments given. SSC Methods MAY also be overloaded with respect to their Address: the SSC Server may execute a different SSC Method instead, and reply with an SSC Method Reply to that different SSC Method Address ("aliased" SSC Methods).
SSC Data Structure Specification implementation. If the SSC Server does not support address pattern matching, it MUST treat the special pattern characters like normal characters. An SSC Client can find out whether address patterns are supported by receiving error replies, or by calling the SSC Method /osc/feature/pattern. 4.3.5 Temporal Semantics and SSC Time Tags Per default, the SSC Server shall invoke the SSC Methods addressed by an SSC Message immediately, i.e.
General SSC Address Schema 5. General SSC Address Schema Some parts of the SSC address space are reserved by this specification for purposes of meta-protocol information, generic device-independent features, and device capability description. The reserved parts of the address space are rooted in the addresses: /osc /device /internal The addresses and methods rooted in these reserved addresses are described in the following sections.
General SSC Address Schema TX: { "out1": { "xlr1": { "mute": true }, "xlr23": { "gain": 3 }}, "out2": { "xlr1": { "gain": 42 }}} RX: { "osc": { "error": [ { "out1": { "xlr23": [ 404, { "desc": "not found" }]}, "out2": { "xlr1": [ 307, { "desc": "not just now" }]} }]}, "out1": { "xlr1": { "mute": true }}} If the request message violates the JSON syntax, the complete message cannot reliably be parsed and MUST NOT be partially parsed or executed, so that the SSC Server MUST send an error response (400, "n
General SSC Address Schema 403 forbidden 404 address not found 406 not acceptable (e.g., wrong type for parameter) 408 request time out 409 conflict 410 gone 413 request too long 414 request too complex 422 unprocessable entity (error in a complex method parameter) 423 locked 424 failed dependency 450 answer too long 454 parameter address not found (e.g., address in a subscription request) 5xx – Server Error 500 internal server error 501 not implemented 503 service unavailable 5.1.
General SSC Address Schema An alternative representation of the same SSC Reply in a format that unbundles the SSC Address Tree into an array of SSC Addresses is: RX: { "osc": { "schema": [ { "out1": { "xlr1": {} }}, { "out1": { "xlr2": {} }} ] }} SSC Clients MUST be able to understand both bundled and unbundled Replies. Note that the responses are empty JSON objects if the address is an SSC Container for more addresses, JSON null if the address is an SSC Method Address.
General SSC Address Schema 5.1.7 Connection-specific SSC Address Space - /osc/state SSC Methods under the /osc/state Address have results which are specific to the connection between SSC Client and SSC Server. This means that it is possible that different SSC Clients invoke the same SSC Method with different arguments, and the immediate reply as well as the resulting state of the SSC Server will differ for each SSC Client.
General SSC Address Schema 5.1.9.1 Subscription notification rate parameters Optional subscription request parameters related to notification rate: • "min" minimum notification period (ms), 0=none, default 0 • "max" maximum notification period (ms), 0=none, default 0 • "bw" maximum bandwidth for replies (byte/s), 0=unlimited, default 0 If "min" is 0, then notifications are not sent when a subscribed address changes in value, they are only sent based on the "max" period.
General SSC Address Schema same time into a single notification. The SSC Client MUST be able to handle a bundled notification if it requests multiple subscriptions in a single request, but it MUST NOT rely on the SSC Server bundling the notifications.
General SSC Address Schema 5.1.9.5 Subscription example transactions Standard case: subscription request, reply and notifications, automatically terminated: TX: { "osc": { "state": { "subscribe": [ { "out1": { "xlr2": { "level": null }}} ] }}} RX: { "osc": { "state": { "subscribe": [ { "out1": { "xlr2": { "level": null }}} ] }}} RX: { "out1": { "xlr2": { "level": 15 }}} ... RX: { "out1": { "xlr2": { "level": 3 }}} ... RX: { "out1": { "xlr2": { "level": 9 }}} ...
General SSC Address Schema Subscribing to multiple addresses, requesting error details, only partially successful: TX: { "osc": { "state": { "subscribe": [ { "out1": { "xlr1": { "level": null, "nope": null }, "xlr2": [ "invalid address" ] } } ] } }, { "error": null }} RX: { "osc": { "state": { "subscribe": [ { "out1": { "xlr1": { "level": null }}} ] }}, { "error": [ "osc": { "state": { "subscribe": [ 210, { "desc": "Partial Success", "failed_addresses": [ { "osc": { "xlr1": { "nope": 404
General SSC Address Schema Example: TX: RX: TX: RX: { { { { "osc": { "state": {"baseaddr":[{ "out1": {"xlr2": null}}] }} "osc": { "state": {"baseaddr":[{ "out1": {"xlr2": null}}] }} "gain": -10 } "gain": -10 } The SSC Client may query the server for the support of this feature by invoking /osc/feature/baseaddr. 5.1.
General SSC Address Schema 5.1.15 SSC protocol feature reflection - /osc/feature This SSC Address Space is provided to enable the SSC Client to query the SSC Server whether optional protocol features are supported. In the spirit of extensibility, the SSC Server MUST send a reply with a value of false for each feature that is doesn’t know about, even if the feature didn’t exist at all when the server was implemented. 5.1.15.
General SSC Address Schema 5.2.4 /device/identity/vendor Read-only string: often "Sennheiser". 5.2.5 /device/name User-settable persistent device name. This name should be the preferred, and most convenient way for the customer to identify devices. If the device has a display, this name should be displayed there; if it has a menu, this name should be configurable. If the device is networked, this name shall be used as the name for device discovery.
General SSC Address Schema Internal interfaces which are not accessible to the user MUST NOT be listed here. All accessible physical ports MUST be listed here, even if they all can only be used in a shared configuration, e.g., if they are connected to an internal switch. 5.2.10.2 /device/network/ether/macs Read-only array containing a list of the MAC addresses of all the user-relevant ethernet interface of the device. The order of the list matches /device/network/ether/interfaces.
SSC Transport Layer Adaptations 6. SSC Transport Layer Adaptations The SSC data format as defined in the previous sections can be transported by different transport protocols, or stored in persistent files. This section specifies what transports are supported, and how the specific features of transport layers shall be applied to transporting SSC Messages. 6.
SSC Transport Layer Adaptations Type eases integration of SSC-over-HTTP into Web-Apps using JSON libraries. The SSC Client MUST send SSC Messages to the SSC Server as the contents of HTTP POST requests. The Reply of the server is transported back as the contents of the HTTP response.
SSC Transport Layer Adaptations HTTP may be provided by the SSC Server as HTTP-over-TLS, optionally secured with server or even client side certificates, if absolute security is required for the SSC system. 6.4 Secure Shell Transport/TCP/IP This is handled exactly like TCP/IP transport. 6.5 SSC Server Discovery Networked devices implement DNS-SD (Apple Bonjour) as discovery protocol. The DNS Service-Type is specified as "_ssc".
SSC Transport Layer Adaptations Normally, a configuration file would contain only one SSC Message, encompassing all configurable settings. Multiple SSC Messages have the same semantics as if they were sent to an SSC Server in the sequence as they appear in the file. Allowing multiple Messages in configurations is useful for log-structured config files, where each setting may be appended, one at a time, as they are configured by the user handling the device.
Developer’s Guide for evolution wireless D1 7. Developer’s Guide for evolution wireless D1 This chapter describes in detail how a developer should use the SSC interface as implemented for the evolution wireless D1. 7.1 Limitations 7.1.1 SSC Transport Layer The SSC Server implemented for Wennebostel devices supports only UDP/IP as transport protocol. All the devices support both IPv4 and IPv6. 7.1.
SSC Method List 8. SSC Method List 8.1 /interface/version Parameter type: String Permission: Read only Pre-condition: N.A. Post-condition: N.A. Description: SSC interface version. Example: TX: {"interface":{"version":null}} RX: {"interface":{"version":"1.0"}} 8.2 /osc/xid Parameter type: N.A. Permission: N.A. Pre-condition: N.A. Post-condition: N.A.
SSC Method List be chosen from the SSC Error List detailed in chapter ""”9. SSC Error List”"". Examples: TX: RX: TX: RX: TX: RX: 8.5 {"out1":{"gain":10}} {"osc":{"error":[{{"out1":[404]}}]}} <-- not found {"write_protection":true} {"osc":{"error":[{"write_protection":[406]}]}} <-- read only {"osc":{"limits":[{"internal":{"debug_screen":null}}]}} {"osc":{"error":[{"osc":{"limits":[454]}}]}} <-- hidden /osc/schema Parameter type: N.A. Permission: N.A. Pre-condition: N.A. Post-condition: N.A.
SSC Method List Examples: TX: {"osc":{"limits":[{"brightness":null}]}} RX: {"osc":{"limits":[{"brightness":[{"type":"Number","max":100,"min":0, "inc":1,"units":"%"}]}]}} TX: {"osc":{"limits":[{"audio":{"equalizer":{"preset":null}}}]}} RX: {"osc":{"limits":[{"audio":{"equalizer":{"preset":[{"type":"Number", "desc":"EQ presets","option":[0,1,2,3,4,5,6,7,8,9,10,11,12,13], "option_desc":["Off","Custom","Vocals","Presence Boost","Mid Cut 1", "Mid Cut 2","High Mid Cut","Low Mid Cut","High Boost", "High Cut", "Me
SSC Method List 8.10 /osc/feature/timetag Parameter type: Boolean. Permission: Read only. Pre-condition: N.A. Post-condition: N.A. Description: A client may query /osc/feature/timetag to inquire whether the SSC Server supports timed method execution. Example: TX: {"osc":{"feature":{"timetag":null}}} RX: {"osc":{"feature":{"timetag":false}}} 8.11 /osc/state/subscribe Parameter type: N.A. Permission: N.A. Pre-condition: N.A. Post-condition: N.A.
SSC Method List Example 3 – multi-parameter with non-default parameter: TX: {"osc":{"state":{"subscribe":[{"#":{"lifetime":2000},"rx1": {"mute_switch_active":null},"mates":{"tx1":{"bat_lifetime":null, "bat_gauge":null,"switch1":{"state":null}}}}]}}} RX: {"osc":{"state":{"subscribe":[{"#":{"lifetime":2000},"rx1": {"mute_switch_active":null},"mates":{"tx1":{"bat_gauge":null}}, "mates":{"tx1":{"bat_lifetime":null}},"mates":{"tx1":{"switch1": {"state":null}}}}]}}} RX: {"rx1":{"mute_switch_active":false},"mates
SSC Method List 8.14 /device/name Parameter type: String Permission: Read/Write, Subscribe-able Pre-condition: N.A. Post-condition: N.A. Description: User-settable persistent device name. This name should be the preferred, and most convenient way for the customer to identify devices. If the device has a display, this name should be displayed there; if it has a menu, this name should be configurable. If the device is networked, this name shall be used as the name for device discovery.
SSC Method List 8.17 /device/identity/version Parameter type: String Permission: Read only Pre-condition: N.A. Post-condition: N.A. Description: Device firmware version. Example: TX: {"device":{"identity":{"version":null}}} RX: {"device":{"identity":{"version":"2.0.0"}}} 8.18 /device/identity/serial Parameter type: String Permission: Read only Pre-condition: N.A. Post-condition: N.A. Description: Unique product number, identical to the number on a product label. The value is given by production.
SSC Method List 8.21 /device/network/ether/macs Parameter type: String Permission: Read only Pre-condition: N.A. Post-condition: N.A. Description: Read-only array containing a list of the MAC addresses of all the user-relevant Ethernet interface of the device. The order of the list matches /device/network/ether/interfaces. The MAC addresses are specified as strings in standard hex-colon-notation.
SSC Method List Example: TX: {"device":{"network":{"ipv4":{"ipaddr":null}}}} RX: {"device":{"network":{"ipv4":{"ipaddr":["192.168.1.203"]}}}} 8.25 /device/network/ipv4/netmask Parameter type: String Permission: Read only Pre-condition: N.A. Post-condition: N.A. Description: Read-only array containing a list of the current IPv4 netmasks of all the user-relevant Ethernet interface of the device. The order of the list matches /device/network/ether/interfaces.
SSC Method List Ethernet interface of the device. The order of the list matches /device/network/ether/interfaces. The IPv4 addresses are specified as strings in standard dot-decimal notation. The stored IPv4 netmasks in EEPROM are used by the device if /device/network/ipv4/auto is set to false during start-up of the device. Example: TX: {"device":{"network":{"ipv4":{"fixed_netmask":["255.255.255.0"]}}}} RX: {"device":{"network":{"ipv4":{"fixed_netmask":["255.255.255.0"]}}}} 8.
SSC Method List 8.32 /device/state Parameter type: Number (limit range) Permission: Read only, Subscribe-able Pre-condition: N.A. Post-condition: N.A. Description: Method to retrieve the state of the sRX1. Index Description 0 Normal 1 Pairing 2 Receiver Update 3 Transmitter Update 4 Transmitter Update Confirmation 5 Transmitter Update Failed Examples: TX: {"device":{"state":null}} RX: {"device":{"state":4}} 8.
SSC Method List Example: TX: {"device":{"max_rf_power_level":null}} RX: {"device":{"max_rf_power_level":10}} 8.36 /device/reset Parameter type: Boolean Permission: Read/Write Pre-condition: N.A. Post-condition: N.A. Description: A soft reset may be necessary for some configuration settings to take effect. Example: TX: {"device":{"reset":true}} RX: {"device":{"reset":true}} 8.37 /device/factory_reset Parameter type: Boolean Permission: Read/Write Pre-condition: N.A.
SSC Method List 8.40 /rx1/rf_quality Parameter type: Number Permission: Read only, Subscribe-able Pre-condition: N.A. Post-condition: N.A. Description: Method to the RF quality in percentage. Example: TX: {"rx1":{"rf_quality":null}} RX: {"rx1":{"rf_quality":50}} 8.41 /rx1/rf_stack_active Parameter type: Boolean Permission: Read/Write, Subscribe-able Pre-condition: N.A. Post-condition: The change has immediately effect. Description: Method to enable/disable the RF stack on the receiver.
SSC Method List 8.44 /rx1/autolock Parameter type: Boolean Permission: Read/Write, Subscribe-able Pre-condition: N.A. Post-condition: The change has immediately effect. Description: Method to modify/get the auto-lock state of the sRX1. This parameter is related to the sRX1 UI menu item "Auto Lock" under "System Settings". Example: TX: {"rx1":{"autolock":null}} RX: {"rx1":{"autolock":true}} 8.
SSC Method List 8.48 /mates/tx1/device_type Parameter type: Number (limit range) Permission: Read, Subscribe-able Pre-condition: /mates/tx1 must be active. Post-condition: NA. Description: Method to retrieve the transmitter type. Index Description 0 Handheld 1 Bodypack 2 Tablestand 3 Boundary Example: TX: {"mates":{"tx1":{"device_type":null}}} RX: {"mates":{"tx1":{"device_type":2}}} 8.
SSC Method List 8.51 /mates/tx1/bat_gauge Parameter type: Number Permission: Read only, Subscribe-able Pre-condition: Link must be established between transmitter and sRX1. Post-condition: N.A. Description: Method to retrieve the capacity of the rechargeable battery, or in case a battery is used the battery voltage level in percentage. Examples: TX: {"mates":{"tx1":{"bat_gauge":null}}} RX: {"mates":{"tx1":{"bat_gauge":100}}} 8.
SSC Method List 8.55 /mates/tx1/bat_cycles Parameter type: Number Permission: Read only, Subscribe-able Pre-condition: Link must be established between transmitter, powered by a rechargeable battery, and sRX1. Post-condition: N.A. Description: Method to retrieve the battery cycle count (charging cycles). Examples: TX: {"mates":{"tx1":{"bat_cycles":null}}} RX: {"mates":{"tx1":{"bat_bars":6}}} 8.
SSC Method List Connected with a MD42: TX: {"mates":{"tx1":{"acoustic":null}}} RX: {"mates":{"tx1":{"acoustic":"MD42"}}} 8.59 /mates/tx1/warnings Parameter type: String Permission: Read only, Subscribe-able Pre-condition: Link must be established between transmitter and sRX1. Post-condition: N.A. Description: Method to get transmitter warnings connected to the sRX1.
SSC Method List Example: TX: {"audio":{"out1":{"gain_db":10}}} RX: {"audio":{"out1":{"gain_db":10}}} 8.63 /audio/out1/type Parameter type: Number (limit range) Permission: Read/Write, Subscribe-able Pre-condition: The parameter value must be inside the index range [1,2]. Index Description 1 Mic 2 Line Post-condition: The change has immediately effect. Description: Method to retrieve/modify the Output type. This parameter is related to the sRX1 UI menu item "Output Type" under "Audio Settings".
SSC Method List 8.65 /audio/equalizer/preset Parameter type: Number (limit range) Permission: Read/Write, Subscribe-able Pre-condition: The parameter value must be inside the index range [0-13]. Index Description 0 Off 1 Custom 2 Vocals 3 Presence Boost 4 Mid Cut 1 5 Mid Cut 2 6 High Mid Cut 7 Low Mid Cut 8 High Boost 9 High Cut 10 Megaphone 11 Telephone 12 Acoustic Guitar 1 13 Acoustic Guitar 2 Post-condition: The change has immediately effect.
SSC Method List Pre-condition: The parameter value must be inside the index range [0-2]. Index Description 0 Off 1 Hard 2 Soft Post-condition: The change has immediately effect. Description: Method to retrieve/modify the AGC preset. This parameter is related to the sRX1 UI menu item "Auto Gain Control" under "Audio Settings". Example: TX: {"audio":{"agc":{"preset":null}}} RX: {"audio":{"agc":{"preset":0}}} 8.
SSC Error List 9. SSC Error List If the request message violates the JSON syntax, the complete message cannot reliably be parsed and MUST NOT be partially parsed or executed, so that the SSC Server MUST send an error response (400, "not understood") relating to the complete message, not to any method address. Error method results for successful method executions MUST NOT be sent without being explicitly requested by the client, by querying "/osc/error".
SSC Error List immediately, the SSC Server SHOULD respond with 202 (Accepted) response instead. 9.2.3 202 Accepted The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this. 9.2.4 210 Partial Success The request has been partially accepted for processing. 9.
SSC Error List The client did not produce a request within the time that the SSC Server was prepared to wait. The client MAY repeat the request without modifications at any later time. 9.4.7 409 Conflict The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.
SSC Error List 9.5.2 501 Not Implemented The SSC Server does not support the functionality required to fulfill the request. This is the appropriate response when the SSC Server does not recognize the request method and is not capable of supporting it for any resource. 9.5.3 503 Service Unavailable The SSC Server is currently unable to handle the request due to a temporary overloading or maintenance of the SSC Server.
