QTools  5.9.3
QSpyView™ Visualization & Monitoring

About QSpyView™

QSpyView™ is a powerful Visualization and Monitoring facility, which allows embedded developers to rapidly create virtual Graphical User Interfaces to monitor and control their embedded devices from a host (desktop) computer. The interfaces created by QSpyView™ can visualize the tracing data produced by QP/Spy™ and can also send various commands to the embedded target.

A visualization and monitoring system like QSpyView™ can be used in all stages of development, manufacturing, and after the deployment, for in-field servicing of embedded devices.
Example of a QSpyView™ session on an embedded board (EFM32-SLSTK)

As you can see in the figure above, a QSpyView™ user interface consists of the text box with extensible menus plus a customizable canvas that can display the QP/Spy™ data in an attractive graphical format, such as animations, graphs, etc. and can contain controls, such as buttons, sliders, etc. The actual functionality of the virtual GUI obviously depends on the target system and the embedded code it is running. Therefore, the QSpyView™ provides only a skeleton, which is then customized by user-supplied scripts.

What's Special About QSpyView™?

The GUIs created with QSpyView™ are naturally platform-neutral and run without any changes on Windows, Linux, or macOS.

QSpyView™ currently supports the following commands (NOTE: QSpyView™ is extensible with functionality specific to the project at hand, so it can provide many more features on top of the basic functionality enumerated below):

  • Set global QS filters inside the Target
  • Set local QS filters inside the Target
  • Inject an arbitrary event to the Target (direct post or publish)
  • Execute a user-defined callback function inside the Target with arguments supplied from QSpyView™
  • Peek data inside the Target and send to QSpyView™
  • Poke data (supplied from QSpyView™) into the Target
  • Execute clock tick inside the Target
  • Request target information (version, all sizes of objects, build time-stamp)
  • Remotely reset the Target
Why UDP? The communication between QSPY and QSpyView is based on UDP, because UDP is inherently packet-oriented (as opposed to TCP, which is stream-oriented) and preserves the packet boundaries.

QSpyView™ Structure

The sequence diagram below shows the general structure of QSpyView™. The embedded Target is running an instrumented code that communicates with the QSPY Host application over the Target data link (red arrows). This communication is based on the QP/Spy Protocol. The QSpyView™ (Tcl/Tk script) attaches to the QSPY host application by means of the UDP socket that QSPY opens when the -u command-line option is selected. This communication (blue arrows) uses the same packet structure as the QP/Spy Protocol, but without the HDLC framing, without transparency (escaping), and without the checksum.

The QSpyView Front-End attaches to the binary-channel of the UDP socket served by QSPY.
Communication between Target, QSPY, and QSpyView
  • A The QSPY Back-End forwards all trace records produced by the Target to the UDP Socket, so that any attached Front-End (such as QSpyView™) receives all this data.

  • B The QSPY Back-End relays all UDP packets with Record-ID in the range 0..127 to the Target.

  • C UDP packets with Record-ID in the range 128..255 are not relayed to the Target, but instead are used for communication between the QSpyView™ Front-End and the QSPY Back-End.

Installing QSpyView™ and Tcl/Tk

QSpyView™ is bundled with QSPY and is installed automatically when you install QTools. Specifically, QSpyView™ consists of the qspy.tcl and qspyview.tcl Tcl scripts located in the qtools folder.


In order to run QSpyView™, you need the Tk interpreter called wish installed on your machine. Wish (version 8.4) is included in the QTools collection for Windows, so it will be available if you install QTools. Also, the Tcl/Tk distribution included in QTools has been already extended with the UDP-Sockets for Tcl, so you can use the tclsh and wish interpreters "as is" without any additional modifications.


On Linux, Tcl/Tk is usually installed, but you need to augment the standard Tcl/Tk distribution with the UDP Sockets for Tcl.

All the tools and instructions of adding UDP Sockets to Tcl are included in the QTools collection for Linux, in the tcludp folder (see QSPY directories and files)

