Companion Tools

These tools provide functionality that the user might find useful. While not strictly a necessary part of the PYToolkit, they can ease certain aspects of its use. In particular, the simwbDLClient module can be daunting due to the complex way that data is recorded in SimWB. Hopefully the user can use this program as-is. If not, then a working example of its use will surely be helpful.

Everything here should run using Python 2 or 3. The following descriptions will simply refer to "python", but could just as easily have referred to a more specific version (e.g. python2, python3.6, etc).

dlxtractrem.py

The dlxtractrem.py command line program can be used to extract logged items from a local or remote machine, storing them locally as Matlab, HDF5 or CSV (comma separated value) data files. A short usage statement is produced by running python dlxtractrem.py without arguments. More detailed help is produced with the -H argument. This program is shipped in source form and is an excellent example of PYToolkit use. You can find this program in /usr/local/ccursim/python/PYToolkit or C:\Concurrent\PYToolkit (assuming the default installation directories).

dlxtractrem.py requires the scipy Python package to create Matlab V5 files, the hdf5storage Python package to create Matlab V7.3 files and the h5py Python package to create HDF5 files. Querying of test information and CSV output is still available without them. Look here for more information on finding/loading Python packages.

simwbTarget.pyc

simwbTarget.pyc is a command line program that guides the user through creating/editing a SimWB XML target configuration file. Simply run the module via python -m simwbTarget and follow the prompts.

Demos

A few Python scripts are provided here demonstrating PYToolkit usage. They have been designed to be both useful as stand-alone command line programs as well as demonstration aids. Just right-click the link and save the program to use it.

These two are the simplest. They are single-use and do not contain all of the complexity of a general purpose, stand-alone program. But they serve as simpler examples to those that are not quite so expert at Python.

startStop.py

HOST = 'localhost'

createTestAndICs.py

HOST = 'localhost'

Usage statements and command line options are shown below along with a brief description of the program. Usage can always be generated with the '-h' option by itself (e.g. python startTest.py -h). These programs will work on both the SimWB host machine as well as on clients (Linux or Windows), just as long as the PYToolkit is available somewhere on your machine's PYTHONPATH. Be aware that getItem.py utilizes ANSI terminal control sequences on output. When running on Windows you need to install ANSI.SYS or remove these sequences from the script.

Most of these programs utilize the getTarget() API call using the default environment variable SIMWB_TARGET (click on the call for more details).

getItem.py

  usage: python getItem.py -s -r RATE -h HOST -u USER/PASS -p PROJECT ITEM ...
         get a SimWB ITEM value from the currently running test
           when ITEM is '?' provide a descriptive list of ITEMs
         -s  display strings as character strings (default is URL encoded)
         -r  repeat every RATE seconds (default is one-shot)
         -h  connect to HOST (default is localhost)
         -u  log in as user USER, password PASS (default is admin/nimda)
         -p  select PROJECT (default is <default>)

setItem.py

  usage: python setItem.py -h HOST -u USER/PASS -p PROJECT ITEM VALUE ...
         set a SimWB ITEM to VALUE in the currently running test
           when ITEM is '?' provide a descriptive list of ITEMs
         -h  connect to HOST (default is localhost)
         -u  log in as user USER, password PASS (default is admin/nimda)
         -p  select PROJECT (default is <default>)

startTest.py

  usage: python startTest.py -h HOST -u USER/PASS -p PROJECT TEST[/SESSION]
         start a SimWB test
           without SESSION auto create the session
         -h  connect to HOST (default is localhost)
         -u  log in as user USER, password PASS (default is admin/nimda)
         -p  select PROJECT (default is <default>)

stopTest.py

  usage: python stopTest.py -h HOST -u USER/PASS
         stop the currently running SimWB test
           no error if no test is running
         -h  connect to HOST (default is localhost)
         -u  log in as user USER, password PASS (default is admin/nimda)

streamLogs.py

  usage: python streamLogs.py
         stream both the SimWB messages and cfgsrv.log output to the terminal

connect2.py

  usage: python connect2.py
         connect to two SimWB systems at the same time

refreshData.py

  This is not so much a stand-alone usable program as it is a really
  small example of how to stream data in a refresh thread. Check it out - 
  you migh find it useful.

startHMI.py

  usage: python startHMI.py -h HOST -u USER/PASS HMI
         start a SimWB HMI
         -h  connect to HOST (default is localhost)
         -u  log in as user USER, password PASS (default is admin/nimda)

pcmcc.py

  usage: pcmcc -h HOST -u USER/PASS -p PROJECT -f -k KEYITEM -r REQITEM -a ANSITEM -s SCRIPT TEST
         add the PCM clear codes script to this TEST (? lists all tests)
         -h  connect to HOST (default is localhost)
         -u  log in as user USER, password PASS (default is admin/nimda)
         -p  select PROJECT (default is <default>) 
         -f  force replacement of an existing script
         -k  examine RTDB item KEYITEM for key-on (default RLY7256_2_CH07_ISP_R)
         -r  create RTDB item REQITEM for the PCM request (default pcm_req)
         -a  create RTDB item ANSITEM for the PCM answer (default pcm_ans)
         -s  use SCRIPT as the script name (default clearcodes)

ASAMDemo.py

ASAMDemoMAPOnly.py

The following three links should download when clicked. If not then right-click and save/download the file.

ASAMDemo.gp

ASAMDemoTarget.xml

simplepid.mdl

Configure SimWB with dlunbufferedio=1 in /etc/ccursim.conf. This is not a firm requirement, but without it you may recieve slightly less capture data than expected (data logger caching and system load could result in a race condition between your read request and SimWB's ability to get the data to disk). Changing dlunbuffered will require a SimWB restart (service simwb restart).

Run the SimWB Control Center, and log into the target machine. If this fails, make sure that the SimWB host has allowed access from the client you are running on (see $SIMWB_ROOT/etc/hosts.access). Create an 'ASAM' project below '<default>', and make it the active project. Leave the control center open.

Run Matlab and open simplepid.mdl in Simulink.

Open the SimWB preferences. Under General, select model-specific. Under RTDB, deselect hierarchical naming. And under Code Generation, select RTWCAPI signals.

Generate an RTDB named 'simplepid' using block names (just select this and leave the others as they are). Build the model. Close Matlab.

Back to the SimWB Control Center. Create a 'simplepid' test using the simplepid model you just built. Create a 'main' session in the simplepid test insuring that logging is enabled and that Direct I/O is unchecked.

Open a bash/cmd.exe window on your client. This can be the server too. Any machine that has a PYToolkit installed. Edit the ASAMDemoTarget.xml file using 'python -m simwbTarget ASAMDemoTarget.xml' or your favorite text editor. If you've followed these instructions you should only need to change the host name, and only then if you are not running on the SimWB server. When running the MAPOnly demo you must edit the file and change the CONFIG dictionary to match the information in the XML file.

Now run the demo using 'python ASAMDemo.py'. The results are stored in ASAMDemo.dat (time, plant_response, reference). You will need gnuplot on your client to see the results plot. Otherwise expect to see some sort of error about the gnuplot command not found.

Take a peek at Concurrent.log (always created when using the ASAM package). It contains a wealth of information that can be invaluable when debugging. Just so you know, the number in the first column are elapsed milliseconds since the previous message. Message ordering can be odd since what you see are three separate streams of data recorded in one file.