Garuda Labview Library User Manual

DE_PR_T_01_V01.03

Dearborn Electronics Confidential Page 1 of 15

Garuda LabVIEW Library

User Manual

Version: 1.0

Submitted by Dearborn Electronics India Pvt. Ltd

687, 16th Main, 4th T Block Jayanagar, Bangalore – 560 041, INDIA

Tel: 91-80-22440404; Fax: 91-80-26534949

DE_PR_T_01_V01.03


Table of Contents 1 Installation .................................................................................................. 4 2 Overview ..................................................................................................... 5 3 LabVIEW ...................................................................................................... 5 4 LabVIEW Library .......................................................................................... 6

4.1 Functional Description (VIs) ................................................................... 6 4.1.1 PassThruOpen ................................................................................................. 6 4.1.2 PassThruClose ................................................................................................. 6 4.1.3 PassThruConnect............................................................................................. 6 4.1.4 PassThruDisconnect ........................................................................................ 7 4.1.5 PassThruReadMsgs ......................................................................................... 7 4.1.6 PassThruWriteMsgs ......................................................................................... 7 4.1.7 PassThruStartPeriodicMsg ............................................................................... 8 4.1.8 PassThruStopPeriodicMsg ............................................................................... 8 4.1.9 PassThruStartMsgFilter ................................................................................... 9 4.1.10 PassThruStopMsgFilter .............................................................................. 10 4.1.11 PassThruSetProgrammingVoltage ............................................................. 10 4.1.12 PassThruReadVersion ............................................................................... 11 4.1.13 PassThruGetLastError ............................................................................... 11 4.1.14 PassThruIoctl ............................................................................................. 11

4.2 Protocol Message Structure ................................................................. 14

DE_PR_T_01_V01.03


Revision History

Version #

Description of Revision Author Date

1.0 First version Mamatha B 18-Jun-12

DE_PR_T_01_V01.03


1 Installation

LabVIEW Libraries require Windows XP Operating System. To install LabVIEW Libraries, follow the steps below:

• Unzip “Garuda2534.zip” and rename Garuda2534._XE to Garuda2534.EXE. • Run “Garuda2534.EXE” to install the Garuda J2534 libraries from Garuda2534

folder. • Copy “Garuda.LLB” to the folder “..\National Instruments\Labview2010\vi.

lib\addons\” location. • The Library files will be now available in the function palette of Labview for

Application development. Note:

1) The LabVIEW Library files use Garuda J2534 DLL available Windows/Systems32 folder. The file name is “Garuda40432.dll”, browse and select this file.

2) The Libraries support LabVIEW 2010 version onwards.

DE_PR_T_01_V01.03


2 Overview

The SAE J2534 Recommended Practice provides the framework to allow reprogramming software applications from all vehicle manufacturers the flexibility to work with multiple vehicle data link interface tools from multiple tool suppliers. J2534 provides a set of APIs using which we can interact with Vehicle ECUs through a Pass-thru hardware device. Garuda is a Pass-thru device that is connected between the PC and the vehicle ECU. The Block diagram is shown below.

3 LabVIEW

LabVIEW is a graphically-based programming language developed by National Instruments. Its graphical nature makes it ideal for test and measurement (T&M), automation, instrument control, data acquisition, and data analysis applications. The user/operator can use the LabVIEW application to communicate with the Vehicle ECUs via Garuda.

PC Application

LabVIEW

Physical Medium (USB)

Garuda Hardware

Vehicle ECU

Garuda J2534 DLL

VISA

DE_PR_T_01_V01.03


4 LabVIEW Library

The LabVIEW library files are provided along with Garuda interface. The LabVIEW developers can build their specific application using these library files. This reduces the time required to build the applications. The LabVIEW library files consist of VIs for the following J2534 API functions. Each J2534 API function has been provided as a VI files and using these library files, Users can develop LabVIEW application to interact with J2534 device.

4.1 Functional Description (VIs)

4.1.1 PassThruOpen Establishes a connection with a Pass-Thru device

Input Parameter Description

Name PassThru Device name

