candriver lib docu

CAN Driver Library for CANcardXL/CANboardXL/CANcaseXL/

CANcardX/CAN-AC2-PCI

User Interface Description

Version 4.3

Vector Informatik GmbH, Ingersheimer Str. 24, D-70499 Stuttgart Tel. +49 711 80670-0, Fax +49 711 80670-111, Email [email protected]

Internet http://www.vector-informatik.de

2

© Vector Informatik GmbH CAN Driver Library Version: 4.3

Contents

1 Overview ................................................................................................................5

1.1 Features ......................................................................................................................6 1.1.1 Multi-Hardware......................................................................................................6 1.1.2 Multi-Application....................................................................................................6 1.1.3 Virtual Channels....................................................................................................7

1.2 Installation ..................................................................................................................7

1.3 Driver Library..............................................................................................................7

1.4 Important Notes..........................................................................................................8 1.4.1 Supported Operating Systems ..............................................................................8

2 Functions ...............................................................................................................9

2.1 Overview ...................................................................................................................12

2.2 Initialisation ..............................................................................................................13 2.2.1 ncdOpenDriver....................................................................................................13 2.2.2 ncdGetDriverConfig ............................................................................................13 2.2.3 ncdGetChannelIndex ..........................................................................................15 2.2.4 ncdGetChannelMask...........................................................................................16 2.2.5 ncdGetApplConfig...............................................................................................16 2.2.6 ncdSetApplConfig ...............................................................................................17 2.2.7 ncdOpenPort.......................................................................................................19

2.3 Configuration............................................................................................................21 2.3.1 ncdSetChannelBitrate .........................................................................................21 2.3.2 ncdSetChannelParams .......................................................................................21 2.3.3 ncdSetChannelParamsC200...............................................................................23 2.3.4 ncdSetChannelOutput.........................................................................................23 2.3.5 ncdSetChannelMode...........................................................................................24 2.3.6 ncdSetReceiveMode ...........................................................................................24 2.3.7 ncdSetChannelTransceiver .................................................................................25

2.3.7.1 Lowspeed ...................................................................................................25 2.3.7.2 Single Wire .................................................................................................25 2.3.7.3 CANcab EVA ..............................................................................................26 2.3.7.4 CANcab 10011 (Truck & Trailer).................................................................26 2.3.7.5 Highspeed ..................................................................................................27

2.3.8 ncdSetNotification ...............................................................................................27 2.3.9 ncdAddAcceptanceRange...................................................................................28 2.3.10 ncdRemoveAcceptanceRange ......................................................................28 2.3.11 ncdResetAcceptance ....................................................................................29 2.3.12 ncdSetChannelAcceptance ...........................................................................30 2.3.13 ncdActivateChannel ......................................................................................31 2.3.14 ncdSetTimerRate ..........................................................................................32 2.3.15 ncdResetClock ..............................................................................................32

2.4 General......................................................................................................................33

3


2.4.1 ncdReceive1 .......................................................................................................33 2.4.2 ncdTransmit ........................................................................................................33 2.4.3 ncdReceive .........................................................................................................34 2.4.4 ncdGetEventString..............................................................................................35 2.4.5 ncdRequestChipState .........................................................................................36 2.4.6 ncdGetState........................................................................................................36 2.4.7 ncdFlushReceiveQueue......................................................................................36 2.4.8 ncdFlushTransmitQueue.....................................................................................36 2.4.9 ncdGetReceiveQueueLevel ................................................................................36 2.4.10 ncdGetErrorString .........................................................................................37 2.4.11 ncdGetChannelVersion .................................................................................37

2.5 Deinitialisation..........................................................................................................38 2.5.1 ncdDeactivateChannel ........................................................................................38 2.5.2 ncdClosePort ......................................................................................................38 2.5.3 ncdCloseDriver ...................................................................................................38

3 Error Codes..........................................................................................................39

3.1 Overview ...................................................................................................................39 3.1.1 VSUCCESS ........................................................................................................39 3.1.2 VPENDING .........................................................................................................39 3.1.3 VERR_QUEUE_IS_EMPTY................................................................................39 3.1.4 VERR_QUEUE_IS_FULL ...................................................................................39 3.1.5 VERR_TX_NOT_POSSIBLE ..............................................................................39 3.1.6 VERR_WRONG_PARAMETER..........................................................................39 3.1.7 VERR_INVALID_CHAN_INDEX .........................................................................39 3.1.8 VERR_INVALID_ACCESS..................................................................................39 3.1.9 VERR_PORT_IS_OFFLINE................................................................................40 3.1.10 VERR_CHAN_IS_ONLINE............................................................................40 3.1.11 VERR_NOT_IMPLEMENTED .......................................................................40 3.1.12 VERR_INVALID_PORT ................................................................................40 3.1.13 VERR_CMD_TIMEOUT ................................................................................40 3.1.14 VERR_HW_NOT_PRESENT........................................................................40 3.1.15 VERR_NOTIFY_ALREADY_ACTIVE............................................................40 3.1.16 VERR_CANNOT_OPEN_DRIVER................................................................40 3.1.17 VERROR.......................................................................................................40

4 Events...................................................................................................................41

4.1 Overview ...................................................................................................................41 4.1.1 V_RECEIVE_MESSAGE - V_TRANSMIT_MESSAGE......................................42 4.1.2 V_CHIP_STATE .................................................................................................43 4.1.3 V_TIMER ............................................................................................................43

5 Programming Examples .....................................................................................44

5.1 Overview ...................................................................................................................44 5.1.1 CANvbas.............................................................................................................45 5.1.2 CANlogDyn .........................................................................................................46 5.1.3 CANlog ...............................................................................................................46 5.1.4 CANgen ..............................................................................................................47

4


5.1.5 CANdemo ...........................................................................................................47 5.1.6 CANcount ...........................................................................................................48 5.1.7 CANtrace ............................................................................................................49 5.1.8 CANsing..............................................................................................................49 5.1.9 CANlatw..............................................................................................................50 5.1.10 CANtracD......................................................................................................50 5.1.11 LabView ........................................................................................................50 5.1.12 Load vcand32.dll dynamically........................................................................51 5.1.13 General .........................................................................................................51

5


1 Overview

If you want to write your own CAN (Controller Area Network) applications instead of using the Vector tools like CANoe and CANalyzer and so on, then you can use the CAN Driver Library with their API functions. The library can be linked with your pro-gram and thus allows access to the CAN bus. Then you can initialize the CAN chips and transmit or receive CAN messages. There are a lot of samples, which give a good overview what’s possible with the library and source code that can be used for your own application. The CAN Driver Library and the corresponding CAN driver is available for different Vector CAN hardware and operating systems. It is designed to run multiple CAN applications using the same CAN hardware con-currently by virtualizing the CAN hardware interfaces. Also it is possible to build ap-plications which run on different CAN hardware without code changes.

6


1.1 Features

1.1.1 Multi-Hardware The interface is hardware independent and is designed to support various CAN hardware. Currently supported are the CANcardXL, CANcardX, and CAN-AC2-PCI. You will find special information in the manual of the corresponding hardware. Several CAN hardware (CAN-AC2-PCI with CANcardX for example) may be used simultaneously.

