PCAN-Light Documentation

, 16:29 Uhr

PCAN-Light Documentation

PCAN-Dongle

PCAN-Dongle Pro

PCAN-ISA

PCAN-PC/104

PCAN-PCI

PCAN-PCI Express

PCAN-PC/104-Plus

PCAN-USB

PCAN-PC Card

Introduction

Reference

Additional Information

Last Update: August 19, 2008

Send feedback to this documentation.


Introduction

Introduction

Welcome to the documentation to PCAN-Light.

The PCAN system of the company PEAK-System Technik GmbH consists of a collection of Windows Device Drivers, which allow the real-time connection of Windows applications to all CAN busses physically connected to a PC.

PCAN-Light is a simple programming interface to the PCAN system. Via several Interface DLLs it is possible to connect own applications to the Device drivers and the PCAN hardware, to communicate with the CAN busses.

In this Chapter

PCAN-Light Basics

This section contains an introduction to PCAN-Light.

Basics to PCAN-Light applications

Information and process flow with a PCAN-Light client.

Overview PCAN-Light

Information to CAN Hardware, PCAN-Light version, and API functions.

License Regulations

License regulations to this software.

Contact Information

Contact information - PEAK-System Technik GmbH.


PCAN-Light Basics

PCAN-Light is the small API variant to PCAN. It makes a fast and comprehensive working possible with the CAN bus system. The connection between the application program and the PCAN hardware is made by the appropriate device driver. The following illustration gives a short overview.

Following rules apply to PCAN-Light client (application software) and PCAN hardware:

  • A client is in each case assigned to a hardware at each time. A connection with one client to different hardware types is not possible at the same time.

  • If a multi-channel hardware is present, each channel is treated like a separate hardware.

  • If a Client sends a message, it will be transferred to every other Client and to the external CAN bus via the hardware.

  • If a PCAN hardware is connected to a client, then no further client can access the same hardware.

  • If a message is received over the hardware, it is received by every client. Every client receives only those messages, which pass its message (acceptance) filter.

  • Every PCAN-Light client has a transmission queue, where CAN messages to be transmitted are waiting until the individual transmission time. At occurrence of the transmission time they are written into the transmission queue of the PCAN hardware.

  • Every hardware contains a transmission queue for buffering CAN messages to be transmitted.

Working serial and parallel with a multi-channel PCAN hardware.

There are two different ways to work with more than one channel of the multi-channel PCAN hardware. Parallel working means to use different clients for each channel of the multi-channel PCAN hardware. Serial working means two switch between two different channels in a serial time. The switching procedure is to close the actual channel, initialize the new channel and possible make a filter adjustment.

See also

PCAN Basics | PCAN-Light Client Basics


Basics of PCAN-Light applications

The following figure illustrates the schematic process flow of an PCAN-Light application software:

Schematic process flow

  1. Start
    There are two different ways to connect a PCAN-Light client with a PCAN hardware:

    1. Start with Non-Plug-and-Play hardware:
      Call the Init function for Non-Plug-and-Play hardware.

    2. Start with Plug-and-Play hardware:
      Call the Init function for Plug-and-Play hardware.

  2. Operate
    After a successful start, the message filter could be adapted at your own conception. Furthermore CAN messages can be read and written. The driver of a type of hardware defined the range of functions and is structured in basic and additional functions.

  3. Finish
    Call the Close function. This process disconnect the application software from PCAN hardware.

Process flow of a PCAN application software with multi-channel PCAN hardware

Each channel of a multichannel PCAN hardware has its own API function library (DLL). Every library uses a different name for the same function. The following figure represent a process flow of a multi-channel PCAN hardware.


Drivers and API functions

PCAN-Light is a collection of drivers. To communicate with the drivers, for every driver there one or more interface DLLs provided, which contain the API functions.

Overview of the current PCAN hardware, device drivers, and Interface DLLs
Hardware | Plug-and-Play Hardware | Driver | Interface DLL
PCAN-Dongle | No | Pcan_dng.sys | Pcan_dng.dll
PCAN-Dongle Pro | No | Pcan_dnp.sys | Pcan_dnp.dll
PCAN-ISA | No | Pcan_isa.sys | Pcan_isa.dll Pcan_2isa.dll (2nd channel)
PCAN-PC/104 | No | Pcan_isa.sys | Pcan_isa.dll Pcan_2isa.dll (2nd channel)
PCAN-PCI | Yes | Pcan_pci.sys | Pcan_pci.dll Pcan_2pci.dll (2nd channel)
PCAN-PCI Express | Yes | Pcan_pci.sys | Pcan_pci.dll Pcan_2pci.dll (2nd channel)
PCAN-PC/104-Plus | Yes | Pcan_pci.sys | Pcan_pci.dll Pcan_2pci.dll (2nd channel)
PCAN-USB | Yes | Pcan_usb.sys | Pcan_usb.dll Pcan_2usb.dll (2nd channel)
PCAN-PC Card | Yes | Pcan_pcc.sys | Pcan_pcc.dll Pcan_2pcc.dll (2nd channel)
Overview of the basic API functions

API Functions

Init Non-Plug-and-Play hardware,

Init Plug-and-Play hardware,

Close,

Write,

Read,

Status,

VersionInfo,

MsgFilter,

ResetFilter,

ResetClient

Apart from the basic functions, there can be additional functions for different hardware types. Link to the detailed overview.


License

PCAN-Light Documentation

Introduction

License Regulations

Namings for products in this manual, that are registered trademarks, are not separately marked. Therefore the missing of the ® sign does not implicate, that the naming is a free trade name. Furthermore the used names do not indicate patent rights or anything similar. PEAK-System Technik GmbH makes no representation or warranties with respect to the use of enclosed software or the contents of this manual, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, PEAK-System Technik GmbH reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.

Copyright © 2000-2008 PEAK-System Technik GmbH

All rights reserved.

No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of PEAK-System Technik GmbH.