Output Parameter Description Return Value Return value from PassThruOpen. DeviceID SAE J2534 device id returned

4.1.2 PassThruClose Terminate a connection with a Pass-Thru device


DeviceID Device ID from PassThruOpen

Output Parameter Description Return Value Return value from PassThruClose.

4.1.3 PassThruConnect Establish a connection with a protocol channel


DeviceID Device ID from PassThruOpen ProtocolID Protocol channel on the specified SAE J2534 device. Flag Protocol connection flags Baudrate Protocol baud rate.

Output Parameter Description

DE_PR_T_01_V01.03


Return Value Return value from PassThruConnect ChannelID Channel ID that is assigned by the DLL. All future

interactions with the protocol channel will be done using the ChannelID.

4.1.4 PassThruDisconnect Terminate a connection with a protocol channel


ChannelID Channel ID from PassThruConnect

Output Parameter Description Return Value Return value from PassThruDisconnect

4.1.5 PassThruReadMsgs Read message(s) from a protocol channel


ChannelID Channel ID from PassThruConnect NumofMsg Number of messages to read is specified. Time out Read timeout (in milliseconds). If a value of 0 is

specified the function retrieves up to NumMsgs messages and returns immediately. Otherwise, the API will not return until the Timeout has expired, an error has occurred, or the desired number of messages has been read. If the number of messages requested has been read, the function shall not return ERR_TIMEOUT, even if the timeout value is zero.

Output Parameter Description Return Value Return value from PassThruReadMsgs. NumofMsg read On return from the function this location will

contain the actual number of messages read. PassThruMsg The data that is read from the channel is placed in

the message structure. Refer Message Structure section for more details.

4.1.6 PassThruWriteMsgs Write message(s) to a protocol channel

Input Parameter Description ChannelID Channel ID from PassThruConnect

DE_PR_T_01_V01.03


PassThruMsg The message to be transmitted must be written in this structure. Refer Message Structure section for more details.

NumofMsg Number of messages to write is specified. Time out Write timeout (in milliseconds).When a value of 0 is

specified, the function queues as many of the specified messages as possible and returns immediately. When a value greater than 0 is specified, the function will block until the Timeout has expired. When an ERR_TIMEOUT is returned, only the number of messages that were sent on the vehicle network is known. The number of messages queued is unknown. Application writers should avoid this ambiguity by using a Timeout value large enough to work on slow devices and networks with arbitration delays.


Return Value Return value from PassThruWriteMsgs. NumofMsg written On return will contain the actual number of

messages that were transmitted (when Timeout is nonzero) or placed in the transmit queue (when Timeout is zero).

4.1.7 PassThruStartPeriodicMsg Start sending a message at a specified time interval on a protocol channel

Input Parameter Description ChannelID Channel ID from PassThruConnect PassThruMsg The periodic msg to be transmitted is written in this

structure. Refer Message Structure section for more details.

Time Interval Time interval between the start of successive transmissions of this message, in milliseconds. The valid range is 5-65535 milliseconds.


Return Value Return value from PassThruStartPeriodicMsg MsgID The message ID that is assigned by J2534 device.

4.1.8 PassThruStopPeriodicMsg Stop a periodic message


ChannelID Channel ID from PassThruConnect

DE_PR_T_01_V01.03


MsgID Message ID that is assigned by the PassThruStartPeriodicMsg function.


Return Value out Return value from PassThruStopPeriodicMsg

4.1.9 PassThruStartMsgFilter Start filtering incoming messages on a protocol channel


ChannelID Channel ID from PassThruConnect FilterType Designates:

PASS_FILTER (1) – allows matching messages into the receive queue. This filter type is only valid on non-ISO 15765 channels BLOCK_FILTER (2) – keeps matching messages out of the receive queue. This filter type is only valid on non-ISO 15765 channels FLOW_CONTROL_FILTER (3) – allows matching messages into the receive queue and defines an outgoing flow control message to support the ISO 15765-2 flow control mechanism. This filter type is only valid on ISO 15765 channels. Refer SAE J2534 document.

