QView™ Visualization & Monitoring

   

About QView™

QView™ is a powerful Visualization and Monitoring facility, which allows embedded developers to rapidly create remote 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 interact with the target by sending commands and injecting events to the embedded target.

As you can see in the screen shots below, a QView™ user interface consists of a text box with extensible menus plus a customizable canvas that can serve as a remote graphical user-interface to your embedded device. The canvas can contain various "widgets", such as buttons, sliders, gauges, graphs, animations, 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 written in Python↑ (version 3).

Example of a QView™ session on an embedded board (Windows host)

Example of a QView™ session (Linux host)

What's Special About It?

QView™ has been specifically designed for extensibility, so that you can quickly customize its GUI and behavior to your specific embedded project, so that you can use QView™ as a powerful custom Human-Machine Interface (HMI) for your projects. The customization is accomplished in Python↑ (version 3), which means that it is naturally platform-neutral and runs without any changes on Windows, Linux, or macOS.

Out of the box, QView™ supports the following commands (NOTE: This basic functionality can be extended in the QView™ customization):

• 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 command 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
• Remotely reset the Target.

Note

A visualization and monitoring system like QView™ can be used in all stages of development, during manufacturing, and also after deployment for in-field servicing of embedded devices.

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.

Attention

The Target must be running the "Spy" build configuration, in which the QP/Spy™ Software Tracing is enabled. Additionally, the QP/Spy implementation in the Target must support bi-directional communication with QSPY.

The QView™ (Python 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.

Communication between Target, QSPY, and QView

A

A Target produces QS trace records, which the QSPY Back-End forwards to the UDP Socket, so that any attached Front-End (such as QView™) receives all this data.

B

The Front-End (QView™) sends commands as UDP packets to QSPY. For some of those packets, the QSPY Back-End supplies additional information (e.g., translation between symbolic names and binary addresses according to the QS dictionaries collected from the Target).

C

The QSPY Back-End then forwards the modified packets to 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.

Installation with pip

You can install the latest qview.py facility with the standard pip package manager.

pip install qview

Alternatively, you can direct pip to install from Quantum Leaps GitHub:

pip install https://github.com/QuantumLeaps/qtools/releases/latest/download/qview.tar.gz

Alternatively, you can direct pip to install from local package:

pip install /qp/qtools/qview/qview.tar.gz

Using QView

Running QView™

If you are using QView™ as a standalone Python script, you invoke it as follows:

qview
pythonw3 <path-to-qview-script>/qview.py [qspy_host[:udp_port]] [local_port]

Alternatively, if you've installed QView™ with pip, you invoke it as follows:

qview [qspy_host[:udp_port]] [local_port]

Alternatively, if you've installed QView™ with pip, and you customize qview with your own Python script <my_qview.py> you invoke it as follows:

pythonw <my_qview.py>

Command-line Options

• qspy_host[:udp_port] — optional host-name/IP-address:port for the host running the QSPY host utility. If not specified, the default is 'localhost:7701'.
• local_port — optional local UDP port to be used by "qview". If not specified, the default is '0', which means that the operating system will choose an open port.

Examples

pythonw %QTOOLS%\qview\qview.py

opens the generic (not customized) "qview".

pythonw dpp.py

opens the qview customization provided in the dpp.py script located in the current directory.

pythonw qpc-examples/qview-dpp/dpp.py localhost:7701

opens "qview" customization provided in the dpp.py script located in the directory qpc-examples/qview-dpp. "qview" will attach to the QSPY utility running at localhost:7701.

pythonw dpp.py 192.168.1.100:7705

opens "qview" customization provided in the dpp.py script located in the current directory. "qview" will attach to the QSPY utility running remotely at IP address 192.168.1.100:7705.

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 (perhaps because 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 Attach button to send ATTACH packets to QSPY, until QView™ receives the ATTACH response from QSPY. If you can't "attach", you can click the Close 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) than 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.py script (e.g., python3 qview.py dpp.py 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 UNKNOWN status

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

Target KNOWN status (build time-stamp)

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

Customization ScriptQView User Interface