Documentation For gryph_db.pl

August 12, 2002

1 Overview

On startup, the program attempts to read the database file, gryph_mon.db which contains the definition of filters, messages and periodic messages used by gryph_mon.pl. The user is then able to modify entries in the various sections of the database file. On exit, the updated data may be written to a database file.

2 Main Window

2.1 Title Bar

The title bar displays the database file currently being edited.

2.2 File Menu

2.2.1 New

This menu item initializes a new database file named Untitled. The title bar indicates that Untitled is being edited.

2.2.2 Open...

This menu item allows a database file to be opened and read. Its name is inserted into the title bar as an indication of which database is being edited. The default database file, gryph_mon.db, is read during startup if it is found. This menu entry allows another database file to be read and edited .

2.2.3 Save

This menu item saves the current database data to the same file from which it was read and is shown in the title bar.

2.2.4 Save as...

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

2.2.5 Exit

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

2.3 Left Menu Button

Selecting one of the program types in the left menu button changes the entries for the right menu button. At the time of this documentation, the three entries in this menu button are as follows:

Monitor: Sets the right menu button entries for gryph_mon, the Gryphon monitor.
Gateway: Sets the right menu button entries for cangate, the simple Gryphon gateway.
Signals: Sets the right menu button entries for a yet to be named and written program that works with gryph_mon to display signals extracted from network messages.

2.4 Right Menu Button

Selecting one of the items in the right menu button displays the current entries, if any, in the database for that item. A displayed entry may be edited deleted or copied. Any editing windows that are open when a menu entry is selected, will be closed without saving any changes that may have been made.

2.5 Display Window

Pressing the right mouse button while the mouse cursor is over the Display window causes a pop-up menu to appear. The selected (highlighted) entry may be either edited, deleted or copied or a new entry may be added. If no entries are present, the edit, delete and copy menu entries are disabled. Double left clicking on an entry, opens an editing window for that item. Multiple editing windows may be open simultaneously.

2.5.1 Triggers

Each trigger currently in the database is displayed on one or more lines. The triggers are sorted by Network and Name.

2.5.2 Filters

Each filter currently in the database is displayed on one or more lines. The filters are sorted by Network and Name.

2.5.3 Messages

Each message currently in the database is displayed on a line. The messages are sorted by Network and Name.

2.5.4 Periodic

Each periodic message currently in the database is displayed on a line. The periodic messages are sorted by Name.

2.5.5 CAN Speeds

Each set of BTR's currently in the database is displayed on a line. The CAN speeds are sorted by Name.

2.5.6 KWP Comm Setup

Each Keyword Protocol 2000 communications setup is displayed on a line. The KWP communications setups are sorted by name.

2.6 Editing Windows

An editing window is opened when either the edit, new or copy entries in the pop-up menu are selected or when an entry is double left clicked. Multiple windows may be opened for a given type of entry (Triggers, Filters, Messages, Periodic). To save changes to an entry, close the editing window by clicking on the Save button. To discard changes to an entry, close the editing window by clicking on the Cancel button or close the window from the title bar. All of the open editing windows are closed without saving the changes when a choosing a type of entry from the menu button.

2.6.1 Triggers

Triggers are used to signal capture events, trigger response messages and toggle periodic messages.

Name

The name may contain any characters except a semicolon (``;''). When used to toggle periodic messages, part of the trigger's name is used by gryph_mon.pl as an identifier. When gryph_mon.pl starts a periodic message in response to a trigger, the trigger's identifier is stored as the initiator. Only another trigger with the same identifier is able to abort that periodic message. The identifier is the first part of the trigger's name, up to the pound sign (``#''). For all other purposes, triggers with identical identifiers are treated as separate entities.

Network

The network for which the trigger is valid can be selected from a menu button. Since triggers are sorted by network and name, it is possible to use the same name for different triggers on different networks.

Line Number Box

This surrounds the entries and controls for each trigger line or condition. A trigger must have at least one trigger condition, but may have no more than 255. In order for an incoming message to conform to a trigger, it must conform to all of its conditions. In other words, the conditions or lines are anded together.

Portion of Message To Check

This menu button selects which portion of the network data (ft_data message) or event message (ft_event message) is to be examined for conformance.

