Revision as of 16:15, 28 March 2015

Visualization Tool

Installation

The tool is known to operate under Windows (64 and 32 bits) and MAC OS systems.

• At present, MATLAB 2014b or later is required. Versions prior to 2014b do not support the direct interface with python utilized by the VT.

• • In the future, a compiled version of the VT may exist.

• Python 2.7.9 [1]. Choose the same number of bits as the version of MATLAB (python support under MATLAB requires that the 'bits' match)

• The Tool lives in the repository Master Branch at the location \Tools\Matlab
  • Pull into a convenient directory (referred to as VT_HOME). To run the tool, this will need to be MATLABs current directory.

• Optional : For direct connection a UART device, or to a PSoC using the USB CDC profile, the pyserial module is required and the Cypress USBSER driver are required. USBSER instructions are possibly specified in the repository Master Branch under the Documentation directory.
  • The easy install is to open a command prompt or terminal window and type pip install pyserial
  • If the pip command is unknown, then its likely not in your path. It typically lives in c:\Python27\Scripts, in which case you may run c:\Python27\Scripts\pip install pyserial
  • For 64 bit windows, if there is a problem with the pip install, another trusted source is the team at UCI : pyserial‑2.7‑py2‑none‑any.whl

Starting Tool (gui_3) for TCP/IP Operation

Start MATLAB 2014b+ and then cd to the VT_HOME directory. Under Windows you may wish to create a MATLAB shortcut where VT_HOME the startup directory.

• You'll need to know the IP address or host names of the instrument. Lets assume its 192.168.7.2
• Within MATLAB, run the command : gui_3('connect', '192.168.7.2')

The Tool GUI and Command Line Interface

The tool may be interacted with both graphically and via the MATLAB command line.

Graphical Interface

Upon startup if the connection is successful, two MATLAB figures will be created. The plotting figure by default is docked with MATLAB and the Variable Chooser is floating.

The variables to be plot are selected by (left) clicking their name within the Variable Chooser figure. Multiple variables are selected by using SHIFT click and/or CTRL click.

The Plot Figure contains several buttons (lower left) and two sliders (bottom).

buttons