See also

Contact Information


Contact Information

This software is a product of:

PEAK-System Technik GmbH

Otto-Röhm-Str. 69

64293 Darmstadt, Germany

Info: | info@peak-system.com
Support: | support@peak-system.com
Web: | www.peak-system.com


Reference

Reference

This section contains information about the functions, structures, Baud rate codes, and error codes of the PCAN-Light API.

Functions

Lists the PCAN-Light functions.

Structures

Lists the defined structures.

Baud Rate Codes

Lists the predefined Baud rates.

Error Codes

Lists Error codes returned by the PCAN-Light functions.


API Functions Overview

The PCAN-Light API provides the following functions for different programming languages:

Basic functions valid for all hardware types
Function | Description
Init Non-Plug-and-Play hardware, Init Plug-and-Play hardware | Initializes Non-Plug-and-Play hardware, sets the Baud rate.
Close | Closes a previously initialized PCAN hardware.
Write | Transmits a CAN message.
Read | Reads a CAN message from the receive queue.
Status | Gets the current status of a PCAN hardware.
VersionInfo | Reads information about driver, driver version, and copyright information from the driver.
ResetClient | Resets the receive and transmit queues of the application.
MsgFilter | Configures the reception filter.
ResetFilter | Closes the reception filter. No more CAN messages will be received.
Additional functions for PCAN-USB
Function | Description
SetUSBDeviceNr | Sets the USB device number to a specified value.
SetUSB2DeviceNr | Sets the USB device number of a second PCAN-USB adapter to a specified value.
GetUSBDeviceNr | Fetches the device number of the USB hardware.
GetUSB2DeviceNr | Fetches the device number of a second PCAN-USB adapter.
Notice:

Each channel of a multi-channel hardware has its own function library. Every library uses a different name for the same function.

Example:

Dual-channel PCAN-PCI card, function "CAN_Write":

Used libraries:

  • Library for the first channel: pcan_pci.dll

  • Library for the second channel: pcan_2pci.dll

Function name in Visual Basic 6, Borland Delphi, and C++:

  • Function name for the first channel: CAN_Write

  • Function name for the second channel: CAN2_Write

Function name in C#, Visual Basic .NET, and C++ CLR:

  • Function name for the first channel: PCAN_PCI.Write

  • Function name for the second channel: PCAN_2PCI.Write


Close Function

Closes a previously initialized PCAN hardware.

Syntax

Visual Basic 6

Declare Function CAN_Close Lib "HWTypDLL" () As Long

Delphi

function CAN_Close(): Longword; stdcall;

C / C++

DWORD __stdcall CAN_Close();

C#

public static extern uint Close();

Visual Basic .NET

Public Shared Function Close() As Integer

End Function

C++ CLR

static unsigned int Close();

Return values

CAN_ERR_OK, CAN_ERR_NOVXD


Init Function (Non-Plug-and-Play hardware)

Initializes a Non-Plug-and-Play hardware.

Syntax

Visual Basic 6

Declare Function CAN_Init Lib "HWTypDLL" ( _

ByVal wBTR0BTR1 As Integer, _

ByVal CANMsgType As Long, _

ByVal CANHwType As Long, _

ByVal IO_Port As Long, _

ByVal Interrupt As Integer _

) As Long

Delphi

function CAN_Init(

wBTR0BTR1: Word;

CANMsgType: Integer;

CANHwType: Integer;

IO_Port: Longword;

Interrupt: Word

): Longword; stdcall;

C / C++

DWORD __stdcall CAN_Init(

WORD wBTR0BTR1,

int CANMsgType,

int CANHwType,

DWORD IO_Port,

WORD Interrupt

);

C#

public static extern uint Init(

ushort wBTR0BTR1,

int CANMsgType,

int CANHwType,

uint IO_Port,

ushort Interrupt

);

Visual Basic .NET

Public Shared Function Init( _

ByVal wBTR0BTR1 As Short, _

ByVal CANMsgType As Integer, _

ByVal CANHwType As Integer, _

ByVal IO_Port As Integer, _

ByVal Interrupt As Short) As Integer

End Function

C++ CLR

static unsigned int Init(

unsigned short wBTR0BTR1,

int CANMsgType,

int CANHwType,

unsigned int IO_Port,

unsigned short Interrupt

);

Parameters

BTR0BTR1

[In] Baud rate initialisation. A valid Baud rate code can be taken from the Baud rates table.

CANMsgType

Defines the size of the CAN ID, 11 or 29 bits.

Identifier | Value | Description
CAN_INIT_TYPE_ST | 0 | 11 Bit-ID operation - Standard frame
CAN_INIT_TYPE_EX | 1 | 29 Bit ID operation - Extended frame

CANHwType

[In] Type of hardware and operation mode.

The following table contains the available hardware types:

Hardware and Mode | Identifer | Value | Description
ISA | HW_ISA | 1 | PCAN-ISA, PCAN-PC/104
Dongle | HW_DONGLE | 2 | All PCAN-Dongle hardware containing a 82C200
Dongle EPP | HW_DONGLE_EPP | 3 | All PCAN-Dongle hardware containing a 82C200, EPP mode
Dongle SJA | HW_DONGLE_SJA | 5 | All PCAN-Dongle hardware containing a SJA1000
Dongle SJA EPP | HW_DONGLE_SJA_EPP | 6 | All PCAN-Dongle hardware containing a SJA1000, EPP mode
Dongle-Pro | HW_DONGLE_PRO | 7 | PCAN-Dongle Pro
Dongle-Pro EPP | HW_DONGLE_PRO_EPP | 8 | PCAN-Dongle Pro, EPP mode
ISA SJA | HW_ISA_SJA | 9 | PCAN-ISA or PCAN-PC/104 containing a SJA1000

IO_Port

[In] I/O address for the parallel port. The appropriate I/O address can be determined from the BIOS of the PC.

Interrupt