Message Frame: The portion of the incoming ft_data message to be checked is in the Message Header Frame which contains the header length, header bits, etc.
Header: The portion of the incoming ft_data message to be checked is in the header (or ID) of the network message
Data: The portion of the incoming ft_data message to be checked is in the data section of the network message.
Extra Data: The portion of the incoming ft_data message to be checked is in the extra data section of the network message.
Event Frame: The portion of the incoming ft_event message to be checked is in the Event Header which contains the Event ID, Event Context, etc.
Event Data: The portion of the incoming ft_event message to be checked is in the data section which may contain additional information.

Type of Comparison

This menu button allows selection of the type of comparison to be used. For logical comparisons, such as Signed Greater Than, the desired section of the incoming message is checked to see if it is greater than the constant entered below as Value.

Byte Offset

This is the relative byte number, starting with zero, of the first byte of the desired portion of the message to be checked.

Bit compare

The following entry fields and display are present for Bit compare.

Match Pattern: The Match Pattern specifies the bit pattern that needs to be matched in order for a message to conform to this trigger condition. The value is in hexadecimal, using 0 through 9 and A through F as the digits. If spaces are present, they are interpreted as byte boundaries. A leading zero is assumed if an odd number of bytes are present between spaces.
byte count: The number of bytes for the pattern and mask are displayed.
Mask: The Mask qualifies the Match Pattern by specifying which are required and which bits are ignored. A bit value of 1 in the Mask indicates that the corresponding bit in the message must match that in the Match Pattern. A bit value of 0 in the Mask indicates that the corresponding bit in the message is ignored.

Digital comparisons

The following entry field is present for Digital comparisons.

Mask: The Mask indicates which bit of a byte should be checked for a state or change of state. The value is in hexadecimal, using 0 through 9 and A through F as the digits. Only a single bit should be set.

Other conversions

The following entry field is present for all comparisons except Bit Compare and Digital comparisons.

Value: The constant to which the value extracted from the incoming message is compared.

Previous Line button

Pressing this button changes the displayed trigger line or condition to the previous one.

Next Line button

Pressing this button changes the displayed trigger line or condition to the next one. If the next one does not exist, default values are used and it is up to the user to change them to valid values.

Delete Line Button

Pressing this button deletes the currently displayed trigger line. If all of the lines of a trigger are deleted, that trigger is deleted when the Save button is pressed.

Cancel button

Pressing this button abandons the changes, if any, that have been made to the entry and closes the window. If a new entry is being edited, it is removed from the list.

Save button

Pressing this button saves the current entry configuration values and closes the window.

2.6.2 Filters

Filters are used to pass or block specific messages or groups or classes of messages from the network to gryph_mon.pl.

Name

The name may contain any characters except a semicolon (``;'').

Network

The network for which the filter is valid can be selected from a menu button. Since filters are sorted by network and name, it is possible to use the same name for different filters on different networks.

Line Number Box

This surrounds the entries and controls for each filter line or condition. A filter must have at least one filter condition, but may have no more than 255. In order for an incoming message to conform to a filter, it must conform to all of its conditions. In other words, the conditions or lines are anded together.

Portion of Message To Check

This menu button selects which portion of the network data message (ft_data message) to be examined for conformance.

Message Frame: The portion of the incoming ft_data message to be checked is in the Message Header Frame which contains the header length, header bits, etc.
Header: The portion of the incoming ft_data message to be checked is in the header (or ID) of the network message
Data: The portion of the incoming ft_data message to be checked is in the data section of the network message.
Extra Data: The portion of the incoming ft_data message to be checked is in the extra data section of the network message.

Type of Comparison

Byte Offset

This is the relative byte number, starting with zero, of the first byte of the desired portion of the message to be checked.

Bit compare

The following entry fields and display are present for Bit compare.

Match Pattern: The Match Pattern specifies the bit pattern that needs to be matched in order for a message to conform to this filter condition. The value is in hexadecimal, using 0 through 9 and A through F as the digits. If spaces are present, they are interpreted as byte boundaries. A leading zero is assumed if an odd number of bytes are present between spaces.
byte count: The number of bytes for the pattern and mask are displayed.
Mask: The Mask qualifies the Match Pattern by specifying which are required and which bits are ignored. A bit value of 1 in the Mask indicates that the corresponding bit in the message must match that in the Match Pattern. A bit value of 0 in the Mask indicates that the corresponding bit in the message is ignored.

