Revision as of 23:45, 15 April 2015

Preliminary documentation for the Visualization Tool revision $Id: gui_3.m 328 2015-03-23 16:19:57Z cbarn $

Installation

The Visualization Tool (VT) is known to operate under Windows (64 and 32 bits) and MAC OS systems. To use the tool, Matlab 2014b and Python 2.7.9 must be installed.

• 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. 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\Visualization
  • Pull into a convenient directory (referred to as VT_HOME). To run the tool, this will need to be MATLABs current directory. Note: a bug requires that the code path contain the string visualization with a lower case 'v'. Either use this name or change the code on lines 68 to 73 with the command edit gui_3

• 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

fixing installation

To check if a previously installed Matlab or Python are correct for the tool, the following may be helpful:

• To see if python will work, a quick test is have python print info about its build, the OS, and hardware. Run the following from Matlab:

py.platform.uname() Success is info about the platform.

>> py.platform.uname()

ans = 

  Python tuple with no properties.

    ('Windows', 'win7', '7', '6.1.7601', 'AMD64', 'Intel64 Family 6 Model 23 Stepping 10, GenuineIntel')

• Determine if you have 32 or 64 bit Matlab. When starting Matlab the 3rd line on the splash screen indicates the number of bits. 64 bit Matlab must be run with 64 bit python (eg AMD64)
  • Also the computer command may be helpful.

• Does Matlab have the correct version of python?
  • Run pyversion. It should look like this:

>> pyversion

       version: '2.7'
    executable: 'c:\python27\python.EXE'
       library: 'C:\Windows\system32\python27.dll'
          home: 'c:\python27'
      isloaded: 0

If not, it can be corrected with: pyversion c:\Python27\python.exe

Also, c:\Python27\pythonw.exe may also be acceptable.

Note, for this to work, 'isloaded' must be zero. If python already isloaded, restart Matlab and then run the previous commabnd.

• Python versions and bits:
  • From windows command prompt run:

python or c:\python27\python

Upon starting the output indicates the version and 'bits' :

Python 2.7.9 (default, Dec 10 2014, 12:28:03) [MSC v.1500 64 bit (AMD64)] on win32

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. The files created are 'filename.mat' and 'filename.png'
• LOG and edit box: When LOG 1, all plotable vectors sent from the instrument are saved 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 distribution also contains helper command(s), function(s), and example(s).

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. Example output:

COMMAND         | MIN/MAX  | FORMAT          | ARGUMENTS                      | DESCRIPTION                                                 
--------------- | -------- | --------------- | ------------------------------ | ------------------------------------------------------------
DATA_INTERVAL   | 1:1      | 1l              | interval_mS                    | set the interval in mS between sending of data vectors      
--------------- | -------- | --------------- | ------------------------------ | ------------------------------------------------------------

• 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

global variables

The data collected is stored in the MATLAB global called 'daf' which is an object of class data_accumulator_cirq_class (DACQ). More details on this class :

• help data_accumulator_cirq_class
• methods data_accumulator_cirq_class
• properties data_accumulator_cirq_class

The 'daf' global is a structure with the field names taken from the Vector Map Dictionary typically sent via PSOC or BBB source code. With the VT active (or previously active) type daf to see all the fields.

To access a specific DACQ object, type daf.(fieldname), eg daf.Syringe_ss_fs

To obtain the live data from the queue, data = daf.Syringe_ss_fs.get();

The VT also creates a number of other variables within the base workspace. These are mostly for development and will either be documented or removed. After starting the tool ($Id: gui_3.m 328 2015-03-23 16:19:57Z cbarn $), the following variables have been added:

whos:

 da                 1x18            113504  struct                               
 daf                1x1              70848  struct                               
 handles_gui        1x1              62727  struct                               
 handles_nsl        1x1              62159  struct                               
 handles_timer      1x1              62727  struct                               
 mc                 1x1                112  py.client.matlab_client      

In the event of an exception variables starting with "exception_" may be created.

gui_3() function

gui_3 help:

 handles = gui_3(action, varargin);

 Actions are 'stop', 'ver', and 'connect'1
 The 'stop' action is equivalent to pressing the red STOP button in the gui.   
 The 'ver' action list the current version:  $Id: gui_3.m 328 2015-03-23 16:19:57Z cbarn $
 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

• substring test (lines 68 to 73) for current directory needs to be removed / changed
  • change line 69 to : if 0 and isempty(ndx)
• When the 480k sample buffer fills, the current (unreleased) tool crashes. The released tool may also.
  • believe to be fixed in 55
• 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.
• Ability to specify the filename create by the GUI SAVE button.
  • 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
• Option to place numerical value of latest data point at graph edge.
• 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