Introduction ============ The Spectran TCP control protocol is based on the generic GPIB protocol for controlling measurement equipment, modified to suit the special requirements of the Spectran hardware. This document will list only the parts of the protocol that are relevant for interfacing with the Spectran and not list commands that are part of the protocol but not usable in the context of the SDK (this includes commands that are part of the GPIB standard but aren't functioning with the Spectran and commands only usable with the RSA line of Spectran devices). At the time of this writing the SDK implements protocol version 1.1 though many elements will still report 1.0 as they haven't changed. General ======= At its core, the Spectran TCP control protocol (or STCP from now on) is a simple text-based communication protocol over a single TCP client-server connection. The server side is usually connected to a Spectran spectrum analyzer over USB and translates incoming commands into the corresponding binary USB protocol commands, as well as handling various maintenance tasks and providing certain convenience functions to reduce implementation overhead on the client. Originally the STCP was implemented for the Remote Spectrum Analyzer (RSA) line of Spectran devices. However due to its portable nature and easy usage we now also ship this SDK to enable an easier and more portable way of programming for all USB-equipped Spectran devices compared to our existing Qt-based ASDK. As this is meant as a programming interface and not a remote control software the STCP server component in the SDK is however limited to localhost connections only. On the other hand it comes with the option to simulate the basic behavior of a Spectran device so you can start working on your program before obtaining a real device. The STCP is defined by a set of commands and a corresponding set of replies, using the general syntax of GPIB commands. The general syntax for a command is (in EBNF notation): COMMAND = GROUP, { ":", GROUP }, [" ", VALUE | "?" ], "\n" GROUP = Letter, { Letter | "_" } VALUE = { Letter | Digit | Whitespace | "_" | "." | "," | "-" | "+" | "&" } Commands are organized into groups and often subgroups, which are separated by colons. The value argument is either the value for the requested operation (e.g. the value for a variable set operation) or "?" to request the current value of the given command. All commands must be terminated by a newline and should only contain ASCII characters. Replies use a similar syntax: REPLY = TYPE, ":", { DATA }, "\n" TYPE = "ACMD" | "AINFO" | "ASWEEP" | "AUTHENTICATION" | "DEVICE_SETUP" DATA = FIELD, { ":", FIELD } FIELD = { Letter | Digit | Whitespace | "_" | "." | "," | "&" | "#" | "%" | "/" | "!" | "-" | "+" }, [ "$", FIELD ] As replies transport highly different amounts of data the format is more flexible when to comes to formatting the payload. Please refer to the documentation of the individual replies below for details on the syntax. Commands ======== STCP commands are organized in three main groups: AUTHENTICATION, SERVER and SPECTRAN. AUTHENTICATION commands ----------------------- The AUTHENTICATION group doesn't actually contain any subcommands. It sends authentication data in the form of a username and hashed password to the server. This is used in the RSA product family to ensure that only authorized users can modify device settings. As the server component in the SDK only accepts localhost connections which always have full access this command is only a formality, the provided user credentials aren't actually checked. Syntax: AUTHENTICATION = "AUTHENTICATION", ":", USERNAME, "&", METHOD, "&", PASSWORD, "\n" USERNAME = { Letter | Digit } METHOD = "AD", { Digit } PASSWORD = { Letter | Digit } METHOD defines what hashing scheme is used for the password, currently this is either "AD4" or "AD1138" which both equal to SHA256. The PASSWORD element contains the password hash as hexdigest, for SHA256 this should contain exactly 64 characters. For connecting to the SDK server the content of each field however is irrelevant. Example: AUTHENTICATION:aaronia&AD4&5b8a605dc30d376b1faf7d3d817e0593161f88554af2ec9139b717c3fdae58a7 Replies: The server will reply with an AUTHENTICATION package stating the access level granted by the given credentials. SERVER commands --------------- The SERVER group contains commands that deal with the connection rather than the Spectran itself. They are all single commands that take no arguments other than the optional "?", and will all reply with a single AINFO package. SERVER:SHUTDOWN --------------- Signals the server process to terminate itself. After sending this command no further commands will be accepted. Will reply with an AINFO package containing a shutdown message. SERVER:CONFIG ------------- Requests the current TCP port number used by the server. Replies with an AINFO package stating the server port: "AINFO:Using port: 2308". SERVER:CLIENTS -------------- Requests a list of all client connections currently connected to this server. Replies with an AINFO package listing all available information of each client connection: AINFO:client:127.0.0.1|port:61720|id:13|User:Administrator|plevel:Administrator|comment:Administrator (your client) SERVER:COMMANDS --------------- Requests a list of all available commands. Note that this list may contain commands that are not documented here as they are of no use with the SDK server, and in some cases may cause problems. Replies with a single AINFO package containing a HTML formatted list of commands. SPECTRAN commands ----------------- The commands actually dealing with the Spectran itself are grouped in this section. There are three different subgroups for different purposes: - INFO commands can request information about the Spectran. These don't take any arguments. - CTRL commands are used to read/write Spectran variables - CALC commands can be used to access specific data segments and advanced processing functions SPECTRAN:INFO:DESCRIPTION ------------------------- Replies with an AINFO package listing the description of the connected Spectran device as listed in the EEPROM: AINFO:Description: Aaronia SPECTRAN HF-60105 Analyzer SPECTRAN:INFO:SERIAL -------------------- Replies with an AINFO package listing the serial number of the connected Spectran device: AINFO:Serial: 00000 SPECTRAN:INFO:OPTIONS --------------------- Replies with an AINFO package listing the hardware options available in the connected Spectran device: AINFO:SF_20x_BROADBAND_DETECTOR,SF_001_MEMORY_EXTENSION_1MB,SF_020_PREAMPLIFIER,SF_015_AUDIO_SIGNAL_DETECTION SPECTRAN:INFO:IDN ----------------- Replies with an AINFO package listing the identification information of the connected Spectran device: AINFO:Aaronia SPECTRAN HF-60105 Analyzer,00000 SPECTRAN:INFO:SETUP ------------------- Requests a DEVICE_SETUP package containing the current Spectran environment (see DEVICE_SETUP reply: DEVICE_SETUP:class:AHFV4SpectranDevice$features:3085$freqCalibrated:9400.000 MHz$info:60105#4#27#1300 mAh NiMH#Beta 42#25.01.2013#00000#T. Adams# $profile:$1:860#2:940#3:3#4:1#5:10#6:-10#10:0#11:0#13:-1#14:-1#15:0#16:0#17:0#18:0#30:900#31:80#32:1#96:0.3#192:-1 SPECTRAN:INFO:FIRMWARE ---------------------- Replies with an AINFO package listing the current firmware version of the connected Spectran device if available: AINFO:V2.20=20110930-121558 SPECTRAN:INFO:CALIBRATIONDATE ----------------------------- Replies with an AINFO package listing the last calibration date as stored in the device information: AINFO:01.01.2014 SPECTRAN:INFO:MAXHOLD --------------------- For convenience the server component keeps track of the highest measurement value received by the connected Spectran device. The stored value can be requested with this command, the resulting AINFO package will list the frequency, measurement value (with unit) and measurement time as well as the timestamp of the last reset, separated by semicolons: AINFO:921.0 MHz;-51.8 dBm;05.11.2014 15:23:54;05.11.2014 16:21:11 SPECTRAN:INFO:RESETMAXHOLD -------------------------- Resets the maximum measurement value stored in the server. Replies with an informal AINFO notification: AINFO:Reset max hold SPECTRAN:CTRL:* --------------- The CTRL group of commands all follow the same pattern of SPECTRAN:CTRL: , where is one of the following subcommands: STARTFRQ, STOPFRQ, CENTFRQ, SPAN, RBW, SWTIME, SWEEPFREQUENCYPOINTS, DETECTOR, SENSOR, DIMENSION, RECEIVER, ATTEN, PREAMP, SWEEPING, SWEEPRESET Not every subcommand is valid for all device types (HF, NF, V4). Please refer to the general Spectran USB API documentation about valid device types and possible values for each variable. can either be "?" to only request the current value, or an unformatted decimal number to set a new value and return the result. The server generally replies with two ACMD packages, one using raw numeric parameters and one using formatted strings. The first is intended for internal processing to avoid unnecessary parsing, the second for use in interfaces or user facing components. Note that in some cases (like setting frequency parameters) a variable change may also trigger a DEVICE_SETUP reply to notify clients about additional changes. Both ACMD replies use the same fields, just with different formatting: ACMD::::: where is the protocol version (currently "1.1"), is reserved for possible multi-device support in the future, specifies which variant of ACMD reply is used (numeric parameters use type "0004", formatted parameters type "0010"), contains the variable ID/name and the variable value: ACMD:1.1:0000:0004:0002:940 ACMD:1.1:0000:0010:StopFrequency:940 MHz The SWEEPING subcommand is a special case as it will also enable/disable the continous generation of ASWEEP packages (see SPECTRAN:CALC:TRACE_CURRENT for syntax) with measurement data. SPECTRAN:CALC:PEAKSUPPRESSION ----------------------------- Reads or modifies the state of the peak suppression function that is used to eliminate some fake signals generated by internal interference of the Spectran. This is disabled by default on the server side to avoid double-suppression by both client and server. Replies with an informational AINFO package containing the current state: AINFO:SuppressionDisabled SPECTRAN:CALC:TRACE_CURRENT SPECTRAN:CALC:TRACE_MAXIMUM SPECTRAN:CALC:TRACE_MINIMUM SPECTRAN:CALC:TRACE_AVERAGE --------------------------- Requests the sweep data of the current measurement, or the maximum/minimum/average values for each frequency point of the current measurement. Replies with a single AINFO package containing the requested data, using the same format as ASWEEP packages (it uses the AINFO type so the reply can be distinguished from regular ASWEEP packages). The syntax for these replies is: AINFO::::...:::... Example: AINFO:12-29-00.621 10.11.2014$12-29-00.621 10.11.2014$-115.244#-117.947#...#-116.362#-115.634$860 MHz#861.5 MHz#...#977 MHz#978.5 MHz SPECTRAN:CALC:TRACE_RESET_MAXIMUM SPECTRAN:CALC:TRACE_RESET_MINIMUM SPECTRAN:CALC:TRACE_RESET_AVERAGE --------------------------------- Triggers a reset of the requested trace data so it is regenerated by future measurements, replies with an AINFO package: AINFO:Resetted Maximum Trace Note that a change of frequency parameters will trigger an internal reset without special notification. SPECTRAN:CALC:TRACE_AVERAGE_BUFFER_SIZE --------------------------------------- Reads or modifies the number of samples to be used for generating the "average" trace. A higher number will result in a more stable trace where isolated peaks are less visible. Replies with an AINFO package listing the current value: AINFO:TraceAverageBufferSize:10