This section describes the structure of the UDP packets exchanged between the QSPY Back-End and the various front-ends, such as QUTest and QView (blue arrows in the sequence diagram below).

Communication between Target, QSPY, and QView

General UDP Packet Structure

UDP packet structure

The UDP packets exchanged between the QSPY Back-End and the QView Front-End consist of:

1-byte Sequence-No, which increments by 1 for every packet and wraps naturally from 0xFF to 0. The sequence number allows QView to detect any data discontinuities.
1-byte Record-ID. The Record-IDs are divided into two categories:
- Records to and from the Target have Record-IDs in the range 0..127. Specifically, QS records originated from the Target are enumerated in ::QSpyRecords. Records destined to the Target are enumerated in ::QSpyRxRecords.
- Records to and from the QSPY Back-End have record-IDs in the range 128..255. Specifically, records destined to QSPY are enumerated in ::QSpyCommands.
optional Data Payload, which can be either text or binary, depending on the UDP Channel to which the front-end attaches. The various Data Payloads for different packets are described in the separate sections below.

UDP Data Channels

The QSPY UDP socket supports two "channels":

binary channel (channel 1), in which the Data Payload is sent in binary, but after removing escaping and checksum;
text channel (channel 2), in which the Data Payload is sent in the QSPY Textual Format;

A Front-End can choose the "data channels" when "attaching" to the QSPY host application (see qspy::attach()). The data channels are not exclusive, meaning that a front-end can "attach" simultaneously to both binary and text channels. In this case, the front-end would receive each packet as both binary and text formats.

Remarks: The binary-channel (0x01) is used by the QView GUI front-end, while the text-channel (0x02) is used by the QUTest Unit Testing front-end.

Packets to the QSPY Back-End

Attach to the QSPY Back-End (QSPY_ATTACH)

This packet has Record-ID==ATTACH and Data Payload of the form:

Data item	binary format	description
channels	B (byte)	Binary bitmask of QSPY channels to attach to

Detach from the QSPY Back-End (QSPY_DETACH)

This packet has Record-ID==DETACH and has no Data Payload.

Save Dictionaries to a File in QSPY (QSPY_SAVE_DICT)

This packet has Record-ID==SAVE_DIC and has no Data Payload.

Text Output to a File in QSPY (QSPY_TEXT_OUT)

This packet has Record-ID==SCREEN_OUT and optional Data Payload of the form:

Data item	binary format	description
Output-state	B (byte)	==0 means turn output off, !=0 means turn output on

NOTE: In case no Data Payload is provided, the command toggles the output from its current state.

Binary Output to a File in QSPY (QSPY_BIN_OUT)

This packet has Record-ID==BIN_OUT and optional Data Payload of the form:

Data item	binary format	description
Output-state	B (byte)	==0 means turn output off, !=0 means turn output on

NOTE: In case no Data Payload is provided, the command toggles the output from its current state.

MATLAB Output to a File in QSPY (QSPY_MATLAB_OUT)

This packet has Record-ID==MATLAB_OUT and optional Data Payload of the form:

Data item	binary format	description
Output-state	B (byte)	==0 means turn output off, !=0 means turn output on

NOTE: In case no Data Payload is provided, the command toggles the output from its current state.

Sequence Output to a File in QSPY (QSPY_SEQUENCE_OUT)

This packet has Record-ID==SEQUENCE_OUT and optional Data Payload of the form:

Data item	binary format	description
Output-state	B (byte)	==0 means turn output off, !=0 means turn output on

NOTE: In case no Data Payload is provided, the command toggles the output from its current state.

Send Event to the Target (QSPY_SEND_EVENT)

This packet has Record-ID==SEND_EVENT and contains the event as Data Payload:

Data item	binary format	description
signal	string/number	Event signal–either symbolic to be extracted from signal-dictionary, or numeric value
parameters	user-defined	Binary data corresponding to all event parameters

NOTE: The QSPY Back-End forwards the event to the Target, see Inject an Event to the Target (EVENT)

Send Current Object to the Target (QSPY_SEND_CURR_OBJ)

This packet has Record-ID==SEND_CURR_OBJ and contains the current object as Data Payload:

Data item	binary format	description
Obj-type	B (byte)	Enumerated type of the current object
Address	string/number	If string, QSPY tries to retrieve the object from dictionaries

NOTE: The QSPY Back-End forwards the current-object to the Target, see Set the Current Object in the Target (CURR_OBJ)

Send Command to the Target (QSPY_SEND_COMMAND)

This packet has Record-ID==SEND_COMMAND and contains the command (including parameters) as Data Payload:

Data item	binary format	description
Command-ID	string or B (byte)	If string, QSPY tries to retrieve the command number from enum-dictionary
Command-Par1	I (unsigned 4-byte integer)	command parameter-1
Command-Par2	I (unsigned 4-byte integer)	command parameter-2
Command-Par3	I (unsigned 4-byte integer)	command parameter-3

