Serial Analyzer 2.7.1
by Crovy
crovy@libero.it
www.javahouse.altervista.org

Index

General Information
Credits
To Do List and Known Bugs
Menu
Command Area
Hot Keys
Tabs
Terminal Area
Status Bar
Programming
Command Mode
Auto Answer
BeanShell
Change Log
Installation



General Information
SerialAnalyzer is a programm mainly conceived to monitorize exchanged data on the serial line. Its first evolution allowed also the data forwarding as a normal PC and it finally evolved as far as including the TCP/IP connection as well as the server function.
Its mainly characterics are therefore:

Credits
Special thanks to Mario Gambino (mario.gambino-sr77@poste.it) for his advice, debug and the installation tool he configured.

To Do List and Known Bugs
To Do List:
  1. implement the plug-in structure;
  2. to be able to change the parameters of the connection from the scripts in BeanShell;
Known Bugs:
  1. Since version 2.6.0 has been introduced the selection of the Look&Feel from a list containing the Look&Feel installed in the system.

    The list of installed Look&Feel is done by analyzing all files "jar" in the folder "JAVA_HOME/lib/ext" and this, particularly on older computers, can take a long time at start of SerialAnalyzer.

    If you need to speed up the start of the program you can delete the library "JcLafChooser.jar" in the directory "lib" where you have installed the SerialAnalyzer. Removing this library is no longer made the search for Look&Feel and you can choose only between the Look&Feel automatically recognized by Java;
  2. By pushing the "F10" button on keyboard, "File" menu will be opened I think it is a problem of Java;


Menu
Menu' functions:

Command Area
Command area functions:

Hot Keys
In this section compare the twelve function buttons to be recalled from keyboard and mouse in order to send defined strings. Each button corresponds also to a visualized comment, which automatically breaks out when getting with the mouse cursor to the relative function button.
Is possible to call a BeanShell script inserting the string "bsh(folder/filename)".


Tabs
This section includes Tabs to select the different screen visualizations:

Terminal Area
In this section will be visualized all data which were received and forwarded through Hot Keys programming, or data directlu keyed in this area. It is moreover possible to forward directly from keyboard all Ascii characters from 0 to 31, simply pushing CONTROL button at the same time. (as identified in the Ascii table). For example, in order to forward a character with code 3 (equivalent to CTRL-C) push button "CTRL" + button "c". Since version 2.7.0 was introduced the option "Command Mode" which allows you to associate at each key a sequence of data to send. Obviously, when this option is enabled as described above, only for data transmitted, it is no longer valid.

Status Bar
The Status Bar displays the following information:

Programming
From version 1.7.0 has been introducted the possibility of creating a programm which can automatically execute repetitive operations. After having keyed the code lines, it is necessary to execute the "compilation", both to control possible mistakes, and making effective the modifications brought to the programm. When the programm is loaded from file, this will be automatically compiled. Here are some rules to be followed during programming:
Programming ezample (send the string "ciao x" ten times, substituting to x the sequentioal number from 1 to 10):
// set the variable 1 to 1
10:set (1,1);
// send "ciao" string
20:send (ciao );
// send the Ascii converted date of the variable 1
30:send Var(1,ASCII,0);
// send a CR LF into exadecimal
35:send ([0D][0A]);
// increase the variable 1
40:add (1,1);
// compare if the variable 1 is <= a 10
50:if (1,<=,10);
// true comparison, get back to line 20confronto vero;
60:go to (20);
// false comparison, end of programm
100:end ();

Command Mode
Since version 2.7.0 of SerialAnalyzer has been added the mode Command Mode selectable from check box CmdMode or from menuCommand.

The default mode is Terminal Mode, in this mode by pressing a button is displayed and sent to the open connection to character referred to the key pressed.

In the mode Command Mode can be associated with each key a sequence of characters to send the connection open as for the definition of the function keys Hot Keys. In this way you can expand almost indefinitely a list of sequences retrieved with the push of a button.

The definition of the association key=command is made in the Programm editor with the same basic rules used for the programming, including compilation.

The differences are as follows: Example program file with the definition of two commands associated with buttons a and A:

>a=sequence associated with the key a lower case

>A=sequence associated with the key A upper

100:end();



Auto Answer
Since version 2.7.0 of SerialAnalyzer is now possible to automatically send the answers by analyzing the data received. In fact this feature was already present (and remained) but did not allow the flexibility introduced now.

In fact, you must define the exact sequence of data to recognize and answer to it.

These definitions are made to the Programming editor with the same basic rules used for programming, including compiling and using the definition of keys of Command Mode.