Digital comparisons

The following entry field is present for Digital comparisons.

Mask: The Mask indicates which bit of a byte should be checked for a state or change of state. The value is in hexadecimal, using 0 through 9 and A through F as the digits. Only a single bit should be set.

Other conversions

The following entry field is present for all comparisons except Bit Compare and Digital comparisons.

Value: The constant to which the value extracted from the incoming message is compared.

Previous Line button

Pressing this button changes the displayed filter line or condition to the previous one.

Next Line button

Pressing this button changes the displayed filter line or condition to the next one. If the next one does not exist, default values are used and it is up to the user to change them to valid values.

Delete Line Button

Pressing this button deletes the currently displayed filter line. If all of the lines of a filter are deleted, that filter is deleted when the Save button is pressed.

Cancel button

Pressing this button abandons the changes, if any, that have been made to the entry and closes the window. If a new entry is being edited, it is removed from the list.

Save button

Pressing this button saves the current entry configuration values and closes the window.

2.6.3 Messages

Messages are used as actions for events and as the messages used to build periodic messages.

Name: The name may contain any characters except a semicolon (``;'').
Network: The network for which the message is valid can be selected from a menu button. Since messages are sorted by network and name, it is possible to use the same name for different messages on different networks.
Header: The Header entry specifies the header or ID portion of the message to be sent to the network. The value is in hexadecimal, using 0 through 9 and A through F as the digits. If spaces are present, they are interpreted as byte boundaries. A leading zero is assumed if an odd number of bytes are present between spaces.
Data: The Data entry specifies the data portion of the message to be sent to the network. The value is in hexadecimal, using 0 through 9 and A through F as the digits. If spaces are present, they are interpreted as byte boundaries. A leading zero is assumed if an odd number of bytes are present between spaces.
Extra Data: The Extra Data entry specifies the extra data portion of the message to be sent to the network. The value is in hexadecimal, using 0 through 9 and A through F as the digits. If spaces are present, they are interpreted as byte boundaries. A leading zero is assumed if an odd number of bytes are present between spaces.
High Voltage Wakeup: This checkbox is present only when CAN has been selected as the Network for the message. If the checkbox is checked, gryph_mon.pl will attempt to send the message out as a high voltage message. If the message is sent out on a network other than single wire CAN, the high voltage aspect is ignored.
Cancel button: Pressing this button abandons the changes, if any, that have been made to the entry and closes the window. If a new entry is being edited, it is removed from the list.
Save button: Pressing this button saves the current entry configuration values and closes the window.

2.6.4 Periodic

Periodic messages are used as actions for events in gryph_mon.pl. Each periodic message entry is composed of two implied nested loops. The inner loop iterates over a single message. The outer loop iterates over one or more inner loops. Each line in the editing window corresponds to an inner loop.

Name

The name may contain any characters except a semicolon (``;'').

Number of Iterations

This is the number of iterations of the outer loop. Any number between 1 and 4,294,967,295 may be entered. Commas may be entered with the number. Any number larger than 4,294,967,295 is replaced with the string ``Infinite''. ``Infinite'' is just another notation for 4,294,967,295.

Type

This is the type of scheduler to use. The critical scheduler is more accurate than the normal scheduler (1 to 2 ms accuracy versus 10 to 20 ms accuracy).

Line Number Box

This surrounds the entries and controls for each periodic line or message. A periodic message must have at least one message, but may have no more than 255.

Wait time before message(s): This wait is performed at the beginning of each outer loop, before the first message is sent.
Message: This menu button contains a list of all of the defined messages. If two or more messages have the same name, but are for different networks, the name is listed only once.
Channel: The channel number over which this message is to be sent . When gryph_mon.pl runs, it lists only those periodic messages that are valid. That is, the network type and channel numbers of all of the constituent messages must be valid.
Number of times to send this message: This is the number of iterations of the inner loop. Any number between 1 and 4,294,967,295 may be entered. Commas may be entered with the number.
Delay time between messages: This is the time to delay between sending copies of this message. If only one copy of the message is sent (Number of times to send this message equals 1), this value is not used.
Previous Line button: Pressing this button changes the displayed periodic line or message to the previous one.
Next Line button: Pressing this button changes the displayed periodic line or message to the next one. If the next one does not exist, default values are used and it is up to the user to change them to valid values.
Delete Line Button: Pressing this button deletes the currently displayed periodic line. If all of the lines of a periodic message are deleted, that periodic message is deleted when the Save button is pressed.