1.1.2 Multi-Application The driver is designed for Windows 98/ME/NT/2000/XP multi-processing (multi-tasking) operating systems. Multiple applications can use the CAN hardware at the same time.

To get driver access an application must open a driver port and retrieve a port han-dle. This port handle is used for all subsequent calls to the driver. If a second application is demanding driver access, it gets the handle to another port. It is possi-ble for an application to open multiple ports.

Application 1

CAN - Driver

ReceiveQueue

CAN Controller

Port 1

Channel 1

TransmitQueue

ReceiveQueue

Port 2

ReceiveQueue

Port 3

Channel 2

TransmitQueue

Application 2

CAN Controller

7


The application then selects the CAN hardware channels it wants to use via the port. Applications may use the same hardware channel simultaneously. This involves virtualizing the hardware channels. From the application‘s perspective it appears as though it alone were using the hardware channel. To send a message from an application, the application chooses one or more chan-nels connected to the port and calls the driver. Channels are identified by bit masks. The message is passed to every selected channel and is transmitted when possible. When a hardware channel receives a message it is passed to every port that is using this channel. Each port maintains its own receive queue. The application at this port can poll the queue to determine whether there are incoming messages, or make asynchronous receive calls, which will be completed when a message arrives and the application will be notified. Nevertheless, multi-processing can also cause some problems. For example, two applications might require different settings for the same channel. Consequently, an application may demand initialisation access for a channel. A channel allows only one port to have this access.

1.1.3 Virtual Channels The driver features a special kind of channel, the virtual channel. It has no connected hardware, it is just a software channel. There are two virtual channels which are con-nected by a virtual CAN bus. Virtual channels are virtualised like any other hardware channel. This allows the user to build and test CAN applications without having a real CAN bus available.

1.2 Installation The installation procedure is described in a separate manual.

1.3 Driver Library Applications can get driver access by using a Windows DLL and a C header file. VCAND32.DLL 32 bit DLL for Windows 98/ME/NT/2000/XP VCAND.H C header

8


1.4 Important Notes

1.4.1 Supported Operating Systems

Windows

98

Windows

ME

Windows

NT4

Windows

2000

Windows

XP

CANcardXL X X X X X

CANcardX X X X X X

CAN-AC2-PCI X X X X X

CANpari X - X X X

9


2 Functions

Initialisation Description

ncdOpenDriver ( ) The driver is loaded if this has not already been done.

ncdGetApplConfig ( ) Gets the application configuration from the CAN hardware control panel.

ncdSetApplConfig ( ) Sets the application configuration

ncdGetChannelIndex() This function looks for an available channel of the given type and returns its index.

ncdGetChannelMask() This function looks for an available channel of the given type and returns its mask.

ncdGetDriverConfig ( ) The driver configuration is returned in a struc-ture containing the number of channels and their characteristics.

ncdOpenPort ( ) The application tells the driver which channels it wants to access and for which of these chan-nels it wants permission to initialise the chan-nel. Only one port can get permission to initialise a channel.

Configuration Description

ncdSetChannelParams ( ) ncdSetChannelBitrate ( ) ncdSetChannelParamsC200 ( )

Bit timing parameters of the CAN channel are set. ncdSetChannelBitrate provides a simplified way to specify the bit rate. ncdSetChannelParamsC200 offers C200 Ba-sic-CAN controller settings.

ncdSetChannelMode ( ) Sets optional generation of TX and TXRQ events when transmitting messages.

ncdSetChannelOutput ( ) To decide if the CAN chip should generate an acknowledge when a CAN message is re-ceived.

ncdSetReceiveMode ( ) Suppress error frame’s and chipstate events.

ncdSetChannelTransceiver ( ) This function is used to set the transceiver modes.

10


Configuration Description

ncdSetNotification( ) Sets up an event to notify the application if there are messages in the port‘s receive queue.

ncdAddAcceptanceRange ( ) Open the acceptance filter for a ID range.

ncdRemoveAcceptanceRange ( ) Remove the acceptance filter for a ID range

ncdResetAcceptance ( ) Reset the acceptance filter -> acceptance fil-ters closed.

ncdSetChannelAcceptance ( ) Sets the acceptance filters used at the port for a channel.

ncdActivateChannel ( ) A number of channels connected to the port are activated.

ncdSetTimerRate ( ) Sets the timer rate for cyclic timer events at the port.

ncdResetClock ( ) The port‘s clock is reset.

General Description

ncdTransmit ( ) A CAN message to be transmitted is put to the designated channels.

ncdReceive ( ) ncdReceive1 ( )

The driver is asked to retrieve events from the port’s receive queue. You can choose whether to poll the port or wait for an incoming event. It is possible to read multiple events at a time, but the caller must provide the memory. The driver is asked to retrieve a single event from the application‘s receive queue.

ncdGetEventString ( ) Used to get information of an event as string.

ncdRequestChipState ( ) The state of a CAN controller is requested.

ncdGetState ( ) The last error code of the port is returned.

ncdFlushReceiveQueue ( ) The receive queue of a port is flushed.

ncdFlushTransmitQueue ( ) The transmit queue of a channel is flushed.

ncdGetReceiveQueueLevel ( ) The number of elements in a port’s receive queue is returned.

ncdGetErrorString ( ) Used to get a description of an error code as string.

ncdGetChannelVersion ( ) Get version information of a channel.

11


Deinitialization Description

ncdDeactivateChannel ( ) A number of channels connected to the port are deactivated.

ncdClosePort ( ) The application’s driver access port is closed.

ncdCloseDriver ( ) The driver is closed.

Port functions for which channel must be deactivated.

ncdSetChannelMode ( ) ncdSetChannelOutput ( ) ncdSetChannelParams ( ) ncdSetChannelBitrate ( ) ncdSetChannelParamsC200 ( ) ncdSetChannelAcceptance ( ) ncdAddAcceptanceRange ( ) ncdRemoveAcceptanceRange ( ) ncdResetAcceptance ( )

Port functions for which init. ac-cess is required.

ncdSetChannelOutput ( ) ncdSetChannelParams ( ) ncdSetChannelBitrate ( ) ncdSetChannelParamsC200 ( ) ncdSetChannelTransceiver ( )

12


2.1 Overview

start

end

ncdOpenDriver()

ncdGetApplConfig()

ncdGetChannelIndex()

ncdGetDriverConfig()

ncdOpenPort()

ncdActivateChannel()

ncdDeactivateChannel()

ncdClosePort()

ncdCloseDriver()

init access?

ncdSetChannelBitrate()

ncdSetChannelOutput()

ncdSetChannelParams() ncdSetChannelParamsC200()

ncdSetAcceptance()

ncdSetNotification()

ncdReceive1()

ncdTransmit()

ncdReceive()

ncdGetEventString()

ncdResetClock()

ncdRequestChipstate()

ncdSetTimerRate()

ncdGetState()

ncdFlushReceiveQueue()

ncdFlushTransmitQueue()

ncdGetReceiveQueueLevel()

yes

no

ncdGetChannelMask()

ncdSetApplConfig()

