Documentation For gryph_mon.pl

January 22, 2002

1 Overview

On startup, the program attempts to read a configuration and a database file. The configuration file is named gryph_mon.cfg and contains the settings made in the program during a previous execution. The database file is named gryph_mon.db and contains the definition of filters, messages, periodic messages and other entities used by the program.

After connecting to a Gryphon, the program determines which network cards are present and lists them in the Configuration menu. After one or more of the channels have been enabled, the monitoring process may be begun by pressing the Start button. Filters, response messages, periodic messages and capture events may be configured before starting the monitor.

The monitor displays the messages that it receives from the enabled channels in the single scrolling pane in the main window. The maximum number of messages and the number of messages to save after a capture event can be set in the Configuration / Gryphon menu while the monitoring is stopped.

After the monitoring has been turned off, the displayed messages may be written to a file with a press of the button.

2 Main window

2.1 Title Bar

The status of the connection to the Gryphon (online, offline or connecting...) is shown to the right of the program name. The address of the Gryphon is shown just to the left of online. The Gryphon client number is shown to the right of online, after the semicolon.

2.2 File Menu

2.2.1 Open...

This menu item allows a configuration file to be opened and read. The default configuration file, gryph_mon.cfg, is read during startup if it is found. This menu item allows another file to be read and used as the configuration file. The configuration file contains all of the options that can be set interactively.

2.2.2 Save as...

This menu item allows the current configuration data to be saved to any filename.

2.2.3 Save

This menu item allows the current configuration data to be saved to the same file from which it was read.

2.2.4 Connect to xxxx / (Disconnect from xxxx)

This menu item connects to the specified Gryphon (denoted by ``xxxx'') and registers with its server as a normal client. The program interrogates the Gryphon and adds a list of available channels, their speeds and events to the Configuration menu. When connected, this menu entry is changed to Disconnect from xxxx which allows the connection to the Gryphon to be broken. When the connection is broken, the information that was added to the Configuration menu is removed.

2.2.5 Database File...

This menu item allows a database file to be opened and read. The database file used the last time or the default database file, gryph_mon.db, is read during startup if it is found. This menu item allows another file to be read and used as the database file. The database file contains all of the filters, triggers, messages, and periodic messages that can be selected interactively.

2.2.6 Exit

This menu item exits the program. If the configuration data has been modified or the program thinks it may have been modified, a dialog box will appear which allows the current configuration to be saved or discarded before exiting.

2.3 Configuration Menu

2.3.1 Gryphon...

Pressing this menu item opens a dialog box from which the following can be set.

The address of the Gryphon. The address may be either a resolvable name or an IP address in dotted quad notation (192.168.0.1). It can changed only when the program is offline (not connected to a Gryphon).
The maximum number of messages to display / save. Since the messages are saved in memory, it is possible to exceed available memory by making this entry too large.
The number of messages to collect after a capture event. A capture event may discard collected messages to make room for the post event messages. The capture / display of messages is stopped after this number of messages has been saved following a capture event. If another capture event occurs before the first is finished, the logic starts over again. That is, some messages already captured may be discarded and the count of messages to be captured before shutting down is again set to this value.
What to do with a new message when the maximum number of messages have already arrived. Either the oldest message is discarded and the new message is kept or the new message is discarded.
Whether the transmit echo for all channels is on or off.
The name of the file to which the captured data is to be written. The filename's extension, if present, is displayed separately. The trailing digits, if present, are removed from the filename which are also displayed separately. The path to the file is not displayed. One or more of the trailing digits may be moved to the base filename if desired.

If no filename is present, the path and filename must be entered or selected via the button labeled ``Set base name of the save file''. If an existing file is selected, it will not be overwritten until the save button on the main window is pressed. Once a filename has been entered, it may be changed from the dialog box without pressing the button. After each file is saved, the numeric portion of the name, if present, is incremented. The number of digits present in the ``Number to append to base filename'' entry determines the number of unique filenames that are possible. For two digits, the numbers range from 0 to 99; for three digits, they range from 000 to 999.

All changes that are made are applied immediately. For this reason, there is no Save or Apply button. The Close button closes the dialog box.

2.3.2 Associations...

This menu item is active only while a connection to a Gryphon is active and the program is not capturing messages. Pressing this menu item opens a dialog box from which actions may be configured to occur in response to triggers. The triggers and actions are defined in the database file. (The gryph_db.pl program may be used to edit the database file.)

Triggers: The first trigger is Hot Key. When an action is associated with Hot Key, a menu button is created next to the trigger. The desired hot key (the spacebar, or F1 through F12) may be selected from that menu button. The default value is the first entry in the menu button list.

The second trigger is Manual Key. The manual key is the button on the main window labeled Manual Trigger.

The third trigger is Startup. This trigger event takes place when the Start button on the main window is pressed.

The rest of the triggers are sorted by network type. In order for a network and its triggers to be displayed, at least one channel for that network must be enabled from the Configuration menu. When an action is associated with a network trigger, a menu button is created next to the trigger. The desired channel number may be selected from that menu button.
Actions: The first action is Capture Event.

The next set of actions are messages that may be sent out on a network. They are sorted by network type. At least one channel for a given network must be enabled from the Configuration menu in order for the messages for that network to be present. When a message is associated with a trigger, a menu button is created next to the message name. The channel number over which the message is to be sent may be selected from that menu button.

The next possible action is the KWP2000 wakeup. It is present only if one or more KWP2000 channels are enabled on the Gryphon and if one or more KWP2000 Comm Setup entries are in the database and if one of them is selected as a channel's speed setting. In addition the selected entry's Note Type must be set to Tester, or one or more KWP2000 messages must be defined in the database.

The last set of actions are periodic messages that may be scheduled. When a periodic message is associated with a trigger, a data entry field is created next to it. The number of iterations from the database file is the default value. The value may be changed to any number between 1 and 4,294,967,295. If a value greater than or equal to 4,294,967,295 is entered, it will be replaced by the word ``infinite''. This does not mean that an infinite schedule has been defined, but that the largest possible value has been entered as the iteration count.
Add Button: The Add button is used to associate an Action with a Trigger. (Control-A may be used instead of the button.) If both a Trigger and an Action are selected (highlighted), and the Add button clicked, a new line will be added to the Configured triggers and actions sub-window. The trigger is on the left and the action is on the right with an arrow showing that one causes the other.

To add an Action to a configured Trigger -> Action set, select the Action to be added from the Action sub-window and an Action in the desired set in the Configured sub-window. The new Action will be added after the one in the configured set. To add an Action to the beginning of the list of Actions for a configured set, select the Trigger of the configured set. When the Trigger occurs, the Actions will be produced in the order that they are listed.
Delete Button: A configured Action may be removed from the list of actions configured for a Trigger by selecting the Action and clicking on the Delete button. (Control-D may be used instead of the button.) If the last Action for a Trigger is deleted, the Trigger is deleted from the Configured sub-window as well. To delete a Trigger and all of its Actions, select the Trigger and click the Delete button.
Close Button: Pressing the Close button (or pressing Control-L) closes the the dialog box. All changes that are made are applied immediately. For this reason, there is no Save or Apply button.

There are no restrictions on which Actions may be used with which Triggers or how many times a given Action or Trigger may be used.

2.3.3 Filters...

This menu item is active only while a connection to a Gryphon is active, one or more channels have been enabled and the program is not capturing messages. Pressing this menu item opens a dialog box from which filters may be applied to the enabled channels. The filters are defined in the database file. (The gryph_db.pl program may be used to edit the database file.)

As each message is received, it is checked for conformance with the filters listed for its channel in the order shown. If the message conforms to a filter, the action (Pass or Block) defined for that filter determines the fate of the message. If a message does not conform to any filters, the action defined by the FINAL filter, which cannot be deleted, determines the fate of the message. In other words, the FINAL filter matches all messages.

Available: A list of defined filters for the enabled channels.
Configured: A list of channels and the filters that are in effect for them.
Add Button: The Add button adds the highlighted filter in the Available sub-window to the channel shown with the ``<'' marker in the Configured sub-window. The new filter is added after the marked line in the Configured sub-window. The channel identifier line and any filter except the FINAL filter may be marked.
Delete Button: The Delete button deletes the marked (with a ``<'' at the end of the line) filter from the list of filters for a channel.

All changes that are made are applied immediately. For this reason, there is no Save or Apply button. The Close button closes the dialog box.

2.3.4 List of available channels

