Qsonix Integration - Manual (Page 6)

Qsonix Integration Guide
Page | 6
Introduction
This document describes how to communicate with Qsonix Digital Media Management Systems using either
RS-232 Serial or TCP/IP communications.
Serial Communications
The rear panel of the Qsonix systems unit has a standard DB-9
serial port labeled “Serial”. Typical connection to this port
requires use of a standard RS-232 null modem cable. Qsonix
systems support communications between 9600 to 38400
baud, 8 data bits, 1 stop bit, no parity, no flow control. Serial
configuration can be set by accessing the Integration tab under
System Settings in the Qsonix software.
Ethernet Communications
The Qsonix system also supports access via a TCP connection
using the same communication protocol found in this
document. The default port number for TCP communications is 5031. This port number can be
configured by accessing the Integration tab under the System Settings in the Qsonix software.
Command Structure
Commands sent to Qsonix systems will always end in a carriage return (ASCII 13). If a sequence of
characters is sent to the unit without ending in a carriage return (an incomplete command), it will be
ignored. The unit will wait up to 5 seconds for the command to be completed (by sending additional
characters including a carriage return) before clearing the input buffer and ignoring the incomplete
command.
A typical command will include a verb and one or more parameters. Parameters are always separated
from each other and from the verb by a space (ASCII 32). For example, the command to begin playback
for Zone 1 is “Play 1” and the command to set the volume for Zone 2 to 50% is “Volume 2 50”.
Command verbs are not case sensitive but are typically specified in proper case for ease of readability.
Some commands support optional parameters. Optional parameters are always last in the list of
parameters and they can be provided to give a more specific command. For example, the Next command
will cause the playback to skip to the next track in the now playing list for the specified zone. The Next
command can also skip forward by more than one track with a single command (example: “Next 2 5” will
skip playback of Zone 2 forward by 5 tracks). When optional parameters are omitted, a default value that
is specified in the command description will be used.
Some parameters will be full strings (such as a track title) that may include spaces within the parameter.
These parameters will be enclosed in double-quotes. For example, the return status message indicating the
currently playing track will return the track title currently playing: Feedback CurrentTrack 1 “Here Comes
the Sun” indicates that Zone 1 is currently playing the track Here Comes the Sun.
Most commands include a parameter that specifies on which zone the command should operate. The
Zone parameter must be a numeric value equal corresponding to the zone the command should operate
on. This must be less than the number of zones supported by the system (typically 1 to 4). A value of 0
can be used to indicate that the command should operate on the “current zone”. The current zone is the
one that is current displayed in the lower right corner of the screen in the “Now Playing” area. The current
zone in this area is also indicated by the color coding in the user interface.
The command reference below will show verbs in boldface and parameters will be shown by name in
italics surrounded by square brackets (ex: [Zone #] or [Volume Percentage]). Optional parameters are
shown in italics and surrounded by braces (ex: {# of tracks}).