ncdSetChannelMode()

ncdGetErrorString()

ncdSetReceiveMode()

ncdGetChannelVersion()

ncdSetChannelTransceiver()

ncdAddAcceptanceRange() ncdRemoveAcceptanceRange() ncdResetAcceptance()

13


2.2 Initialisation

2.2.1 ncdOpenDriver Syntax : Vstatus ncdOpenDriver ( void ) Description : Each application must call this function to load the driver. If this call is unsuccessful, no other API calls are possible.

2.2.2 ncdGetDriverConfig Syntax : Vstatus ncdGetDriverConfig ( int* pChanCount, VDriverConfig* pDriverConfig) Parameters :

Name Description

pChanCount Points to a variable, where the number of channels is returned

pDriverConfig Points to a user buffer for the information the driver returns. If a NULL pointer is passed, the driver will only return the number of channels supported.

The driver returns the following structure containing the information: typedef struct _VDriverConfig {

char driverName[MAX_DRIVER_NAME+1];

unsigned short driverVersion;

void* dispatcher;

unsigned char channelCount;

VChannelConfig channel[1];

} VDriverConfig;

Name Description

driverName [ ] Array of ASCII characters containing the driver name.

driverVersion Version of the driver (example: 0x0300 means 3.0)

dispatcher Internal use

14


Name Description

channelCount Number indicating how many channels of information follow.

channel [ ] The structure containing information for the first channel. If there are more channels, the information will follow directly after this structure.

typedef struct _VChannelConfig {

char name[MAX_CHAN_NAME+1];

unsigned char hwType;

unsigned char hwIndex;

unsigned char hwChannel;

unsigned char tranceiverType;

unsigned char channelIndex;

unsigned long channelMask;

// Channel

unsigned char isOnBus;

VchipParams chipParams;

unsigned char outputMode;

unsigned char flags;

}

Name Description

name [ ] Array of ASCII characters containing the channel’s name.

hwType HWTYPE_CANCARDXL, HWTYPE_VIRTUAL, ... (see vcand.h)

hwIndex Index of the hardware (same type) (0,1,...)

hwChannel Index of the channel (same hardware) (0,1,...)

tranceiverType TRANSCEIVER_TYPE_W210, TRANSCEIVER_TYPE_251, ...

channelIndex Global channel index (0,1,...)

channelMask Global channel mask (1<<channelIndex)

isOnBus The Flag specifies whether the channel is on the bus.

chipParams Currently active bit timing

outputMode Currently active output mode

flags Currently active options MSGFLAG_TX,MSGFLAG_TXRQ

15


Description :

This function can be called at any time after a successful ncdOpenDriver(). The caller gets information how many channels are currently available. First there might be a call passing the NULL pointer for pDriverConfig to obtain the total number of channels; then the user allocates enough memory for all of the chan-nel’s information and calls pDriverConfig again pointing to the allocated memory. There are two functions ncdGetChannelMask and ncdGetChannelIndex, which sim-plify looking for an appropriate channel. The hardware type, hardware index and hardware channel may be entered, and the functions return the channel index or mask if there is one. Example : vErr = ncdGetDriverConfig(&n,NULL); // Get the number of chan-nels

if (vErr) __leave;

printf(“ %u channels found\n”,n);

gDriverConfig = malloc(SIZEOF_VDRIVERCONFIG(n));

if (!gDriverConfig) __leave;

// Get information about all channels

vErr = ncdGetDriverConfig(&n,gDriverConfig);

if (vErr) __leave;

// build a channel mask for all channels

for (i=0; i<n; i++) {

gChannelMask |= gDriverConfig->channel[i].channelMask;

}

2.2.3 ncdGetChannelIndex Syntax : int ncdGetChannelIndex( int hwType,

int hwIndex,

int hwChannel );

Parameters :

Name Description

hwType -1, HWTYPE_CANCARDXL,... (see vcand.h)

hwIndex -1,0,1 ( to distinguish between two cards of same type)

hwChannel -1,0,1 ( which hardware channel of the selected device )

16


Return value : channelIndex Description : Gets the channel index for one channel of a particular hardware. Parameter -1 means all possibilities were checked. Return value -1 means no such channel was found.

2.2.4 ncdGetChannelMask Syntax : Vaccess ncdGetChannelMask( int hwType,

int hwIndex,

int hwChannel );

Parameters :

Name Description

hwType -1, HWTYPE_CANCARDXL,... (see vcand.h)

hwIndex -1,0,1 ( to distinguish between two cards of same type)

hwChannel -1,0,1 ( which hardware channel of the selected device )

Return value : channelmask Description : Gets the channel mask for one channel of a particular hardware. Parameter -1 means all possibilities were checked. Return value 0 means no channel was found.

2.2.5 ncdGetApplConfig Syntax : Vstatus ncdGetApplConfig( char* appName,

int appChannel,

int* hwType,

int* hwIndex,

int* hwChannel)

17


Parameters :

Name Description

appName Name of Application

appChannel 0,1,...


hwIndex Index of the hardware (0,1,...)

hwChannel Index of the channel (connector) (0,1,...)

Description : ncdGetApplConfig returns the hwIndex, hwChannel and hwType for a specific Appli-cation and application channel. This gives the ability to register own applications into the Vector CAN DRIVER CONFIGURATION found in the control panel. The values hwIndex and hwChannel, which contains the hardware information, can be used in a subsequent call to ncdGetChannelMask or ncdGetChannelIndex. m_hwType = HWTYPE_CANCARDX;

m_channel = 0;

m_hwIndex = 0;

ncdGetApplConfig("CANlogDyn",0,(int *)&m_hwType,

&m_hwIndex,&m_channel);

ncdSetApplConfig("CANlogDyn",0,m_hwType,m_hwIndex,

m_channel);

m_channelMask = ncdGetChannelMask(m_hwType,0,m_channel);

ncdOpenPort ( &m_portHandle, "CANlogDyn" , m_channelMask ,

m_channelMask, &m_permissionMask,128);

2.2.6 ncdSetApplConfig Syntax : Vstatus ncdSetApplConfig( char* appName,

int appChannel,

int hwType,

int hwIndex,

int hwChannel)

18


Parameters :

Name Description

appName Name of Application

appChannel 0,1,...


hwIndex Index of the hardware (slot) (0,1,...)

hwChannel Index of the channel (connector) (0,1,...)

Description : Correspondig to ncdGetApplConfig( ) this function sets the application configuration, but it can also done in the CAN DRIVER CONFIGURATION. If the application name does not exist, a new one is generated.

19


2.2.7 ncdOpenPort Syntax : Vstatus ncdOpenPort ( VportHandle *portHandle,

char *userName,

Vaccess accessMask,

Vaccess initMask,

Vaccess *permissionMask,

int rxQueueSize)

Parameters :

Name Description

portHandle Pointer to a variable where the port handle is returned. This handle must be used for any further calls to the port. If -1 is returned, the port was neither created nor opened.

userName The name of the application which uses the port must be unique on each call.

accessMask Mask specifying which channels shall be used with this port.

initMask Mask specifying the channels for which the ports wants addi-tional access for initialisation (e.g. to set the bit timing). Only one port can have init access to a channel.

permissionMask Pointer to a variable where the mask is returned for the chan-nel for which init access is granted.

rxQueueSize Size of the port’s receive queue allocated by the driver. Speci-fies how many events can be stored in the queue. The value should be a power of 2. If not, the value is rounded up to the next power of 2. (max. queue size is 32k)

If the call is unsuccessful, check permissionMask. Some channels may have been opened successfully; they are returned in permissionMask.

Vstatus Meaning

VSUCCESS Access to all requested channels, but init access only for channels returned in permission mask.

VERROR Open failed, no access.

The application tells the driver the channels it wants to access and for which of these channels it wants permission to initialise the channel. Only one port can get init per-mission to initialise a channel. The permitted init access is returned.

20


Example : This example should help you to understand the meanings of channel index and channel mask. The following example is a possible configuration.

Index Mask

virtual channel1 channel2

0 1

0x0001 0x0002

CANcardX channel1 channel2

2 3

0x0004 0x0008

Channels are identified by their channel index. Most functions expect a bit mask to identify multiple channels. The bit mask is constructed by channelMask = 1<< channelIndex. Channel mask : CANcardX channel1

............ 0 0 1 0 0

CANcardX channel2

............ 0 1 0 0 0

channel mask for CANcardX channel1 and channel2

............ 0 1 1 0 0

// select CANcardX channel 1

gChannelMask = ncdGetChannelMask(HWTYPE_CANCARDX,-1,0);

if(!gChannelMask) return VERR_HW_NOT_PRESENT;

// try to get init access to all channels

gInitMask = gChannelMask;

vErr = ncdOpenPort(&gPortHandle,„CANDEMO„,gChannelMask,gInitMask,

&gPermissionMask,1024);

21


2.3 Configuration

2.3.1 ncdSetChannelBitrate Syntax : Vstatus ncdSetChannelBitrate (VportHandle portHandle,

Vaccess accessMask,

unsigned long bitrate)

Parameters :

Name Description

bitrate Bit rate in BPS. May be in the range 5000 - 1000000

Description : ncdSetChannelBitrate provides a simple way to specify the bit rate.

2.3.2 ncdSetChannelParams Syntax : Vstatus ncdSetChannelParams ( VportHandle portHandle,

Vaccess accessMask,

VchipParams* pChipParams )

Parameters :

Name Description

pChipParams Pointer to an array of chip parameters. There must be a parame-ter structure for each channel selected by accessMask. The first structure belongs to the least significant bit that is set at access-Mask.

The structure for the chip parameters has the following format. struct _Vchip_params {

unsigned long bitRate;

unsigned char sjw;

unsigned char tseg1;

unsigned char tseg2;

unsigned char sam;

};

22


Name Description

bitRate This value specifies the real bit rate, e.g. 125,000.

Sjw The ‘sjw’ value of CAN bus timing.

tseg1 The ‘tseg1’ value of CAN bus timing.

tseg2 The ‘tseg2’ value of CAN bus timing.

Sam The ‘sam’ value of CAN bus timing. Samples may be 1 or 3.

For more information about the bit timing of the CAN controller please refer to some of the CAN literature or CAN controller data sheets. Description : This initialises the channels defined by accessMask with the given parameters. To call this function the port must have init access and the selected channels must be deactivated. Return value : VERR_WRONG_PARAMETER The parameter are not valid. Example : To calculate your baudrate use following formula:

Baudrate = f/(2*presc*(1+tseg1+tseg2)

presc: CAN-Prescaler [1..64]

sjw: CAN-Synchronisation-Jump-Width [1..4]

tseg1: CAN-Time-Segment-1 [1..16]

tseg2: CAN-Time-Segment-2 [1..8]

sam: CAN-Sample-Mode 1:3Sample

f: crystal frequency is 16 MHz

The Prescaler will be conformed automatically.

Here are some examples:

Presc sjw tseg1 tseg2 sam

1 MBaud 1 1 4 3 0

500 kBaud 1 1 8 7 0

100 kBaud 4 4 12 8 1

10 kBaud 32 4 16 8 1

23


2.3.3 ncdSetChannelParamsC200 Syntax : Vstatus ncdSetChannelParamsC200 ( VportHandle portHandle,

Vaccess accessMask,

unsigned char btr0,

unsigned char btr1)

Parameters :

Name Description

btr0 BTRO value for a C200 or 527 compatible controller.

btr1 BTR1 value for a C200 or 527 compatible controller.

Description : ncdSetChannelParamsC200 offers C200 Basic-CAN controller settings.

2.3.4 ncdSetChannelOutput Syntax : Vstatus ncdSetChannelOutput ( VportHandle portHandle,

Vaccess accessMask,

int mode )

Parameters :

Name Description

mode mode specifies the output mode of the CAN chip. OUTPUT_MODE_SILENT = No acknowledge will be generated on receive (silent mode) OUTPUT_MODE_NORMAL = Acknowledge (normal mode)

Description : If mode is OUTPUT_MODE_SILENT the CAN chip will not generate an acknowledge when a CAN message is received. It’s not possible to send messages, but you can receive messages in the silent mode . Normal mode is the default mode. To call this function the port must have init access to the specified channels, and the channels must be deactivated.

24


2.3.5 ncdSetChannelMode Syntax : Vstatus ncdSetChannelMode ( VportHandle portHandle,

Vaccess accessMask,

int tx,

int txrq )

Parameters :

Name Description

tx A flag specifying whether the channel should generate receipts when a message is transmitted by the CAN chip. 1 = generate receipts, 0 = deactivated.

txrq A flag specifying whether the channel should generate receipts when a message is requested for transmission by the CAN chip. 1 = generate receipts, 0 = deactivated.

Description : For the CAN channels defined by accessMask this sets whether the caller will get a TX and/or a TXRQ receipt for transmitted messages. The defaults are TXRQ deacti-vated and TX activated.

2.3.6 ncdSetReceiveMode Syntax : Vstatus ncdSetReceiveMode( VportHandle Port,

unsigned char ErrorFrame,

unsigned char ChipState)

Parameters :

Name Description

Port Port Handle

ErrorFrame suppress error frames

ChipState suppress chipstate events

Description : Suppress error frames and chipstate events with „0“ und allow with „1“. Default is allow error frames and chipstate events.

25


2.3.7 ncdSetChannelTransceiver Syntax : Vstatus ncdSetChannelTransceiver ( VportHandle portHandle,

Vaccess accessMask,

int type,

int lineMode,

int resNet)

Description : This function is used to set the transceiver modes. The possible transceiver modes depend on the transceiver type connected to the CANcardXL, CANcardX or CAN-AC2-PCI. The port must have init access to the channels. Parameters for following CANcabs:

2.3.7.1 Lowspeed Lowspeed (252/1053/1054)

type TRANSCEIVER_TYPE_252

VCAN_TRANSCEIVER_LINEMODE_SLEEP Put CANcab into sleep mode

lineMode

VCAN_TRANSCEIVER_LINEMODE_NORMAL Enable normal opera-tion

resNet Must be TRANSCEIVER_RESNET_NA

You can detect a transceiver error by checking the MSGFLAG_NERR in the event returned by ncdReceive or ncdReceive1.

2.3.7.2 Single Wire rrr

Single Wire (5790c and 5790opto c)

type TRANSCEIVER_TYPE_SWC

TRANSCEIVER_LINEMODE_SWC_SLEEP Switch to sleep mode

TRANSCEIVER_LINEMODE_SWC_NORMAL Switch to normal opera-tion

TRANSCEIVER_LINEMODE_SWC_FAST Switch transceiver to fast mode

lineMode

TRANSCEIVER_LINEMODE_SWC_WAKEUP Enable sending of high voltage messages (used to wakeup sleep-ing nodes on the bus)

26


Single Wire (5790c and 5790opto c)


Each message will be send as high voltage message, if you set TRANSCEIVER_LINEMODE_SWC_WAKEUP with ncdSetChannelTransceiver(...). If you want to send one high voltage message for single wire, use the flag MSGFLAG_WAKEUP for ncdTransmit(...). To flush the queue and transmit a high voltage message make a „or“ combination between the MSGFLAG_WAKEUP and MSGFLAG_OVERRUN. event.tagData.msg.flags = MSGFLAG_WAKEUP;

vErr = ncdTransmit(gPortHandle, chanMask, &event); You can detect high voltage messages by checking the MSGFLAG_WAKEUP in the event returned by ncdReceive or ncdReceive1.

2.3.7.3 CANcab EVA The CANcab EVA has two Output Lines which can be switched. rrr

CANcab EVA

type TRANSCEIVER_TYPE_EVA

VCAN_TRANSCEIVER_LINEMODE_EVA_00 Both Output Lines Low

VCAN_TRANSCEIVER_LINEMODE_EVA_01 Output 1 is High and Output 2 is Low

VCAN_TRANSCEIVER_LINEMODE_EVA_10 Output 1 is Low and Output 2 is High

lineMode

VCAN_TRANSCEIVER_LINEMODE_EVA_11 Both Output Lines High


2.3.7.4 CANcab 10011 (Truck & Trailer) The CANcab 10011 can operate in two wire mode (normal operation) or in one wire mode on CAN High or CAN Low.

CANcab 10011

type TRANSCEIVER_TYPE_TT

VCAN_TRANSCEIVER_LINEMODE_NORMAL Normal operation on CAN High and CAN Low

Line Mode

VCAN_TRANSCEIVER_LINEMODE_TT_CAN_H One Wire Mode onCAN High

27


CANcab 10011

VCAN_TRANSCEIVER_LINEMODE_TT_CAN_L One Wire Mode on CAN Low

VCAN_TRANSCEIVER_LINEMODE_EVA_11 Both Output Lines High


2.3.7.5 Highspeed Highspeed (1041 and 1041opto)

type TRANSCEIVER_TYPE_1041

VCAN_TRANSCEIVER_LINEMODE_SLEEP Put CANcab into sleep mode

lineMode

VCAN_TRANSCEIVER_LINEMODE_NORMAL Enable normal opera-tion


2.3.8 ncdSetNotification Syntax : Vstatus ncdSetNotification ( VportHandle portHandle,

unsigned long *handle,

int queueLevel)

Parameters :

Name Description

handle WIN32 event handle

queueLevel Queue level that triggers this event

Description : This sets up an event to notify the application if there are messages in the port‘s re-ceive queue. queueLevel specifies the number of messages that triggers the event. Note that the event is triggered only once when the queueLevel is reached. An application should read all available messages by ncdReceive or ncdReceive1 to be sure to re-enable the event. Example : h = CreateEvent(NULL, FALSE, FALSE, NULL);

28


vErr = ncdSetNotification (gPortHandle,&h, 1);

// Wait for event while (WaitForSingleObject(h,1000)==WAIT_TIMEOUT); do { vErr = ncdReceive1(gPortHandle,&pEvent); // Get the event }while (vErr == 0);

2.3.9 ncdAddAcceptanceRange Syntax : Vstatus ncdAddAcceptanceRange( VportHandle portHandle,

Vaccess accessMask,

unsigned long first_id,

unsigned long last_id);

Parameters :

Name Description

first_id first ID to pass acceptance filter.

last_id last ID to pass acceptance filter.

Description : ncdAddAcceptanceRange is only implemented for standard identifier. You can set a range for the acceptance filter several times. Different ports may have different filters for a channel. If the CAN hardware cannot implement the filter, the driver virtualises filtering. Available in driver version 3.0 or greater. Note: The default is acceptance filters closed! Example : // receive ID between 10 and 17, 22 and 33;

vErr = ncdAddAcceptanceRange (gPortHandle,gChannelMask,10,17);

vErr = ncdAddAcceptanceRange (gPortHandle,gChannelMask,22,33);

2.3.10 ncdRemoveAcceptanceRange Syntax : Vstatus ncdRemoveAcceptanceRange(VportHandle portHandle,

Vaccess accessMask,

unsigned long first_id,

unsigned long last_id);

29


Parameters :

Name Description

first_id first ID of the range to be filtered.

last_id last ID of the range to be filtered.

Description : The specified ID’s will not pass the acceptance filter. ncdRemoveAcceptanceRange is only implemented for standard identifier. You can remove a range of the accep-tance filter several times. Different ports may have different filters for a channel. If the CAN hardware cannot implement the filter, the driver virtualises filtering. Available in driver version 3.0 or greater. Note: The default is acceptance filters closed! Example : // remove range between 10 and 13, 27 and 30 .

ncdRemoveAcceptanceRange (gPortHandle , gChannelMask, 10, 13);

ncdRemoveAcceptanceRange (gPortHandle , gChannelMask, 27, 30);

2.3.11 ncdResetAcceptance Syntax : Vstatus ncdResetAcceptance( VportHandle portHandle,

Vaccess accessMask,

int extended);

Parameters :

Name Description

extended reset for extended(=1) or standard (=0) identifier filtering.

Description : The filter is completely closed. No ID will pass the filter. ncdResetAcceptance is only implemented for standard identifier. Different ports may have different filters for a channel. If the CAN hardware cannot implement the filter, the driver virtualises filtering. Available in driver version 3.0 or greater. Note: The default is acceptance filters closed! Example : // close the filter completly.

ncdResetAcceptance (gPortHandle , gChannelMask,0);

30


2.3.12 ncdSetChannelAcceptance Syntax : Vstatus ncdSetChannelAcceptance ( VportHandle portHandle,

Vaccess accessMask,

VsetAcceptance *filter)

Parameters :

Name Description

filter Pointer to an acceptance filter.

The structure for the acceptance filter has the following outline. struct _Vset_acceptance {

unsigned long code; unsigned long mask;

};

Name Description

code The acceptance code for id filtering

mask The acceptance mask for id filtering bit = 1 means relevant

To distinguish whether the filter is for standard or extended identifiers. For extended identifiers the MSB of the code and mask are set. Description : Different ports may have different filters for a channel. If the CAN hardware cannot implement the filter, the driver virtualises filtering. Accept if ((id ^ code) & mask) == 0).

