TECHNOLOGIEN MIT VORSPRUNG

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 meansgraphic, electronic or mechanical, including photocopying, recording, taping or storage in an information retrieval system-without prior written 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 GmbH Oststrae 18 39114 Magdeburg Tel.: Fax: +49-391-54 45 63-10 +49 -391-54 45 63-99

Email: kontakt@ifak-system.com www.ifak-system.de

CAN Interfaces

Developer Manual

Contents
Kapitel 1: Hardware Installation
General Information . .... ... ... ... .... ... ... ... ... ..1 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Our Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Interfaces isCAN USB/isCAN PCI . ... .... ... ... ... ... ..2

Kapitel 2: Software Installation and Configuration

Driver Software Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 isCAN-LabView-Library Installation . . . . . . . . . . . . . . . . . . . . . . 4 Initialization 5 isCAN_DeviceInitEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 isCAN_CloseDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Configuration isCAN_SetBaud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 isCAN_SetBaudRegister . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

isCAN_SetMessageID . . . . . . . . . . . . . . . . . . . . . . . . .13 isCAN_SetMessageExID . . . . . . . . . . . . . . . . . . . . . . .16 isCAN_SetupDevice. . . . . . . . . . . . . . . . . . . . . . . . . . .18

Data Transmission

isCAN_ReceiveMessageEx . . . . . . . . . . . . . . . . . . . . .20 isCAN_TransmitMessageEx . . . . . . . . . . . . . . . . . . . .21

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

ifak system GmbH

CAN Interfaces

II

ifak system GmbH

CAN Interfaces

General Information

CHAPTER 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::
Courier New: Arial
File names, Code sequences Names, Commands, Remarks WARNING Dangerous electrical voltage

Our Service
In case you have any questions which cant be solved by this manual, please contact our service by phone, fax or e-mail: ifak system GmbH Oststrasse 18, 39114 Magdeburg, Germany Tel.: +49 - 391 - 544 563-10 Fax: +49 - 391 - 544 563-99 E-mail: kontakt@ifak-system.com

ifak system GmbH

Hardware Installation

CAN Interfaces

Interfaces isCAN USB/isCAN PCI

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

ifak system GmbH

CAN Interfaces

Driver Software Installation

CHAPTER 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.

ifak system GmbH

Software Installation and Configuration

CAN Interfaces

Installation LabView Library Installation

The isCAN LabView-Library includes two individual Zip archives 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.zip The zip file contains the VIs of the LabView CAN Library. isCAN_LV_Examples.zip The 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

ifak system GmbH

CAN Interfaces

Initialization

CHAPTER 3:

INTERFACES FOR CAN APPLICATION

Initialization
isCAN_DeviceInitEx
4

Format

Input Number of the isCAN device as assigned by the configuration tool. Determines the CAN baud rate. (see table: Codes for Baudrate) Error input (see appendix > Error Codes)

DeviceNr in Baud Error in

4

Output Number of the isCAN device as assigned by the configuration tool. Error output (see appendix > Error Codes)

DeviceNr out Error out

ifak system GmbH

Interfaces for CAN application

CAN Interfaces

Description

Initializes a device with the chosen DeviceNr in and sets an initial baudrate. The message filtering is disabled. If the CAN controller 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 1 2 3 4 5 6 7 8 9 CAN_OFFLINE CAN_BAUD_10 CAN_BAUD_20 CAN_BAUD_50 CAN_BAUD_100 CAN_BAUD_115 CAN_BAUD_250 CAN_BAUD_500 CAN_BAUD_800 CAN_BAUD_1000

ifak system GmbH

CAN Interfaces

Initialization

isCAN_CloseDevice
4

Format

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

Error input (see appendix > Error Codes)

DeviceNr in Error in
4

Output Number of the isCAN device as assigned by the configuration tool Error output (see appendix > Error Codes) Description

DeviceNr out Error out

4

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.

ifak system GmbH

Interfaces for CAN application

CAN Interfaces

ifak system GmbH