The differences are as follows:
  • You can have a single program file that contains both the program and the definitions of Command Mode and the definitions of Auto Answer;
  • the line must begin with the characters ">aa=" followed by the letter that identifies the key associated with the response and the character "=";
  • after the character "=" is defined as the sequence of characters to be recognized in order to send the reply button associated with the previously defined;
  • see Command Mode for more information;
Example program file with the definition of two different responses of the buttons a e A:

>a=sequence associated with the key to lower case

>aa=a=received a character, I respond with a sequence from the key a

>A=A key sequence associated with the upper

>aa=A=A character received, reply with sequence from the key A

100:end();



BeanShell
From version 2.1.0 of the SerialAnalyzer it is be implemented the interface with the program, always in Java, BeanShell that allows to construct of the scripts in Java called from the SerialAnalyzer so as to to allow to integrate functionality personalized to the SerialAnalyzer.

An example much simple one is the calculation of the checksum. All the protocols of communication have a field with the checksum of the frame. From the SerialAnalyzer it is possible to insert this data, but it goes calculated manually and if we are worth a single byte of the frame we must update also the data of the checksum. With a script in BeanShell simple one is possible to automate this operation in way much.

For the relative instructions of BeanShell can be consulted relative documentation at the address http://www.beanshell.org/
During the phase of development/debug of a script in BeanShell, it is advised to open also the window where it comes redirected the Standard Output and the Standard Error (Menu - > Tools - > StdOut/Err Window) so as to to verify all the messages of error that BeanShell gives back.

Hour we analyze the implementazione of the BeanShell with the SerialAnalyzer.

In the first place it is necessary to specify that scripts are two modality in order to execute one: from menu "Tools" or "HotKeys" (it can be recalled also from the tool of programming integrated in the SerialAnalyzer and works like the HotKeys).

This distinction has been made in order to cover various requirements.


In the folder where it is installed the SerialAnalyzer comes created a folder "bsh" that in its turn it is divided in "menu" and "prog" in order differentiating the scripts called from menu and those from programming/HotKeys. From these folder they must obligatorily be created of the own ones folder in order to divide in categories the various scripts. As an example it can be created a folder "Checksum", is under the folder "menu" that under the folder "prog", and be put the files here to us containing the scrip which must have the extension "bsh".

Under the folder "menu" a single level of folders can be created, while under the folder "prog" more levels can be created than folders that obviously they must be written when the script is recalled.

The folders, and the scripts, created under the folder "menu" come automatically visualize to you like voice in menu "Tools" of the SerialAnalyzer (if new folders or files are created it is necessary to restart the SerialAnalyzer in order to see modernized the voices of the menu).
I, as an example, have inserted a script for the calculation of the checksum that reads the data that I have previously selected from the window "Terminal" and visualizes me the result in a JOptionPane.

On the contrary of the folders and the scripts created under the folder "menu", folders and the scripts created under the folder "prog" they are not visualizes to you in the menu, but scripts are called only from "HotKeys" inserting the word key "bsh(folder/script)". As "folder" agrees the first one, or more levels, after the folder "prog" (than therefore it does not go written), while for "script" the name of the file of the script without extension agrees. Attention to respect capital and very small letters like the name of the file. For the separator of the file "/" it can be used "/"or" \ ", it comes then automatically adapted to the used operating system.


From version 2.2.0 is possible to call scripts present in the same folder of properties file.
The scripts must be puttinges in a folder ?SaBsh? where the two usuals folders ?menu? and ?prog? must be present. In the folder ?menu?, on the contrary of that present in the folder of the SerialAnalyzer, others folders cannot be created, all scripts called from menu must be in this folder.
When load the properties file from a different folder of start of the SerialAnalyzer, the program automatically tries the scripts and, if present, it enable in menu ?Tools? the voice ?PropertiesPathScript? with the list of scripts.
For the scripts called from programming/HotKeys the symbol "@" must be put before the name of the script, as an example bsh(@folder/script);

Attention, with the operating system Linux I have noticed that if the SerialAnalyzer comes executed from shell with the command "java - jar SerialAnalyzer.jar" all works correctly and the property of system (Java) "user.dir" point correctly to the folder where it is present the file "SerialAnalyzer.jar" and therefore the program sees the folder correctly "bsh" where the scripts in BeanSheel are present.
If instead the file "SerialAnalyzer.jar" it comes executed with a double click from the files browser, Konqueror, Nautilus, etc etc, the property of system (Java) "user.dir" point always to home of the user and therefore the program does not find the folder "bsh" and consequently the scripts in BeanShell.
In order to verify the value of the property "user.dir" from the SerialAnalyzer it must select the voice "System Info" in menu "Help".

