Adding a custom GUI to XJEase or XJRunner
This application note describes how to interface XJEase or XJRunner with a graphical front end, creating a complete, customised JTAG test system. The examples given are for use with the XJDemo board (v1.2).
The simplest way of creating a custom GUI for XJTAG is to use the command-line versions of XJEase or XJRunner to execute the tests, together with a method of communicating with the graphical front end. This application note looks at two way of passing information between a GUI and XJTAG.
The first method is to use a set of files which are shared between the GUI and the XJTAG command-line program. This method is timer-activated, and needs careful synchronisation between the two programs so that instructions are not missed or overwritten.
The second method is to use a redirected I/O pipe, and is event-driven. The standard I/O pipe is simply a communication channel, which takes input (normally from the keyboard or mouse) and passes it to a program, and similarly takes output from the program to display on the screen. The pipe can instead be redirected and controlled by a GUI. This method requires version 1.3.1 or later of XJTAG.
In this application note, the GUI is generated using TCL/TK, for two reasons: it is quick and relatively easy to create a GUI in TCL/TK, and the ability to do I/O pipe redirection is part of the language. This application note does not intend to teach the user TCL/TK; however, it is an easy language to learn, and the full code required for this example is available to download.
Method 1 - File Passing
In this example, we use two files to communicate between TCL and XJTAG: "Instruct.io" to send instructions from the GUI to XJEase and "Response.io" to receive data back from XJTAG.
Each time the user clicks a button on the GUI, the TCL script creates the file "Instruct.io". XJTAG waits for the file to be created, then reads it and processes each line in turn. When XJTAG reaches the end of the file, it deletes "Instruct.io" and waits for the GUI to create it again.
While XJTAG is waiting for "Instruct.io" to be created, it monitors the state of the switch inputs on the XJDemo board. It then records the current state of the switches in "Response.io". The TCL script checks "Response.io" while it is waiting for user input, and displays the switch states in the GUI.
Code Overview - XJEase (demo_board_file.xje)
To implement file passing, we have added a global switch (gSwitch) and three functions (GUIinterface, ExecInst and ReadSwitches) to the standard XJEase code for the XJDemo board.
The switch gSwitch allows you to switch between normal, command-line-only execution and a GUI front end. When gSwitch is set to '1', the code is in GUI mode. As gSwitch is a global variable, its value can be set when XJEase is started, using the 'set gSwitch=1' command-line parameter.
GUIinterface is the main control function, and is called from CircuitTest when gSwitch is set to GUI mode. GUIinterface calls the ReadSwitches function every 100ms while waiting for the GUI to create "Instruct.io". ReadSwitches takes one argument - the file name used to send data back to the GUI. ReadSwitches then reads the state of each of the three switches in turn, and writes their values to the file as a single line, overwriting any previous content in the file.
GUIinterface also checks whether the GUI has created the file "Instruct.io". When it finds this file, GUIinterface reads it a line at a time, calling ExecInst to interpret execute each instruction from the GUI.
ExecInst takes one argument - the latest line of text read from "Instruct.io". The line will start with a command, followed by a '!' character, then any parameters for the command. ExecInst returns a value of '0' to continue running, or '1' to stop running tests (e.g. when the user has closed the GUI).
Code Overview - TCL/TK (demo_gui_file.tcl)
The TCL/TK script contains two sections. The first section defines how the GUI should look and how it should respond to user input (e.g. mouse clicks). This consists of the Prefs procedure and most of the Gui procedure. In this example, we have made extensive use of the label widget - you could use buttons, canvases or check boxes in TCL/TK to achieve the same result, but labels keep things simple, while giving all the functionality we need.
The second section controls what happens while the program is running, including interfacing to XJTAG. Once the TCL/TK Gui procedure has set up the front end and started XJTAG (setting gSwitch=1), it continually attempts to read the "Response.io" file. If "Response.io" can be read, Gui updates the state of the switches displayed on-screen.
If the user clicks on an LED symbol, the TCL/TK SetLED procedure is run. Similarly, clicking on the 'Clear' button will run the ClearLED procedure. Both of these will create (or open) the "Instruct.io" file, write in the required instructions and close the file. Note the use of the '-nonewline' flag to prevent a blank line at the end of the file.
Finally, when the user clicks 'Close', the GUI closes down, which stops the TCL/TK script checking for "Response.io" and runs the SetExit procedure. SetExit creates (or opens) "Instruct.io" and writes in the exit command to tell the XJEase script to terminate.
Method 2 - I/O Pipe Redirection
This method requires significantly less code than the previous method, but it needs version 1.3.1 or greater of XJTAG.
The following is a brief description of the main coding differences from the File Passing method.
Code Overview - XJEase (demo_board_pipe.xje)
With the file passing method, multiple instructions could be contained in the same file. With I/O redirection, each command is received separately, so we can combine the GUIinterface and ExecInst functions.
Note that we use 'GETKEY', rather than 'WAITKEY', to check for input in GUIinterface. 'WAITKEY' would block any code execution while waiting for input, but we need to continually check the state of the switches. If there were no feedback from the board, however, 'WAITKEY' would provide a better solution, as it frees up computer resources while waiting for input.
Code Overview - TCL/TK (demo_gui_pipe.tcl)
With no files to handle, the TCL/TK script can be reduced to just three procedures: Prefs, Gui and Read_SW_Settings.
Prefs is used to set up the fonts and colours for the GUI, and is identical to the previous method.
Gui simply describes the GUI, and lists what commands should be sent to XJTAG (using the I/O pipe) when each button is clicked. Each command should end with the '\r' character, which is sent from TCL/TK using 'puts -nonewline' (as before) with a '\r' character at the end of each command.
Read_SW_Settings is called whenever XJTAG sends any data back. It reads the I/O pipe, interprets the data and displays the switch states on-screen. To set this up, the TCL/TK scripts uses the 'fileevent' command.
The I/O redirection is done in the top-level TCL/TK program at the end, on the 'set prog' line. Note also the 'fconfigure' command, used to correctly configure the I/O pipe.
More complex examples
This application note has described the basic mechanisms for adding a custom GUI to XJEase. To inspire you to greater things, here are a couple of examples of what else you could create: