IsCAN Labview Developer

TECHNOLOGIEN MITVORSPRUNG

isCAN USB/isCAN PCI

LabVIEW

Developer Manual

Copyright © ifak system GmbH 2008, all rights reserved.

No part of this work may be reproduced in any form or by any means-graphic, electronic or mechanical, including photocopying, recording, taping or storage in an information retrieval system-without prior writ-ten permission of the ifak system GmbH.

Information in this manual is subject to change without notice and does not represent a commitment of the ifak system GmbH.

ifak system GmbHOststraße 1839114 Magdeburg

Tel.: +49-391-54 45 63-10Fax: +49 -391-54 45 63-99

Email: [email protected]

CAN Interfaces Developer Manual

ifak system GmbH I

Contents

Kapitel 1: Hardware Installation

General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Our Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Interfaces isCAN USB/isCAN PCI . . . . . . . . . . . . . . . . . . . . . . 2

Kapitel 2: Software Installation and Configuration

Driver Software Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3isCAN-LabView-Library Installation . . . . . . . . . . . . . . . . . . . . . . 4

Initialization 5isCAN_DeviceInitEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6isCAN_CloseDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

ConfigurationisCAN_SetBaud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9isCAN_SetBaudRegister . . . . . . . . . . . . . . . . . . . . . . . . . . . 11isCAN_SetMessageID . . . . . . . . . . . . . . . . . . . . . . . . .13isCAN_SetMessageExID . . . . . . . . . . . . . . . . . . . . . . .16isCAN_SetupDevice. . . . . . . . . . . . . . . . . . . . . . . . . . .18

Data TransmissionisCAN_ReceiveMessageEx . . . . . . . . . . . . . . . . . . . . .20isCAN_TransmitMessageEx . . . . . . . . . . . . . . . . . . . .21

Appendix

Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

CAN Interfaces

II ifak system GmbH

CAN Interfaces General Information

ifak system GmbH 1

C H A P T E R 1 :

HARDWARE INSTALLATION

General Information

Documentation

This documentation contains important information for the secure and correct operation of the interfaces isCAN USB and isCAN PCI. Please read this documentation carefully before using one of the devices. Throughout the manual different fonts are used to indicate different meanings. A short explanation can be found below::

Our Service

In case you have any questions which can´t be solved by this manual, please contact our service by phone, fax or e-mail:

ifak system GmbHOststrasse 18, 39114 Magdeburg, GermanyTel.: +49 - 391 - 544 563-10Fax: +49 - 391 - 544 563-99E-mail: [email protected]

Courier New: File names, Code sequences

Arial Names, Commands, Remarks

WARNING Dangerous electrical voltage

Hardware Installation CAN Interfaces

2 ifak system GmbH

Interfaces isCAN USB/isCAN PCI

Please look up the user/developer manual isCAN USB/isCAN PCI.

CAN Interfaces Driver Software Installation

ifak system GmbH 3

C H A P T E R 2 :

SOFTWARE INSTALLATION AND CONFIGURATION

Driver Software Installation

The driver and configuration software has to be installed before using the isCAN LabView Library.

Please look up the chapter "Driver and Configuration Software" in the user or developer manual isCAN USB/isCAN PCI for the installation of the driver and configuration software.

Software Installation and Configuration CAN Interfaces

4 ifak system GmbH

Installation LabView Library Installation

The isCAN LabView-Library includes two individual Zip archi-ves which one can unpack with 7 Zip. 7 Zip can be downloaded here: http://www.7-zip.org.

Content of the isCAN LabView-package:

isCAN_LV_Lib.zipThe zip file contains the VIs of the LabView CAN Library.

isCAN_LV_Examples.zipThe zip file contains the examples of the LabView CAN Library.

Steps of installation

1. Finishing LabView

2. Unpack the Zip archive with an appropriate program "isCAN_LV_Lib.zip" into the directory "user.lib" of the LabView installation

e.g.

"C:\Programme\National Instruments\LabView 6.1\user.lib\"

3. The Zip archive "isCAN-LV_Examples.zip" can be unpacked into any directory kann in

4. Restarting LabView

CAN Interfaces Initialization

ifak system GmbH 5

C H A P T E R 3 :

INTERFACES FOR CAN APPLICATION

Initialization

isCAN_DeviceInitEx

4 Format

4 Input

4 Output

DeviceNr in Number of the isCAN device as assigned by the configuration tool.

Baud Determines the CAN baud rate.(see table: Codes for Baudrate)

Error in Error input (see appendix > Error Codes)

DeviceNr out

Number of the isCAN device as assigned by the configuration tool.

Error out Error output (see appendix > Error Codes)

Interfaces for CAN application CAN Interfaces

6 ifak system GmbH

4 Description

Initializes a device with the chosen DeviceNr in and sets an ini-tial baudrate. The message filtering is disabled. If the CAN con-troller was already in the state Operation it is switched back to the Reset state and initialized again.

To initialize the device without connecting to the CAN bus, one has to set the parameter baud to the value CAN_OFFLINE. When required, the device can be switched online by changing the baudrate using the function isCAN_SetBaud or isCAN_SetBaudRegister.

Table 1: Codes for Baudrate

Wert Baud

0 CAN_OFFLINE

1 CAN_BAUD_10

2 CAN_BAUD_20

3 CAN_BAUD_50

4 CAN_BAUD_100

5 CAN_BAUD_115

6 CAN_BAUD_250

7 CAN_BAUD_500

8 CAN_BAUD_800

9 CAN_BAUD_1000

CAN Interfaces Initialization

ifak system GmbH 7

isCAN_CloseDevice

4 Format

4 Input

4 Output

4 Description

The function terminates the connection to the local CAN device. Every device in use must be closed with this function before unloading the DLL in your program.



DeviceNr outNumber of the isCAN device as assigned by the configuration tool



8 ifak system GmbH

CAN Interfaces Configuration

ifak system GmbH 9

Configuration

isCAN_SetBaud

4 Format

4 Input

4 Output

4 Description

Changes the baud rate of the device chosen by DeviceNr in The command sets the device temporarily into the state Reset.

DeviceNr inNumber of the isCAN device as assigned by the configuration tool.

BaudDetermines the CAN baud rate (see Codes for baud rate Table 1)


DeviceNr outNumber of the isCAN device as assigned by the configuration tool.



10 ifak system GmbH

Afterwards the device connects to the bus using the new baud rate setting.

If one submits the value CAN_OFFLINE to the function, then the device disconnects from the bus. One can switch the device online again by submiiting a different baud rate value.

After a baud rate change the behaviour of the internal queues both on the device and in the DLL can be determined using the function isCAN_SetupDevice. SetupCmd = SETUPCMD_BAUDCHG and SetupBaudchg = SETUP_BAUDCHG_DEFAULT would cause the DLL and the device to empty all queues and discarding the messsages. by default CAN messages remain in the data buffers (SetupBaudchg = SETUP_BAUDCHG_DEFAULT).

Table 2: Codes for Setup Baudchg

SetupBaudchg Wert

SETUP_BAUDCHG_DEFAULT 0

SETUP_BAUDCHG_CLEAR 1


ifak system GmbH 11

isCAN_SetBaudRegister

4 Format

4 Input

4 Output

4 Description

The function accesses the baudrate registers BTR0 and BTR1 of the CAN-ASIC, thus allowing the setting of any supported baudrate. Additionally it is possible to adapt the Bit timing to a special CAN environment.


regBTR0 baud rate register (Byte 0)

regBTR1 baud rate register (Byte 1)





12 ifak system GmbH

The register values should be calculated as recommended by the application note AN97046 from Philips. The calculation should be based on the clock frequency of 24 MHz. The behaviour of the internal queues can be influenced in the same manner as explained for isCAN_SetBaud.


ifak system GmbH 13

isCAN_SetMessageID

4 Format

4 Input

4 Output

4 Description

With the help of this function one can configure a filter for CAN messages so that only the defined subset of the CAN messages are passed to the application. The messages filter of the device chosen with DeviceNr in is set to accept only messages with the CAN identifier Message ID. Every call of the function increase the number of accepted messages.


MessageID CAN-Message-ID



Error out Error input (see appendix > Error Codes)


14 ifak system GmbH

The message identifier value CAN_ALL_MESSAGES r(0xFFF) disables the message filtering. The function may set the control-ler temporarily to the Reset state.

There is no restriction regarding the number of calls to the func-tion isCAN_SetMessageID. Hoewever, it should be taken into account that every further call can make the bit mask "more fuzzy". For instance, if the application requires only the mes-sages with the MessageID 0x010 and 0x020, the subsequent call to this funtion result in the receiption of all messages with th IDs of 0x000 and 0x030. The message filtering takes place within the CAN ASIC, its filtering algorithm determining the explained behaviour. The function provides just a more comfortable inter-face to the ASICs registers (the filter is generated automatically by the function).

Use the function isCAN_SetupDevice to change the behav-iour of isCAN_SetMessageID in the way that a second filter-ing by software is added. If the software filter is enable only the messages with the exact MessageID are passed to the application. Unfortunately this property is not available for messages with extended MessageIDs (29 bit according to CAN 2.0B).

The function isCAN_SetupDevice can be used to deter-mined the behaviour of the internal queues if the message filter is changed. If the parameter SetupCmd of the isCAN_SetupDevice funtion is set to SETUPCMD_FILTER, the parameter SetupFilter contains the expected behaviour:


ifak system GmbH 15

Table 3: Codes for Setup Filter

HINWEIS: *This property can´t be used for Messages in the Extended Frame Format 29 bit according to CAN 2.0B (see isCAN_SetMessageExID).

Nr Setup Filter Meaning

0 SETUP_FILTER_DEFAULT initial behaviour; all message received before the call of isCAN_SetMessageID remain in the queues

1 SETUP_FILTER_CLEAR all message received before the

call of isCAN_SetMessageID are

discarded

2 SETUP_FILTER_EXACT * received messages are passed through the secondary software filter

3 SETUP_FILTER_EXACT_WITH_CLEAR *

received messages are passed through the secondary software filter and all message received

before the call of isCAN_SetMessageID are

discarded

4 SETUP_FILTER_IMMEDIATELY all message received before the call of isCAN_SetMessageIDwhich do not match the filter are discarded


16 ifak system GmbH

isCAN_SetMessageExID

4 Format

4 Input

4 Output

4 Description

Identical to the function isCAN_SetMessageID, provides a filtering of MessageIDs in the Extended Frame Format. After-wards you have to call the function with the message identifier CAN_ALL_MESSAGES_EX (0xFFFFFFFF) as a MessageID to accept all messages again. See also the description of isCAN_SetMessageID.


MessageID CAN-Message-ID





ifak system GmbH 17

ATTN:

If applied to a CAN network with both Standard and Extended message Frame Formats the functions isCAN_SetMessageID and isCAN_SetMessageExID may cause unexpected results, e.g. discarding of messages which one wants to pass the filter. For example the lowest bits of Mes-sageID will filter the first bits of the data field of a standard CAN message after a call to isCAN_SetMessageExID. After a call to isCAN_SetMessageID the 11 bit filter condition of Mes-sageID will be applied to the 11 highest bits of the 29 bits of a MessageID in Extended Frame Format.


18 ifak system GmbH

isCAN_SetupDevice

4 Format

4 Input


SetupCmd Selection of the setup command

SetupFilterParameters for the command SETUPCMD_FILTER

SetupBaudchgParameters for the command SETUPCMD_BAUDCHG

SetupTransmitParameters for the command SETUPCMD_TRANSMIT



ifak system GmbH 19

4 Output

4 Description

With this function the standard behaviour of different API func-tions can be modified. The can be applied individually to each device. The device must have been initialized before the function is called. The parameter setupcmd determines which property shall be changed.

Table 4: .Codes for SetupCmd

The parameters SetupFilter, SetupBaudchg und SetupTransmit determines the behaviour of the functions. It is explained in the description of the respective functions.

DeviceNr out Number of the isCAN device as assigned by the configuration tool.

Error out Error outpu (see appendix > Error Codes)

No Name Meaning

1 SETUPCMD_FILTER influences the behavior of the function isCAN_SetMessage(Ex)ID

2 SETUPCMD_BAUDCHG influences the behavior of the function isCAN_SetBaud/isCAN_SetBaudRegister

3 SETUPCMD_TRANSMIT influences the behavior of the function isCAN_TransmitMessageEx


20 ifak system GmbH

CAN Interfaces Data Transmission

ifak system GmbH 21

Data Transmission

isCAN_ReceiveMessageEx

4 Format

4 Input

4 Output

4 Description

Calls on the firmware in order to check for the occurrence of new messages. If the receive queue contains no new message the function returns an error.



DeviceNr outNumber of the isCAN device as assigned bythe configuration tool.

CAN_Message Buffer with received CAN-Message



22 ifak system GmbH

If data are processed continuously, the function must be periodi-cally called.

In addition the information whether the message was received in the Standard Frame Format (CAN_Message.bExtended = false) or in the Extended Frame Format (CAN_Message.bExtended = true) is passed to the calling application in the field bExtendedof the CAN_Message cluster.

isCAN_TransmitMessageEx

4 Format

4 Input

4 Output


CAN_Message Buffer with CAN-Message to send


DeviceNr outNumber of the isCAN device as assigned bythe configuration tool.


CAN Interfaces Data Transmission

ifak system GmbH 23

4 Description

Sends a CAN message via the device chosen with DeviceNr. It is submitted via the buffer CAN_Message. By default the function isCAN_TransmitMessage works synchronously. The func-tion only returns after sending the message successfully or breaks off and gives back an error code.This behaviour can be changed by the function isCAN_SetupDevice in that way, that the function works asynchronously. Therefore submit to the function for setupcmd the value SETUPCMD_TRANSMIT (=3) and for property the value SETUP_TRANSMIT_ASYNC (=1). When the function returns a NULL, the sending of messages happens asynchronously (older driver versions return an error code instead).After calling above function, isCAN_TransmitMessage

doesn’t block. The message is linked into a queue, afterwards the function goes back to the caller directly. The return value is CAN_NO_ERROR (=0). When the queues can’t record more messages, then the error code is CAN_TRANSMIT_BUFFER_BUSY (=7). If a message can’t be sent or an error occurs, the application receives no information.

In the additional field bExtended of the CAN_Message cluster one can determine whether the message is sent in the Standard Frame Format (CAN_Message.bExtended = false) or in theExtended Frame Format (CAN_Message.bExtended = true).

4 Remarks:

In the recent driver version the asynchronous functionality is not available for the PCI board isCAN PCI.

After the first calling of isCAN_TransmitMessageEx (in the asynchronous modus) one should not switch back into the synchronous modus. Moreover one is not advised to call the functions isCAN_SetMessageID and isCAN_SetBaud


24 ifak system GmbH

subsequently. This should be done before.

CAN Interfaces

ifak system GmbH 25

APPENDIXError Codes

Wert Error Beschreibung

0 CAN_NO_ERROR function successfully executed

1 CAN_OPEN_ERROR no access to device

2 CAN_DEVICE_NOT_FOUD

device with ID not found

3 CAN_DRIVER_ERROR

driver operation failed

4 CAN_INVALID_PARAMETER

an invalid parameter was passed to an API function

5 CAN_DEVICE_NOT_ONLINE

operation allowed only in online state

6 CAN_DEVICE_TIMEOUT

a time out occurred

7 CAN_TRANSMIT_BUFFER_BUSY

device is transmitting a message

8 CAN_RECEIVE_BUFFER_EMPTY

no message received

9 CAN_THREAD_NOT_STARTED

the callback thread is not running

10 CAN_THREAD_ALREADY_STARTED

thread is already running

11 CAN_BUFFER_OVERRUN

the last event was lost because of an full event FIFO

12 CAN_DEVICE_NOT INITIALIZED

CAN Interfaces

26 ifak system GmbH

13 CAN_DEVICE_REMOVED

device is disconnected

15 CAN_DEVICE_ALREADY_IN_USE

the specified device is already used by this or another application

16 CAN_BUS_ERROR

17 CAN_BUS_OFF

18 CAN_ERROR_PASSIVE

CAN controller internal error counter reached a limit. There is probably a pro-blem concerning the physical connec-tion.

19 CAN_DATA_OVERRUN

20 CAN_ERROR_WARNING

24 CAN_RECEIVED_EFF_MESSAGE

Extended Frame Format messsage received call isCAN_ReceiveMessageEx

30 CAN_SEND_ERROR Send error. isCAN device is probably alone on th bus.

31 CAN_SEND_NO_ACK no acknowledge, node is probably alone on the bus

32 CAN_ERR_CRITICAL_BUS

critical bus timing or bus length

35 CAN_THREAD_IS_BLOCKED

callback thread is blocked, stopping thread failed

40 CAN_DEVICE_NOT_LICENCED

need a licence number under NT4

41 CAN_ACCESS_DENIED no access rights for operation

IsCAN Labview Developer

Documents

ifak system

baud rate

extended frame

baud error

id error input

standard frame

messageid

baud rate