Sennheiser Sound Control Protocol (SSC) versatile command, control, and configuration for networked audio systems Developer‘s guide for EW-DX EW-DX EM 2 (Firmware 1.1.3) Sennheiser electronic GmbH & Co. KG Am Labor 1, 30900 Wedemark, Germany, www.sennheiser.com v1.1.
Table of Contents 1.... Introduction.........................................................................................................................................6 2... Open Sound Control Overview.......................................................................................................... 7 2.1....... JavaScript Object Notation Overview.........................................................................................7 3... Conventions........................................
8.24.... /device/link_density_mode........................................................................................................ 21 8.25.... /device/language........................................................................................................................ 21 8.26.... /device/frequency_ranges........................................................................................................ 22 8.27.... /device/frequency_code..............................................
8.73.... /rx2/sync_settings/trim............................................................................................................ 33 8.74.... /rx2/sync_settings/name_ignore............................................................................................. 33 8.75.... /rx2/sync_settings/mute_config_ignore................................................................................. 33 8.76.... /rx2/sync_settings/mute_config...........................................................
8.122... /mates/tx2/battery/gauge....................................................................................................... 50 8.123... /mates/tx2/warnings.................................................................................................................51 8.124... /mates/tx2/version.....................................................................................................................51 8.125... /mates/tx2/type......................................................
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 For command and control applications it is desirable to access single properties independently. This can be achieved in JSON syntax by the simple convention, that all the properties of a SSC Server that are not mentioned in a JSON message are left unchanged.
SSC Data Structure Specification 4.3.2 SSC Messages A Message is the protocol unit of transmission. Any application that sends SSC Messages is a SSC Client, any application that receives SSC Messages is a SSC Server. A SSC Message MUST be sent as a single closed JSON form describing a JSON object. Extra whitespace between the elements of the message MUST be ignored by the receiver. This means that every SSC Message is enclosed in a pair of curly brackets { }. 4.3.
SSC subscriptions - /osc/state/subscribe 5. SSC subscriptions - /osc/state/subscribe A subscription request is sent by a client to a server for an address pattern to subscribe to. The SSC Server normally accepts the subscription request, and remembers that the requesting client wishes to be notified about value changes of the subscribed addresses. The SSC Server MAY refuse subscription requests, subject to device-specific policy or implementation specific limitations.
SSC subscriptions - /osc/state/subscribe Optional subscription request parameters related to termination: • "cancel" "true" cancels the subscription (default false). • "count" maximum number of notifications to send, default 1000 • "lifetime" maximum lifetime (s) of the subscription, default 10s The SSC Client may renew a subscription at any time, thereby resetting all of the lifetime limitations.
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.
Developer’s Guide for EW-DX EM 2 7. Developer’s Guide for EW-DX EM 2 This chapter describes in detail how a developer should use the SSC interface as implemented for the EW-DX EM 2. 7.1 Limitations 7.1.1 SSC Transport Layer The SSC Server implemented for EW-DX devices supports only UDP/IP as transport protocol. All the devices support IPv4. 7.1.2 Subscriptions The EW-DX EM 2 receiver supports SSC Method subscriptions from up to eight different SSC clients simultaneously.
SSC Method List (EW-DX EM 2) 8. SSC Method List (EW-DX EM 2) 8.1 /device/identification/visual Command to start/stop device identification visual (true: start; false: stop; null: read status). • type: Read/Write • value: Number • limits type: Boolean const: false writeable: true subscr: true 8.2 /device/identity/version Product version. • type: Read-only • value: String • limits type: String const: true writeable: false 8.
SSC Method List (EW-DX EM 2) 8.6 /device/network/ether/macs List of MAC addresses. • type: Read-only • value: String • limits type: String const: true writeable: false count: 1 8.7 /device/network/ether/interfaces List of all Ethernet interfaces. • type: Read-only • value: String • limits type: String const: true writeable: false count: 1 8.8 /device/network/ipv4/manual_netmask Static (manual) Netmask like "255.255.255.0".
SSC Method List (EW-DX EM 2) 8.10 /device/network/ipv4/manual_gateway Static (manual) Gateway address like "192.168.1.1". • type: Read/Write • value: String • limits type: String const: false writeable: true count: 1 subscr: true 8.11 /device/network/ipv4/netmask Online Netmask like "255.255.255.0". • type: Read-only • value: String • limits type: String const: false writeable: false count: 1 subscr: true 8.
SSC Method List (EW-DX EM 2) 8.14 /device/network/ipv4/gateway Online Gateway address like "192.168.1.1". • type: Read-only • value: String • limits type: String const: false writeable: false count: 1 subscr: true 8.15 /device/network/ipv4/auto Command to configure IP settings automatically (true: use DHCP and ZeroConf (Auto-IP); false: set IP address/netmask/gateway manually).
SSC Method List (EW-DX EM 2) 8.19 /device/preset_spacing Get device preset spacing in kHz depending on LD mode being active or not. • type: Read/Write • value: Number • limits type: Number const: true writeable: false units: kHz Example: Tx: {"device":{"preset_spacing":null}} Rx: {"device":{"preset_spacing":300}} 8.20 /device/restore Command to restore device default settings.
SSC Method List (EW-DX EM 2) 8.23 /device/location Command to set or read the device location. • type: Read/Write • value: String • limits type: String const: false writeable: true length: 400 subscr: true 8.24 /device/link_density_mode Switch RF transmission link density mode on if true is specified or off (standard mode) if false is specified.
SSC Method List (EW-DX EM 2) 8.26 /device/frequency_ranges Command to read receiver device frequency ranges. Format of replied string array: ["::", "::",...
SSC Method List (EW-DX EM 2) 8.30 /osc/state/auth/access Read authentication access of current SSC client. Response value is an array of strings, comma separated. • limits type: String const: false writeable: false count: -1 subscr: true 8.31 /osc/state/prettyprint SSC reply output style is not supported. Returns false. • limits (hidden) 8.32 /osc/state/close SSC connection close. • limits (hidden) 8.33 /osc/state/subscribe SSC subscriptions. • limits (hidden) 8.
SSC Method List (EW-DX EM 2) 8.40 /osc/version SSC protocol version. • limits (hidden) 8.41 /osc/xid SSC transaction ID. • limits (hidden) 8.42 /osc/ping SSC ping. • limits (hidden) 8.43 /osc/error SSC error state. • limits (hidden) 8.44 /rx1/identification/visual Command to start/stop receiver channel 1 identification visual (true: start; false: stop; null: read status). • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.
SSC Method List (EW-DX EM 2) 8.46 /rx1/presets/active Set/get frequency from specific (presets) frequency list for receiver channel 1. • type: Read/Write • value: String • limits type: String const: false writeable: true subscr: true Example: select from factory list (index=0, channel=2): {"rx1":{"presets":{"active":"factory:0:2"}}} or select from user list (index=0, channel=1): {"rx1":{"presets":{"active":"user:0:1"}}} 8.
SSC Method List (EW-DX EM 2) 8.49 /rx1/sync_settings/name_ignore Skip/apply channel name setting on TX sync action for receiver channel 1. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.50 /rx1/sync_settings/mute_config_ignore Skip/apply mute configuration (mute mode) setting on TX sync action for receiver channel 1.
SSC Method List (EW-DX EM 2) 8.53 /rx1/sync_settings/lowcut TX low cut frequency for receiver channel 1. • type: Read/Write • value: String • limits type: String const: false writeable: true options: Option Description off off 30 Hz 30 Hz 60 Hz 60 Hz 80 Hz 80 Hz 100 Hz 100 Hz 120 Hz 120 Hz subscr: true 8.54 /rx1/sync_settings/lock_ignore Skip/apply Auto Lock setting on TX sync action for receiver channel 1.
SSC Method List (EW-DX EM 2) 8.57 /rx1/sync_settings/led TX LED off/on for receiver channel 1. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.58 /rx1/sync_settings/frequency_ignore Skip/apply frequency setting on TX sync action for receiver channel 1. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.
SSC Method List (EW-DX EM 2) 8.61 /rx1/warnings Active warnings on receiver channel 1 stored in an array of strings. Warnings: [Aes256Error, LowSignal, NoLink, RfPeak]. • type: Read-only • value: String • limits type: String const: false writeable: false count: -1 options: Option Description Aes256Error AES 256 error LowSignal LowSignal NoLink NoLink RfPeak RfPeak subscr: true Example: Tx: {"rx1":{"warnings":null}} Rx: {"rx1":{"warnings":["Aes256Error","RfPeak"]}} 8.
SSC Method List (EW-DX EM 2) 8.64 /rx1/mates Information about active mates of the receiver channel 1 stored as array of string values. • type: Read-only • value: String • limits type: String const: true writeable: false count: 1 Example: Tx: {"rx1":{"mates":null}} Rx: {"rx1":{"mates":["mates/tx1"]}} 8.65 /rx1/gain Gain level for receiver channel 1. Valid values in range [-3dB..+42dB], increment step = 3dB.
SSC Method List (EW-DX EM 2) 8.67 /rx1/audio Information about active audio inputs/outputs of the receiver channel 1 stored as array of string values. • type: Read-only • value: String • limits type: String const: true writeable: false count: 1 Example: Tx: {"rx1":{"audio":null}} Rx: {"rx1":{"audio":["audio1/out1"]}} 8.68 /rx1/restore Command to restore device audio default settings of receiver channel 1. Valid options: "AUDIO_DEFAULTS" (restore audio defaults only).
SSC Method List (EW-DX EM 2) 8.70 /rx2/presets/user/0 Set/get list of user frequencies [kHz] for receiver channel 2. • type: Read/Write • value: Number • limits type: Number const: false writeable: true count: -1 subscr: true Example: {"rx2":{"presets":{"user":{"0":[548000, 548300, 548600]}}}} 8.71 /rx2/presets/active Set/get frequency from specific (presets) frequency list for receiver channel 2.
SSC Method List (EW-DX EM 2) 8.73 /rx2/sync_settings/trim TX trim for receiver channel 2. • type: Read/Write • value: Number • limits type: Number const: false writeable: true units: dB max: 6 min: -12 inc: 1 subscr: true 8.74 /rx2/sync_settings/name_ignore Skip/apply channel name setting on TX sync action for receiver channel 2. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.
SSC Method List (EW-DX EM 2) 8.76 /rx2/sync_settings/mute_config TX mute configuration (mute mode) for receiver channel 2. • type: Read/Write • value: String • limits type: String const: false writeable: true options: Option Description off Disabled rf_mute RF Mute af_mute AF Mute subscr: true 8.77 /rx2/sync_settings/lowcut_ignore Skip/apply low cut frequency setting on TX sync action for receiver channel 2.
SSC Method List (EW-DX EM 2) 8.79 /rx2/sync_settings/lock_ignore Skip/apply Auto Lock setting on TX sync action for receiver channel 2. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.80 /rx2/sync_settings/lock TX Autolock off/on for receiver channel 2. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.
SSC Method List (EW-DX EM 2) 8.83 /rx2/sync_settings/frequency_ignore Skip/apply frequency setting on TX sync action for receiver channel 2. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.84 /rx2/sync_settings/cable_emulation_ignore Skip/apply cable emulation setting on TX sync action for receiver channel 2. • type: Read/Write • value: Boolean • limits type: Boolean const: false writeable: true subscr: true 8.
SSC Method List (EW-DX EM 2) 8.86 /rx2/warnings Active warnings on receiver channel 2 stored in an array of strings. Warnings: [Aes256Error, LowSignal, NoLink, RfPeak]. • type: Read-only • value: String • limits type: String const: false writeable: false count: -1 options: Option Description Aes256Error AES 256 error LowSignal LowSignal NoLink NoLink RfPeak RfPeak subscr: true Example: Tx: {"rx2":{"warnings":null}} Rx: {"rx2":{"warnings":["Aes256Error"]}} 8.
SSC Method List (EW-DX EM 2) 8.89 /rx2/mates Information about active mates of the receiver channel 2 stored as array of string values. • type: Read-only • value: String • limits type: String const: true writeable: false count: 1 Example: Tx: {"rx2":{"mates":null}} Rx: {"rx2":{"mates":["mates/tx2"]}} 8.90 /rx2/gain Gain level for receiver channel 2. Valid values in range [-3dB..+42dB], increment step = 3dB.
SSC Method List (EW-DX EM 2) 8.92 /rx2/audio Information about active audio inputs/outputs of the receiver channel 2 stored as array of string values. • type: Read-only • value: String • limits type: String const: true writeable: false count: 1 Example: Tx: {"rx2":{"audio":null}} Rx: {"rx2":{"audio":["audio1/out2"]}} 8.93 /rx2/restore Command to restore device audio default settings of receiver channel 2. Valid options: "AUDIO_DEFAULTS" (restore audio defaults only).
SSC Method List (EW-DX EM 2) 8.95 /audio1/out2/level AF output level for receiver channel 2. Valid values in range [-24dB..+18dB], increment step = 6dB. • type: Read/Write • value: Number • limits type: Number const: false writeable: true units: dB max: 18 min: -24 inc: 6 subscr: true 8.96 /m/rx1/rssi Returns RF radio signal strength indicator (RSSI) for receiver channel 1. • type: double (ro) • value range: -107.0..0.
SSC Method List (EW-DX EM 2) 8.98 /m/rx1/divi Returns RF diversity indicator for receiver channel 1. 0 is for None; 1 is for antenna input A; 2 is for antenna input B. • type: number (ro) • limits type: Number const: false writeable: false max: 2 min: 0 inc: 1 options: Option Description 0 none 1 antenna input A 2 antenna input B subscr: true Example: {"m":{"rx1":{"divi":null}}} 8.99 /m/rx1/af Returns audio level for receiver channel 1.
SSC Method List (EW-DX EM 2) 8.101 /m/rx2/rsqi Returns RF signal quality indicator for receiver channel 2. • type: number (ro) • value range: 0..100 [%] • limits type: Number const: false writeable: false units: % max: 100 min: 0 inc: 1 subscr: true Example: {"m":{"rx2":{"rsqi":null}}} 8.102 /m/rx2/divi Returns RF diversity indicator for receiver channel 2. 0 is for None; 1 is for antenna input A; 2 is for antenna input B.
SSC Method List (EW-DX EM 2) 8.103 /m/rx1/af Returns audio level for receiver channel 2. • type: double (ro) • value range: -138.5..0.0 [dBfs] • limits type: Number const: false writeable: false units: dBfs max: 0 min: -138.5 subscr: true 8.104 /mates/tx1/battery/type TX battery type info got from receiver channel 1 stored as string. Possible values: "Battery", "Primary Cell". Replied error code 424 indicates that TX is not present or doesn‘t send valid battery information.
SSC Method List (EW-DX EM 2) 8.106 /mates/tx1/battery/gauge TX battery gauge (charge in percent) got from receiver channel 1 stored as number. Replied error code 424 indicates that TX is not present or doesn‘t send valid battery gauge. • type: Read-only • value: int • limits type: Number const: false writeable: false units: % max: 100 min: 0 inc: 1 subscr: true Example: Tx: {"mates":{"tx1":{"battery":{"gauge":null}}}} Rx: {"mates":{"tx1":{"battery":{"gauge":65}}}} 8.
SSC Method List (EW-DX EM 2) 8.108 /mates/tx1/version TX SW version information got from receiver channel 1 stored as a string . Replied error code 424 indicates that TX is not present or doesn‘t send valid information. • type: Read-only • value: string • limits type: String const: false writeable: false subscr: true Example: Tx: {"mates":{"tx1":{"version":null}}} Rx: {"mates":{"tx1":{"version":"1.2.3"}}} 8.
SSC Method List (EW-DX EM 2) 8.111 /mates/tx1/name TX name information got from receiver channel 1 stored as a string. Replied error code 424 indicates that TX is not present or doesn‘t send valid information. • type: Read-only • value: string • limits type: String const: false writeable: false subscr: true Example: Tx: {"osc":{"state":{"subscribe":[{"#":{"min":0, "max":0,"count":1000, "lifetime":60},"mates":{"tx1":{"name":null}}}]}}} Rx: {"mates":{"tx1":{"name":"DEVICE2"}}} 8.
SSC Method List (EW-DX EM 2) 8.113 /mates/tx1/mute TX Mute Switch On/Off information got from receiver channel 1 stored as a bool. Replied error code 424 indicates that TX is not present or doesn‘t send valid information. • type: Read-only • value: bool • limits type: Boolean const: false writeable: false subscr: true Example: Tx: {"osc":{"state":{"subscribe":[{"#":{"min":0, "max":0,"count":1000, "lifetime":60},"mates":{"tx1":{"mute":null}}}]}}} Rx: {"mates":{"tx1":{"mute":true}}} 8.
SSC Method List (EW-DX EM 2) 8.116 /mates/tx1/led TX LED information got from receiver channel 1 stored as a bool. Replied error code 424 indicates that TX is not present or doesn‘t send valid information. • type: Read-only • value: bool • limits type: Boolean const: false writeable: false subscr: true Example: Tx: {"osc":{"state":{"subscribe":[{"#":{"min":0, "max":0,"count":1000, "lifetime":60},"mates":{"tx1":{"led":null}}}]}}} Rx: {"mates":{"tx1":{"led":true}}} 8.
SSC Method List (EW-DX EM 2) 8.119 /mates/tx1/cable_emulation TX cable emulation information got from receiver channel 1 stored as a string. Replied error code 424 indicates that TX is not present or doesn‘t send valid information.
SSC Method List (EW-DX EM 2) 8.121 /mates/tx2/battery/lifetime TX battery lifetime in minutes got from receiver channel 2 stored as number. Replied error code 424 indicates that TX is not present or doesn‘t send valid battery information. • type: Read-only • value: int • limits type: Number const: false writeable: false subscr: true Example: Tx: {"mates":{"tx2":{"battery":{"lifetime":null}}}} Rx: {"mates":{"tx2":{"battery":{"lifetime":312}}}} 8.
SSC Method List (EW-DX EM 2) 8.123 /mates/tx2/warnings TX warnings occuring on receiver active link channel 2 stored in an array of strings. Warnings: [AfPeak, LowBattery]. • type: Read-only • value: string • limits type: String const: false writeable: false count: -1 options: Option Description AfPeak AF Peak LowBattery Low Battery subscr: true Example: Tx: {"mates":{"tx2":{"warnings":null}}} Rx: {"mates":{"tx2":{"warnings":[]}}} 8.
SSC Method List (EW-DX EM 2) 8.126 /mates/tx2/trim TX trim information got from receiver channel 2 stored as a number. Replied error code 424 indicates that TX is not present or doesn‘t send valid information. • type: Read-only • value: number • limits type: Number const: false writeable: false units: dB max: 6 min: -12 inc: 1 subscr: true Example: Tx: {"mates":{"tx2":{"trim":null}}} Rx: {"mates":{"tx2":{"trim":-12}}} 8.
SSC Method List (EW-DX EM 2) 8.128 /mates/tx2/mute_config TX mute configuration (mute mode) information got from receiver channel 2 stored as a string. Replied error code 424 indicates that TX is not present or doesn‘t send valid information.
SSC Method List (EW-DX EM 2) 8.130 /mates/tx2/lowcut TX lowcut information got from receiver channel 2 stored as a string. Replied error code 424 indicates that TX is not present or doesn‘t send valid information. Valid strings: "off", "30 Hz", "60 Hz", ...
SSC Method List (EW-DX EM 2) 8.133 /mates/tx2/identification TX identification information got from receiver channel 2 stored as a boolean. Replied error code 424 indicates that TX is not present or doesn‘t send valid information.
SSC Method List (EW-DX EM 2) 8.135 /mates/tx2/cable_emulation TX cable emulation information got from receiver channel 2 stored as a string. Replied error code 424 indicates that TX is not present or doesn‘t send valid information.
SSC Error List (EW-DX EM 2) 9.