Cancel button

Pressing this button abandons the changes, if any, that have been made to the entry and closes the window. If a new entry is being edited, it is removed from the list.

Save button

Pressing this button saves the current entry configuration values and closes the window.

2.6.5 CAN Speeds

CAN speed entries may be used to define custom baud rates for CAN cards.

Name: The name may contain any characters except a semicolon (``;'').
Bits per Second: This is both a data entry and display field. Click on the down arrow to the right of the field to open a list of valid baud rates. Left click on an entry to select the bit rate. The BTR values are changed appropriately. The Baud Rate Prescaler and Time Quanta per Bit sliders are also changed. As other data entries are changed or sliders moved that change the bit rate, this value is updated to show the new bit rate.
Radio button(s): A row of radio buttons is displayed below the Bits per Second entry. Each button corresponds to a unique solution for the current bit rate. Clicking on a button selects that unique solution which is a combination of the Baud Rate Prescaler and Time Quanta per Bit values. Right clicking anywhere in the main window causes the next unique bit rate solution to be selected.
BTR0 and BTR1: These are both data entry and display fields. A new value may be entered (hexadecimal only) in either field and the bit rate and other parameters will be updated as necessary. Likewise any changes to any of the sliders or Bits per Second will cause one or both of the values to be changed.
Baud Rate Prescaler and Time Quanta per Bit sliders: These two sliders determine the bit rate on the CAN bus. As either one is moved, the Bits per Second value is updated as are the radio buttons that indicate the number of unique solutions for that bit rate. The Bit Timing Registers are also updated as the sliders are moved. The values to the left of the sliders indicate the current values. The sliders move automatically to indicate new values as the bit rate or BTRs are changed. The Baud Rate Prescaler ranges from 0 through 63. The Time Quanta per Bit ranges from 6 through 25. The Time Quanta per Bit includes the Synchronization Segment and the single segments added to both Tseg1 and Tseg2
Tseg1 and Tseg2: These two sliders show how the Time Quanta per Bit value is allocated on either side of the Sample Point.
Sample Point in Percent: This slider may be moved without changing the bit rate. It changes the values of Tseg1 and Tseg2 and displays the sample point as a percentage of the bit time. When a bit rate is selected via either the Bits per Second entry or via the radio buttons, the largest possible value for the sample point is calculated and the slider is moved to that position.
Resync Jump Width: The value of this slider is limited by Tseg2. The value is also shown as a percentage of the bit time.
Sampling Mode: Either one or three samples per bit time may be selected.
Cancel button: Pressing this button abandons the changes, if any, that have been made to the entry and closes the window. If a new entry is being edited, it is removed from the list.
Save button: Pressing this button saves the current entry configuration values and closes the window.

2.6.6 KWP Comm Setup

Various Keyword Protocol 2000 communications parameters may be specified.

Name: The name may contain any characters except a semicolon (``;'').
Source Address: The source address is a single byte which can be entered as two hexadecimal digits (0 through 9 and A through F).
Target Address: The source address is a single byte which can be entered as two hexadecimal digits (0 through 9 and A through F).
Target Addr Type: Either Functional or Physical may be selected from the menubutton.
Wakeup Type: The type of wakeup can be set to CARB, 5 Baud, or Fast via the menubutton.
Protocol Type: Either KWP 2000 or ISO 9141 may be selected from the menubutton.
Node Type: The node type may be set to either Monitor, Tester or ECU via the menubutton.
Wakeup Timings: Various wakeup timings may be set individually. The ``Use defaults'' button may be used to return all of the entries to their default values.
Message Timings: Various message timings may be set individually. The ``Use defaults'' button may be used to return all of the entries to their default values.
Cancel button: Pressing this button abandons the changes, if any, that have been made to the entry and closes the window. If a new entry is being edited, it is removed from the list.
Save button: Pressing this button saves the current entry configuration values and closes the window.

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