CAN Interfaces

Configuration

Configuration
isCAN_SetBaud
4

Format

Input Number of the isCAN device as assigned by the configuration tool. Determines the CAN baud rate (see Codes for baud rate Table 1) Error input (see appendix > Error Codes)

DeviceNr in

Baud Error in
4

Output Number of the isCAN device as assigned by the configuration tool. Error output (see appendix > Error Codes)

DeviceNr out Error out

4

Description

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

ifak system GmbH

Interfaces for CAN application

CAN Interfaces

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 SETUP_BAUDCHG_DEFAULT SETUP_BAUDCHG_CLEAR Wert 0 1

10

ifak system GmbH

CAN Interfaces

Configuration

isCAN_SetBaudRegister
4

Format

Input Number of the isCAN device as assigned by the configuration tool. baud rate register (Byte 0) baud rate register (Byte 1) Error input (see appendix > Error Codes)

DeviceNr in regBTR0 regBTR1 Error in

4

Output Number of the isCAN device as assigned by the configuration tool. Error output (see appendix > Error Codes)

DeviceNr out Error out

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.
11

ifak system GmbH

Interfaces for CAN application

CAN Interfaces

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.

12

ifak system GmbH

CAN Interfaces

Configuration

isCAN_SetMessageID
4

Format

Input Number of the isCAN device as assigned by the configuration tool. CAN-Message-ID Error input (see appendix > Error Codes)

DeviceNr in MessageID Error in

4

Output Number of the isCAN device as assigned by the configuration tool. Error input (see appendix > Error Codes)

DeviceNr in Error out

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.

ifak system GmbH

13

Interfaces for CAN application

CAN Interfaces

The message identifier value CAN_ALL_MESSAGES r(0xFFF) disables the message filtering. The function may set the controller temporarily to the Reset state. There is no restriction regarding the number of calls to the function 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 messages 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 interface to the ASICs registers (the filter is generated automatically by the function). Use the function isCAN_SetupDevice to change the behaviour of isCAN_SetMessageID in the way that a second filtering 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 determined 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:

14

ifak system GmbH

CAN Interfaces

Configuration

Table 3: Codes for Setup Filter Nr 0 Setup Filter SETUP_FILTER_DEFAULT Meaning

initial behaviour; all message received before the call of isCAN_SetMessageID remain in the queues all message received before the call of isCAN_SetMessageID are discarded received messages are passed through the secondary software filter received messages are passed through the secondary software filter and all message received before the call of isCAN_SetMessageID are discarded all message received before the call of isCAN_SetMessageID which do not match the filter are discarded

SETUP_FILTER_CLEAR

SETUP_FILTER_EXACT *

SETUP_FILTER_EXACT_WITH_ CLEAR *

SETUP_FILTER_IMMEDIATELY

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

ifak system GmbH

15

Interfaces for CAN application

CAN Interfaces

isCAN_SetMessageExID
4

Format

Input Number of the isCAN device as assigned by the configuration tool. CAN-Message-ID Error input (see appendix > Error Codes)

DeviceNr in MessageID Error in

4

Output Number of the isCAN device as assigned by the configuration tool. Error output (see appendix > Error Codes)

DeviceNr out Error out

4

Description

Identical to the function isCAN_SetMessageID, provides a filtering of MessageIDs in the Extended Frame Format. Afterwards 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.

16

ifak system GmbH

CAN Interfaces

Configuration

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 MessageID 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 MessageID will be applied to the 11 highest bits of the 29 bits of a MessageID in Extended Frame Format.

ifak system GmbH

17

Interfaces for CAN application

CAN Interfaces

isCAN_SetupDevice
4

Format

Input

DeviceNr in SetupCmd SetupFilter SetupBaudchg SetupTransmit Error in

Number of the isCAN device as assigned by the configuration tool. Selection of the setup command Parameters for the command SETUPCMD_FILTER Parameters for the command SETUPCMD_BAUDCHG Parameters for the command SETUPCMD_TRANSMIT
Error input (see appendix > Error Codes)

18

ifak system GmbH

CAN Interfaces

Configuration

Output

DeviceNr out Error out

4

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

Error outpu (see appendix > Error Codes)

Description

With this function the standard behaviour of different API functions 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 No 1 2 Name SETUPCMD_FILTER SETUPCMD_BAUDCHG Meaning influences the behavior of the function isCAN_SetMessage(Ex)ID influences the behavior of the function isCAN_SetBaud/ isCAN_SetBaudRegister influences the behavior of the function isCAN_TransmitMessageEx

SETUPCMD_TRANSMIT

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

ifak system GmbH

19

Interfaces for CAN application

CAN Interfaces

20

ifak system GmbH

CAN Interfaces

Data Transmission

Data Transmission
isCAN_ReceiveMessageEx
4

Format

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

DeviceNr in Error in
4

Error input (see appendix > Error Codes)

Output Number of the isCAN device as assigned by the configuration tool. Buffer with received CAN-Message

DeviceNr out CAN_Message Error out

4

Error output (see appendix > Error Codes)

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.

ifak system GmbH

21

Interfaces for CAN application

CAN Interfaces

If data are processed continuously, the function must be periodically 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 bExtended of the CAN_Message cluster.

isCAN_TransmitMessageEx
4

Format

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

DeviceNr in

CAN_Message Buffer with CAN-Message to send Error in

4

Error input (see appendix > Error Codes)

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

DeviceNr out Error out

Error output (see appendix > Error Codes)

22

ifak system GmbH

CAN Interfaces

Data Transmission

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 function 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 doesnt 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 cant record more messages, then the error code is CAN_TRANSMIT_BUFFER_BUSY (=7). If a message cant 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 the Extended 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

ifak system GmbH

23

Interfaces for CAN application

CAN Interfaces

subsequently. This should be done before.

24

ifak system GmbH

CAN Interfaces

APPENDIX
Error Codes
Wert Error Beschreibung

0 1 2 3 4 5 6 7 8 9 10 11 12

CAN_NO_ERROR CAN_OPEN_ERROR

function successfully executed no access to device

CAN_DEVICE_NOT_F device with ID not found OUD CAN_DRIVER_ERRO R driver operation failed

CAN_INVALID_PARA an invalid parameter was passed to an METER API function CAN_DEVICE_NOT_ ONLINE operation allowed only in online state

CAN_DEVICE_TIMEO a time out occurred UT CAN_TRANSMIT_BU FFER_BUSY device is transmitting a message

CAN_RECEIVE_BUFF no message received ER_EMPTY CAN_THREAD_NOT_ the callback thread is not running STARTED CAN_THREAD_ALRE thread is already running ADY_STARTED CAN_BUFFER_OVER RUN CAN_DEVICE_NOT INITIALIZED the last event was lost because of an full event FIFO

ifak system GmbH

25

CAN Interfaces

13 15 16 17 18

CAN_DEVICE_REMO VED CAN_DEVICE_ALRE ADY_IN_USE CAN_BUS_ERROR CAN_BUS_OFF

device is disconnected the specified device is already used by this or another application

CAN_ERROR_PASSIV CAN controller internal error counter E reached a limit. There is probably a problem concerning the physical connection. CAN_DATA_OVERR UN CAN_ERROR_WARNI NG CAN_RECEIVED_EFF Extended Frame Format messsage _MESSAGE received call isCAN_ReceiveMessageEx CAN_SEND_ERROR Send error. isCAN device is probably alone on th bus.

19 20 24

30 31 32 35
40 41

CAN_SEND_NO_ACK no acknowledge, node is probably alone on the bus CAN_ERR_CRITICAL _BUS critical bus timing or bus length

CAN_THREAD_IS_BL callback thread is blocked, stopping OCKED thread failed

CAN_DEVICE_NOT_LI CENCED CAN_ACCESS_DENIED

need a licence number under NT4 no access rights for operation

26

ifak system GmbH