Downloading and Running TF32J Time-frequency Analysis for Java. Paul Milenkovic Department of Electrical and Computer Engineering

Size: px

Start display at page:

Download "Downloading and Running TF32J Time-frequency Analysis for Java. Paul Milenkovic Department of Electrical and Computer Engineering"

Stephen Collins
6 years ago
Views:

1 Downloading and Running TF32J Time-frequency Analysis for Java Paul Milenkovic Department of Electrical and Computer Engineering TF32J Time-frequency Analysis for Java is an application for viewing waveforms on one or more channels and performing spectrum analysis of those waveforms. TF32J can be extended with plug-in modules written in either native code (typically C++) or in Java. Such plug-in modules can implement signal generators as well as digital filters. TF32J can be launched from a command prompt, from the Eclipse environment using the TF32J Java source files, or it can be launched from inside Matlab. When launched from Matlab, Matlab commands may be used to load waveforms and apply digital filters to those waveforms in the TF32J program. To install TF32J in your user account, please browse to the ECE 432 ECOW-2 Web page, click on the link called TF32J, and extract the files to the directory from which you launch Matlab. If you install Matlab at home or on a laptop computer, that directory is something like C:\Documents and Settings\<my login name>\my Documents\MATLAB For Windows 7 at CAE, that directory is I:\MATLAB whereas under Linux at CAE, that same directory is ~/MATLAB With this choice of directory, Matlab can invoke TF32J. Simply start Matlab under Windows. Under Linux, please start Matlab from the command line by opening a terminal window, changing to that directory, and by starting Matlab from a command prompt according to ~%cd MATLAB ~/MATLAB% matlab If you want to install those files to a different directory, please check with the instructor before proceeding as the above procedures need to be changed.

2 Launching TF32J from the Command Line The TF32J application may be launched from the command line using the Windows batch file TF32J.bat or the Linux shell script tf32j.sh. From Windows, open a Command Window, change to the I:\MATLAB directory, and invoke I:\MATLAB>tf32j sine.voc In Linux, you need to set execute permission on the TF32J shell script with the command ~/MATLAB% chmod 755 tf32j.sh which you only need to do once, after which you may invoke ~/MATLAB%./tf32j.sh sine.voc whenever you want to start TF32J. Remember that in Linux the correct upper and lower case of command names and files names is important whereas for Windows it is not. It is assumed in this example that the file sine.voc has been edited to read TF32WaveSynthesis module:track lib=vocfilt proc=sinegeni params # end_params end_module module:track lib=vocfilt proc=sinegeni params # end_params end_module When you launch TF32J using sine.voc as a command line argument, TF32J performs the Files Open menu command on that file on startup, which synthesizes a sum of sine waves of frequencies 500 and 1000 Hz, Volts peak amplitude, and zero degrees initial phase, resulting in a display looking something like what is shown on the next page.

4 To get a closer look at the waveform plot, you can click two times with the left mouse button on the green waveform plot to place a pair of cursors, you can click and drag those cursors to where you want them, and you can select Zoom in to get and

6 In the previous example, the native code module VocFilt is selected (file VocFilt.dll under Windows that had been downloaded to your Matlab directory, file libvocfilt.so under Linux that had been downloaded to the TF32lib subdirectory to your Matlab directory). The line proc=sinegeni invokes a native-code sine wave generator inside that module. In this example, the lines lib=javafilt and proc= Once you have successfully implemented a Java sine wave generator in the source code module SineFilter.java that compiles to SineFilter.class, all inside the subdirectory myjava to your Matlab directory, you can modify sine.voc to read TF32WaveSynthesis module:track lib=javafilt proc=javafilteri params SineFilter # end_params end_module module:track lib=javafilt proc=javafilteri params SineFilter # end_params end_module Opening that file should give the same results before if your SineFilter module has been compiled correctly.