[In] Interrupt number of the parallel port. The appropriate interrupt value can be determined from the BIOS of the PC.

Return values

CAN_ERR_OK, CAN_ERR_ILLHW, CAN_ERR_NOVXD, CAN_ERR_REGTEST, CAN_ERR_RESOURCE

See also

Close Function


Init Function (Plug-and-Play hardware)

Initializes a Plug-and-Play hardware.

Syntax

Visual Basic 6

Declare Function CAN_Init Lib "HWTypDLL" ( _

ByVal wBTR0BTR1 As Integer, _

ByVal CANMsgType As Long _

) As Long

Delphi

function CAN_Init(

wBTR0BTR1: Word;

CANMsgType: Integer

): Longword; stdcall;

C / C++

DWORD __stdcall CAN_Init(

WORD wBTR0BTR1,

int CANMsgType

);

C#

public static extern uint Init(

ushort wBTR0BTR1,

int CANMsgType

);

Visual Basic .NET

Public Shared Function Init( _

ByVal wBTR0BTR1 As Short, _

ByVal CANMsgType As Integer) As Integer

End Function

C++ CLR

static unsigned int Init(

unsigned short wBTR0BTR1,

int CANMsgType

);

Parameters

BTR0BTR1

[In] Baud rate initialisation. Valid Baud rate codes can be taken from the Baud rates table.

CANMsgType

[In] Defines the size of the CAN ID, 11 or 29 bits.

Identifier | Value | Description
CAN_INIT_TYPE_ST | 0 | 11 Bit-ID operation - Standard frame
CAN_INIT_TYPE_EX | 1 | 29 Bit ID operation - Extended frame
Return values

CAN_ERR_OK, CAN_ERR_ILLHW, CAN_ERR_NOVXD, CAN_ERR_REGTEST, CAN_ERR_RESOURCE

See also

Close Function


MsgFilter Function

Configures the reception filter.

Syntax

Visual Basic 6

Declare Function CAN_MsgFilter Lib "HWTypDLL" ( _

ByVal FromID As Long, _

ByVal ToID As Long, _

ByVal CANMsgType As Long _

) As Long

Delphi

function CAN_MsgFilter(

FromID: Longword;

ToID: Longword;

CANMsgType: Integer

): Longword; stdcall;

C / C++

DWORD __stdcall CAN_MsgFilter(

DWORD FromID,

DWORD ToID,

int CANMsgType

);

C#

public static extern uint MsgFilter(

uint FromID,

uint ToID,

int CANMsgType

);

Visual Basic .NET

Public Shared Function MsgFilter( _

ByVal FromID As Integer, _

ByVal ToID As Integer, _

ByVal CANMsgType As Integer) As Integer

End Function

C++ CLR

static unsigned int MsgFilter(

unsigned int FromID,

unsigned int ToID,

int CANMsgType

);

Parameters

FromID

[In] The lowest CAN ID to be received.

ToID

[In] The highest CAN ID to be received.

CANMsgType

[In] Message type, Standard (11-bit identifier) or Extended (29-bit identifier), to be filtered. Must be one of the parameters MSGTYPE_STANDARD or MSGTYPE_EXTENDED.

Return values

CAN_ERR_ILLCLIENT, CAN_ERR_ILLNET,CAN_ERR_OK, CAN_ERR_NOVXD, CAN_ERR_REGTEST

Remarks

FromID must be smaller or equal to ToID.

Calling MsgFilter can only expand the message filter. If a smaller CAN ID range is required than a range that has been configured before, first call ResetFilter to close the filter completely, then call MsgFilter to configure the filter to the new CAN ID range.

To configure the message filter, the CAN controller has to enter the Reset state. This will affect other applications that communicate with the same PCAN hardware.

Examples

Filter Range and Message Type | Sample Message | Result
5C0h - 5FFh, MSGTYPE_STANDARD | 5BFh, MSGTYPE_STANDARD | Message is NOT written into the receive queue of the application.
5C0h - 5FFh, MSGTYPE_STANDARD | 5C0h, MSGTYPE_STANDARD | Message is written into the receive queue of the application.
5C0h - 5FFh, MSGTYPE_EXTENDED | 5BFh, MSGTYPE_STANDARD | Message is written into the receive queue of the application.
5C0h - 5FFh, MSGTYPE_EXTENDED | 5C0h, MSGTYPE_STANDARD | Message is written into the receive queue of the application.
5C0h - 5FFh, MSGTYPE_EXTENDED | 5BFh, MSGTYPE_EXTENDED | Message is NOT written into the receive queue of the application.
5C0h - 5FFh, MSGTYPE_EXTENDED | 5C0h, MSGTYPE_EXTENDED | Message is written into the receive queue of the application.

Note: Standard frames are using the bit positions 28 to 18 of the Acceptance Mask/Code registers in the SJA1000 CAN controller. Drivers for 82C200 CAN controllers have to shift the bits down to positions 10 to 0.


Read Function

Reads a CAN message from the receive queue.

Syntax

Visual Basic 6

Declare Function CAN_Read Lib "HWTypDLL" ( _

ByRef MsgBuff As TPCANMsg _

) As Long

Delphi

function CAN_Read(

var MsgBuff: TPCANMsg

): Longword; stdcall;

C / C++

DWORD __stdcall CAN_Read(

TPCANMsg* MsgBuff

);

C#

public static extern uint Read(

out TPCANMsg MsgBuff

);

Visual Basic .NET

Public Shared Function Read( _

ByRef MsgBuff As TPCANMsg) As Integer

End Function

C++ CLR

static unsigned int Read(

TPCANMsg %MsgBuff

);

Parameters

MsgBuff

[Out] Returns a CAN message/status message from the receive queue.

Return values

CAN_ERR_OK, CAN_ERR_NOVXD, CAN_ERR_QRCVEMPTY

Remarks