MaskMsg For a PASS_FILTER or BLOCK_FILTER: This designates a pointer to the mask message that will be applied to each incoming message (i.e., the mask message that will be ANDed to each incoming message) to mask any unimportant bits. When using the CAN protocol, setting the first 4 bytes of MaskMsg to $FF makes the filter specific to one CAN ID. Using other values allows for the reception or blocking of multiple CAN identifiers. For a FLOW_CONTROL_FILTER: The mask shall consist of 4 or 5 bytes of $FF, with a corresponding DataSize. Five bytes are only allowed when the extended address bit in TxFlags is set. Refer Message Structure section for more details.

PatternMsg For a PASS_FILTER or BLOCK_FILTER: Designates a pointer to the pattern message that will be compared to the incoming message after the mask message has been applied. If the result matches this pattern message and the FilterType is PASS_FILTER, then the incoming message will be added to the receive queue (otherwise it will be discarded). If the result matches this pattern message and the FilterType is BLOCK_FILTER, then the incoming message will be discarded (otherwise it

DE_PR_T_01_V01.03


will be added to the receive queue). Message bytes in the received message that are beyond the DataSize of the pattern message will be treated as “don’t care”. For a FLOW_CONTROL_FILTER: Designates a pointer to the CAN ID (with optional extended address) at the other end of an ISO 15765-2 conversation. Any messages on the bus not matching a PatternMsg must be discarded. Refer Message Structure section for more details.

FlowControlMsg This pointer must be null when requesting a PASS_FILTER or a BLOCK_FILTER, otherwise ERR_INVALID_MSG shall be returned. For a FLOW_CONTROL_FILTER: Designates a pointer to the CAN ID used when sending CAN frames during an ISO15765-2 segmented transmission or reception. This is the CAN ID to match against the CAN ID in a segmented PassThruWriteMsg. This message shall only contain the CAN ID (and extended address byte if the ISO15765_EXT_ADDR flag is set). Refer Message Structure section for more details.


Return Value Return value from PassThruStartMsgFilter. FilterID The filter ID that is assigned by the J2534 device

4.1.10 PassThruStopMsgFilter Stops filtering incoming messages on a protocol channel


ChannelID Channel ID from PassThruConnect FilterID Filter ID that is assigned by the

PassThruStartMsgFilter function.

Output Parameter Description Return Value Return value from PassThruStopMsgFilter

4.1.11 PassThruSetProgrammingVoltage Set a programming voltage on a specific pin.


DE_PR_T_01_V01.03


DeviceID Device ID returned from PassThruOpen Pin Number The pin on which the programming voltage will be

set. Voltage in mV The voltage (in millivolts) to be set.

Output Parameter Description Return Value Return value from PassThruSetProgrammingVoltage

4.1.12 PassThruReadVersion Reads the version information for the DLL and API


DeviceID Device ID returned from PassThruOpen

Output Parameter Description Return Value Return value from PassThruReadVersion. Firmware Version Firmware version string. This string is determined by

the interface vendor that supplies the device. DLLVersion DLL version string. This string is determined by the

interface vendor that supplies the DLL. APIVersion API version string in YY. MM format. This string

corresponds to the date of the approved document

4.1.13 PassThruGetLastError Gets the text description of the last error


Return Value Return value from PassThruGetLastError Error Description Text string description for an error detected during

the last function call

4.1.14 PassThruIoctl General I/O control functions for reading and writing protocol configuration parameters (e.g. initialization, baud rates, programming voltages, etc.). Note: IOCTL commands to be defined.

4.1.14.1 GET_CONFIG Gets the vehicle network configuration of the pass-thru device

Input Parameter Description ChannelID Channel ID from PassThruConnect Parameter Names Parameter is an INPUT that represents the

parameter to be obtained Value Value is an OUTPUT that represents the value of

DE_PR_T_01_V01.03


that parameter. The value need not be provided for GET_CONFIG


Return Value Return value from J2534 PassThruIoctl DLL. Config Array Cluster containing the parameter and its respective

Value

4.1.14.2 SET_CONFIG Sets the vehicle network configuration of the pass-thru device