• STOP : Clicking this button is the preferred way to stop the Tool. The two figures and connection will be closed.
• GRAPH*** : Pause / Resume the update of the graphic display. In the background, data from the instrument is collected. (At
• DATA : Sending a command to the instrument to stop or start sending data. After stopping and restarting, the graph will typically contain an empty space for the stopped time interval.
• SAVE : Save a snapshot of the GUI and the instrument data within the 'data accumulator circular queue' variables. The snap shot may require many seconds (a minute?) during which time, current data from the instrument may be lost. This data structure maintains the most recent DATA_ACCUMULATOR_MAX_LENGTH (currently 480,000) samples from each field.
• LOG and edit box: When LOG 1, all plotable vectors sent from the instrument are save into a sqlite3 database (on the local file system). The base filename for the SQL DB is specified in the edit box. The base file name is extended with current date and time and the extension .sqlite3 (eg The gxlog_20150328_093407.sqlite3)

*** At present the pause/resume button behavior is broken.

sliders

The sliding controls at the bottom are still under development and have broken the graphic pause feature. The sliders themselves are also somewhat working / broken depending on one's expectations.

• Viewport width slider : The left slider controls the viewport window size. The control linear position (x) specifies an 10^x seconds viewport size. The limits are 1 second and 1000 seconds. This slider operates as expected, although the initial position does not match the actual viewport.
• Viewport position slider : The larger right slider control the start position of the viewport within the complete set of captured samples with left the oldest data. Ideally moving the slider from the right position would pause the graph at that position, however instead the graph continues to scroll at a reduced by moving it to the right.

Command Line Interface

The MATLAB command line may be used to control several features of the tool and instrument. There are three primary means of interacting with the tool via the command line. These include sending commands via the gui_3() function, matlab global variables, and the matlab_client python object (technically also a global variable). The tool source package also contains several helper commands/functions.

python object (mc)

The global variable mc is a python object from the class matlab_client in client.py. This objects methods are the primary means that the matlab code interacts with the python code responsible for communicating with and decoding messages from the instrument.

Some of the methods of interest:

• mc.help(); : List the commands from the command dictionary. This table contains the command, the minimum and maximum number of arguments, a field name for each argument, the data type of the argument list (as a python struct format string), and a description of the command.
• mc.send_user_command_string(string); : eg mc.send_user_command_string('icore_datarate 100'); Command strings consist of a COMMAND (digits without intervening whitespace or punctuation) followed by and optional set of 1 or more whitespaces and a comma separated list of values. Value types must be consistent with the underlay argument type.
• mc.stop_data_stream();  : send the GX message to stop sending data
• mc.start_data_stream(); : send the GX message to start sending data

matlab globals

The data collected is stored in the matlab class data_accumulator_cirq_class. See help data_accumulator_cirq_class (to be improved) methods data_accumulator_cirq_class properties data_accumulator_cirq_class

Access to the data on the MATLAB command line is via the 'daf' (data accumulator fields) and 'da' (data accumulator) variable.

For obtain the 'fd' data with : daf.iCore_in_fd.get()

gui_3() function

gui_3 help:

 handles = gui_3(action, varargin);

 Two actions are 'connect' and 'stop'
 The 'stop' action is equivalent to pressing the red STOP button in the gui.  
 The 'connect' action requires an argument string to specify the connection.

 Examples : 
 gui_3('stop');
 TCP/IP to BBB default : gui_3('connect','192.168.7.2');
 connection to localhost TCP port 10000 : gui('connect','localhost:10000')   
 PC UART : gui('connect','COM1')
 MAC USB serial : gui('connect','/dev/tty.usbmodem_fd131')

• A future version of the gui_3() will contain useful matlab help. help gui_3

helper commands, functions, examples

command : gui_stop

 Shorthand for gui_3('stop')

function : get_uart();

 [uart_device, uart_str] = get_uart(pattern);

 Uses python to return cell array of UART devices as uart_device
 and cell array of the string related to each device (uart_str)

 Example:

 List all COM PORTS:
 com = get_uart();

 List the PC USB UART devices:
 com = get_uart('USBSER')

 On the MAC list the /dev/tty devices with the substring usbmodem:
 com = get_uart('usbmodem')

 Starting  the gui with the first COM PORT:
 com = get_uart('USBSER');  gui_3('connect', com{1} );

Example : live_data_test.m

 Example of accessing the live data set within the daf structure array 
 created by the gui application

Bugs / Issues

• When the 480k sample buffer fills, the current (unreleased) tool crashes. The released too may also.
• When the data dictionary contains the L data type (unsigned long), values between 2^31 and 2^32-1 cause the tool to crash.

• Fix right slider behavior. Moving slider from extreme right will cause a pause
• Selecting pause will adjust position of right slider slightly left. Selecting resume will move the slider to the extreme right.
• Fix initial values of the sliders

Features To Be Added

• Ability to save / load a configuration file.
• Ability to display a description string (units) at either the title or y-axis. The description string could be placed in either the vector dictionary, or the configuration file.
  • The config file will contain the set of selected variables and any other user made interface adjustments (most of which to be developed)
• Ability to specify the Y axis limits. Each subplot to contain a micro-control to enable/disable AUTO axis
• Improve Variable chooser variable display. Explorer +- nesting is not possible, but indenting the fields of each vector is. The activity level of each vector to be display.
• When paused, the X-axis of all subplots optionally linked allowing the MATLAB toolbar pan and zoom to operate.
• Ability to load saved data from VT created .mat files and sqlite3 databases
• Ability to place multiple fields within a single subplot
• Ability to change the X-axis variable
• Multiple plot figures
• Ability to stream from a local / remote SQL server/database
• Ability to send commands from the plot figure
• Simplify startup allowing the GUI to list / select the instrument connection