The Read function passes back the next CAN message or the next status message from the receive queue. The read message is written to 'MsgBuff'. The message type (see TPCANMsg.MSGTYPE field) of a CAN message indicates if the message is a 11-bit, 29-bit, RTR, or status message. This value should be checked every time a message has been read successfully.

If the bit MSGTYPE_STATUS is set in the TPCANMsg.MSGTYPE field, the message is a status message. The ID and LEN fields do not contain valid data. The first 4 data bytes of the message contain the Error Code. The MSB of the Error Code is in data byte 0, the LSB is in data byte 3.

Examples:

Data0 | Data1 | Data2 | Data3 | Error | Error Code | Description
00h | 00h | 00h | 02h | CAN_ERR_OVERRUN | 0002h | CAN controller has been read out too late.
00h | 00h | 00h | 04h | CAN_ERR_BUSLIGHT | 0004h | Bus error: An error counter has reached the 'Light' limit.
00h | 00h | 00h | 08h | CAN_ERR_BUSHEAVY | 0008h | Bus error: An error counter has reached the 'Heavy' limit.
00h | 00h | 00h | 10h | CAN_ERR_BUSOFF | 0010h | Bus error: CAN Controller is in 'Bus Off' state.

Note:

If a BUSOFF status message is received, the CAN controller has to be initialized again using the Init function. If that is not done, no more CAN messages can be transmitted.

See also

Write Function


ResetClient Function

PCAN-Light Documentation

Reference

Function ResetClient

Resets the receive and transmit queues of the application, without performing a reset of the CAN controller.

Syntax

Visual Basic 6

Declare Function CAN_ResetClient Lib "HWTypDLL" () As Long

Delphi

function CAN_ResetClient(): Longword; stdcall;

C / C++

DWORD __stdcall CAN_ResetClient();

C#

public static extern uint ResetClient();

Visual Basic .NET

Public Shared Function ResetClient() As Integer

End Function

C++ CLR

static unsigned int ResetClient();

Return values

CAN_ERR_ILLCLIENT ,CAN_ERR_OK, CAN_ERR_NOVXD


ResetFilter Function

PCAN-Light Documentation

Reference

Function ResetFilter

Closes the receive filter. No more CAN messages will be received.

Syntax

Visual Basic 6

Declare Function CAN_ResetFilter Lib "HWTypDLL" () As Long

Delphi

function CAN_ResetFilter(): Longword; stdcall;

C / C++

DWORD __stdcall CAN_ResetFilter();

C#

public static extern uint ResetFilter();

Visual Basic .NET

Public Shared Function ResetFilter() As Integer

End Function

C++ CLR

static unsigned int ResetFilter();

Return values

CAN_ERR_OK, CAN_ERR_NOVXD

See also

MsgFilter Function


Status Function

PCAN-Light Documentation

Reference

Function Status

Gets the current status of a PCAN hardware.

Syntax

Visual Basic 6

Declare Function CAN_Status Lib "HWTypDLL" () As Long

Delphi

function CAN_Status(): Longword; stdcall;

C / C++

DWORD __stdcall CAN_Status();

C#

public static extern uint Status();

Visual Basic .NET

Public Shared Function Status() As Integer

End Function

C++ CLR

static unsigned int Status();

Return values

CAN_ERR_OK, CAN_ERR_BUSHEAVY, CAN_ERR_BUSOFF, CAN_ERR_NOVXD, CAN_ERR_OVERRUN


VersionInfo Function

PCAN-Light Documentation

Reference

Function VersionInfo

Reads information about driver, driver version, and copyright information from the driver.

Syntax

Visual Basic 6

Declare Function CAN_VersionInfo Lib "HWTypDLL" ( _

ByVal TextBuff As String _

) As Long

Delphi

function CAN_VersionInfo(

TextBuff: PChar

): Longword; stdcall;

C / C++

DWORD __stdcall CAN_VersionInfo(

LPSTR TextBuff

);

C#

public static extern uint VersionInfo(

StringBuilder TextBuff

);

Visual Basic .NET

Public Shared Function VersionInfo( _

ByVal TextBuff As StringBuilder) As Integer

End Function

C++ CLR

static unsigned int VersionInfo(

StringBuilder^ TextBuff

);

Parameters

TextBuff

[Out] Pointer or reference to a text buffer. The returned text has a maximum length of 255 characters.

If using a PCAN-USB adapter, and using an interface DLL Pcan_usb.dll version 1.45.0.0 or later, the returned text additionally contains the Firmware version of the adapter.

Return values

CAN_ERR_OK, CAN_ERR_NOVXD


Write Function

PCAN-Light Documentation

Reference

Function Write

Transmits a CAN message.

[Visual Basic 6]

Declare Function CAN_Write Lib "HWTypDLL" ( _

ByRef MsgBuff As TPCANMsg _

) As Long

[Borland Delphi]

function CAN_Write(

var MsgBuff: TPCANMsg

): Longword; stdcall;

[C++]

DWORD __stdcall CAN_Write(

TPCANMsg* MsgBuff

);