NOTE: The QSPY Back-End forwards the command to the Target, see Execute a User-Defined Command in the Target (COMMAND)

Send Test Probe to the Target (QSPY_SEND_TEST_PROBE)

This packet has Record-ID==SEND_TEST_PROBE and contains the test-probe as Data Payload.

Send and Show a Note to QSPY (QSPY_SHOW_NOTE)

This packet has Record-ID==SHOW_NOTE and contains the note (text) as Data Payload:

Data item	binary format	description
message	string	message to display

Clear QSPY Screen (QSPY_CLEAR_SCREEN)

This packet has Record-ID==CLEAR_SCREEN and has no Data Payload.

Packets from the QSPY Back-End

Attach Response from the QSPY Back-End (ATTACH)

This packet has Record-ID==ATTACH and has no Data Payload.

Detach Request from the QSPY Back-End (DETACH)

This packet has Record-ID==DETACH and has no Data Payload.

Records to the Target

Query Target Info (INFO)

This packet has Record-ID==INFO and has no Data Payload.

Note: To understand the following detailed UDP packet descriptions, it is highly recommended to read the Python documentation for the Python struct.pack() command.

All data to and from the Target is sent according to the QP/Spy™ Data Protocol in little endian.

Code Example:

::qspy::sendPkt [binary format c $::qspy::QS_RX(INFO)]

Execute a User-Defined Command in the Target (COMMAND)

This packet has Record-ID==COMMAND and Data Payload of the form:

Data item	binary format	description
Command-ID	B (byte)	command number
Command-Par1	I (unsigned 4-byte integer)	command parameter-1
Command-Par2	I (unsigned 4-byte integer)	command parameter-2
Command-Par3	I (unsigned 4-byte integer)	command parameter-3

Reset the Target (RESET)

This packet has Record-ID==RESET and has no Data Payload.

Call QF_TICK_X() in the Target (TICK)

Data item	binary format	description
Tick-rate	B (byte)	system tick rate number

Peek Target Memory (PEEK)

This packet has Record-ID==PEEK and Data Payload of the form:

Data item	binary format	description
Peek-addr	Target-dependent Typically I	Address of the data in the Target
Peek-length	B (byte)	Number of bytes to peek

Poke Target Memory (POKE)

This packet has Record-ID==POKE and Data Payload of the form:

Data item	binary format	description
Poke-addr	Target-dependent Typically I	Address of the data in the Target
Poke-length	B (byte)	Number of bytes to poke (<= 8)
Poke-data	user-defined	Binary data to poke to the Target (8 bytes maximum)

Note: The Poke-data part of the Data Payload must be formatted with the particular endianness of the Target and with any padding required for proper alignment of objects in the Target memory.

Set Global Filters in the Target (GLB_FILTER)

This packet has Record-ID==GLB_FILTER and Data Payload of the form:

Data item	binary format	description
Data Len	B (byte)	Number of bytes sent (currently 16)
Filters	16B	8-bit bytes (128-bits), each bit corresponding to Global Filter

Set Local Filters in the Target (LOC_FILTER)

This packet has Record-ID==LOC_FILTER and Data Payload of the form:

Data item	binary format	description
Data Len	B (byte)	Number of bytes sent (currently 16)
Filters	16B	8-bit bytes (128-bits), each bit corresponding to Local Filter

Inject an Event to the Target (EVENT)

This packet has Record-ID==EVENT and Data Payload of the form:

Data item	binary format	description
AO prio	B (byte)	Priority of the recipient AO (0 to publish the event)
signal	Target-dependent Typically H	signal of the event
parameters	user-defined	Binary data corresponding to all event parameters

The Event signal sig must be formatted according to the Target configuration (see Q_SIGNAL_SIZE).

The Event parameters must be formatted with the particular endianness of the Target and with any padding required for proper alignment of objects in the Target memory.

The parameters need to match exactly the event memory layout in your Target, including the endianness and any padding that the Target compiler might be using. (To test the correct binary format and padding, you can use the Generate Event... command).

For example, let's assume that the parameters of your event are: a byte, followed by a 2-byte integer, followed by a 4-byte integer. Also, let's assume that your Target is little endian. From the Generate Event... command you discover that to format this event correctly you need to use the following event parameters:

Par #	format	data (example)
par1:	B	0x11
par2:	B	0x00
par3:	H	0x1122
par4:	I	0x11223344

Set the Current Object in the Target (CURR_OBJ)

This packet has Record-ID==CURR_OBJ and Data Payload of the form:

Data item	binary format	description
Obj-type	B (byte)	Enumerated type of the current object
Address	Target-dependent Typically I	Address of the current object

QSPY DictionariesQSPY Sequence Output