Input Parameter Description ChannelID Channel ID from PassThruConnect Parameter Names Parameter is an INPUT that represents the

parameter to be obtained Value Value is an Input that represents the value of that

parameter. The value need to be provided for SET_CONFIG


Return Value Return value from J2534 PassThruIoctl DLL. Config Array Cluster containing the parameter and its respective

Value

4.1.14.3 READ_VBATT Reads the Battery voltage on pin 16 of the J1962 connector



Return Value Return value from J2534 PassThruIoctl DLL. Voltage in mV The units will be in milli-volts and will be

rounded to the nearest tenth of a volt.

4.1.14.4 FIVE_BAUD_INIT Directs the pass-thru device to initiate a 5 baud initialization sequence

Input Parameter Description ChannelID Channel ID from PassThruConnect Target Address the five baud address sent from the

tester to the ECU

Output Parameter Description Return Value Return value from J2534 PassThruIoctl DLL. BytePtr two key bytes sent from the ECU to the

DE_PR_T_01_V01.03


tester.

4.1.14.5 FAST_INIT Directs the pass-thru device to initiate a fast initialization sequence

Input Parameter Description ChannelID Channel ID from PassThruConnect InputPtr InputPtr Points to the structure PASSTHRU_MSG.

The Start Communication Request Message is written in the “Data” field Refer Message Structure section for more details.


Return Value Return value from J2534 PassThruIoctl DLL. OutputPtr OutputPtr Points to the structure PASSTHRU_MSG.

The Start Communication Response Message is obtained in the “Data” field Refer Message Structure section for more details.

4.1.14.6 CLEAR_TX_BUFFER Directs the pass-thru device to clear all messages in its transmit queue.



Return Value Return value from J2534 PassThruIoctl DLL.

4.1.14.7 CLEAR_RX_BUFFER Directs the pass-thru device to clear all messages in its receive queue.




4.1.14.8 CLEAR_PERIODIC_MSGS Directs the pass-thru device to clear all periodic messages on the channel, thus stopping all periodic message transmission


DE_PR_T_01_V01.03




4.1.14.9 CLEAR_MSG_FILTERS Directs the pass-thru device to clear all message filters on the channel




4.2 Protocol Message Structure The following message structure will be used for all messages (Transmit, Receive, Filters, and periodic). The total message size (in bytes) is the DataSize, and includes header bytes, ID bytes, and data bytes. For consistency, all interfaces should detect only the errors listed for each protocol in the following sections when returning ERR_INVALID_MSG. C / C++ Definition typedef struct { unsigned long ProtocolID; unsigned long RxStatus; unsigned long TxFlags; unsigned long Timestamp; unsigned long DataSize; unsigned long ExtraDataIndex; unsigned char Data[4128]; } PASSTHRU_MSG; Elements description ProtocolID: Protocol type RxStatus: Receive message status – See RxStatus in “Message Flags and Status Definition” section TxFlags: Transmit message flags – See TxFlags in “Message Flags and Status Definition” Section Timestamp: Received message timestamp (microseconds): For the START_OF_FRAME indication, the timestamp is for the start of the first bit of the message. For all other indications and transmit and receive messages, the timestamp is the end of the last bit of the message. For all other error indications, the timestamp is the time the error is detected.

DE_PR_T_01_V01.03


DataSize: Data size in bytes, including header bytes, ID bytes, message data bytes, and extra data, if any. ExtraDataIndex: Start position of extra data in received message (for example, IFR). The extra data bytes follow the body bytes in the Data array. The index is zero-based. When no extra data bytes are present in the message, ExtraDataIndex shall be set equal to DataSize. Therefore, if DataSize equals ExtraDataIndex, there are no extra data bytes. If ExtraDataIndex=0, then all bytes in the data array are extra bytes. Data: Array of data bytes. Includes message headers, message body, and any extra data bytes. The application must fill all fields for each PASSTHRU_MSG structure passed to the API, except for RxStatus, Timestamp, and ExtraDataIndex. These three fields are only valid when reading a message or indication with PassThruReadMsg.

Documents

Garuda Labview Library User Manual