[C#]

public static extern uint Write(

ref TPCANMsg MsgBuff

);

[Visual Basic .NET]

Public Shared Function Write(

ByRef Msgbuff As TPCANMsg) As Integer

End Function

Parameters

MsgBuff

[In] Message to transmit.

Return values

CAN_ERR_OK, CAN_ERR_BUSOFF, CAN_ERR_NOVXD, CAN_ERR_QXMTFULL, CAN_ERR_RESOURCE

See also

Function Read


GetUSBDeviceNr Function

Gets the device number of a USB hardware (PCAN-USB only).

Syntax

Visual Basic 6

Declare Function GetUSBDeviceNr Lib "pcan_usb.dll" ( _

ByRef l As Long _

) As Long

Delphi

function GetUSBDeviceNr(

var l: Long

): Longword; stdcall;

C / C++

DWORD __stdcall GetUSBDeviceNr(

long* l

);

C#

public static extern uint GetUSBDeviceNr(

out int l

);

Visual Basic .NET

Public Shared Function GetUSBDeviceNr( _

ByRef l As Integer) As Integer

End Function

C++ CLR

static unsigned int GetUSBDeviceNr(

int %l

);

Parameter

l

[Out] The USB device number stored in the hardware.

Return values

CAN_ERR_ILLHW, CAN_ERR_ILLPARAMTYPE, CAN_ERR_OK, CAN_ERR_NOVXD

See also

SetUSBDeviceNr Function

GetUSB2DeviceNr Function

SetUSB2DeviceNr Function


GetUSB2DeviceNr Function

Gets the device number of a second PCAN-USB adapter.

Syntax

Visual Basic 6

Declare Function GetUSB2DeviceNr Lib "pcan_2usb.dll" ( _

ByRef l As Long _

) As Long

Delphi

function GetUSB2DeviceNr(

var l: Long

): Longword; stdcall;

C / C++

DWORD __stdcall GetUSB2DeviceNr(

long* l

);

C#

public static extern uint GetUSBDeviceNr(

out int l

);

Visual Basic .NET

Public Shared Function GetUSBDeviceNr( _

ByRef l As Integer) As Integer

End Function

C++ CLR

static unsigned int GetUSBDeviceNr(

int %l

);

Parameter

l

[Out] The USB device number stored in the hardware.

Return values

CAN_ERR_ILLHW, CAN_ERR_ILLPARAMTYPE, CAN_ERR_OK, CAN_ERR_NOVXD

See also

SetUSB2DeviceNr Function

GetUSBDeviceNr Function

SetUSBDeviceNr Function


SetUSBDeviceNr Function

PCAN-Light Documentation

Reference

Function SetUSBDeviceNr

Sets the USB device number (PCAN-USB only).

Syntax

Visual Basic 6

Declare Function SetUSBDeviceNr Lib "pcan_usb.dll" ( _

ByVal l As Long _

) As Long

Delphi

function SetUSBDeviceNr(

l: Long

): Longword; stdcall;

C / C++

DWORD __stdcall SetUSBDeviceNr(

long l

);

C#

public static extern uint SetUSBDeviceNr(

int l

);

Visual Basic .NET

Public Shared Function SetUSBDeviceNr( _

l As Integer) As Integer

End Function

C++ CLR

static unsigned int SetUSBDeviceNr(

int l

);

Parameters

l

[In] A valid USB device number. The numeric range is 0 to 255.

Return values

CAN_ERR_ILLHW, CAN_ERR_ILLPARAMTYPE, CAN_ERR_ILLPARAMVAL, CAN_ERR_OK, CAN_ERR_NOVXD, CAN_ERR_REGTEST

See also

GetUSBDeviceNr Function

GetUSB2DeviceNr Function

SetUSB2DeviceNr Function


SetUSB2DeviceNr Function

PCAN-Light Documentation

Reference

Function SetUSB2DeviceNr

Sets the USB device number of a second PCAN-USB adapter.

Syntax

Visual Basic 6

Declare Function SetUSB2DeviceNr Lib "pcan_2usb.dll" ( _

ByVal l As Long _

) As Long

Delphi

function SetUSB2DeviceNr(

l: Long

): Longword; stdcall;

C / C++

DWORD __stdcall SetUSB2DeviceNr(

long l

);

C#

public static extern uint SetUSBDeviceNr(

int l

);

Visual Basic .NET

Public Shared Function SetUSBDeviceNr( _

l As Integer) As Integer

End Function

C++ CLR

static unsigned int SetUSBDeviceNr(

int l

);

Parameters

l

[In] A valid USB device number. The numeric range is 0 to 255.

Return values

CAN_ERR_ILLHW, CAN_ERR_ILLPARAMTYPE, CAN_ERR_ILLPARAMVAL, CAN_ERR_OK, CAN_ERR_NOVXD, CAN_ERR_REGTEST

See also

GetUSB2DeviceNr Function

GetUSBDeviceNr Function

SetUSBDeviceNr Function


Baud Rate Codes

The Baud rate is the transfer speed on the CAN bus.

The following Baud rate codes are predefined:

Identifier | Baud Rate Code | Baud Rate
CAN_BAUD_1M | 0014h | 1 MBit/s
CAN_BAUD_500K | 001Ch | 500 kBit/s
CAN_BAUD_250K | 011Ch | 250 kBit/s
CAN_BAUD_125K | 031Ch | 125 kBit/s
CAN_BAUD_100K | 432Fh | 100 kBit/s
CAN_BAUD_50K | 472Fh | 50 kBit/s
CAN_BAUD_20K | 532Fh | 20 kBit/s
CAN_BAUD_10K | 672Fh | 10 kBit/s
CAN_BAUD_5K | 7F7Fh | 5 kBit/s

The following Baud Rates are also common:

Baud Rate | Baud Rate Code
800 kBit/s | 0016h
95,23 kBit/s | C34Eh
83,33 kBit/s | 4B14h
47,6 kBit/s | 1414h
33,33 kBit/s | 1D14h

You can create your own baud rate code by using BaudTool, a freeware tool from PEAK-System Technik GmbH. This tool shows you the corresponding baud rate code to any required transfer rate. Take a look at our homepage.

See also

Reference


Error Codes

In the PCAN-Light API, the following error codes are possible. Errors are generally returned as bit masks, i.e. several error codes can be combined with each other.

Errors arranged by name
Name | Value | Description
CAN_ERR_BUSHEAVY | 0008h | Bus error: An error counter has reached the 'Heavy' limit.
CAN_ERR_BUSLIGHT | 0004h | Bus error: An error counter has reached the 'Light' limit.
CAN_ERR_BUSOFF | 0010h | Bus error: The CAN controller is in 'Bus Off' state.
CAN_ERR_ILLPARAMTYPE | 4000h | Parameter is not permitted/applicable here.
CAN_ERR_ILLPARAMVAL | 8000h | Parameter value is invalid.
CAN_ERR_NOVXD | 0200h | Driver is not loaded.
CAN_ERR_OK | 0000h | No error.
CAN_ERR_OVERRUN | 0002h | CAN controller has been read out too late.
CAN_ERR_QOVERRUN | 0040h | Receive queue has been read out too late.
CAN_ERR_QRCVEMPTY | 0020h | Receive queue is empty.
CAN_ERR_QXMTFULL | 0080h | Transmit queue is full.
CAN_ERR_REGTEST | 0100h | Register test of the 82C200/SJA1000 has failed.
CAN_ERR_RESOURCE | 2000h | Resource (FIFO, client, timer) cannot be created.
CAN_ERR_XMTFULL | 0001h | Transmit buffer of the controller is full.
CAN_ERRMASK_ILLHANDLE | 1C00h | Mask for all handle errors.
Errors arranged by value
Value | Name | Description
0000h | CAN_ERR_OK | No error.
0001h | CAN_ERR_XMTFULL | Transmit buffer of the controller is full.
0002h | CAN_ERR_OVERRUN | CAN controller has been read out too late.
0004h | CAN_ERR_BUSLIGHT | Bus error: An error counter has reached the 'Light' limit.
0008h | CAN_ERR_BUSHEAVY | Bus error: An error counter has reached the 'Heavy' limit.
0010h | CAN_ERR_BUSOFF | Bus error: The CAN controller is in 'Bus Off' state.
0020h | CAN_ERR_QRCVEMPTY | Receive queue is empty.
0040h | CAN_ERR_QOVERRUN | Receive queue has been read out too late.
0080h | CAN_ERR_QXMTFULL | Transmit queue is full.
0100h | CAN_ERR_REGTEST | Register test of the 82C200/SJA1000 has failed.
0200h | CAN_ERR_NOVXD | Driver is not loaded.
1C00h | CAN_ERRMASK_ILLHANDLE | Mask for all handle errors.
2000h | CAN_ERR_RESOURCE | Resource (FIFO, client, timer) cannot be created.
4000h | CAN_ERR_ILLPARAMTYPE | Parameter is not permitted/applicable here.
8000h | CAN_ERR_ILLPARAMVAL | Parameter value is invalid.


Structures

The PCAN-Light API defines the following structures:

Name | Description
TPCANMsg | Defines a CAN message.

See also

Reference


TPCANMsg Structure

Defines a CAN message.

Syntax

Visual Basic 6

Public Type TPCANMsg

ID As Long

MSGTYPE As Byte

LEN As Byte

DATA(8) As Byte

End Type

Delphi

TPCANMsg = record

ID: Longword;

MSGTYPE: Byte;

LEN: Byte;

DATA: array[0..7] of Byte;

end;

C / C++

typedef struct

{

DWORD ID;

BYTE MSGTYPE;

BYTE LEN;

BYTE DATA[8];

} TPCANMsg;

C#

public struct TPCANMsg

{

public uint Id;

public byte MsgType;

public byte Len;

public byte[] Data;

}

Visual Basic .NET

Structure TPCANMsg

Public ID As int32

Public MSGTYPE As Byte

Public LEN As Byte

Public DATA() As Byte

End Structure

C++ CLR

value struct TPCANMsg

{

unsigned int ID;

unsigned char MsgType

unsigned char Len;

array<unsigned char>^ Data;

};

Fields

ID

11/29-bit CAN identifier.

MSGTYPE

Bit mask indicating the type of the message. Several message types can be combined.

Identifer | Value | Description
MSGTYPE_STANDARD | 00h | Data Frame. CAN message with data contents and an 11-bit CAN ID.
MSGTYPE_RTR | 01h | Remote Transmit Request (RTR).
MSGTYPE_EXTENDED | 02h | Data Frame. CAN message with data contents according to CAN 2.0B standard (29-bit CAN ID).
MSGTYPE_STATUS | 80h | Status message. The first 4 data bytes contain an Error Code. MSB of the Error Code is in data byte 0, LSB is in data byte 3.

LEN

Number of data bytes in a data message (Data Length Code).

DATA

Data bytes of a CAN message. The size can be 0 to 8 bytes.

Examples

Standard message:

ID | MSGTYPE | LEN | Data0 bis Data7
100h | 00h | 5 | 01h 23h ADh 4Fh 80h
4ABh | MSGTYPE_STANDARD | 8 | 01h 23h 45h 67h 89h ABh CDh EFh

Extended message:

ID | MSGTYPE | LEN | Data0 bis Data7
0000102Ah | 02h | 5 | 01h 23h ADh 4Fh 80h
000004ABh | MSGTYPE_EXTENDED | 8 | 01h 23h 45h 67h 89h ABh CDh EFh

RTR message:

ID | MSGTYPE | LEN
100h | 01h | 5
100h | MSGTYPE_RTR | 8

Note: The data bytes in a RTR message are void.

Combination of MSGTYPE:

ID | MSGTYPE | LEN
000030CDh | 01h OR 02h | 5
000030CDh | 03h | 5
000030CDh | MSGTYPE_RTR OR MSGTYPE_EXTENDED | 5

A RTR message that has a 29-Bit CAN-ID.

See also

Read Function

Write Function

Error Codes


Additional Information

Additional Information

PCAN is the platform for PCAN-Light. In the following topics there is an overview of PCAN and the fundamental practice with the interface DLL CanApi2.

PCAN Basics

This section contains an introduction to PCAN.

CanApi2

This section compares the PCAN-Light and CanApi2 interfaces, with a function description of CanApi2.

PCAN products

This section introduces and compares different PCAN products.


PCAN Basics

PCAN is a synonym for PEAK CAN APPLICATIONS and is a flexible system for planning, developing and using Controller Area Networks (CAN). It is a powerful product for both the developer and the end-user.

The PCAN system consists of a collection of Windows Device Drivers. These allow the Real-time connection of Windows applications to all CAN busses that are physically connected to the PC via a PCAN hardware. The interface to the user and the manager of a CAN-equipped installation are the so-called PCAN clients. With their help process factors are controlled and visualized. The drivers permit the connection of several clients, which are then able to communicate via the CAN busses. Furthermore, several hardware components are supported, which are based on the CAN controller Philips SJA1000.

So-called Nets are available. These specify virtual CAN busses that are extended into the PC. Several clients can connect to a virtual CAN bus. The connection to the outside world (a physical CAN bus) is possible with a hardware interface, e.g. the PCAN-Dongle or the PCAN-ISA card. The following figures give an overview of possible configurations.

Following rules apply to PCAN clients, nets and hardware:

  • A PCAN client can be connected to more than one net.

  • A net supplies several PCAN clients.

  • A hardware component belongs to not more than one Net.

  • A Net can have no hardware.

  • If a Client sends a message, it will be transferred to every other Client and to the external CAN bus via the hardware.

  • If a message is received over the hardware, it is received by every client. Every client receives only those messages, which pass its acceptance filter.

  • Definition of the installed hardware and of the nets. Per hardware several nets may be defined. But only one net can be active.

  • Clients connect to a net about the net name.

  • Every PCAN client has a transmission queue, where CAN messages to be transmitted are waiting until the individual transmission time. At occurrence of the transmission time they are written into the transmission queue of the PCAN hardware.

  • Every hardware contains a receive queue for buffering received CAN messages.

See also

PCAN-Light Basics

Basics of PCAN-Light applications


CanApi2

PCAN-Light Documentation

Additional Information

CanApi2 Interface

CanApi2 is a synonym for CAN Application Programming Interface (version 2) and is a comprehensively programming interface to the PCAN system of the company PEAK-System Technik GmbH. This interface is more comprehensive than PCAN-Light.

Important difference to PCAN-Light:

  • Transmit a CAN message at a fixed point of time.

  • Information about the receive time of a CAN message.

  • Several application programs could be connected to one PCAN-PC hardware.

  • Detailed information to PCAN-PC hardware and the PCAN system (PCAN net and PCAN client).

  • Easy switching between different PCAN-PC hardware.

  • The PCAN client is connected via the net to the PCAN-PC hardware.

The following text is a short overview to the CanApi2 functions. The functions itself can be categorized as follows:

Control

Register and remove functions for nets and hardware.

Configuration

Configuration functions for nets and hardware.

Client

Functions for the management of the clients.

Communication

Functions for the data interchange over the CAN bus.

Information

Functions for the information about clients, nets and hardware.

Control

Register and remove functions for nets and hardware.

Function | Description
CloseAll | Disconnects all hardware, nets, and clients.
RegisterHardware | Registers a Non-Plug-and-Play CAN hardware.
RegisterHardwarePCI | Registers a PCI CAN hardware.
RegisterNet | Defines of a PCAN net.
RemoveHardware | Removes and deactivates CAN hardware.
RemoveNet | Removes a PCAN net.
Configuration

Configuration functions for nets, drivers, and hardware.

Function

Description

SetDeviceName

Sets the PCAN device to be used for subsequent CanApi2 function calls.

SetDriverParam

Configures a driver parameter, e.g. the size of the receive or transmit buffer.

SetHwParam

Configures a hardware parameter, e.g.

  • the PEAK serial number,

  • and additional parameters for the PCAN-USB hardware.

SetNetParam

Configures net parameter.

Client

Functions for the management of the clients.

Function

Description

ConnectToNet

Connects a client to a PCAN net.

DisconnectFromNet

Disconnects a client from a PCAN net.

RegisterClient

Registers an application as PCAN client.

RegisterMsg

Expands the reception filter of a client.

RemoveAllMsgs

Resets the filter of a Client for a connected Net.

RemoveClient

Removes a client from the driver.

ResetClient

Resets the receive and transmit queue of a client.

ResetHardware

Resets a CAN hardware.

SetClientFilter

Configures the reception filter of a client.

SetClientFilterEx

Configures the reception filter of a client.

SetClientParam

Configures a client parameter, e.g.

  • Self-receive mode of transmitted messages

  • improve the accuracy of the reception filter.

Communication

Functions for the data interchange over the CAN bus.

Function | Description
Read | Reads a received CAN message, including the reception time stamp.
Read_Multi | Reads multiple received CAN messages.
Write | Transmits a CAN message at a specified time.
Information

Functions for the information about clients, nets, drivers, and hardware.

Function

Description

GetClientParam

Retrieves client parameter, e.g.

  • total number of transmitted or received CAN messages,

  • the PCAN driver name, PCAN net, or PCAN client name

  • the number of received bits.

GetDeviceName

Retrieves the currently used PCAN device.

GetDiagnostic

Reads the diagnostic text buffer.

GetDriverName

Retrieves the name of a PCAN device type.

GetDriverParam

Retrieves a driver parameter.

GetErrText

Translates an error code into a text.

GetHwParam

Retrieves a hardware parameter.

GetNetParam

Retrieves a net parameter.

GetSystemTime

Gets the system time.

Msg2Text

Creates a text form of a CAN message.

Status

Detects the current status of a CAN hardware.

VersionInfo

Reads version and copyright information from the driver.


PEAK software and drivers for CAN bus applications

Software

PEAK-System GmbH makes available some applications. PCAN-View is a small and easy-to-use CAN monitor that allows CAN messages to be viewed in conjunction with a PCAN adapter. This application is included in every PCAN hardware package and is the basic version of the more sophisticated PCAN-Explorer CAN monitor. A short comparison table is shown at the end of the topic.

Driver

PCAN-Light and the more comprehensive CanApi2 are interfaces to the PCAN drivers. Every kind of PCAN hardware has its own driver.

Overview of PCAN software packages

The following table compares some properties of PCAN software packages:

Property

PCAN-Light

PCAN-Evaluation

PCAN-Developer

Applications included in package

  • PCAN-View

  • PCAN-View,

  • PCAN Status Display and

  • PCAN Nets Configuration

  • PCAN-View,

  • PCAN Status Display,

  • PCAN Nets Configuration,

  • PCAN-Explorer and

  • PCAN-Trace

Windows 9x/ME

Yes

Yes

Yes

Windows NT/2000/XP/Vista

Yes

Yes

Yes

Supports all PCAN-PC hardware

One card and one CAN channel per driver

Yes

Yes

Multiple programs on one driver

No

Yes

Yes

CAN communication between programs

No

Yes

Yes

Maximum number of supported hardware devices per driver

1

16

16

Maximum number of programs per hardware device

1

32

32

Advanced hardware status information

No

Yes

Yes

Real-time accuracy of outgoing (1.) and incoming messages (2.)

No time stamps

  1. 1 ms Win9x/ME and 10 ms (NT/2000/XP/Vista)

  2. 1/1000 ms

  1. 1 ms Win9x/ME and 10 ms (NT/2000/XP/Vista)

  2. 1/1000 ms

Event on message receiption

No, application must poll

Yes

Yes

Internal message buffer on driver per program

2048 - 32000

2048 - 32000

2048 - 32000

Software simulation between programs (no hardware required for development)

No

Yes

Yes

One interface for all PCAN adapters

Different DLL's

One DLL

One DLL

Driver

Driver for Plug-and-Play hardware and driver for Non-Plug-and-Play hardware

CanApi2

CanApi2

Hotline support for developers

No

Yes

Yes

Hardware configuration via Control Panel

Task performed in application

Yes

Yes

User-definable Message filter

Yes

Yes

Yes

PCAN-View and PCAN-Light are freeware, you can download this software via the Internet.

Comparison of PCAN-View and PCAN-Explorer
Property | PCAN-View | PCAN-Explorer
Separate representation from transmit and receive CAN messages. Once is shown in the transmit list and the other in the receive list | Yes | Yes
Variable baud rate settings | Yes | Yes
Any number of messages can be included in a transmit list | No | Yes
Transmit message at fixed interval or manually | Yes | Yes
Display of error status | Yes | Yes
Saving and retrieving created transmit lists in order to emulate different CAN nodes | No | Yes
Symbolic representation of messages by allocation of identifiers | No | Yes
Symbolic representation of data within data bytes | No | Yes
Configurable, integrated data logger | No | Yes
Macro creation in Visual Basic Script | No | Yes
Integration of Add-ins (e.g. Plotter, CANdb-Import/Export, Instruments Panel) | No | Yes
Automation via Scripting or COM interfaces | No | Yes


Product descriptions

Product

Product description

PCAN-View

Simple CAN monitor. Some features:

  • Separated representation of transmit and receive messages.

  • Variable baud rate settings up to 1MBit/s.

  • Incoming, outgoing and error status display.

PCAN Status Display

Status monitor for retrieving statistical information about the currently active clients, and to examine the nets and hardware used by those clients.

PCAN Nets Configuration

Setting up and managing PCAN nets for the connection of software applications to the CAN hardware.

PCAN-Explorer

Advanced CAN monitor.

Some features:

  • Separated representation from transmit and receive CAN messages. Once is shown in the transmit list and the other in the receive list.

  • Variable baud rate settings via net definition.

  • Any number of messages can be included in a transmit list and sent at fixed intervals, manually or in response to a remote frame.

  • Display error status.

  • Saving and retrieving created transmit lists in order to emulate different CAN nodes.

  • Symbolic representation of data within data bytes.

  • Configurable, integrated data logger.

  • Macro creation in Visual Basic Script.

  • Integration of add-ins (e.g. Plotter, CANdb-Import, User Panel)

PCAN-Trace

This program is a data logger for up to 9,999,000 CAN messages. It enables CAN messages to be quickly recorded, saved and even played back on the CAN bus.


PCAN hardware

The following figure shows the available PCAN hardware:

Hardware | Plug-and-Play Hardware | Multi-channel Hardware available | Number of possible channels
PCAN-Dongle | No | No | 1
PCAN-ISA | No | Yes | 1 - 2
PCAN-PC/104 | No | Yes | 1 - 2
PCAN-PCI | Yes | Yes | 1 - 2
PCAN-PCI Express | Yes | Yes | 1 - 2
PCAN-PC/104-Plus | Yes | Yes | 1 - 2
PCAN-USB | Yes | No | 1
PCAN-PC Card | Yes | Yes | 1 - 2


HWTypDLL

PCAN-Light libraries

Possible values for the HWTypDLL placeholder:

Hardware | HWTypDLL
PCAN-Dongle | Pcan_dng.dll
PCAN-Dongle Pro | Pcan_dnp.dll
PCAN-ISA (single-channel version) | Pcan_isa.dll
PCAN-ISA (dual-channel version) Channel 1 Channel 2 | Pcan_isa.dll Pcan_2isa.dll
PCAN-USB | Pcan_usb.dll
PCAN-USB (2nd adapter) | Pcan_2usb.dll
PCAN-PC Card (single-channel version) | Pcan_pcc.dll
PCAN-PC Card (dual-channel version) Channel 1 Channel 2 | Pcan_pcc.dll Pcan_2pcc.dll
PCAN-PCI (single-channel version) | Pcan_pci.dll
PCAN-PCI (dual-channel version) Channel 1 Channel 2 | Pcan_pci.dll Pcan_2pci.dll


Multi-channel hardware

Multi-channel hardware and their interfaces DLLs:

Hardware | Interface DLL
PCAN-ISA (dual-channel version) Channel 1 Channel 2 | Pcan_isa.dll Pcan_2isa.dll
PCAN-PC Card (dual-channel version) Channel 1 Channel 2 | Pcan_pcc.dll Pcan_2pcc.dll
PCAN-PCI (dual-channel version) Channel 1 Channel 2 | Pcan_pci.dll Pcan_2pci.dll