QTools 6.8.2
QView™ Visualization & Monitoring

About QView™

QView™ 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 QView™ can visualize the tracing data produced by QP/Spy™ and can also send various commands to the embedded target.

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

As you can see in the figure above, a QView™ 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 QView™ provides only a skeleton, which is then customized by user-supplied scripts.

What's Special About QView™?

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

QView™ currently supports the following commands (NOTE: QView™ 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 QView™
  • Peek data inside the Target and send to QView™
  • Poke data (supplied from QView™) into the Target
  • Execute clock tick inside the Target
  • Request target information (version, all sizes of objects, build time-stamp)
  • Remotely reset the Target
Remarks
Why UDP? The communication between QSPY and QView is based on UDP, because UDP is inherently packet-oriented (as opposed to TCP, which is stream-oriented) and preserves the packet boundaries.

QView™ Structure

The sequence diagram below shows the general structure of QView™. 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 QView™ (Tcl/Tk script) attaches to the QSPY host application by means of the UDP socket that QSPY opens specifically for attaching various "front-ends". 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.

Note
The QView Front-End attaches to the binary-channel of the UDP socket served by QSPY (blue arrows in the sequence diagram below).
Attention
The QSPY UDP channel should not be confused with the QSPY target communication channel (red arrows in the sequence diagram below), which can be serial-port, TCP/IP, or a binary-file.
Communication between Target, QSPY, and QView
  • 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 QView™) 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 QView™ Front-End and the QSPY Back-End.

Installing QView™ and Tcl/Tk

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

Windows

In order to run QView™, 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.

Linux

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

Note
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 QView™

Being a Tcl/Tk application, QView™ 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 QView™).

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

wish qview.tcl

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

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

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

wish qview.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 QView™. If you choose to launch it from the directory containing the extension script, you need to fully-qualify the location of the qview.tcl script, as follows:

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

qview shortcut properties

Attaching QView 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 QView™ is launched, it tries to attach by sending the ATTACH packet to QSPY. If QSPY responds with the ATTACH response, QView™ considers that it is "attached".

However, if the ATTACH response does not arrive within a second or two (because perhaps QSPY is not running), QView™ opens a modal dialog box that reminds you to run QSPY, 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 QView 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 QView™ receives the ATTACH response from QSPY. If you can't "attach", you can click the Cancel button to close QView™.

Note
Because UDP works over networks, the QSPY Back-End can run on a different machine (e.g., a lab computer) that the the QView™ 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 qview.tcl script (e.g., wish qview.tcl dpp.tcl 192.168.1.101).

Recognizing the Target

Before QView™ 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, QView™ 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 QView™ status bar shows the build time-stamp of the Target image.


Next: QView User Interface