SOUNDTUBE STNet 3rd Party Control Software API User Guide
- October 30, 2023
- SOUNDTUBE
Table of Contents
SOUNDTUBE STNet 3rd Party Control Software API
Overview
All SoundTube DNA devices have the ability to be controlled remotely by a 3rd party system. They utilize a simple ASCII over UDP protocol to allow for real- time control of a subset of the product features. This document describes the protocol that the UDP command interface uses.
Command Message Format
The control messages used by the direct UDP command interface have a very
simple format. No matter what the device, the format of the message is always
the same. The overall format of the message contains only printable ASCII
characters so that they can be debugged easily. Each message contains a number
of data fields each separated by a space. The message is then terminated with
a carriage return. The general format of a message is shown below:
Field Name | Description |
---|---|
The command that will be given to the device. | |
First optional parameter. See device command tables below for |
specific details
A typical message would look something like the following:
OV 1 25.0
Command Responses
Each command sent to a device should return a response. Like the original command, the response only contains printable ACSII characters, each field is separated by a space and the message is terminated carriage return. The general format of a response message is shown below.
Field Name | Description |
---|---|
Success or failure indication: “ACK” if successful; “NACK if |
unsuccessful
If the command is successful, the device will return an ACK response. The ACK
message for our example message above would be
ACK IG 1 25.0
If the command is processed but for some reason unsuccessful, the device will
return a NACK response instead of an ACK. Just like the ACK, the original
command will also be include in the NACK message.
NACK IG 1 25.0
There are cases where the device will not respond to a command at all. This is
caused when the device unable to process the message it was sent for some
reason. The most typical situation where this could happen is that the
terminating
UDP Port Configuration
Commands are sent by placing them in a UDP packet which is sent directly to the IP address of the device being controlled. All direct UDP messages should be sent to port 49494 of the recipient device. Responses to commands will be directed back to the specific IP address and port that the request originated from.
Commands – DNA
The following commands are available for the DNA.
Description
| Command| Param 1|
Param 2
---|---|---|---
Output Volume
| OUTPUT| Channel # (0 or 1)| None or (0.0 to 99.0 dB)
Location| LOCATION| “Device Location” (max32 characters)|
–
Load preset values
| LOAD PRESET| x (x = [0..9])| –
Save preset values| SAVE PRESET| x (x = [0..9])|
–
Version Info
| VERSION| –| –
Status Request| STATUS| |
Output Level
Ths command sets a output level for the amplifier outputs. The valid output level range is between -100 dB and +12 dB in 1 dB increments. An OUTPUT command without a level parameter will be acknowledged and returned with the current output level setting. This allows the command to be used as a “get” command.
Example command(Set): OUTPUT 0 0.0
Example response: ACK OUTPUT 0 0.0
Example command (Get): OUTPUT 0
Example response: ACK OUTPUT 0 0.0
Location
Command to get or set the location string used to describe where the amplifier is located.
Example command (Set): LOCATION LOBBY
Example response: ACK LOCATION LOBBY
Example command (Get): LOCATION
Example response:
Load/Save Presets
The LOAD PRESET and SAVE PRESET commands allow the different configurations to be saved as presets. There are ten presets available 0 through 9. A preset stores the devices configuration and includes the DSP settings, the output gain setting, and the location setting. The response to this command from the device is the same format as for a basic command response.
Example command:
LOAD PRESET 5
SAVE PRESET 3
Example response:
ACK LOADPRESET 5
ACK SAVE PRESET 3
Version
Returns the software version of the host processor. The command takes no
parameters.
Example command: VERSION
Example response: ACK VERSION 1.3
Status Request
The amplifier responds to a status request message, but also has support for asynchronous status messaging to more efficiently updated 3rd party monitoring software on the network.
The status request message has the following syntax and response parameters.
Response| Param 1 ( Speaker Status)| Param 2 (Amp Error
Status)| Param 3 (Over Temp Status)| Param 4 (Power Source)
---|---|---|---|---
ACK STATUS| 0 = OK
a = Impedance Error| 0 = OK
1 = Amplifier Error| 0 = OK
1 = Over Temp| 0 = PoE+
1 = DC Powered
2 = PoE
Example command: STATUS
Example response:
BIAMP
“ACK [BI] STATUS a/b/c/d
Where a is a bitmask as follows:
bit(1) = tweeter
bit(2) = woofer
FULL
“ACK [FULL] STATUS a/b/c/d
Where a is a bitmask as follows:
bit(1) = master
bit(2) = slave 1
bit(3) = slave 2
bit(4) = slave 3
Firmware version 1.10
Additional Notes:
- The response to the “STATUS” command also now includes [BI] or [FULL] to indicate mode as “IPD (Bi-AMP)’ or “IPD4 (Full-channel)”
- The following values are returned: Both the BI-AMP and FULL-Channel bit order matches the GUI layout.
BI-AMP possible values are
0 – no error
- tweeter error
- woofer error
- tweeter and woofer error.
FULL range possible values are
0 – no error
- Master error
- speaker 1 error
- master and speaker 1 error
- speaker 2 error
- master and speaker 2 error
- speaker 1 and speaker 2 error
- master, speaker 1, speaker 2 error
- speaker 3 error
- master and speaker 3 error
- speaker 1 and speaker 3 error
- master, speaker 1, and speaker 3 error
- speaker 2 and speaker 3 error
- master, speaker 2, and speaker 3 error
- speaker 1, speaker 2, and speaker 3 error
- master, speaker 1, speaker 2, and speaker 3 error
Multicast Status Message
A status message also gets sent asynchronously to the multicast IP address of 239.254.50.123 on port 49494. The message format is slightly different that the polled status message.
Example response: AMP-STATUS 0 0 0 0
Response| Param 1 (Amp Error Status)| Param 2 (Over Temp
Status)| Param 3 ( Speaker Status)
---|---|---|---
AMP-STATUS| 0 = OK
1 = Amplifier Error| 0 = OK
1 = Over Temp| 0 = OK
1 = Impedance Error
Document Information
Document title: | DNA 3rd Party Control |
---|---|
Document file name: | DNA 3rd Party Software API.pdf |
Revision number: | <03> |
Issued by: | SoundTube |
Issue Date: | 2/25/2022 |
Status: | Released |
Revision | Date |
--- | --- |
01 | 10/23/15 |
02 | 10/17/17 |
03 | 02/25/22 |
(previously 1 or 2)
Customers Support
SoundTube Entertainment
13720 W. 109th St., Lenexa, KS 66215
Phone 855.663.5600
www.soundtube.com
625-00010 Rev 03
References
- SoundTube Entertainment - Home | MSE Audio - MSE Audio
- SoundTube Entertainment - Home | MSE Audio - MSE Audio
Read User Manual Online (PDF format)
Read User Manual Online (PDF format) >>