Using Protocol Analyzer wtih the Option for Creating Decoders
Reload Decoders
When writing a decoder, it is often very useful to be able to view the results of changes right away. To reload the decoders to determine the effect of decoder changes, load a capture file into the protocol analyzer. Change your decoder in a text editor and save your changes. In the protocol analyzer, open the Frame Display window and click the icon on the far right of the toolbar that looks like two arrows.
Building Methods
Your custom methods will be automatically built for you, provided you have Microsoft's Visual C++ 2008 (known also as Visual C++ 9.0) installed on your system. Assuming that you do, all you need to do is start the protocol analyzer. It should detect that you have a method that needs to be built and ask you if you want to build it now.
You can also build your methods at any time by using the toolbar buttons. Start the protocol analyzer. If you are in live mode (i.e. you have the data capture icons on your toolbar), go to the File menu on the Control window and choose Close. Any open capture files will be closed, and the protocol analyzer will enter View Mode. You will find two icons in addition to the File-Open icon.
The icon with the red arrow, will recompile all methods that have changed. The second icon, will rebuild all methods for which there are source files. In the <installation path>\Executables\Core directory, a Method.Log will be created. This file has the inputs and outputs to every method called for every field in the file. You want to use this with a file of just a few frames because otherwise the log file gets very large and it's very difficult to match the log data against the capture file.
How to Insert Fictitious Protocol into a Fictitious Product
If you are writing decoders for industrial automation analyzers, you may want to add your decoder as a separate analyzer in the launcher. This way your users can simply click on the "Analyze My Custom Industrial Protocol" link instead of choosing a generic analyzer and setting the stack within the software themselves.
The example product is called "Fictitious Product". The example protocol is called "Fictitious Protocol". All references to file names and tags in files will use that name for convenience.
File “FP.personality” must be modified so that an option to analyze data with the new decoder or stack will be presented by the launch application. The decoder-writer will determine the name of the personality file. In general, to insert the new protocol, change "Fictitious Protocol" or "FictitiousProtocol", the placeholders in the examples below, to the name of the desired protocol. Spaces are not important in items that are for display only or in items that are used in determining the application command line. Items in italics are just display items, and are completely at the decoder-writer's discretion. Items in bold-type must be consistent both inside a file and across the files. Note that angle brackets, '<' and '>', are used to indicate variable entries, and are not a part of the actual syntax.
The resulting file path will be: FP.personality will be put into My Decoders.
You will need to include this files in your distribution package along with the method(s) and decoder(s).
The contents of file "FP.personality" are:
[Rules]
0x7f000404,0x7f000000,0x7f000000 TCP - Fictitious Protocol
[Filters]
Include Fictitious Protocol,Predefined\TCP IP\Include,,Include,port 9998 or port 9999
[Port Assignments:TCP]
9998-9999,0x7f000000
[Predefined Stacks]
Fictitious Protocol with autotraverse,Auto,0x7f000000,
[Common Personality]
CbSizeInKbytes=16398
FileSizeInKbytes=32793
WrapBuffer=FALSE
CompanionSizeMultiplier=3
StartupWindows=CVStaDisp
EnableNodeFilters=true
[Personality`Fictitious Product`Ethernet`FictitiousProtocol]
ShortcutName=Ethernet\A Fictitious Protocol
SetupCommand=.\Fts /"Fictitious Product=Ethernet" /Setup /OEMKEY="FictitiousProtocol"
OemTitle=Fictitious Product Protocol Analyzer for Fictitious Protocol
Description=Double-click to analyze your Fictitious Protocol network, or click the [Go!] button.
The Rules, Filters, Port Assignments and Predefined Stacks sections are described in "Putting It All Together": "[ProtocolName].personaility Files". The Common Personality section does not need to be included in your custom personality file. If no Common Personality section is found, the software will use the one found in the personality file for the product, which is as it should be.
You will need to change the Personality section. Line order within the section is not important, with the exception of the first line.
The first line is the personality section header, and it must be the first line. The format is "[Personality`<Product Name>`<Driver Key>`<OEM Key>]". In this example, the data are being collected from an Ethernet network, so we must set the Driver Key to "Ethernet". We have decided to use a tag "FictitiousProtocol" as the OEM Key (to differentiate from other Ethernet personalities). The decoder-writer will determine that key value, but it must be consistent within and across the files. You can find the appropriate values for the Product Name and Driver Key by looking in the personality file for your product.
The next line is the Shortcut name. The format is "ShortcutName=<Driver Group>\<Protocol Display Name>". The driver group will generally already be displayed in the selector, so to put the protocol in an existing group, use one of those names ‐ in this case, "Ethernet" has been used. Another name could be used, but that will create a new group. The Protocol Display Name is at the discretion of the decoder-writer.
The next line is the SetupCommand. This is the command line that will be used to launch the setup mode of the protocol analyzer. The format is "SetupCommand=.\Fts /"<Product Name>=<Driver Key>" /Setup /OEMKEY="<OEM Key>".
The next line is the OemTitle. This is the title that will be displayed on the Control Window of the protocol analyzer. The format is "OemTitle=<Decoder-writer's choice of title>".
The next, and in this case last, line is Description. This is the description of the action that the "Go" button will perform in the selector application. The format is "Description=<Decoder-writer's choice of description>".
Pay careful attention to the leading character in the personality section of the personality file. This character is used as a separator, and is a grave accent, and is found on the upper-left key on a keyboard, co-located with the '~'.