Running QSpyView™

Being a Tcl/Tk application, QSpyView™ requires the Tk interpreter called wish (windowing shell) to run. This Tcl/Tk interpreter needs to be augmented with the UDP socket extension, because the standard Tcl/Tk distributions typically don't support UDP. (NOTE: The Tcl/Tk interpreters included in the QTools collection for Windows are already augmented with the UDP socket extension, so you don't need to do anything to use them for QSpyView™).

In the simplest form, QSpyView™ might be started by changing to the folder qtools\qspy\qspyview and double-clicking on the qspyview.tcl script. Alternatively, you might open the Command Prompt and type:

wish qspyview.tcl

This would launch QSpyView™ in the "default" configuration, without any customization specific to a project at hand.

However, it also possible to launch QSpyView™ customized to a particular project, such as the DPP application, by providing commands and views specific to the project at hand. For this QSpyView™ provides an extension mechanism to provide another script as a command-line parameter to the qspyview.tcl script.

QSpyView takes up to three optional command-line parameters, with the following usage:

wish qspyview.tcl [<cust_script> [<qspy_host> [<qspy_port>]]]

where <cust_script> is the customization script (e.g., dpp.tcl), <qspy_host> is the network host name or IP address of the host running the QSPY "Back-End", and <qspy_port> is the UDP port number opened by the QSPY "Back-End". If the parameters <qspy_host> and <qspy_port> are not provided, the defaults of localhost and 7701 are assumed.

For example, the DPP example provides the extension script named dpp.tcl, located in the QP examples directory. In this case, you need to choose from which directory you want to launch QSpyView™. If you choose to launch it from the directory containing the extension script, you need to fully-qualify the location of the qspyview.tcl script, as follows:

wish %QTOOLS%\qspy\qspyview\qspyview.tcl dpp.tcl
In practice, the easiest way to launch QSpyView™ is to define a shortcut, like the one provided with the DPP example:

qspyview shortcut properties

Attaching QSpyView to QSPY

In contrast to TCP, which is stream-oriented, UDP is packet-oriented, so the only way to "attach" two ends of communication is to exchange packets. Consequently, immediately after QSpyView™ is launched, it tries to attach by sending the ATTACH packet to QSPY. If QSPY responds with the ATTACH response, QSpyView™ considers that it is "attached".

However, if the ATTACH response does not arrive within a second or two (because perhaps QSPY is not running), QSpyView™ opens a modal dialog box that reminds you to run QSPY with the -u command-line option, as shown in the screen-shot below:

Attach to QSPY dialog box

Depending how you start QSPY, the dialog box might close automatically, which means that QSpyView has successfully attached to QSPY. However, if the dialog box does not close, you need to click the OK button to send ATTACH packet to QSPY, until QSpyView™ receives the ATTACH response from QSPY. If you can't "attach", you can click the Cancel button to close QSpyView™.

Because UDP works over networks, the QSPY Back-End can run on a different machine (e.g., a lab computer) that the the QSpyView™ Front-End (e.g., office computer). These two machines can even run different operating systems, for example Linux on the lab computer and Windows in the office, or vice versa. All you need to do is to provide the host-name parameter as the third command-line argument to the qspyview.tcl script (e.g., wish qspyview.tcl dpp.tcl

Recognizing the Target

Before QSpyView™ can correctly interpret any data from the Target, it needs to obtain certain information about the Target, such as the sizes of object pointers, function pointers, event signals, etc. This information is provided in the QS_TARGET_INFO trace record coming from the Target.

To inform you about the Target status, QSpyView™ displays the Target: UNKNOWN in the status bar when the target is "unknown":

Target UNKNONW status

If this happens, you can explicitly request the Target information by means of the "Commands->Query Target Info" menu:

Target KNONW status (build time-stamp)

After the Target information is received, the QSpyView™ status bar shows the build time-stamp of the Target image.

Next: QSpyView User Interface