Note: The default is acceptance filters closed!Example :

standard (11bit) extended (29 bit)

Open all: acc.mask

acc.code

0x000

0x000

0x80000000

0x80000000

Open for Id 1 (0x001): acc.mask

acc.code

0x7FF

0x001

0x9FFFFFFF

0x80000001

31


Close: acc.mask acc.code

0xFFF

0xFFF

0xFFFFFFFF

0xFFFFFFFF

vErr = ncdSetChannelAcceptance(gPortHandle,gChannelMask,&acc);

if (vErr) __leave;

To set the acceptance filter for several Id’s use following formula: code = id(1)

mask = 0XFFF

loop over id(1) ... id(n)

mask = (!(id(n)&mask)xor(code&mask))and mask

Example for Id=4 and Id=6:

binary general rule

Id=6 (0x006)

Id=4 (0x004)

0110

0100

-> mask

-> code 1101

0110

mask:

Compare the Id’s at each bit position. If they are different, mask at this bit posi-tion must be “0”

code:

Take one Id (it doesn’t matter which one)

2.3.13 ncdActivateChannel Syntax : Vstatus ncdActivateChannel ( VportHandle portHandle,

Vaccess accessMask )

Description : The selected channels go ‚on the bus‘. From now on the user can transmit and re-ceive messages on the CAN bus. The CAN controller channel is activated if this has not already been done.

32


2.3.14 ncdSetTimerRate Syntax : Vstatus ncdSetTimerRate ( VportHandle portHandle,

unsigned long timerRate )

Parameters :

Name Description

timerRate Value specifying the interval for cyclic timer events generated by a port. If 0 is passed no cyclic timer events will be generated.

Description : This call sets up the rate for the port‘s cyclic timer events. The resolution is 10 µs. The minimum and maximum timerRate values depend on the hardware. If a value is outside of the allowable range the limit value is used. Note:Timer events will only be generated if no other event occurred during the timer interval. The timer events are generated on the card and the acceptance filter is real-ized on PC. This may lead to the situation, that an application will receive no can messages and no timer events, if the can messages are blocked by the acceptance filter.

2.3.15 ncdResetClock Syntax : Vstatus ncdResetClock ( VportHandle portHandle )

Description : Clocks of all channels connected to the port are reset.

33


2.4 General

2.4.1 ncdReceive1 Syntax : Vstatus ncdReceive1 ( VportHandle portHandle,

Vevent **ppEvent)

Parameters :

Name Description

ppEvent Pointer to pointer to received event

Return value : VERR_QUEUE_IS_EMPTY No event is available Description : The driver is asked to retrieve a single event from the application‘s receive queue. This function is optimised for speed. It returns a pointer to the received event. Lifetime of the data is until the next call of ncdReceive1. It returns VERR_QUEUE_IS_EMPTY and *ppEvent=NULL if no event is available.

2.4.2 ncdTransmit Syntax : Vstatus ncdTransmit ( VportHandle portHandle,

Vaccess accessMask,

Vevent *pEvent )

Parameters :

Name Description

pEvent Pointer to a driver event that is to be transmitted on every se-lected channel.

Return value : VERR_QUEUE_IS_FULL A channel‘s transmit queue is full.

34


Description : A CAN message will be put to the designated channels to be transmitted. Example : event.tag = V_TRANSMIT_MSG;

event.tagData.msg.id = 100;

event.tagData.msg.flags = 0;

event.tagData.msg.data[0] = 1;








event.tagData.msg.dlc = 8;

vErr = ncdTransmit(gPortHandle, chanMask, &event);

2.4.3 ncdReceive Syntax :

Vstatus ncdReceive ( VportHandle portHandle,

int receiveMode,

unsigned int waitHandle,

int* pEventCount,

Vevent *pEventList )

Parameters :

Name Description

receiveMode Specifies the calling mode for this function. VCAN_POLL The function reads the port’s receive queue

and returns immediately. pEventCount indi-cates whether events were read or not.

VCAN_NOTIFY VCAN_NOTIFY is obsolete and not supported in all new driver versions (>=3.0). Please use ncdSetNotification(...).

waitHandle Handle to the Win32 event when using VCAN_NOTIFY (<3.0) .

pEventCount Pointer to a long, specifying how many events should be read. On return the value contains the number of read events.

35


Name Description

pEventList Pointer to a user buffer. The buffer must be large enough for *pEventCount events.

Description : For a successful call the channels must be initialized and activated. The function reads the port‘s receive queue. When the function uses VCAN_POLL, a maximum of *pEventCount events are read from the queue and passed to the user buffer (pEventList). When there are fewer events in the queue, the function reads them and stores the number at *pEventCount. If the queue is empty ‘0’ is written to *pEventCount. Example : count = 4;

vErr = ncdReceive(gPortHandle,VCAN_POLL,h,&count,&rxEv[0]);

if (vErr==VSUCCESS) {

if (count!=0) {

for (i=0; i<count; i++)

printf(“%s\n”,ncdGetEventString(&rxEv[i]));

}

}

2.4.4 ncdGetEventString Syntax : char * ncdGetEventString ( Vevent *ev )

Parameters :

Name Description

ev Pointer to Vevent

Return value : Text string Description : Returns a textual description of the given event( more details see chapter 4.Events). // RX_MSG=receive a message, c=channel( ex. virtual channel1),

// t=timestamp=1936284628, id=identifier 1, l=dlc= 8,

// data=0102030405060708, tid=internal use

RX_MSG c=1, t=1936284628, id=0001, l=8, 0102030405060708 tid=0

36


2.4.5 ncdRequestChipState Syntax : Vstatus ncdRequestChipState ( VportHandle portHandle,


Description : This function requests a CAN controller chipstate for all selected channels. For each channel, a V_CHIPSTATE event can be received by calling ncdReceive().

2.4.6 ncdGetState Syntax : Vstatus ncdGetState ( VportHandle portHandle )

Description : The last error code of the port is returned.

2.4.7 ncdFlushReceiveQueue Syntax : Vstatus ncdFlushReceiveQueue ( VportHandle portHandle )

Description : The function flushes the port‘s receive queue.

2.4.8 ncdFlushTransmitQueue Syntax : Vstatus ncdFlushTransmitQueue ( VportHandle portHandle,


Description : The function flushes the transmit queues of the selected channels.

2.4.9 ncdGetReceiveQueueLevel Syntax : Vstatus ncdGetReceiveQueueLevel ( VportHandle portHandle,

int* level )

37


Parameters :

Name Description

level Pointer to a long where the actual count of events in the receive queue is returned.

Description The function returns the count of events in the port’s receive queue.

2.4.10 ncdGetErrorString Syntax : char * ncdGetErrorString( Vstatus err )

Parameters :

Name Description

err Error code (chapter 3)

Return value : Text string Description : Returns a textual description of the given error code.

2.4.11 ncdGetChannelVersion Vstatus ncdGetChannelVersion( unsigned long ChannelIndex,

unsigned long* FwVersion,

unsigned long* HwVersion,

unsigned long* SerialNumber)

Parameters :

Name Description

ChannelIndex Global channel index (0,1,...)

FwVersion Firmware Version (1376293dez=1.50.025hex; Version 1.5)

HwVersion Hardware Version (256dez=1.00hex; Version 1.0)

SerialNumber Hardware Serial Number (0505200)

Description : Get version information if available.

38


2.5 Deinitialisation

2.5.1 ncdDeactivateChannel Syntax : Vstatus ncdDeactivateChannel ( VportHandle portHandle,


Description : The selected channels go ‚off the bus‘. The CAN controller channel is deactivated if there is no further port which activated the channel.

2.5.2 ncdClosePort Syntax : Vstatus ncdClosePort ( VportHandle portHandle )

Return value : VSUCCESS is always returned, because even on an error it is not safe to perform further port or channel accesses. Description : The port is closed and the channels are deactivated.

2.5.3 ncdCloseDriver Syntax : Vstatus ncdCloseDriver ( void )

Description : The driver is closed. This is used to unload the driver if no other application is using it.

39


3 Error Codes

3.1 Overview In this section all error codes are described which may be returned by a driver call.

3.1.1 VSUCCESS Code : 0 Description : The driver call was successful.

3.1.2 VPENDING Code : 1 Description : Can only occur at ncdReceive() called with VCAN_NOTIFY. There were no events in the receive queue. The driver will notify the user of a WIN32 event if events arrive.

3.1.3 VERR_QUEUE_IS_EMPTY Code : 10 Description : The receive queue of the port is empty. The user can proceed normally.

3.1.4 VERR_QUEUE_IS_FULL Code : 11 Description : The transmit queue of a channel is full. The transmit event will be lost.

3.1.5 VERR_TX_NOT_POSSIBLE Code : 12 Description : The hardware is busy and not able to transmit an event at once.

3.1.6 VERR_WRONG_PARAMETER Code : 101 Description : At least one parameter passed to the driver was wrong or invalid.

3.1.7 VERR_INVALID_CHAN_INDEX Code : 111 Description : The driver attempted to access a channel with an invalid index.

3.1.8 VERR_INVALID_ACCESS Code : 112 Description : The user made a call to a port specifying channel(s) for which he had not declared access at opening of the port.

40


3.1.9 VERR_PORT_IS_OFFLINE Code : 113 Description : The user called a port function whose execution must be online, but the port is offline.

3.1.10 VERR_CHAN_IS_ONLINE Code : 116 Description : The user called a function whose desired channels must be offline, but at least one channel is online.

3.1.11 VERR_NOT_IMPLEMENTED Code : 117 Description : The user called a function which isn’t implemented.

3.1.12 VERR_INVALID_PORT Code : 118 Description : The driver attempted to access a port by an invalid pointer or index.

3.1.13 VERR_CMD_TIMEOUT Code : 121 Description : The timeout condition occurred while waiting for the response event of a command.

3.1.14 VERR_HW_NOT_PRESENT Code : 129 Description : The hardware is not present (or could not be found) at a channel. This may occur with removable hardware or faulty hardware.

3.1.15 VERR_NOTIFY_ALREADY_ACTIVE Code : 131 Description : A ncdReceive() call with notify option is already active at the called port. This second receive call is ignored.

3.1.16 VERR_CANNOT_OPEN_DRIVER Code : 201 Description : The attempt to load or open the driver failed. That might be because the driver file cannot be found, the driver is already loaded, or parts of a previously unloaded driver are still in the system.

3.1.17 VERROR Code : 255 Description : An unspecified error occurred.

41


4 Events

4.1 Overview Events are the data structures passed from the driver to the application. Events usu-ally contain CAN messages, errorframes, chipstates, etc. A C struct for the event is defined in VCAND.H. The structure of a driver event has the following outline.

Data type Name Description

unsigned char tag Specifies the type of event. See below.

unsigned char chanIndex Contains the channel index on which the event was received (if applicable).

unsigned char transId Internal use only. The application must not use the transId, be-cause it will be overwritten!!!

unsigned char portHandle Internal use only. The application must not use the portHandle, because it will be overwritten!!!

unsigned long timeStamp This field contains the time when the event oc-curred. The resolution is 10/usec, and the timer may be reset by ncdResetClock.

union tagData The information data of the event.

Possible values for tag:

Event type Description

V_RECEIVE_MSG CAN message received on the CAN bus.

V_TRANSMIT_MSG CAN message to transmit on the CAN bus.

V_CHIP_STATE Current state of the CAN bus controller.

V_TIMER A timer event generated by the hardware.

V_TRANSCEIVER An event from the CANcab transceiver.

There are different structures for the events distinguished by the tag. The structures are placed in the tagData union and are described in the following chapters.

42


4.1.1 V_RECEIVE_MESSAGE - V_TRANSMIT_MESSAGE These events specify messages transmitted or received on the CAN bus.

Name Description

id The CAN identifier of the message. If the MSB of the id is set, it is an ex-tended identifier.

flags The flags notify some special messages or states. To set multiple flags they are OR‘d.

MSGFLAG_ERROR_FRAME The event is an error frame MSGFLAG_OVERRUN An overrun occurred in the CAN controller MSGFLAG_REMOTE_FRAME The event is a remote frame MSGFLAG_TX Notification of successful transmission

of a message MSGFLAG_TXRQ Notification of request for transmission

of a message MSGFLAG_NERR The transceiver reported a error while

the message was received. (only possi-ble on Lowspeed CANcabs)

MSGFLAG_WAKEUP High voltage message for Single Wire. To flush the queue and transmit a high voltage message make a „or“ combina-tion between the MSGFLAG_WAKEUP and MSGFLAG_OVERRUN.

dlc The length of a message

data[8] Array containing the data

43


4.1.2 V_CHIP_STATE The state of the selected channels is requested by ncdRequestChipState. The reply will be received as an event (V_CHIP_STATE). For each channel, an event can be received by calling ncdReceive().

Name Description

busStatus Returns the state of the CAN controller. The following codes are possible:

BUSSTAT_BUSOFF BUSSTAT_ERROR_PASSIVE BUSSTAT_ERROR_WARNING BUSSTAT_ERROR_ACTIVE

The bus is offline One of the error counters has reached the error level One of the error counters has reached the warning level The bus is online

txErrorCounter Error counter for the transmit section of the CAN controller

rxErrorCounter Error counter for the receive section of the CAN controller. (tx and rx counter -> only CANcardX)

4.1.3 V_TIMER A timer event can be generated cyclically by the driver to keep the application alive.

44


5 Programming Examples

5.1 Overview Several programming examples are available.

CANvbas - utilizes all important functions from the driver library. - Visual Basic project. - with vbAddAcceptanceRange(...), vbAddAcceptanceRange(...),

vbResetAcceptance(...)

CANlogDyn - log messages from the CAN bus - Windows program written with Visual C++ 6.0 - load vcand32.dll dynamically with loadlib.cpp - with ncdGetApplConfig(...) and ncdSetApplConfig(...)

CANlog - log messages from the CAN bus - Borland 5.02 project - with ncdReceive1(...)

CANgen - generate messages on the CAN bus. - MS Visual 6.0 project - with ncdTransmit(...) - with thread for transmit the messages

CANdemo - utilizes different functions from the driver library - with ncdGetDriverConfig(...)

CANcount - count messages from the CAN bus - with ncdGetApplConfig(...) and ncdSetApplConfig(...)

CANdelph - trace messages from the CAN bus - Delphi project 2.0.

CANlatw - get the time delay of a sending message between TxRq and Tx - Borland C++ Builder 3.0 project

CANtrace - trace messages from the CAN bus

LabView - three samples (OpenCAN.vi, CloseCAN.vi, Send&read.vi) - LabView project 5.1 - library VLabLib.llb with all functions

45


5.1.1 CANvbas Function: You can use the canvbas sample to generate and log messages to/from the CAN bus. This sample utilizes all important functions from the driver library. In contrast to chapter 5.1.5 CANdemo, this sample is written in Visual Basic with similar functions.

46


5.1.2 CANlogDyn Function: You can use the CANlogDyn sample to log messages from the CAN bus on screen. In contrast to chapter 5.1.3 CANlog, this sample is written with Visual C++ 6.0.

5.1.3 CANlog Function: You can use the canlog sample to log messages from the CAN bus on screen. Options:

CANLOG -bx : Set bitrate to x (default = 500000)

-v : Use virtual channel 1 (default CANcardX channel 1

-chx : Set channel (default x = 1)

-pci : Use CAN-AC2-PCI

-cancardxl : Use CANcardXL

-h : Help

-ESC : Exit

47


5.1.4 CANgen Function: You can use the cangen sample to generate messages on the CAN bus. Options:

CANGEN -ix : Set identifier to x (default = 100)

-bx : Set bitrate to x (default = 500000)

-cx : Set transmission cycle to x ms (default = 1000)

-nx : Set transmission burst size to x msgs (default = 1)

-v : Use virtual channel 1 (default CANcardX channel 2)

-l : Log events to screen

-chx : Set channel (default x = 2)



-h : Help

-ESC : Exit

The fastest possible transmission cycle is 1ms.

5.1.5 CANdemo Function: You can use the candemo sample to generate and log messages to/from the CAN bus. This sample utilizes all important functions from the driver library. CANdemo is running with a baudrate of 500 kBaud by default. You can change the baudrate by calling CANdemo with a baudrate, e.g. „CANdemo 100000“, so CANdemo is in this case running with a baudrate of 100 kBaud. While the program is running you can change the options by pressing the appropri-ate key. Options:

CANDEMO -t : Transmit a message

-b : Transmit a message burst

-m : Transmit a remote message

-g : Request chipstate

-s : Start/Stop

-r : Reset clock

48


-c/C/1-9 : Select channel

-i/I : Select transmit id

-x : Select extended id

-o : Toggle output mode

-a : Toggle timer

-v : Toggle logging to screen

-h : Help

-ESC : Exit

5.1.6 CANcount Function: You can use the cancount sample to count messages from the CAN bus on screen. Options:

CANCOUNT -bx : Set bitrate to x (default = 500000)

-v : Use a virtual channel (default CANcardX)

-l : Log messages on screen

-2 : Use channel 2 (default channel 1)



-h : Help

-ESC : Exit

49


5.1.7 CANtrace Function: You can use the cantrace sample to trace messages from the CAN bus on screen. Options:

CANTRACE -bx : Set bitrate to x (default = 500000)

-v : Use a virtual channel (default CANcardX)

-2 : Use channel 2 (default channel 1)



-h : Help

-ESC : Exit

5.1.8 CANsing Function: You can use the cansing sample to generate your own library that provides some comp ability with cancard.dll from Softing. Because of the large number of different Versions of the Softing API this sample is only tested with the API CANcard V2.04. We have implemented the queue-oriented (or FIFO-oriented) functions only; these seem to be the most commonly used ones. We are providing this software in order to facilitate the porting of your applications to use CANcardXL, CANcardX and CAN-AC2-PCI. We do not claim 100% comp ability with current or future software from Softing. This sample was implemented by read-ing Softing‘s manuals and undocumented features have probably remained unim-plemented. Example: Generate your own library with cansing.c and vcand32.lib (Borland ) or vcandm32.lib (Microsoft). Result: new cansing.lib Link the new import library to your current software project and include „CANsing.h“ instead of „cancard.h“.

50


5.1.9 CANlatw Function: You can use the CANlatw sample to get the time delay of a sending message be-tween TxRq (message is loaded into CAN controller) and Tx (message is sent to CAN bus). This delay depends on baudrate, length of the CAN message and time lost due to arbitration processes. CANlatw display the evaluated values online as histogram. CANlatw uses the following defaults:

Baudrate: 500 kBaud Identifier: 100 Cycle Time: 1s Messages per Cycle: 1

You can change these defaults with the following command line options: -mx :set messages per cycle to x

-ix :set identifier to x

-cx :set cycle time to x (seconds)

-bx :set baudrate to x (both, baud and kBaud can be used)

CANlatw is built with the "Borland C++ Builder", Version 3.0.

5.1.10 CANtracD Function: You can use the CANtracD sample to trace messages from the CAN bus on screen. In contrast to chapter 5.1.7 CANtrace this sample is written with Delphi 7.0and you exit by pressing “Crtl + C”.

5.1.11 LabView VLabLib.llb utilizes all important functions from the driver library. VLabSample.llb includes three samples:

• OpenCAN.vi : open CAN

• CloseCAN.vi : close CAN

• Send&read.vi : send and read messages from the CAN bus The library and samples are generated with LabView 5.1.

51


5.1.12 Load vcand32.dll dynamically If you want to load the vcand32.dll dynamically, please insert the file loadlib.cpp in your project. The vcand.h supports loading of vcand32.dll dynamically. Sample 5.1.2 CANlogDyn shows how to load it. Important is, that it is not necessary to change your source code, because ncdOpenDriver() loads the dll and ncdCloseDriver() unloads the dll.

5.1.13 General To compile a new exe file you will need the import library, header file and the dll. VCAND32.DLL Driver DLL for Vector CANcardX (Borland and Microsoft) VCAND.H Header for CANGEN, CANLOG and CANDEMO VCAND32.LIB IMPORT-LIBRARY for Vector CANcardX (Borland) VCANDM32.LIB IMPORT-LIBRARY for Vector CANcardX (Microsoft) VCAND32.DEF Def file for Borland VCANDM32.DEF Def file for Microsoft VBCANIF.DLL Driver DLL for Vector CANcardX (Visual Basic) CANlibD.pas Unit für Delphi32 VLabLib.llb Library for LabView The files are generated with Borland 5.02 and Microsoft VC++ 6.0. The module definition-files are created with impdef.exe from Borland. If you are working with another compiler version you should use module definition file vcand32.def or vcandm32.def to create a new import library with lib.exe (using VC++) or implib.exe (using Borland). Example :

1. lib /def:vcandm32.def 2. Result: new vcandm32.lib 3. Link the new import library to your project

To run the sample programs on Windows98/ME/2000/XP or NT you will need a Vec-tor CAN hardware like CANcardXL with the appropriate drivers.

candriver lib docu

Documents