7 What Has Just Taken Place The Linux shell script tf32j.sh contains a single line that launches the TF32J Java application. That line is too long to show here, so parts are listed here. The part java -Djava.library.path=TF32lib launches the Java runtime environment called the Java Virtual Machine (JVM) and tells the JVM that native code modules needed for TF32J are found in ~/MATLAB/TF32lib. Those modules are libtf32jcmp.so implementing the core functions of the TF32 application, libvsyncx.so, implementing video monitor vertical retrace synchronization for smooth waveform scrolls, libjavafilt.so that loads and runs filter plug-in modules written in Java, and libvocfilt.so containing a set of filter plug-in modules written in C++. Under Windows, the batch file TF32J.bat contains the line reads java -Djava.library.path=.;TF32lib because the native modules JavaFilt.dll and VocFilt.dll need to be in the launch directory where native modules can also find them whereas TF32JCmp.dll and VSyncX.dll may reside in the TF32lib subdirectory. The parameter -classpath TF32lib/TF32J.jar:TF32lib/TF32Plot.jar tells the JVM (Java Virtual Machine) where to find all of the Java executables (file extension.class) under Linux. The.jar extension denotes Java Archive files into which have been stored one or more Java compiled class files with extension.class. Owing to Windows using the backslash instead of the forward slash to denote directory hierarchy, and Java under Windows using the semicolon instead of the full colon to separate entries on the class path, that parameter is rendered under Windows as -classpath TF32lib\TF32J.jar;TF32lib\TF32Plot.jar The JAR file TF32J.jar contains the class files for the TF32J Java application. The TF32Plot.jar module contains classes that allow TF32J to produce plots of the waveform and time-frequency spectrogram display to a file. TF32J.jar contains a link to miglayout swing.jar within the TF32lib subdirectory. Miglayout is a 3rd-party GUI layout manager used for dialog boxes in TF32J you can look up the Web site to learn more about this useful Free and Open Source software module. TF32Plot.jar in turn has internal class path links to the free-hep*.jar files within TF32lib. The VectorGraphics library of FreeHEP ( is Free and Open Source software from the HEP (High-Energy Physics) Consortium of Stanford/SLAC, LLNL (Lawrence- Livermore National Laboratory), and CERN (European Organization for Nuclear Research). Vector Graphics is a tool for obtaining hard copy versions of Java graphics displays.

8 Running TF32J from Matlab At this point, exit TF32J. Before starting Matlab, check that there is a file called classpath.txt in your MATLAB directory containing the lines TF32lib/TF32J.jar TF32lib/TF32Plot.jar and a file called librarypath.txt in that directory containing the lines. TF32lib These lines serve the same purpose as the classpath and Djava.library.path= entries in the Linux shell script, the Windows batch file that launch TF32J as a Java application. It turns out that Matlab is written along similar lines as TF32J. Matlab is largely a collection of nativecode modules for each of the target operating systems that Matlab runs under, but the Command Window and other parts of the user interface and graphical displays of Matlab are written in Java. Because a JVM (Java Virtual Machine) is loaded in the process of starting Matlab, it is important to instruct that JVM where to find the TF32J modules, which is done by having copies of the classpath.txt and librarypath.txt files supplied with Matlab inside the MATLAB startup directory, and to have the above entries added to those files. You can use the Start Menu under Windows to launch Matlab from the collection of CAE Course Software, which will start Matlab within the I:\MATLAB directory. To do the same thing under Linux, you must not use the menu launcher as that will start MATLAB in your ~\ user home directory. Instead, open a Console Window, change to the MATLAB subdirectory of your user home directory, and invoke ~/MATLAB% matlab Launch TF32J from Matlab command prompt with the command >>t = javaobjectedt(tf32j) Juggling Flaming Chain Saws Yes, but to make the act dramatic, are the chain saws running? The above way creating an object instance of the TF32J class and assigning it to a Matlab variable uses the Matlab javaobjectedt command to access methods (function calls of class TF32J) in a thread-safe way. One of the objectives in designing a graphical user interface (GUI) is giving the appearance that multiple actions are taking place at the same time. This is commonly implemented using a single thread of program execution and by using an event-based architecture for sequencing actions such as screen updates and response to mouse clicks and mouse movement. There have been attempts to use

9 multiple threads to do the same thing, with varying degrees of success owing to threads being asynchronous and the event model being synchronous and only having the appearance of being asynchronous in a properly written GUI program. The BeOS operating system used multiple GUI threads, but I have never programmed for it and cannot answer what challenges that posed. The developers of Swing, the GUI for Java are said to have considered using multiple threads, but settled on a compromise where the GUI runs on the Event Dispatch Thread (EDT) which is separate from the main application thread on which a Java application is launched. Most Java Swing applications run a short main thread program that simply creates a JFrame object as the main application window and lets all further execution take place on the EDT in response to Swing events. The designers of Matlab made a decision sometime after the release of Matlab 6 to use two threads to use the main thread for the execution of Matlab commands and M-files, and to use the Swing EDT for the GUI. That means that for Matlab to launch a Java Swing application such as TF32J, proper synchronization measures are required when a Matlab command invokes methods on TF32J. The Matlab developers provide the command javaobjectedt, which provides all of the required thread synchronization protocols. What if you launch TF32J this way? >>t = TF32J Bad things happen. Basically, Matlab crashes, where Matlab is generally regarded as crash-proof. Matlab crashes in random fashion in response to invoking some method on object t. The reason I call this Juggling Flaming Chain Saws because you have to take an active safety measure (making sure the chain saws are turned off; using javaobjectedt) to make sure there is not a serious accident, although crashing Matlab is perhaps an inconvenience rather than a matter of a dangerous entertainment act. Some future version of TF32J may incorporate the required synchronization procedures that you will not have to call javaobjectedt; in the mean time, it is something you need to remember to do every time. You can still invoke Files Open from the TF32J menu, or you can do the same thing from the Matlab command window with the Matlab command >>t.openwavefile('sine.voc') where you should see the TF32J window pop up with something like

10 From Matlab, we have more control over what we load into the TF32J display. From the Matlab command Window, try the commands resulting in t.zerowave t.dllfilt(1, 'JavaFilt', 'JavaFilterI', 'SineFilter', [1000.0, 0.7, 0.0], false)

This action has 1) overwritten the display with the zero waveform, and 2) run the SineFilter Java program with parameters to generate a sine wave of 1000 Hz that the sine is 1000 Hz is seen in the

11 This action has 1) overwritten the display with the zero waveform, and 2) run the SineFilter Java program with parameters to generate a sine wave of 1000 Hz that the sine is 1000 Hz is seen in the two spectrum analyzer displays where the frequency tick marks are at 1 khz spacing. This is a very simple example more complex scripts for generating and filtering waveforms may be implemented using Matlab scripts to control TF32J. A summary of the public methods of the TF32J object may be listed with the Matlab command >>methods(t, '-full') and the TF32J application may be terminated with the Matlab command >> t.close Your instructor will review methods of the TF32J object accessible from Matlab and how to make use of them.