In order to facilitate the choice of the script, in "Tools" menu it has been inserted a voice "Select Program Script" that allows to be navigate in the folder "prog" of the scripts and to select one script. Once selected the script comes automatically paste in the Clipboard the string in order to recall the selected script, as an example "bsh(Checksum/Crc16)".

When it comes called a script, the SerialAnalyzer puts on hand of the references to variable and the methods that hour we will go to analyze.

Vars reference:
  • parent = it represents the class "BeanShellCaller" used from the SerialAnalyzer for call the script. It is necessary to make reference "parent" in order calling all the methods that the SerialAnalyzer puts on hand
  • parent.jFrame = it represents the reference to the JFrame of the SerialAnalyzer for to use the GUI in the script (as an example in order to center the JOptionPane);


Method reference:
  • String getSelectedText() = it returns in one string the data selects to you in the window "Terminal";
  • Vector stringToIntDataVect(String) = it returns in a Vector of Integer the binary data you are converted from the string of text ascii with the conventions in order to represent the data used from the SerialAnalyzer ([02] for the exadecimal data and <002> for that it decimates them);
  • String intToString(int) = returns an ascii string, in the CTRL -->HEX format, of the integer binary data;
  • Vector getApplicationDataVect() = return a Vector of Integer of binary data from the SerialAnalyzer. In particular they are those data inserted before the call to the script. As an example if we define the key "F1" with following string "[02]provabsh(Checksum/8bit)", calling this method from the script comes given back to me, in binary shape, "0x02 0x70 0x72 0x6f 0x76 0x61".
  • String getApplicationDataString() = return a ascii string, in the CTRL -->HEX format, of the data from the SerialAnalyzer. In particular they are those data inserted before the call to the script. As an example if we define the key "F1" with following string "[02]provabsh(Checksum/8bit)", calling this method from the script comes given back to me exactly the same string "[02]prova".

    Since version 2.6.1
  • setScriptDataVect(Vector) = it gives back to the SerialAnalyzer a Vector of Integer containing the binary data to send as a result of the call to the script from HotKeys. Referring itself to the example before, it has been called the script in order to calculate the checksum, the script calculates and must give back a Vector of Integer with the original data and the data of the checksum;
  • boolean isStopThread() = used to understand if the SerialAnalyzer demands to interrupt the Thread of the script
  • sendData(String) = used for send one string of data in ascii, with the conventions in order to represent the data used from the SerialAnalyzer, on the opened communication channel. The data send to you come visualize to you in the window "Terminal";
  • sendData(Vector) = used for send a Vector of Integer of binary data on the opened communication channel. The data send to you do not come visualize to you in the window "Terminal";
  • enableRxData(boolean) = used to qualify the management of the data received. This involves that the script is taken care to on hand read (through a Thread) the data from the pipedInputStream put, otherwise risks the block to the SerialAnalyzer
  • enableSendDisp(boolean) = used to qualify the visualization of the data transmitted;
  • enableRxDisp(boolean) = used to qualify the visualization of the data received;
  • endScript() = used to signal the end of the script;
    It is one called obligatory to add to the end of the script!
  • int getRxData() = used for read a received data;
    Return -1 in case of data not available, otherwise returns the data.
  • clearTerminalArea() = used for clear the terminal area.
  • boolean clientIsOpen() = used for see if the client connection is open.
    Return true if is open, false if is close.
  • boolean clientOpen() = used for open the client connection.
    Return true If it is opened, false for any errors.
  • clientClose() = used for close the client connection.
  • setLastBshFilePath(String) = allows you to store the path of a file managed in the script.

    This can be handy the next time the script is running to tell at the JFileChooser the folder used previously. The data is stored until you close the Serial Analyzer.

    Since version 2.7.0
  • String getLastBshFilePath() = returns the path previously stored with setLastBshFilePath.

    Since version 2.7.0
  • setLastBshFileName(String) = allow you to store the name of a file managed in the script.

    This can be handy the next time the script is running to tell at the JFileChooser the file used previously. The data is stored until you close the Serial Analyzer.

    Since version 2.7.0
  • String getLastBshFileName() = returns the name of the file previously saved with setLastBshFileName.

    Since version 2.7.0

In the folder bsh some examples of script are supplied.


Change Log
Here follows a resume of all Serial-Analyzer Change Log:

Installation
SerialAnalyzer is a Java developed program, and that means you have to be already installed on your PC the Java Virtual Machine (JRE) produced by SUN. It can operate with JRE from version 1.5 onwards.
Latest versions are provided with an installation tool (still on Java) which automatizes the whole procedure.

In order to operate a manual installation, do as follows: