Documentation For gryph_lin.pl

May 26, 2005

1  Overview

On startup, the program attempts to read a configuration, a database and a LIN LDF file. The configuration file is named gryph_lin.cfg and contains the settings made in the program during a previous execution. The database file is named gryph_lin.db and contains the definition of filters, messages, periodic messages and other entities used by the program. The LDF (LIN Description File) file's name is the one loaded during the last execution of the program. (Its name is stored in the configuration

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  Select LDF...

This menu item allows an LDF file to be selected and read. The name of the last LDF file loaded and read via this menu entry is saved in the configuration file. Each time the program is loaded, the last read LDF file is automatically read by the program.

2.2.2  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 modes 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.3  Reload Database File

This menu item allows the current database file to be re-read so that changes in the current database file may be utilized by the program.

2.2.4  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_lin.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 commands, messages, periodic messages, filters and triggers that can be selected interactively.

2.2.5  Exit

This menu item exits the program. If the configuration data has been modified or the program thinks it may have been modified, the configuration file will be saved before exiting.

2.3  Configuration Menu

By clicking the left mouse button on the dashed line at the top of the menu, a separate window is created that contains the menu.

2.3.1  Gryphon...

Pressing this menu item opens a dialog box from which the following can be set. 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 may 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  Emulation...

Pressing this menu item opens a dialog box from which the Gryphon and Channel number used to emulate each LIN node may be specified. The default state is for none of the nodes to be emulated. The emulated nodes may be on any channel on any Gryphon. That is, the emulated nodes are not constrained to any one channel or Gryphon. The emulation status of each node is represented by the information in the rows under the separation line. The channel or channels for the emulated nodes are set active if the Gryphon selected for the monitoring process is the same as that selected for emulation.
Node name
The entries in the Node name column are the names of the LIN nodes as read from the LDF. The master node is at the top of the list. A node name may be selected by left clicking on it. Holding the Control key while left clicking on a node name, adds or subtracts it from the selected nodes. Holding the Shift key while left clicking on a node name, selects all of the node names between the last selected Node name and the newly selected node name. By selecting two or more nodes, all of the following actions apply to all of the selected nodes if the action is for one of the selected nodes.
IP address  /  Bonjour name
Left clicking on the button labeled either IP address or Bonjour name changes the selected entry or entries in that column to be either for an IP address or a Bonjour (Zeroconf) name. If the column label (switch) is set to IP address, an IP address may be entered in the selected data entry box. If the column label (switch) is set to Bonjour name, a name may be selected from the list that is displayed by pressing the arrow button to the right of the selected data entry box. It is not possible to manually enter a name. Changing or setting the Gryphon address for the master node may change or set the Gryphon address for the monitor function. On the other hand, changing or setting the Gryphon address for the monitor function will not change or set any of these addresses.
Emulate on Gryphon
Left clicking on a checkbox specifies whether or not the LIN node or nodes are to be emulated or not.
Channel scan
The Scan button scans the Gryphon for LIN version 2.0 cards and populates the spinbox to its right with the channel numbers of the LIN cards found.
Channel
The channel spinbox allows the channel to be used to emulate the node to be selected. If no suitable cards are found on the Gryphon, the spinbox is disabled.
Close
The Close closes the dialog box. The button is active only if no nodes are being emulated or if all of the emulated nodes are assigned either an IP addresses or Bonjour name and a channel number. If the button is disabled and the user attempts to close the dialog box via the title bar, the current window will be closed, but a new one with the same information will appear. This is done to prevent an emulated node from not being assigned to a channel on a Gryphon.

2.3.3  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 list in 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 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 have been 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.

Special note for use under Microsoft Windows: Under normal operation, the entries in the lower sub-window are not highlighted when selected. Additional code was added to the program to allow selected entries to be highlighted under most circumstances. The additional code does not work if one or more Configured triggers and actions are added to an empty list in the lower sub-window. Closing the Association Configuration dialog box and opening it again corrects the problem.

2.3.4  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.
Close Button Pressing the Close button closes the the dialog box. All changes that have been made are applied immediately. For this reason, there is no Save or Apply button.

2.3.5  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 bit rates 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 radio button that corresponds to the current bit rate 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. As a convenience to the user, the channels being used for emulation are enabled automatically if they are on the same Gryphon.

The current bit rate, as read from the Gryphon, is shown as the selected radio button. Pressing a different radio button does not change the bit rate of the channel until the Start button on the Main Window is pressed. If the channel is not enabled, its bit rate is not changed or set.

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 is saved automatically. The saved font size and weight are used as the startup values for future executions.

2.5  Time display mode Menu Button

The Time display mode Menu Button can be used to change how the timestamp is displayed. The selected mode (Timestamp, Relative or Differential) may be changed only when data is not being collected. The selected mode remains active while data is being collected and determines what is displayed in the second column of the scrolling window. There are no restrictions regarding how many times the mode may be changed or in what order it may be changed.

2.5.1  Timestamp

The Timestamp menu button entry changes the scrolling window's second column header to be Timestamp. The Gryphon timestamp is placed as received in the second column of the scrolling window. The least significant digit is tens of microseconds.

2.5.2  Relative

The Relative menu button entry changes the scrolling window's second column header to be Relative. The value of the first captured Gryphon timestamp is subtracted from all of the timestamps of the messages being received or those in the display buffer depending on whether data collection is active or stopped. If old data is scrolled out of the display buffer (not to be confused with the display window), the relative values are not recalculated until the display mode is changed to another value and back to Relative. In other words, the first entry will not have a relative time of zero if one or more entries have scrolled out of the display buffer until the relative times are recalculated. The time units are seconds with a space following the millisecond location.

2.5.3  Differential

The Differential menu button entry changes the scrolling window's second column header to be Differential. The value of the previous timestamp is subtracted from that of the current timestamp to find the time difference between the two. (Since there is no previous time for the first timestamp, it is set to zero.)

2.6  Scrolling Window

Received messages and events are displayed in the scrolling window. For each network message, its channel number, timestamp, Rx/Tx flag, Frame ID (frame name from the LDF), ID (frame ID displayed as a hexadecimal byte), data portion of the message (in hexadecimal) and the checksum. If the correct checksum is present in a message, the Checksum column is empty. If the checksum is incorrect, the invalid checksum is placed in the Checksum column

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

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

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 restore the normal scrolling action, 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.7  Progress Bar

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

2.8  Start Button

Pressing the Start button causes filtering and response messages to be sent to the Gryphon based on the current configuration. If a schedule is selected in the Active Schedule menu button, that schedule is activated. If any messages are displayed in the scrolling window, they are deleted. The Start button stays depressed and its label is changed to Stop.

Pressing the Stop button turns off reception of network traffic, deletes filters, responses and periodic messages and deactivates the schedule if one was running.

Pressing Control-S toggles the Start/Stop button.

2.9  Save as Button

The Save as button is active any time 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 an optional trailing 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 optional trailing 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.10  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.11  Transmit Edit Button

The Transmit Edit button is active whenever data collection is in progress. Left clicking on the Transmit Edit button causes an Edit Message dialog box to appear. Each time the button is pressed, a new dialog box appears. All of the dialog boxes are independent of each other. All of the data entered in a dialog box is lost when it is closed. Pressing Control-T is an alternate way to cause an Edit Message dialog box to appear.

2.11.1  Frame ID

This is frame ID to be sent on the LIN bus or the frame ID associated with the data to be sent to the card. The frame ID to use may be either selected from the menu button or entered directly in the data entry box. The button to the right of the frame ID data entry box can be used to toggle the frame ID display between decimal and hexadecimal.

2.11.2  Data

This is the data portion of the message to be sent to the Gryphon. If just the frame ID is to be sent, these entries are ignored. Each data entry box is for a byte of the data portion of the message. The Decimal/Hexadecimal button is used to switch the byte display and entry between decimal and hexadecimal. The clear button is present to allow a simple method of clearing the entry of old data. If a node is not being emulated, all of its frames (messages) will have their data entry boxes disabled.

2.11.3  Update Data

Pressing this button causes the data to be sent to the LIN card which stores it. The program knows which slaves are being emulated and where the emulation is being performed. In other words, the program is able to send the data to the correct card on the correct Gryphon. If a node is not being emulated, this button is disabled.

2.11.4  Send ID

Pressing this button causes the the frame ID to be sent to the card which sends it out on the LIN bus immediately.

2.12  Clear Button

The Clear button is active whenever data is present in the Scrolling Window. Pressing the button deletes all of the data in the Scrolling Window. Control-C also clears the Scrolling Window.

2.13  Status Lines

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

2.14  Main Window size and position

Each time the program is exited, 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.
This document was translated from LATEX by HEVEA.