When the program connects to a Gryphon, it finds which channels are available and lists them as cascade menu entries. The enabled/disabled state of the channels is shown in the Configuration menu. Two entries follow which allow all of the channels to be enabled or disabled.

The cascaded menus consist of an enable/disable checkbox, a list of speeds available for the channel shown as radio buttons and a list of events to display shown as checkboxes. Left clicking on the dashed line at the top of the cascaded menu creates a dialog box of the menu. The predefined speeds in the Gryphon are listed first. If the channel is CAN, any special speeds that have been defined in the database file are listed next. The same applies to KWP2000 channels and any KWP Comm Setup entries. The radio button that corresponds to the current speed is selected. The list of events shows which events are to be displayed in the Scrolling Window. If the first entry, Display all events is selected, the rest of the checkboxes are disabled.

In order to receive and display messages from a channel, that channel has to be enabled. Once a channel is enabled, its checkbox turns blue and the label changes from Disabled to Enabled.

The current speed, as read from the Gryphon, is shown as the selected radio button. Pressing a different radio button does not change the speed of the channel until the Start button on the Main Window is pressed. If the channel is not enabled, its speed is not changed or set. The current speeds of the channels are read once when the connection is made to the Gryphon. After that, the program maintains its own values which may or may not correspond to the current speeds of the channels.

After the Start button is pressed, changing the speed of a channel via a radio button does not change the speed of the channel until that channel is disabled and then enabled.

Responses and periodic messages may be sent out on channels that are not enabled.

2.4 Font Menu

The Font menu allows the font size and weight used by the Scrolling Window and its label to be changed. Changing either of them marks a change in the configuration data which causes a dialog box to appear on shutdown unless the configuration was previously saved. The saved font size and weight are used as the startup values for future executions.

2.5 Scrolling Window

Received messages and events are displayed in the scrolling window. For each network message, its channel number, timestamp, Rx/Tx flag, header, data and extra data are displayed. The header, data and extra data are shown as hexadecimal bytes separated by spaces. A colon is used to separate the three fields from each other.

For each Event message displayed, the channel number, timestamp, the letters EV and the name of the event are shown.

Informational messages also appear in response to a hot key being pressed, a response message being sent and a periodic message start or stopping.

As the data fills the window, the scrollbar allows older data to be viewed. When the scroll box is moved from its normal position at the bottom of the scrollbar, the scrolling action of the data is stopped. To continue scrolling through the data, move the scrollbox to the bottom of the scrollbar.

When a message arrives that is too long for the window, a horizontal scrollbar appears at the bottom of the scrolling window.

2.6 Progress Bar

The Progress Bar shows the ratio of received messages to the maximum allowed via a yellow indicator.

2.7 Start Button

Pressing the Start button causes filtering and response messages to be sent to the Gryphon based on the current configuration. If any messages are displayed in the scrolling window, they are deleted. The Start button stays depressed and changes its label to Stop.

Pressing the Stop button turns off reception of network traffic and deletes filters, responses and periodic messages.

Pressing Control-S toggles the Start/Stop button.

2.8 Save as Button

The Save as button is active anytime that there are messages displayed in the scrolling window and data collection is not in progress. If no filename is displayed in the button, pressing it will cause a file selection dialog box to be displayed. Selecting a file from that dialog box saves the captured data, increments the numeric component of the filename and places the name of the next filename to be used in the Save as button. If a filename is displayed in the button, pressing it will save the captured data in the filename, increment the numeric component of the filename and update the name of the next filename to be used in the Save as button.

Pressing Control-V produces the same result as left clicking on the Save as button.

2.9 Manual trigger Button

The Manual trigger button is active whenever data collection is in progress. Left clicking on the Manual trigger button, causes a Capture Event to occur and whatever other action(s) may be associated with it. A Control-M is the same as pressing the button. This button and its associated hot key are always active whenever data is being collected.

2.10 Status Line

Various messages indicating the state of the program are displayed here.

2.11 Main Window size and position

Each time the configuration is saved, the Main Window's current size and position are saved. These values are used for subsequent executions as the Main Window's default (starting) size and location. Changing the Main Window's size and/or location does not cause a dialog box to be shown during shutdown. If you want to save the window's size and location for future use, you have to explicitly save the configuration file or modify some other configuration parameter so that the dialog box will appear during shutdown.

This document was translated from L^AT_EX by H^EV^EA.