PCAN-Basic Documentation
Home

Welcome to the documentation of PCAN-Basic,

the new small Version of the PCAN-API from PEAK-System.

Introduction [image] DLL API Reference [image] Additional Information

Last Update: 26.07.2022

Copyright © 2022. PEAK-System Technik GmbH. All rights reserved.
Send feedback to this documentation


Introduction

Introduction

Welcome to the documentation to PCAN-Basic.

The PCAN system of the company PEAK-System Technik GmbH comprises 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-Basic, successor of PCAN-Light, is a simple programming interface to the PCAN system. Via the PCAN-Basic Dll it is possible to connect own applications to the Device drivers and the PCAN hardware, to communicate with the CAN busses.

In this Chapter

Topics | Description
Understanding PCAN-Basic | This section contains an introduction to PCAN-Basic API.
Using Events | Offers support about how to read CAN messages using notifications.
License Regulations | License regulations to this software.
Contact information | Contact information - PEAK-System Technik GmbH.


Understanding PCAN-Basic

Understanding PCAN-Basic

PCAN-Basic is a programming application interface (API) for CAN communication using the PCAN system of the company PEAK-System Technik GmbH. It comprises 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-Basic supports connecting several CAN channels simultaneously, from the same or different types of devices. The following list shows the PCAN-Channels that can be connected per PCAN-Device:

 | PCAN-ISA | PCAN-Dongle | PCAN-PCI | PCAN-USB | PCAN-PC-Card | PCAN-LAN
Number of Channels | 8 | 1 | 16 | 16 | 2 | 16

Using the PCAN-Basic

The PCAN-Basic offers the possibility to use several PCAN-Channels within the same application easily. The communication process is divided in 3 phases: initialization, interaction and finalization of a PCAN-Channel.

Initialization: In order to do CAN communication using a channel, it is necessary to first initialize it. This is done making a call to the function CAN_Initialize (class-method: Initialize), or CAN_InitializeFD (class-method: InitializeFD) in case FD communication is desired.

Interaction: After a successful initialization, a channel is ready to communicate with the connected CAN bus. Further configuration is not needed. The functions CAN_Read and CAN_Write (class-methods: Read and Write) can be then used to read and write CAN messages. If the channel being used is FD capable and it was initialized using CAN_InitializedFD, then the functions to use are CAN_ReadFD and CAN_WriteFD (class-methods: ReadFD and WriteFD). If desired, extra configuration can be made to improve a communication session, like changing the message filter to target specific messages.

Finalization: When the communication is finished, the function CAN_Uninitialize (class-method: Uninitialize) should be called in order to release the PCAN-Channel and the resources allocated for it. In this way the channel is marked as "Free" and can be used from other applications.

Hardware and Drivers

Overview of the current PCAN hardware and device drivers:

Hardware | Plug-and-Play Hardware | Driver
PCAN-Dongle | No | Pcan_dng.sys
PCAN-ISA | No | Pcan_isa.sys
PCAN-PC/104 | No | Pcan_isa.sys
PCAN-PCI | Yes | Pcan_pci.sys
PCAN-PCI Express | Yes | Pcan_pci.sys
PCAN-PCI Express FD | Yes | Pcan_pci.sys
PCAN-cPCI | Yes | Pcan_pci.sys
PCAN-miniPCI | Yes | Pcan_pci.sys
PCAN-miniPCIe | Yes | Pcan_pci.sys
PCAN-miniPCIe FD | Yes | Pcan_pci.sys
PCAN-M.2 | Yes | Pcan_pci.sys
PCAN-Chip PCIe FD | Yes | Pcan_pci.sys
PCAN-PC/104-Plus | Yes | Pcan_pci.sys
PCAN-PC/104-Plus Quad | Yes | Pcan_pci.sys
PCAN-PC/104-Express | Yes | Pcan_pci.sys
PCAN-PC/104-Express FD | Yes | Pcan_pci.sys
PCAN-ExpressCard | Yes | Pcan_pci.sys
PCAN-ExpressCard 34 | Yes | Pcan_pci.sys
PCAN-USB | Yes | Pcan_usb.sys
PCAN-USB FD | Yes | Pcan_usb.sys
PCAN-USB Pro | Yes | Pcan_usb.sys
PCAN-USB Pro FD | Yes | Pcan_usb.sys
PCAN-USB Hub | Yes | Pcan_usb.sys
PCAN-USB X6 | Yes | Pcan_usb.sys
PCAN-Chip USB | Yes | Pcan_usb.sys
PCAN-PC Card | Yes | Pcan_pcc.sys
PCAN-Ethernet Gateway DR | Yes | Pcan_lan.sys
PCAN-Wireless Gateway DR | Yes | Pcan_lan.sys
PCAN-Wireless Gateway | Yes | Pcan_lan.sys
PCAN-Wireless Automotive Gateway | Yes | Pcan_lan.sys
See Also

PCAN Fundamentals

PCAN-API


Using Events

Using Events

Event objects can be used to notify a client on reception of a CAN message automatically. This has following advantages:

  • The client program doesn't need to check periodically for received messages any longer.
  • The response time on received messages is reduced.

To use events, the client application must call the CAN_SetValue (class-method: SetValue) function to set the parameter PCAN_RECEIVE_EVENT. This parameter sets the handle for the event object. When receiving a message, the driver sets this event to the "Signaled" state.

Another thread must be started in the client application, which waits for the event to be signaled, using one of the Win32 synchronization functions (e.g. WaitForSingleObject) without increasing the processor load. After the event is signaled, the receive buffer of the client can be read with the CAN_Read (class method: Read) function, and the CAN messages can be processed.

Remarks

Tips for the creation of the event object:

  • Creation of the event as "auto-reset"
    • Trigger mode "set" (default): After the first waiting thread has been released, the event object's state changes to non-signaled. Other waiting threads are not released. If no threads are waiting, the event object's state remains signaled.
    • Trigger mode "pulse": After the first waiting thread has been released, the event object's state changes to non-signaled. Other waiting threads are not released. If no threads are waiting, or if no thread can be released immediately, the event object's state is simply set to non-signaled.
  • Creation of the event as "manual-reset"
    • Trigger mode "set" (default): The state of the event object remains signaled until it is set explicitly to the non-signaled state by the Win32 [image] ResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations, can be released while the object's state remains signaled.
    • Trigger mode "pulse": All waiting threads that can be released immediately are released. The event object's state is then reset to the non-signaled state. If no threads are waiting, or if no thread can be released immediately, the event object's state is simply set to non-signaled.
See Also

CAN_SetValue (class-method: SetValue)

CAN_Read (class-method: Read)


License Regulations

License Regulations

The use of this software is subject to the terms of the [image] End User License Agreement of PEAK-System Technik GmbH.

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-2019 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

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 data types (classes, structures, types, defines, enumerations) and API functions which are contained in the PCAN-Basic API.

In this Chapter

Topic | Description
Namespaces | Lists the defined namespaces for Microsoft's .NET Framework programming environment.
Modules | Lists the defined modules for Python 2.6 programming environment.
Units | Lists the defined units for Delphi's programming environment.
Classes | Lists the defined classes that implement the PCAN-Basic API.
Structures | Lists the defined structures.
Types | Lists the defined types.
Methods | Lists the defined class methods for using the PCAN-Basic API.
Functions | List the defined functions for using the PCAN-Basic API.
Definitions | Lists the defined values.


Namespaces

Namespaces

PEAK offers the implementation of some specific programming interfaces as namespaces for the .NET Framework programming environment. The following namespaces are available to be used:

Namespaces
 | Name | Description
{} | Peak | Contains all namespaces that are part of the managed programming environment from PEAK-System.
{} | Peak.Can | Contains types and classes for using the PCAN API from PEAK-System.
{} | Peak.Can.Light | Contains types and classes for using the PCAN-Light API from PEAK-System.
{} | Peak.Can.Basic | Contains types and classes for using the PCAN-Basic API from PEAK-System.
{} | Peak.Lin | Contains types and classes used to handle with LIN devices from PEAK-System.
{} | Peak.RP1210A | Contains types and classes used to handle with CAN devices from PEAK-System through the TMC Recommended Practices 1210, version A, as known as RP1210(A).


Peak.Can.Basic

Peak.Can.Basic

The Peak.Can.Basic namespace contain types and classes for using the PCAN-Basic API within the .NET Framework programming environment, in order to handle with PCAN devices from PEAK-System.

Remarks

Under the Delphi environment, these elements are enclosed in the PCANBasic-Unit. The functionality of all elements included here is just the same. The difference between this namespace and the Delphi unit consists in the fact that Delphi accesses the Windows API directly (it is not Managed Code).

Aliases
Alias | Description
TPCANHandle | Represents a PCAN-hardware channel handle.
TPCANBitrateFD | Represents a bit rate with flexible data rate.
TPCANTimestampFD | Represents the timestamp of a CAN message with flexible data rate.
Classes
Class | Description
PCANBasic | Defines a class which represents the PCAN-Basic API.
Structures
Structure | Description
TPCANMsg | Defines a CAN message.
TPCANTimestamp | Defines a time-stamp of a CAN message.
TPCANMsgFD | Defines a CAN message with flexible data rate.
Enumerations
Enumeration | Description
TPCANStatus | Represents a PCAN status/error code.
TPCANDevice | Represents a PCAN device.
TPCANParameter | Represents a PCAN parameter to be read or set.
TPCANMessageType | Represents the type of a CAN message
TPCANType | Represents the type of a Not-Plug-And-Play PCAN hardware.
TPCANMode | Represents a PCAN filter mode.
TPCANBaudrate | Represents a PCAN bit rate register value.


Modules

Modules

PEAK offers the implementation of some specific programming interfaces as modules for programming under Python (ver. 2.6). The following modules are available to be used:

Modules
 | Name | Description
{} | PCAN-Basic-Module | Python module for using the PCAN-Basic API from PEAK-System.


PCANBasic Module

PCANBasic Module

The Peak.Can.Basic module contain types and classes for using the PCAN-Basic API within Python 2.6 programming environment, in order to handle with PCAN devices from PEAK-System.

Classes
Class | Description
PCANBasic | Defines a class which represents the PCAN-Basic API.
Structures
Structure | Description
TPCANMsg | Defines a CAN message. The members of this structure are sequentially byte aligned.
TPCANTimestamp | Defines a time-stamp of a CAN message.
TPCANMsgFD | Defines a CAN message with flexible data rate.


Units

Units

PEAK offers the implementation of some specific programming interfaces as Units for the Delphi's programming environment. The following units are available to be used:

Units
 | Name | Description
{} | PCANBasic-Unit | Delphi unit for using the PCAN-Basic API from PEAK-System.


PCANBasic Unit

PCANBasic Unit

The PCANBasic-Unit contain types and classes for using the PCAN-Basic API within the Delphi's programming environment, in order to handle with PCAN devices from PEAK-System.

Remarks

For the .NET Framework, these elements are enclosed in the Peak.Can.Basic namespace. The functionality of all elements included here is just the same. The difference between this Unit and the .NET namespace consists in the fact that Delphi accesses the Windows API directly (it is not Managed Code).

Aliases
Alias | Description
TPCANHandle | Represents a PCAN-hardware channel handle.
TPCANBitrateFD | Represents a bit rate with flexible data rate.
TPCANTimestampFD | Represents the timestamp of a CAN message with flexible data rate.
Classes
Class | Description
TPCANBasic | Defines a class which represents the PCAN-Basic API.
Structures
Structure | Description
TPCANMsg | Defines a CAN message.
TPCANTimestamp | Defines a time-stamp of a CAN message.
TPCANMsgFD | Defines a CAN message with flexible data rate.
Enumerations
Enumeration | Description
TPCANStatus | Represents a PCAN status/error code.
TPCANDevice | Represents a PCAN device.
TPCANParameter | Represents a PCAN parameter to be read or set.
TPCANMessageType | Represents the type of a CAN message
TPCANType | Represents the type of a Not-Plug-And-Play PCAN hardware.
TPCANMode | Represents a PCAN filter mode.
TPCANBaudrate | Represents a PCAN bit rate register value.


Classes

Classes

The following classes are offered to make use of the PCAN-Basic API in a managed or unmanaged way.

Classes
Class | Description
PCANBasic | Defines a class to use the PCAN-Basic API within the Microsoft's .NET Framework programming environment, and Python.
TPCANBasic | Defines a class to use the PCAN-Basic API within the Delphi programming environment.


PCANBasic

PCANBasic

Defines a class which represents the PCAN-Basic API for using within the Microsoft's .NET Framework and Python (ver. 2.6).

Syntax
C#
public static class PCANBasic
C++ / CLR
public ref class PCANBasic abstract sealed
Visual Basic
Public NotInheritable Class PCANBasic
Python
class PCANBasic
Remarks

The PCANBasic class collects and implements the PCAN-Basic API functions. Each method is called just like the API function with the exception that the prefix "CAN_" is not used. The structure and functionality of the methods and API functions is the same.

Within the .NET Framework from Microsoft, the PCANBasic class is a static, not inheritable, class. It can (must) directly be used, without any instance of it, e.g. :

TPCANStatus res;
// Static use, without any instance
//
res = PCANBasic.Initialize(PCAN_USBBUS1,PCAN_BAUD_500K);

Within Python, a variable must be instantiated with an object of type PCANBasic, in order to use the API.

# Object instantiation
#
objPCAN = PCANBasic()
res = objPCAN.Initialize(PCAN_USBBUS1, PCAN_BAUD_500K)

Note that this class under Delphi is called TPCANBasic.

See Also

Methods

Definitions

Delphi: TPCANBasic


TPCANBasic

TPCANBasic

Defines a class which represents the PCAN-Basic API in the Delphi programming environment.

Syntax
Pascal OO
TPCANBasic = class
Remarks

TPCANBasic is a class containing only class-methods and constant members, allowing their use without the creation of any object, just like an static class of another programming languages. It collects and implements the PCAN-Basic API functions. Each method is called just like the API function with the exception that the prefix "CAN_" is not used. The structure and functionality of the methods and API functions is the same.

Note that this class under .NET Framework is called PCANBasic.

See Also

Methods

Definitions

.NET Framework: PCANBasic


Structures

Structures

The PCAN-Basic API defines the following structures:

Name | Description
TPCANMsg | Defines a CAN message.
TPCANTimestamp | Defines the point of time at which a CAN message was received.
TPCANMsgFD | Defines a CAN message with flexible data rate.
TPCANChannelInformation | Describes an available PCAN channel.
See Also

Reference


TPCANMsg

TPCANMsg

Defines a CAN message.

Syntax
C++
typedef struct
{
    DWORD ID;
    TPCANMessageType  MSGTYPE;
    BYTE LEN;
    BYTE DATA[8];
} TPCANMsg;
Pascal OO
TPCANMsg = record
    ID: Longword;
    MSGTYPE: TPCANMessageType;
    LEN: Byte;
    DATA: array[0..7] of Byte;
end;
C#
public struct TPCANMsg
{
    public uint ID;
    [MarshalAs(UnmanagedType.U1)]
    public TPCANMessageType MSGTYPE;
    public byte LEN;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 8)]
    public byte[] DATA;
}
C++ / CLR
public value struct TPCANMsg
{
    UInt32 ID;
    [MarshalAs(UnmanagedType.U1)]
    TPCANMessageType MSGTYPE;
    Byte LEN;
    [MarshalAs(UnmanagedType::ByValArray, SizeConst = 8)]
    array<Byte>^ DATA;
}
Visual Basic
Public Structure TPCANMsg
    Public ID As UInt32
    <MarshalAs(UnmanagedType.U1)> _
    Public MSGTYPE As TPCANMessageType
    Public LEN As Byte
    <MarshalAs(UnmanagedType.ByValArray, SizeConst := 8)> _
    Public DATA As Byte()
End Structure
Python
from ctypes import *
class TPCANMsg (Structure):
    _fields_ = [ ("ID",  c_uint),
                 ("MSGTYPE",  TPCANMessageType),
                 ("LEN",  c_ubyte),
                 ("DATA", c_ubyte * 8) ]
Remarks

The members of this structure are sequentially byte aligned.

Fields
Name | Description
ID | 11/29-bit message identifier.
MSGTYPE | Type of the message. Bit mask indicating the type of the message. Several message types can be combined.
LEN | Data Length Code of the message (0..8).
DATA | Data of the message (DATA[0]..DATA[7]).
See Also

CAN_Read (class-method: Read)

CAN_Write (class-method: Write)

TPCANTimestamp


TPCANTimestamp

TPCANTimestamp

Defines a time-stamp of a CAN message. The time-stamp contains the number of microseconds since the start of Windows.

Syntax
C++
typedef struct
{
    DWORD  millis;
    WORD   millis_overflow;
    WORD   micros;
} TPCANTimestamp;
Pascal OO
TPCANTimestamp = record
    millis: Longword;
    millis_overflow: Word;
    micros: Word;
end;
C#
public struct TPCANTimestamp
{
    public uint millis;
    public ushort millis_overflow;
    public ushort micros;
}
C++ / CLR
public value struct TPCANTimestamp
{
    UInt32 millis;
    UInt16 millis_overflow;
    UInt16 micros;
};
Visual Basic
Public Structure TPCANTimestamp
    Public millis As UInt32
    Public millis_overflow As UInt16
    Public micros As UInt16
End Structure
Python
from ctypes import *
class TPCANTimestamp (Structure):
    _fields_ = [ ("millis",  c_uint),
                 ("millis_overflow",  c_ushort),
                 ("micros",  c_ushort) ]
Remarks

The members of this structure are sequentially byte aligned.

Calculation of total of microseconds : micros + 1000 * millis + 0x100000000 * 1000 * millis_overflow

Fields
Name | Description
millis | Base-value: milliseconds: 0.. 2^32-1.
millis_overflow | Roll-arounds of millis.
micros | Microseconds: 0..999.
See Also

CAN_Write (class-method: Write)

TPCANMsg


TPCANMsgFD

TPCANMsgFD

Defines a CAN message with flexible data rate.

Syntax
C++
typedef struct
{
    DWORD ID;
    TPCANMessageType MSGTYPE;
    BYTE DLC;
    BYTE DATA[64];
} TPCANMsgFD;
Pascal OO
TPCANMsgFD = record
    ID: Longword;
    MSGTYPE: TPCANMessageType;
    DLC: Byte;
    DATA: array[0..63] of Byte;
end;
C#
public struct TPCANMsgFD
{
    public uint ID;
    [MarshalAs(UnmanagedType.U1)]
    public TPCANMessageType MSGTYPE;
    public byte DLC;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 64)]
    public byte[] DATA;
}
C++ / CLR
public value struct TPCANMsgFD
{
    UInt32 ID;
    [MarshalAs(UnmanagedType::U1)]
    TPCANMessageType MSGTYPE;
    Byte DLC;
    [MarshalAs(UnmanagedType::ByValArray, SizeConst = 64)]
    array<Byte>^ DATA;
};
Visual Basic
Public Structure TPCANMsgFD
    Public ID As UInt32
    <MarshalAs(UnmanagedType.U1)> _
    Public MSGTYPE As TPCANMessageType
    Public DLC As Byte
    <MarshalAs(UnmanagedType.ByValArray, SizeConst:=64)> _
    Public DATA As Byte()
End Structure
Python
from ctypes import *
class TPCANMsgFD (Structure):
    _fields_ = [ ("ID",      c_uint),
                 ("MSGTYPE", TPCANMessageType),
                 ("DLC",     c_ubyte),
                 ("DATA",    c_ubyte * 64) ]
Remarks

The members of this structure are sequentially byte aligned.

Longer Data field with CAN FD messages:

The length of data bytes contained in a CAN message is given by the DATA LENGTH CODE field (DLC). The coding of the DLC within FD messages is different. There are 7 additional codes (from 9 to 15) that allows a FD Messages to transport up to 64 bytes of data. The relationship between DLC and data bytes length is as follows:

DLC | Data Bytes
0 | 0
1 | 1
2 | 2
3 | 3
4 | 4
5 | 5
6 | 6
7 | 7
8 | 8
9 | 12
10 | 16
11 | 20
12 | 24
13 | 32
14 | 48
15 | 64
Fields
Name | Description
ID | 11/29-bit message identifier.
MSGTYPE | Type of the message. Bit mask indicating the type of the message. Several message types can be combined.
DLC | Data Length Code of the message (0..15).
DATA | Data of the message (DATA[0]..DATA[63]).
See Also

CAN_ReadFD (class-method: ReadFD)

CAN_WriteFD (class-method: WriteFD)


TPCANChannelInformation

TPCANChannelInformation

Describes an existing PCAN channel.

Syntax
C++
typedef struct
{
    TPCANHandle channel_handle;
    TPCANDevice device_type;
    BYTE controller_number;
    DWORD device_features;
    char device_name[MAX_LENGTH_HARDWARE_NAME];
    DWORD device_id;
    DWORD channel_condition;
}TPCANChannelInformation;
Pascal OO
TPCANChannelInformation = record
    channel_handle: TPCANHandle;
    device_type: TPCANDevice;
    controller_number: Byte;
    device_features: Longword;
    device_name: array [0..MAX_LENGTH_HARDWARE_NAME-1] of AnsiChar;
    device_id: Longword;
    channel_condition: Longword;
end;
C#
public struct TPCANChannelInformation
{
    [MarshalAs(UnmanagedType.U2)]
    public TPCANHandle channel_handle;
    [MarshalAs(UnmanagedType.U1)]
    public TPCANDevice device_type;
    public byte controller_number;
    public uint device_features;
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = PCANBasic.MAX_LENGTH_HARDWARE_NAME)]
    public string device_name;
    public uint device_id;
    public uint channel_condition;
}
C++ / CLR
public value struct TPCANChannelInformation
{
    [MarshalAs(UnmanagedType::U2)]
    TPCANHandle channel_handle;
    [MarshalAs(UnmanagedType::U1)]
    TPCANDevice device_type;
    Byte controller_number;
    UInt32 device_features;
    [MarshalAs(UnmanagedType::ByValTStr, SizeConst = MAX_LENGTH_HARDWARE_NAME)]
    String^ device_name;
    UInt32 device_id;
    UInt32 channel_condition;
};
Visual Basic
Public Structure TPCANChannelInformation
    <MarshalAs(UnmanagedType.U2)> _
    Public channel_handle As TPCANHandle
    <MarshalAs(UnmanagedType.U1)> _
    Public device_type As TPCANDevice
    Public controller_number As Byte
    Public device_features As UInt32
    <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=PCANBasic.MAX_LENGTH_HARDWARE_NAME)> _
    Public device_name As String
    Public device_id As UInt32
    Public channel_condition As UInt32
End Structure
Python
from ctypes import *
class TPCANChannelInformation (Structure):
    _fields_ = [ ("channel_handle",    TPCANHandle),
                 ("device_type",       TPCANDevice),
                 ("controller_number", c_ubyte),
                 ("device_features",   c_uint),
                 ("device_name",       c_char * MAX_LENGTH_HARDWARE_NAME),
                 ("device_id",         c_uint),
                 ("channel_condition", c_uint) ]
Remarks

The members of this structure are sequentially byte aligned.

Fields
Name | Description
channel_handle | Handle of the PCAN Channel (see TPCANHandle).
device_type | Kind of device represented by the PCAN Channel (see TPCANDevice).
controller_number | Index of the CAN-Controller represented by the PCAN Channel.
device_features | Capabilities of the PCAN Channel (see FEATURE flags).
device_name | Name of the device represented by the PCAN channel.
device_id | Identification number of the device to which the PCAN Channel belongs.
channel_condition | Availability status of the PCAN Channel (see AVAILABILITY flags).
See Also

CAN_GetValue(class-method: GetValue)

Parameter PCAN_ATTACHED_CHANNELS


Types

Types

The PCAN-Basic API defines the following types:

Name | Description
TPCANHandle | Represents a PCAN hardware channel handle.
TPCANStatus | Represents a PCAN status/error code.
TPCANDevice | Represents a PCAN device.
TPCANParameter | Represents a PCAN parameter to be read or set.
TPCANMessageType | Represents the type of a PCAN message.
TPCANType | Represents the type of PCAN hardware to be initialized.
TPCANMode | Represents a PCAN filter mode.
TPCANBaudrate | Represents a PCAN bit rate register value.
TPCANBitrateFD | Represents a bit rate string with flexible data rate.
TPCANTimestampFD | Represents the timestamp of a CAN message with flexible data rate.


TPCANHandle

TPCANHandle

Represents a PCAN-hardware channel handle.

Syntax
C++
#define TPCANHandle WORD
Pascal OO
TPCANHandle = Word;
C#
using TPCANHandle = System.UInt16;
C++ / CLR
#define TPCANHandle System::UInt16
Visual Basic
Imports TPCANHandle = System.UInt16
Python
TPCANHandle  = c_ushort
Remarks

FD capable Hardware:

Some hardware can transmit using a flexible data rate (FD capable). Although there are no special PCAN-Handles to identify these hardware, it is possible to ask if a hardware is able to communicate using the FD protocol. The PCAN-Basic parameter PCAN_CHANNEL_FEATURES allows to investigate whether a hardware is FD capable before being initialized.

.NET Framework programming languages:

An alias is used to represent a Channel handle under Microsoft .NET in order to originate an homogeneity between all programming languages listed above.

Aliases are defined in the Peak.Can.Basic Namespace for C# and VB .NET. However, including a namespace does not include the defined aliases.

If it is wished to work with aliases, those must be copied to the working file, right after the inclusion of the Peak.Can.Basic Namespace. Otherwise, just use the native type, which in this case is a UInt16.

C#:

using System;
using Peak.Can.Basic;
using TPCANHandle = System.UInt16; // Alias's declaration for System.UInt16

Visual Basic:

Imports System
Imports Peak.Can.Basic
Imports TPCANHandle = System.UInt16 ' Alias declaration for System.UInt16
See Also

PCAN Handle Definitions


TPCANStatus

TPCANStatus

Represents a PCAN status/error code. According with the programming language, this type can be a group of defined values or an enumeration.

Syntax
C++
#define TPCANStatus DWORD

#define PCAN_ERROR_OK 0x00000
#define PCAN_ERROR_XMTFULL 0x00001
#define PCAN_ERROR_OVERRUN 0x00002
#define PCAN_ERROR_BUSLIGHT 0x00004
#define PCAN_ERROR_BUSHEAVY 0x00008
#define PCAN_ERROR_BUSWARNING  PCAN_ERROR_BUSHEAVY
#define PCAN_ERROR_BUSPASSIVE 0x40000
#define PCAN_ERROR_BUSOFF 0x00010
#define PCAN_ERROR_ANYBUSERR (PCAN_ERROR_BUSWARNING | PCAN_ERROR_BUSLIGHT | PCAN_ERROR_BUSHEAVY | PCAN_ERROR_BUSOFF | PCAN_ERROR_BUSPASSIVE)
#define PCAN_ERROR_QRCVEMPTY 0x00020
#define PCAN_ERROR_QOVERRUN 0x00040
#define PCAN_ERROR_QXMTFULL 0x00080
#define PCAN_ERROR_REGTEST 0x00100
#define PCAN_ERROR_NODRIVER 0x00200
#define PCAN_ERROR_HWINUSE 0x00400
#define PCAN_ERROR_NETINUSE 0x00800
#define PCAN_ERROR_ILLHW 0x01400
#define PCAN_ERROR_ILLNET 0x01800
#define PCAN_ERROR_ILLCLIENT 0x01C00
#define PCAN_ERROR_ILLHANDLE (PCAN_ERROR_ILLHW | PCAN_ERROR_ILLNET | PCAN_ERROR_ILLCLIENT)
#define PCAN_ERROR_RESOURCE 0x02000
#define PCAN_ERROR_ILLPARAMTYPE 0x04000
#define PCAN_ERROR_ILLPARAMVAL 0x08000
#define PCAN_ERROR_UNKNOWN 0x10000
#define PCAN_ERROR_ILLDATA 0x20000
#define PCAN_ERROR_ILLMODE 0x80000
#define PCAN_ERROR_CAUTION 0x2000000
#define PCAN_ERROR_INITIALIZE 0x4000000
#define PCAN_ERROR_ILLOPERATION 0x8000000
Pascal OO
{$Z4}
TPCANStatus = (
    PCAN_ERROR_OK = $00000,
    PCAN_ERROR_XMTFULL = $00001,
    PCAN_ERROR_OVERRUN = $00002,
    PCAN_ERROR_BUSLIGHT = $00004,
    PCAN_ERROR_BUSHEAVY = $00008,
    PCAN_ERROR_BUSHWARNING  = Byte(PCAN_ERROR_BUSHEAVY),
    PCAN_ERROR_BUSPASSIVE = $40000,
    PCAN_ERROR_BUSOFF = $00010,
    PCAN_ERROR_ANYBUSERR = Byte(PCAN_ERROR_BUSHWARNING) Or Byte(PCAN_ERROR_BUSLIGHT) Or Byte(PCAN_ERROR_BUSHEAVY) Or Byte(PCAN_ERROR_BUSOFF) Or Byte(PCAN_ERROR_BUSPASSIVE),
    PCAN_ERROR_QRCVEMPTY = $00020,
    PCAN_ERROR_QOVERRUN  = $00040,
    PCAN_ERROR_QXMTFULL = $00080,
    PCAN_ERROR_REGTEST = $00100,
    PCAN_ERROR_NODRIVER = $00200,
    PCAN_ERROR_HWINUSE = $00400,
    PCAN_ERROR_NETINUSE = $00800,
    PCAN_ERROR_ILLHW = $01400,
    PCAN_ERROR_ILLNET = $01800,
    PCAN_ERROR_ILLCLIENT = $01C00,
    PCAN_ERROR_ILLHANDLE = Byte(PCAN_ERROR_ILLHW) Or Byte(PCAN_ERROR_ILLNET) Or Byte(PCAN_ERROR_ILLCLIENT),
    PCAN_ERROR_RESOURCE = $02000,
    PCAN_ERROR_ILLPARAMTYPE = $04000,
    PCAN_ERROR_ILLPARAMVAL = $08000,
    PCAN_ERROR_UNKNOWN = $10000,
    PCAN_ERROR_ILLDATA = $20000,
    PCAN_ERROR_ILLMODE = $80000,
    PCAN_ERROR_CAUTION = $2000000,
    PCAN_ERROR_INITIALIZE = $4000000,
    PCAN_ERROR_ILLOPERATION = $8000000
);
C#
[Flags]
public enum TPCANStatus : uint
{
    PCAN_ERROR_OK = 0x00000,
    PCAN_ERROR_XMTFULL = 0x00001,
    PCAN_ERROR_OVERRUN = 0x00002,
    PCAN_ERROR_BUSLIGHT = 0x00004,
    PCAN_ERROR_BUSHEAVY = 0x00008,
    PCAN_ERROR_BUSWARNING   = PCAN_ERROR_BUSHEAVY,
    PCAN_ERROR_BUSPASSIVE   = 0x40000,
    PCAN_ERROR_BUSOFF = 0x00010,
    PCAN_ERROR_ANYBUSERR = (PCAN_ERROR_BUSWARNING | PCAN_ERROR_BUSLIGHT | PCAN_ERROR_BUSHEAVY | PCAN_ERROR_BUSOFF | PCAN_ERROR_BUSPASSIVE),
    PCAN_ERROR_QRCVEMPTY = 0x00020,
    PCAN_ERROR_QOVERRUN = 0x00040,
    PCAN_ERROR_QXMTFULL = 0x00080,
    PCAN_ERROR_REGTEST = 0x00100,
    PCAN_ERROR_NODRIVER = 0x00200,
    PCAN_ERROR_HWINUSE = 0x00400,
    PCAN_ERROR_NETINUSE = 0x00800,
    PCAN_ERROR_ILLHW = 0x01400,
    PCAN_ERROR_ILLNET = 0x01800,
    PCAN_ERROR_ILLCLIENT = 0x01C00,
    PCAN_ERROR_ILLHANDLE = (PCAN_ERROR_ILLHW | PCAN_ERROR_ILLNET | PCAN_ERROR_ILLCLIENT),
    PCAN_ERROR_RESOURCE = 0x02000,
    PCAN_ERROR_ILLPARAMTYPE = 0x04000,
    PCAN_ERROR_ILLPARAMVAL = 0x08000,
    PCAN_ERROR_UNKNOWN = 0x10000,
    PCAN_ERROR_ILLDATA = 0x20000,
    PCAN_ERROR_ILLMODE = 0x80000,
    PCAN_ERROR_CAUTION = 0x2000000,
    PCAN_ERROR_INITIALIZE = 0x4000000,
    PCAN_ERROR_ILLOPERATION = 0x8000000,
}
C++ / CLR
[Flags]
public enum class TPCANStatus : UInt32
{
    PCAN_ERROR_OK = 0x00000,
    PCAN_ERROR_XMTFULL = 0x00001,
    PCAN_ERROR_OVERRUN = 0x00002,
    PCAN_ERROR_BUSLIGHT = 0x00004,
    PCAN_ERROR_BUSHEAVY = 0x00008,
    PCAN_ERROR_BUSWARNING   = PCAN_ERROR_BUSHEAVY,
    PCAN_ERROR_BUSPASSIVE = 0x40000,
    PCAN_ERROR_BUSOFF = 0x00010,
    PCAN_ERROR_ANYBUSERR = (PCAN_ERROR_BUSWARNING | PCAN_ERROR_BUSLIGHT | PCAN_ERROR_BUSHEAVY | PCAN_ERROR_BUSOFF | PCAN_ERROR_BUSPASSIVE),
    PCAN_ERROR_QRCVEMPTY = 0x00020,
    PCAN_ERROR_QOVERRUN = 0x00040,
    PCAN_ERROR_QXMTFULL = 0x00080,
    PCAN_ERROR_REGTEST = 0x00100,
    PCAN_ERROR_NODRIVER = 0x00200,
    PCAN_ERROR_HWINUSE = 0x00400,
    PCAN_ERROR_NETINUSE = 0x00800,
    PCAN_ERROR_ILLHW = 0x01400,
    PCAN_ERROR_ILLNET = 0x01800,
    PCAN_ERROR_ILLCLIENT = 0x01C00,
    PCAN_ERROR_ILLHANDLE = (PCAN_ERROR_ILLHW | PCAN_ERROR_ILLNET | PCAN_ERROR_ILLCLIENT),
    PCAN_ERROR_RESOURCE = 0x02000,
    PCAN_ERROR_ILLPARAMTYPE = 0x04000,
    PCAN_ERROR_ILLPARAMVAL = 0x08000,
    PCAN_ERROR_UNKNOWN = 0x10000,
    PCAN_ERROR_ILLDATA = 0x20000,
    PCAN_ERROR_ILLMODE = 0x80000,
    PCAN_ERROR_CAUTION = 0x2000000,
    PCAN_ERROR_INITIALIZE = 0x4000000,
    PCAN_ERROR_ILLOPERATION = 0x8000000,
}
Visual Basic
<Flags()> _
Public Enum TPCANStatus As UInt32
    PCAN_ERROR_OK = &H0
    PCAN_ERROR_XMTFULL = &H1
    PCAN_ERROR_OVERRUN = &H2
    PCAN_ERROR_BUSLIGHT = &H4
    PCAN_ERROR_BUSHEAVY = &H8
    PCAN_ERROR_BUSWARNING = PCAN_ERROR_BUSHEAVY
    PCAN_ERROR_BUSPASSIVE = &H40000
    PCAN_ERROR_BUSOFF = &H10
    PCAN_ERROR_ANYBUSERR = (PCAN_ERROR_BUSWARNING Or PCAN_ERROR_BUSLIGHT Or PCAN_ERROR_BUSHEAVY Or PCAN_ERROR_BUSOFF Or PCAN_ERROR_BUSPASSIVE)
    PCAN_ERROR_QRCVEMPTY = &H20
    PCAN_ERROR_QOVERRUN = &H40
    PCAN_ERROR_QXMTFULL = &H80
    PCAN_ERROR_REGTEST = &H100
    PCAN_ERROR_NODRIVER = &H200
    PCAN_ERROR_HWINUSE = &H400
    PCAN_ERROR_NETINUSE = &H800
    PCAN_ERROR_ILLHW = &H1400
    PCAN_ERROR_ILLNET = &H1800
    PCAN_ERROR_ILLCLIENT = &H1C00
    PCAN_ERROR_ILLHANDLE = (PCAN_ERROR_ILLHW Or PCAN_ERROR_ILLNET Or PCAN_ERROR_ILLCLIENT)
    PCAN_ERROR_RESOURCE = &H2000
    PCAN_ERROR_ILLPARAMTYPE = &H4000
    PCAN_ERROR_ILLPARAMVAL = &H8000
    PCAN_ERROR_UNKNOWN = &H10000
    PCAN_ERROR_ILLDATA = &H20000
    PCAN_ERROR_ILLMODE = &H80000
    PCAN_ERROR_CAUTION = &H2000000
    PCAN_ERROR_INITIALIZE = &H4000000
    PCAN_ERROR_ILLOPERATION = &H8000000
End Enum
Python
TPCANStatus = int

PCAN_ERROR_OK = TPCANStatus(0x00000)
PCAN_ERROR_XMTFULL = TPCANStatus(0x00001)
PCAN_ERROR_OVERRUN = TPCANStatus(0x00002
PCAN_ERROR_BUSLIGHT = TPCANStatus(0x00004)
PCAN_ERROR_BUSHEAVY = TPCANStatus(0x00008)
PCAN_ERROR_BUSWARNING = TPCANStatus(PCAN_ERROR_BUSHEAVY)
PCAN_ERROR_BUSPASSIVE = TPCANStatus(0x40000)
PCAN_ERROR_BUSOFF = TPCANStatus(0x00010)
PCAN_ERROR_ANYBUSERR = TPCANStatus(PCAN_ERROR_BUSWARNING | PCAN_ERROR_BUSLIGHT | PCAN_ERROR_BUSHEAVY | PCAN_ERROR_BUSOFF | PCAN_ERROR_BUSPASSIVE)
PCAN_ERROR_QRCVEMPTY = TPCANStatus(0x00020)
PCAN_ERROR_QOVERRUN = TPCANStatus(0x00040)
PCAN_ERROR_QXMTFULL = TPCANStatus(0x00080)
PCAN_ERROR_REGTEST = TPCANStatus(0x00100)
PCAN_ERROR_NODRIVER = TPCANStatus(0x00200)
PCAN_ERROR_HWINUSE = TPCANStatus(0x00400)
PCAN_ERROR_NETINUSE = TPCANStatus(0x00800)
PCAN_ERROR_ILLHW = TPCANStatus(0x01400)
PCAN_ERROR_ILLNET = TPCANStatus(0x01800)
PCAN_ERROR_ILLCLIENT = TPCANStatus(0x01C00)
PCAN_ERROR_ILLHANDLE = TPCANStatus(PCAN_ERROR_ILLHW | PCAN_ERROR_ILLNET | PCAN_ERROR_ILLCLIENT)
PCAN_ERROR_RESOURCE = TPCANStatus(0x02000)
PCAN_ERROR_ILLPARAMTYPE = TPCANStatus(0x04000)
PCAN_ERROR_ILLPARAMVAL = TPCANStatus(0x08000)
PCAN_ERROR_UNKNOWN = TPCANStatus(0x10000)
PCAN_ERROR_ILLDATA = TPCANStatus(0x20000)
PCAN_ERROR_ILLMODE = TPCANStatus(0x80000)
PCAN_ERROR_CAUTION = TPCANStatus(0x2000000)
PCAN_ERROR_INITIALIZE = TPCANStatus(0x4000000)
PCAN_ERROR_ILLOPERATION = TPCANStatus(0x8000000)
Remarks

Note that the values of the different PCAN-Status definitions are able to be bitwise combined. In some cases it is possible to get more than one error code as result of calling a function.

*Note that the values of PCAN_ERROR_INITIALIZE and PCAN_ERROR_ILLOPERATION were changed!

PCAN_ERROR_INITIALIZE changed from 0x40000 to 0x4000000

PCAN_ERROR_ILLOPERATION changed from 0x80000 to 0x8000000

Values
Name | Value | Description
PCAN_ERROR_OK | 0x00000 (000000) | No error. Success.
PCAN_ERROR_XMTFULL | 0x00001 (000001) | Transmit buffer in CAN controller is full.
PCAN_ERROR_OVERRUN | 0x00002 (000002) | CAN controller was read too late.
PCAN_ERROR_BUSLIGHT | 0x00004 (000004) | Bus error: an error counter reached the 'light' limit.
PCAN_ERROR_BUSHEAVY | 0x00008 (000008) | Bus error: an error counter reached the 'heavy' limit.
PCAN_ERROR_BUSWARNING | 0x00008 (000008) | Bus error: an error counter reached the 'warning' limit.
PCAN_ERROR_BUSPASSIVE | 0x40000 (262144) | Bus error: the CAN controller is error passive.
PCAN_ERROR_BUSOFF | 0x00010 (000016) | Bus error: the CAN controller is in bus-off state.
PCAN_ERROR_ANYBUSERR | 0x4001C (262172) | Mask for all bus errors.
PCAN_ERROR_QRCVEMPTY | 0x00020 (000032) | Receive queue is empty.
PCAN_ERROR_QOVERRUN | 0x00040 (000064) | Receive queue was read too late.
PCAN_ERROR_QXMTFULL | 0x00080 (000128) | Transmit queue is full.
PCAN_ERROR_REGTEST | 0x00100 (000256) | Test of the CAN controller hardware registers failed (no hardware found).
PCAN_ERROR_NODRIVER | 0x00200 (000512) | Driver not loaded.
PCAN_ERROR_HWINUSE | 0x00400 (001024) | PCAN-Hardware already in use by a PCAN-Net.
PCAN_ERROR_NETINUSE | 0x00800 (002048) | A PCAN-Client is already connected to the PCAN-Net.
PCAN_ERROR_ILLHW | 0x01400 (005120) | PCAN-Hardware handle is invalid.
PCAN_ERROR_ILLNET | 0x01800 (006144) | PCAN-Net handle is invalid.
PCAN_ERROR_ILLCLIENT | 0x01C00 (007168) | PCAN-Client handle is invalid.
PCAN_ERROR_ILLHANDLE | 0x01C00 (007168) | Mask for all handle errors.
PCAN_ERROR_RESOURCE | 0x02000 (008192) | Resource (FIFO, Client, timeout) cannot be created.
PCAN_ERROR_ILLPARAMTYPE | 0x04000 (016384) | Invalid parameter.
PCAN_ERROR_ILLPARAMVAL | 0x08000 (032768) | Invalid parameter value.
PCAN_ERROR_UNKNOWN | 0x10000 (065536) | Unknown error
PCAN_ERROR_ILLDATA | 0x20000 (131072) | Invalid data, function, or action.
PCAN_ERROR_ILLMODE | 0x80000 (524288) | Driver object state is wrong for the attempted operation.
PCAN_ERROR_CAUTION | 0x2000000 (33554432) | Operation succeeded but with irregularities.
PCAN_ERROR_INITIALIZE* | 0x4000000 (67108864) | Channel is not initialized.
PCAN_ERROR_ILLOPERATION* | 0x8000000 (134217728) | Invalid operation.


TPCANDevice

TPCANDevice

Represents a PCAN device. According with the programming language, this type can be a group of defined values or an enumeration.

Syntax
C++
#define TPCANDevice BYTE

#define PCAN_NONE 0x00
#define PCAN_PEAKCAN 0x01
#define PCAN_ISA 0x02
#define PCAN_DNG 0x03
#define PCAN_PCI 0x04
#define PCAN_USB 0x05
#define PCAN_PCC 0x06
#define PCAN_VIRTUAL 0x07
#define PCAN_LAN 0x08
Pascal OO
{$Z1}
TPCANDevice = (
    PCAN_NONE = 0,
    PCAN_PEAKCAN = 1,
    PCAN_ISA = 2,
    PCAN_DNG = 3,
    PCAN_PCI = 4,
    PCAN_USB = 5,
    PCAN_PCC = 6,
    PCAN_VIRTUAL = 7,
    PCAN_LAN = 8
);
C#
public enum TPCANDevice : byte
{
    PCAN_NONE = 0,
    PCAN_PEAKCAN = 1,
    PCAN_ISA = 2,
    PCAN_DNG = 3,
    PCAN_PCI = 4,
    PCAN_USB = 5,
    PCAN_PCC = 6,
    PCAN_VIRTUAL = 7,
    PCAN_LAN = 8
}
C++ / CLR
public enum class TPCANDevice : Byte
{
    PCAN_NONE = 0,
    PCAN_PEAKCAN = 1,
    PCAN_ISA = 2,
    PCAN_DNG = 3,
    PCAN_PCI = 4,
    PCAN_USB = 5,
    PCAN_PCC = 6,
    PCAN_VIRTUAL = 7,
    PCAN_LAN = 8
};
Visual Basic
Public Enum TPCANDevice As Byte
    PCAN_NONE = 0
    PCAN_PEAKCAN = 1
    PCAN_ISA = 2
    PCAN_DNG = 3
    PCAN_PCI = 4
    PCAN_USB = 5
    PCAN_PCC = 6
    PCAN_VIRTUAL = 7
    PCAN_LAN = 8
End Enum
Python
TPCANDevice = c_ubyte

PCAN_NONE = TPCANDevice(0x00)
PCAN_PEAKCAN = TPCANDevice(0x01)
PCAN_ISA = TPCANDevice(0x02)
PCAN_DNG = TPCANDevice(0x03)
PCAN_PCI = TPCANDevice(0x04)
PCAN_USB = TPCANDevice(0x05)
PCAN_PCC = TPCANDevice(0x06)
PCAN_VIRTUAL = TPCANDevice(0x07)
PCAN_LAN = TPCANDevice(0x08)
Remarks

The PCAN-Devices PCAN_PEAKCAN and PCAN_VIRTUAL are not used within the PCAN-Basic API.

Values
Name | Value | Description
PCAN_NONE | 0 | Undefined, unknown or not selected PCAN device value.
PCAN_PEAKCAN | 1 | PCAN Non-Plug And Play devices. NOT USED WITHIN PCAN-Basic API.
PCAN_ISA | 2 | PCAN-ISA, PCAN-PC/104.
PCAN_DNG | 3 | PCAN-Dongle.
PCAN_PCI | 4 | PCAN-PCI, PCAN-cPCI, PCAN-miniPCI, PCAN-PC/104-Plus, and PCAN-PCI Express.
PCAN_USB | 5 | PCAN-USB and PCAN-USB Pro.
PCAN_PCC | 6 | PCAN-PC Card.
PCAN_VIRTUAL | 7 | PCAN Virtual hardware. NOT USED WITHIN PCAN-Basic API.
PCAN_LAN | 8 | PCAN Gateway devices.


TPCANParameter

TPCANParameter

Represents a PCAN parameter or a PCAN Value that can be read or set. According with the programming language, this type can be a group of defined values or an enumeration. With some exceptions, a channel must first be initialized before their parameters can be read or set. Syntax

C++
#define TPCANParameter BYTE

#define PCAN_DEVICE_ID 0x01
#define PCAN_5VOLTS_POWER 0x02
#define PCAN_RECEIVE_EVENT 0x03
#define PCAN_MESSAGE_FILTER 0x04
#define PCAN_API_VERSION 0x05
#define PCAN_CHANNEL_VERSION 0x06
#define PCAN_BUSOFF_AUTORESET 0x07
#define PCAN_LISTEN_ONLY 0x08
#define PCAN_LOG_LOCATION 0x09
#define PCAN_LOG_STATUS 0x0A
#define PCAN_LOG_CONFIGURE 0x0B
#define PCAN_LOG_TEXT 0x0C
#define PCAN_CHANNEL_CONDITION 0x0D
#define PCAN_HARDWARE_NAME 0x0E
#define PCAN_RECEIVE_STATUS 0x0F
#define PCAN_CONTROLLER_NUMBER 0x10
#define PCAN_TRACE_LOCATION 0x11
#define PCAN_TRACE_STATUS 0x12
#define PCAN_TRACE_SIZE 0x13
#define PCAN_TRACE_CONFIGURE 0x14
#define PCAN_CHANNEL_IDENTIFYING 0x15
#define PCAN_CHANNEL_FEATURES 0x16
#define PCAN_BITRATE_ADAPTING 0x17
#define PCAN_BITRATE_INFO = 0x18
#define PCAN_BITRATE_INFO_FD = 0x19
#define PCAN_BUSSPEED_NOMINAL = 0x1A
#define PCAN_BUSSPEED_DATA = 0x1B
#define PCAN_IP_ADDRESS = 0x1C
#define PCAN_LAN_SERVICE_STATUS = 0x1D
#define PCAN_ALLOW_STATUS_FRAMES = 0x1E
#define PCAN_ALLOW_RTR_FRAMES = 0x1F
#define PCAN_ALLOW_ERROR_FRAMES = 0x20
#define PCAN_INTERFRAME_DELAY = 0x21
#define PCAN_ACCEPTANCE_FILTER_11BIT = 0x22
#define PCAN_ACCEPTANCE_FILTER_29BIT = 0x23
#define PCAN_IO_DIGITAL_CONFIGURATION = 0x24
#define PCAN_IO_DIGITAL_VALUE = 0x25
#define PCAN_IO_DIGITAL_SET = 0x26
#define PCAN_IO_DIGITAL_CLEAR = 0x27
#define PCAN_IO_ANALOG_VALUE = 0x28
#define PCAN_FIRMWARE_VERSION = 0x29
#define PCAN_ATTACHED_CHANNELS_COUNT = 0x2A
#define PCAN_ATTACHED_CHANNELS = 0x2B
#define PCAN_ALLOW_ECHO_FRAMES = 0x2C
#define PCAN_DEVICE_PART_NUMBER = 0x2D
Pascal OO
{$Z1}
TPCANParameter = (
    PCAN_DEVICE_ID = 1,
    PCAN_5VOLTS_POWER = 2,
    PCAN_RECEIVE_EVENT = 3,
    PCAN_MESSAGE_FILTER = 4,
    PCAN_API_VERSION = 5,
    PCAN_CHANNEL_VERSION = 6,
    PCAN_BUSOFF_AUTORESET = 7,
    PCAN_LISTEN_ONLY = 8,
    PCAN_LOG_LOCATION = 9,
    PCAN_LOG_STATUS = 10,
    PCAN_LOG_CONFIGURE = 11,
    PCAN_LOG_TEXT = 12,
    PCAN_CHANNEL_CONDITION = 13,
    PCAN_HARDWARE_NAME = 14,
    PCAN_RECEIVE_STATUS = 15,
    PCAN_CONTROLLER_NUMBER = 16,
    PCAN_TRACE_LOCATION = 17,
    PCAN_TRACE_STATUS = 18,
    PCAN_TRACE_SIZE = 19,
    PCAN_TRACE_CONFIGURE = 20,
    PCAN_CHANNEL_IDENTIFYING = 21,
    PCAN_CHANNEL_FEATURES = 22,
    PCAN_BITRATE_ADAPTING = 23,
    PCAN_BITRATE_INFO = 24,
    PCAN_BITRATE_INFO_FD = 25,
    PCAN_BUSSPEED_NOMINAL = 26,
    PCAN_BUSSPEED_DATA = 27,
    PCAN_IP_ADDRESS = 28,
    PCAN_LAN_SERVICE_STATUS = 29,
    PCAN_ALLOW_STATUS_FRAMES = 30,
    PCAN_ALLOW_RTR_FRAMES = 31,
    PCAN_ALLOW_ERROR_FRAMES = 32,
    PCAN_INTERFRAME_DELAY = 33,
    PCAN_ACCEPTANCE_FILTER_11BIT = 34,
    PCAN_ACCEPTANCE_FILTER_29BIT = 35,
    PCAN_IO_DIGITAL_CONFIGURATION = 36,
    PCAN_IO_DIGITAL_VALUE = 37,
    PCAN_IO_DIGITAL_SET = 38,
    PCAN_IO_DIGITAL_CLEAR = 39,
    PCAN_IO_ANALOG_VALUE = 40,
    PCAN_FIRMWARE_VERSION = 41,
    PCAN_ATTACHED_CHANNELS_COUNT = 42,
    PCAN_ATTACHED_CHANNELS = 43,
    PCAN_ALLOW_ECHO_FRAMES = 44,
    PCAN_DEVICE_PART_NUMBER = 45
);
C#
public enum TPCANParameter : byte
{
    PCAN_DEVICE_NUMBER = 1,
    PCAN_5VOLTS_POWER = 2,
    PCAN_RECEIVE_EVENT = 3,
    PCAN_MESSAGE_FILTER = 4,
    PCAN_API_VERSION = 5,
    PCAN_CHANNEL_VERSION = 6,
    PCAN_BUSOFF_AUTORESET = 7,
    PCAN_LISTEN_ONLY = 8,
    PCAN_LOG_LOCATION = 9,
    PCAN_LOG_STATUS = 10,
    PCAN_LOG_CONFIGURE = 11,
    PCAN_LOG_TEXT = 12,
    PCAN_CHANNEL_CONDITION = 13,
    PCAN_HARDWARE_NAME = 14,
    PCAN_RECEIVE_STATUS = 15,
    PCAN_CONTROLLER_NUMBER = 16,
    PCAN_TRACE_LOCATION = 17,
    PCAN_TRACE_STATUS = 18,
    PCAN_TRACE_SIZE = 19,
    PCAN_TRACE_CONFIGURE = 20,
    PCAN_CHANNEL_IDENTIFYING = 21,
    PCAN_CHANNEL_FEATURES = 22,
    PCAN_BITRATE_ADAPTING = 23,
    PCAN_BITRATE_INFO = 24,
    PCAN_BITRATE_INFO_FD = 25,
    PCAN_BUSSPEED_NOMINAL = 26,
    PCAN_BUSSPEED_DATA = 27,
    PCAN_IP_ADDRESS = 28,
    PCAN_LAN_SERVICE_STATUS = 29,
    PCAN_ALLOW_STATUS_FRAMES = 30,
    PCAN_ALLOW_RTR_FRAMES = 31,
    PCAN_ALLOW_ERROR_FRAMES = 32,
    PCAN_INTERFRAME_DELAY = 33,
    PCAN_ACCEPTANCE_FILTER_11BIT = 34,
    PCAN_ACCEPTANCE_FILTER_29BIT = 35,
    PCAN_IO_DIGITAL_CONFIGURATION = 36,
    PCAN_IO_DIGITAL_VALUE = 37,
    PCAN_IO_DIGITAL_SET = 38,
    PCAN_IO_DIGITAL_CLEAR = 39,
    PCAN_IO_ANALOG_VALUE = 40,
    PCAN_FIRMWARE_VERSION = 41,
    PCAN_ATTACHED_CHANNELS_COUNT = 42,
    PCAN_ATTACHED_CHANNELS = 43,
    PCAN_ALLOW_ECHO_FRAMES = 44,
    PCAN_DEVICE_PART_NUMBER = 45,
}
C++ / CLR
public enum class TPCANParameter : Byte
{
    PCAN_DEVICE_ID = 1,
    PCAN_5VOLTS_POWER = 2,
    PCAN_RECEIVE_EVENT = 3,
    PCAN_MESSAGE_FILTER = 4,
    PCAN_API_VERSION = 5,
    PCAN_CHANNEL_VERSION = 6,
    PCAN_BUSOFF_AUTORESET = 7,
    PCAN_LISTEN_ONLY = 8,
    PCAN_LOG_LOCATION = 9,
    PCAN_LOG_STATUS = 10,
    PCAN_LOG_CONFIGURE = 11,
    PCAN_LOG_TEXT = 12,
    PCAN_CHANNEL_CONDITION = 13,
    PCAN_HARDWARE_NAME = 14,
    PCAN_RECEIVE_STATUS = 15,
    PCAN_CONTROLLER_NUMBER = 16,
    PCAN_TRACE_LOCATION = 17,
    PCAN_TRACE_STATUS = 18,
    PCAN_TRACE_SIZE = 19,
    PCAN_TRACE_CONFIGURE = 20,
    PCAN_CHANNEL_IDENTIFYING = 21,
    PCAN_CHANNEL_FEATURES = 22,
    PCAN_BITRATE_ADAPTING = 23,
    PCAN_BITRATE_INFO = 24,
    PCAN_BITRATE_INFO_FD = 25,
    PCAN_BUSSPEED_NOMINAL = 26,
    PCAN_BUSSPEED_DATA = 27,
    PCAN_IP_ADDRESS = 28,
    PCAN_LAN_SERVICE_STATUS = 29,
    PCAN_ALLOW_STATUS_FRAMES = 30,
    PCAN_ALLOW_RTR_FRAMES = 31,
    PCAN_ALLOW_ERROR_FRAMES = 32,
    PCAN_INTERFRAME_DELAY = 33,
    PCAN_ACCEPTANCE_FILTER_11BIT = 34,
    PCAN_ACCEPTANCE_FILTER_29BIT = 35,
    PCAN_IO_DIGITAL_CONFIGURATION = 36,
    PCAN_IO_DIGITAL_VALUE = 37,
    PCAN_IO_DIGITAL_SET = 38,
    PCAN_IO_DIGITAL_CLEAR = 39,
    PCAN_IO_ANALOG_VALUE = 40,
    PCAN_FIRMWARE_VERSION = 41,
    PCAN_ATTACHED_CHANNELS_COUNT = 42,
    PCAN_ATTACHED_CHANNELS = 43,
    PCAN_ALLOW_ECHO_FRAMES = 44,
    PCAN_DEVICE_PART_NUMBER = 45,
};
Visual Basic
Public Enum TPCANParameter As Byte
    PCAN_DEVICE_ID = 1
    PCAN_5VOLTS_POWER = 2
    PCAN_RECEIVE_EVENT = 3
    PCAN_MESSAGE_FILTER = 4
    PCAN_API_VERSION = 5
    PCAN_CHANNEL_VERSION = 6
    PCAN_BUSOFF_AUTORESET = 7
    PCAN_LISTEN_ONLY = 8
    PCAN_LOG_LOCATION = 9
    PCAN_LOG_STATUS = 10
    PCAN_LOG_CONFIGURE = 11
    PCAN_LOG_TEXT = 12
    PCAN_CHANNEL_CONDITION = 13
    PCAN_HARDWARE_NAME = 14
    PCAN_RECEIVE_STATUS = 15
    PCAN_CONTROLLER_NUMBER = 16
    PCAN_TRACE_LOCATION = 17
    PCAN_TRACE_STATUS = 18
    PCAN_TRACE_SIZE = 19
    PCAN_TRACE_CONFIGURE = 20
    PCAN_CHANNEL_IDENTIFYING = 21
    PCAN_CHANNEL_FEATURES = 22
    PCAN_BITRATE_ADAPTING = 23
    PCAN_BITRATE_INFO = 24
    PCAN_BITRATE_INFO_FD = 25
    PCAN_BUSSPEED_NOMINAL = 26
    PCAN_BUSSPEED_DATA = 27
    PCAN_IP_ADDRESS = 28
    PCAN_LAN_SERVICE_STATUS = 29
    PCAN_ALLOW_STATUS_FRAMES = 30
    PCAN_ALLOW_RTR_FRAMES = 31
    PCAN_ALLOW_ERROR_FRAMES = 32
    PCAN_INTERFRAME_DELAY = 33
    PCAN_ACCEPTANCE_FILTER_11BIT = 34
    PCAN_ACCEPTANCE_FILTER_29BIT = 35
    PCAN_IO_DIGITAL_CONFIGURATION = 36
    PCAN_IO_DIGITAL_VALUE = 37
    PCAN_IO_DIGITAL_SET = 38
    PCAN_IO_DIGITAL_CLEAR = 39
    PCAN_IO_ANALOG_VALUE = 40
    PCAN_FIRMWARE_VERSION = 41
    PCAN_ATTACHED_CHANNELS_COUNT = 42
    PCAN_ATTACHED_CHANNELS = 43
    PCAN_ALLOW_ECHO_FRAMES = 44
    PCAN_DEVICE_PART_NUMBER = 45
End Enum
Python
TPCANParameter = c_ubyte

PCAN_DEVICE_ID = TPCANParameter(0x01)
PCAN_5VOLTS_POWER = TPCANParameter(0x02)
PCAN_RECEIVE_EVENT = TPCANParameter(0x03)
PCAN_MESSAGE_FILTER = TPCANParameter(0x04)
PCAN_API_VERSION = TPCANParameter(0x05)
PCAN_CHANNEL_VERSION = TPCANParameter(0x06)
PCAN_BUSOFF_AUTORESET = TPCANParameter(0x07)
PCAN_LISTEN_ONLY = TPCANParameter(0x08)
PCAN_LOG_LOCATION = TPCANParameter(0x09)
PCAN_LOG_STATUS = TPCANParameter(0x0A)
PCAN_LOG_CONFIGURE = TPCANParameter(0x0B)
PCAN_LOG_TEXT = TPCANParameter(0x0C)
PCAN_CHANNEL_CONDITION = TPCANParameter(0x0D)
PCAN_HARDWARE_NAME = TPCANParameter(0x0E)
PCAN_RECEIVE_STATUS = TPCANParameter(0x0F)
PCAN_CONTROLLER_NUMBER = TPCANParameter(0x10)
PCAN_TRACE_LOCATION = TPCANParameter(0x11)
PCAN_TRACE_STATUS = TPCANParameter(0x12)
PCAN_TRACE_SIZE = TPCANParameter(0x13)
PCAN_TRACE_CONFIGURE = TPCANParameter(0x14)
PCAN_CHANNEL_IDENTIFYING = TPCANParameter(0x15)
PCAN_CHANNEL_FEATURES = TPCANParameter(0x16)
PCAN_BITRATE_ADAPTING = TPCANParameter(0x17)
PCAN_BITRATE_INFO = TPCANParameter(0x18)
PCAN_BITRATE_INFO_FD = TPCANParameter(0x19)
PCAN_BUSSPEED_NOMINAL = TPCANParameter(0x1A)
PCAN_BUSSPEED_DATA = TPCANParameter(0x1B)
PCAN_IP_ADDRESS = TPCANParameter(0x1C)
PCAN_LAN_SERVICE_STATUS = TPCANParameter(0x1D)
PCAN_ALLOW_STATUS_FRAMES = TPCANParameter(0x1E)
PCAN_ALLOW_RTR_FRAMES = TPCANParameter(0x1F)
PCAN_ALLOW_ERROR_FRAMES = TPCANParameter(0x20)
PCAN_INTERFRAME_DELAY = TPCANParameter(0x21)
PCAN_ACCEPTANCE_FILTER_11BIT = TPCANParameter(0x22)
PCAN_ACCEPTANCE_FILTER_29BIT = TPCANParameter(0x23)
PCAN_IO_DIGITAL_CONFIGURATION = TPCANParameter(0x24)
PCAN_IO_DIGITAL_VALUE = TPCANParameter(0x25)
PCAN_IO_DIGITAL_SET = TPCANParameter(0x26)
PCAN_IO_DIGITAL_CLEAR = TPCANParameter(0x27)
PCAN_IO_ANALOG_VALUE = TPCANParameter(0x28)
PCAN_FIRMWARE_VERSION = TPCANParameter(0x29)
PCAN_ATTACHED_CHANNELS_COUNT = TPCANParameter(0x2A)
PCAN_ATTACHED_CHANNELS = TPCANParameter(0x2B)
PCAN_ALLOW_ECHO_FRAMES = TPCANParameter(0x2C)
PCAN_DEVICE_PART_NUMBER = TPCANParameter(0x2D)
Values

Name | Value | Data Type | Description
PCAN_DEVICE_ID | 1 | Integer | Device identifier parameter.
PCAN_5VOLTS_POWER | 2 | Integer | PCAN "5-volt power" parameter.
PCAN_RECEIVE_EVENT | 3 | Handle | PCAN receive event handler parameter.
PCAN_MESSAGE_FILTER | 4 | Integer | PCAN message filter parameter.
PCAN_API_VERSION | 5 | String | PCAN-Basic API version parameter.
PCAN_CHANNEL_VERSION | 6 | String | PCAN device channel version parameter.
PCAN_BUSOFF_AUTORESET | 7 | Integer | PCAN "reset on bus-off" parameter.
PCAN_LISTEN_ONLY | 8 | Integer | PCAN "listen-only" parameter.
PCAN_LOG_LOCATION | 9 | String | Directory path for log files.
PCAN_LOG_STATUS | 10 | Integer | Debug-Log activation status.
PCAN_LOG_CONFIGURE | 11 | Integer | Configuration of the debugged information (LOG_FUNCTION_***).
PCAN_LOG_TEXT | 12 | String | Custom insertion of text into the log file.
PCAN_CHANNEL_CONDITION | 13 | Integer | Availability status of a PCAN-Channel.
PCAN_HARDWARE_NAME | 14 | String | PCAN "hardware name" parameter.
PCAN_RECEIVE_STATUS | 15 | Integer | "Receive Status" parameter for incoming messages.
PCAN_CONTROLLER_NUMBER | 16 | Integer | Index of a CAN-Controller in a PCAN device.
PCAN_TRACE_LOCATION | 17 | String | Directory path for PCAN trace files.
PCAN_TRACE_STATUS | 18 | Integer | PCAN-Trace activation status.
PCAN_TRACE_SIZE | 19 | Integer | Configuration of the maximum size for a PCAN-Trace.
PCAN_TRACE_CONFIGURE | 20 | Integer | Configuration of the trace file storing modes (TRACE_FILE_***).
PCAN_CHANNEL_IDENTIFYING | 21 | Integer | USB Channel Identifying activation status.
PCAN_CHANNEL_FEATURES | 22 | Integer | Capabilities of a PCAN device (FEATURE_***).
PCAN_BITRATE_ADAPTING | 23 | Integer | Attachment to an existing connection with unknown/different bit rate.
PCAN_BITRATE_INFO | 24 | Integer | Current bit rate as BTR0BTR1 value (Standard CAN).
PCAN_BITRATE_INFO_FD | 25 | String | Current bit rate as FD String value (CAN-FD).
PCAN_BUSSPEED_NOMINAL | 26 | Integer | Current nominal CAN bus speed in bits/second.
PCAN_BUSSPEED_DATA | 27 | Integer | Current CAN data speed in bits/second.
PCAN_IP_ADDRESS | 28 | String | Remote address as a IPv4 formated string.
PCAN_LAN_SERVICE_STATUS | 29 | Integer | Running status of the LAN Service (Virtual PCAN-Gateway)
PCAN_ALLOW_STATUS_FRAMES | 30 | Integer | "Receive Status" parameter for Status frames.
PCAN_ALLOW_RTR_FRAMES | 31 | Integer | "Receive Status" parameter for RTR frames.
PCAN_ALLOW_ERROR_FRAMES | 32 | Integer | "Receive Status" parameter for Error frames.
PCAN_INTERFRAME_DELAY | 33 | Integer | Delay, in microseconds, between sending frames.
PCAN_ACCEPTANCE_FILTER_11BIT | 34 | 64-Bit Integer | Acceptance filter over code and mask for 11-bit CAN IDs.
PCAN_ACCEPTANCE_FILTER_29BIT | 35 | 64-Bit Integer | Acceptance filter over code and mask for 29-bit CAN IDs.
PCAN_IO_DIGITAL_CONFIGURATION | 36 | Integer | Activation of digital pins as outputs.
PCAN_IO_DIGITAL_VALUE | 37 | Integer | Multiple setting of digital pin values.
PCAN_IO_DIGITAL_SET | 38 | Integer | Selective setting of digital pin values to "high".
PCAN_IO_DIGITAL_CLEAR | 39 | Integer | Selective setting of digital pin values to "low".
PCAN_IO_ANALOG_VALUE | 40 | Integer | Value reading of a single analog pin.
PCAN_FIRMWARE_VERSION | 41 | String | Firmware version of a PCAN device.
PCAN_ATTACHED_CHANNELS_COUNT | 42 | Integer | Amount of PCAN channels attached to a system.
PCAN_ATTACHED_CHANNELS | 43 | Array of TPCANChannelInformation | Information about PCAN channels attached to a system.
PCAN_ALLOW_ECHO_FRAMES | 44 | Integer | "Receive Status" parameter for Echo frames.
PCAN_DEVICE_PART_NUMBER | 45 | String | PEAK's device part number (IPEH number).
Characteristics

PCAN_DEVICE_ID

Access:

Channel status:

  • For Read: The channel can be initialized or uninitialized.
  • For Write: The channel must be initialized to be able to set this parameter.

Description: This parameter is used on PCAN hardware to distinguish between 2 (or more) devices of the same type connected to the same computer. This value is persistent, i.e. the identifier will not be lost after disconnecting and connecting again a device.

Possible values: According with the firmware version, this value can be a number in the range [1..255] or [1..4294967295].

Default value: If this parameter was never set before, the value is the maximum value possible for the used resolution. For 8-bits: 255 (FFh), for 32 bits: 4294967295 (FFFFFFFFh).

PCAN-Device: PCAN-USB, PCAN-PCI, PCAN-LAN.

REMARKS:

  • This parameter was originally called PCAN_DEVICE_NUMBER.
  • PCAN-PCI: Only FPGA based devices. Requires a device driver version equal to or greater than 4.2.0.
  • PCAN-LAN: Only devices with a firmware version equal to or greater than 2.8.2. Requires a device driver version equal to or greater than 4.2.0.

PCAN_5VOLTS_POWER

Access:

Channel status:

  • For Read: The channel can be initialized or uninitialized.
  • For Write: The channel must be initialized to be able to set this parameter.

Description: This parameter is used for switching the external 5V on the D-Sub connector. This is useful when connecting external bus converter modules to the device (AU5790 / TJA1054)).

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: PCAN-PCC, PCAN-USB.

PCAN_RECEIVE_EVENT

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used to let the PCAN driver notify an application when CAN messages are placed in its receive queue. This way message processing tasks of an application can react faster and make a more efficient use of the processor time.

Possible values: This value has to be a handle for an event object returned by the Windows API function [image] CreateEvent or the value 0 (IntPtr.Zero in a managed environment). When setting this parameter, the value of 0 resets the parameter in the PCAN driver. When reading the value of 0 indicate that no event handle is set. For more information about reading with events, please refer to the topic Using Events.

Default value: Disabled (0).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_MESSAGE_FILTER

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter allows the user to easily configure the message filter of a PCAN channel. With it is possible to fully open or completely close the filter.

Possible values: When setting only two values are possible: PCAN_FILTER_OPEN, PCAN_FILTER_CLOSE. When reading it is possible to receive a third value, PCAN_FILTER_CUSTOM, which indicates that the filter is configured to receive a custom range of IDs. Note that other values will considered invalid.

Default value: Complete opened (PCAN_FILTER_OPEN).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_API_VERSION

Access:

Channel status: N/A.

Description: This parameter is used to get information about the PCAN-Basic API implementation version.

Possible values: The value is a null-terminated string indicating the version number of the API implementation. The returned text has the following form: x.x.x.x for major, minor, release and build. It represents the binary version of the API, within two 32-bit integers, defined by four 16-bit integers. The length of this text value will have a maximum length of 24 bytes, 5 bytes for represent each single version value, three separator characters ( , or . ) and the null-termination.

Default value: N/A.

PCAN-Device: N/A. All PCAN devices, including the PCAN_NONEBUS channel.

PCAN_CHANNEL_VERSION

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This parameter is used to get version information about the Driver of a PCAN Channel.

Possible values: The value is a null-terminated string which contains version number, driver name and copyright information about the driver used to handle with an specified PCAN channel. The length of the this text will have a maximum length of 256 bytes (null-termination included) .

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_BUSOFF_AUTORESET

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter instructs the PCAN driver to reset automatically the CAN controller of a PCAN channel when a bus-off state is detected. Since no communication is possible on a bus-off state, it is useful to let the driver to catch this event automatically and reset the controller, avoiding extra handling of this problem in an application.

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: Reseting the hardware has a duration of ~ 500 milliseconds. After receiving the PCAN_ERROR_BUSOFF error, an application should wait that time before trying to read or write again.

PCAN_LISTEN_ONLY

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This parameter allows the user to set a CAN hardware in Listen-Only mode. When this mode is set, the CAN controller doens't take part on active events (eg. transmit CAN messages) but stays in a passive mode (CAN monitor), in which it can analyse the traffic on the CAN bus used by a PCAN channel. See also the Philips Data Sheet "SJA1000 Stand-alone CAN controller".

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices* (excluding PCAN_NONEBUS) containing a SJA1000 CAN controller.

REMARKS: Configuring this parameter without having the channel initialized, does a so called "pre-initialization". This means that the channel will be set in Listen-Only mode as soon as possible, after it has been successfully connected, using CAN_Initialize (class-method: Initialize). Once the channel is disconnected, further initializations of this channel are done in normal mode. It is necessary to set this parameter again before each initialization process, if the behavior described before is required. This is useful to avoid or minimize arbitration problems when connecting to a CAN-network.

* The Listen-Only mode cannot be set for PCAN-LAN devices via this parameter. This setting can only be made directly on the device via its configuration interface.

PCAN_LOG_LOCATION

Access:

Channel status: N/A.

Description: This value is used to set the folder location on a computer for the Log-File generated by the PCAN-Basic API, within a debug session. Setting this value starts recording debug information automatically. If a debug session is running (a log file is being written), PCAN_LOG_LOCATION instructs the API to close the current log file and to start the process again with the new folder information. Note that the name of the log file cannot be specified, this name is fixed as PCANBasic.log.

Possible values: This value must be a fully-qualified and valid path to an existing directory on the executing computer. There is no limit for the length of the string but it is recommended to use a length not bigger than MAX_PATH. For more information see [image] Naming Files, Paths, and Namespaces.

Default value: Calling process's folder.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_LOG_STATUS

Access:

Channel status: N/A.

Description: This value is used to control the activity status of a debug session within the PCAN-Basic API. If the log status is set to ON without having set a location for the log file or without having configured the information to be traced, then the session process will start with the default values.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will be considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_LOG_CONFIGURE

Access:

Channel status: N/A.

Description: This value is used to configure the debug information to be included in the log file generated in a debug session within the PCAN-Basic API.

Possible values: The value must be one of the following values or a combination of them:

  • LOG_FUNCTION_DEFAULT: This value is always active. It defines the default information to be traced, which is an unexpected exception, like a memory access violation. After having configured the log with more options, this value can be used to reset that configuration, setting the log with its default value again. This kind of entry is marked with the word "EXCEPTION"* in the log file.
  • LOG_FUNCTION_ENTRY: This value causes an entry in the log file each time an API function is entered. This kind of entry is marked with the word "ENTRY"* in the log file.
  • LOG_FUNCTION_PARAMETERS: This value causes an entry in the log file each time an API function is entered, showing the name of the parameters passed to the function as well as their values. This kind of entry is marked with the word "PARAMETERS"* in the log file.
  • LOG_FUNCTION_LEAVE: This value causes an entry in the log file each time an API function is abandoned. This kind of entry is marked with the word "EXIT"* in the log file.
  • LOG_FUNCTION_WRITE: This value causes an entry in the log file each time a CAN message is written, using the function CAN_Write (class-method: Write). This kind of entry is marked with the word "CHANNEL 0xXX (Y)"* in the log file, where XX is the channel number in hex notation, and Y the word "OUT"* denoting the direction (outgoing). The complete CAN message is also represented as hex text.
  • LOG_FUNCTION_READ: This value causes an entry in the log file each time a CAN message is read, using the functions CAN_Read/CAN_ReadFD (class-methods: Read, ReadFD). This kind of entry is marked with the word "CHANNEL 0xXX (Y)"* in the log file, where XX is the channel number in hex notation, and Y the word "IN"* denoting the direction (incoming). The complete CAN message is also represented as hex text.

* Note that the PCAN-Basic API supports several languages. The log file uses the language of the operating system. If this language is not one of the supported languages, English will be used.

* These words are always written in English, independently of the operating system's language.

Default value: Exceptions and Errors (LOG_FUNCTION_DEFAULT).

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_LOG_TEXT

Access:

Channel status: N/A.

Description: This value is used to insert custom information in the log file generated in a debug session within the PCAN-Basic API. Setting this value starts recording debug information automatically.

This is very useful when it is desired to specially mark places of an application's execution path while debugging PCAN-Basic tasks. Furthermore, an application could use this feature as an own Log file. To do so, just use the default log's configuration (PCAN_LOG_CONFIGURE set to LOG_FUNCTION_DEFAULT) and include the desired information using PCAN_LOG_TEXT. In this way the log file will contain only user-defined debug information. Note that the name of the log file cannot be specified, this name is fixed as PCANBasic.log.

Possible values: This value must be a null-terminated string. There is no limit for the length of the string but it is recommended to use a length not bigger than MAX_PATH. For more information see [image] Naming Files, Paths, and Namespaces.

Default value: N/A.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_CHANNEL_CONDITION

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This parameter is used to check and detect available PCAN hardware on a computer, even before trying to connect any of them. This is useful when an application wants the user to select which hardware should be used in a communication session.

Possible values: This parameter can have one of these values: PCAN_CHANNEL_UNAVAILABLE, PCAN_CHANNEL_AVAILABLE, PCAN_CHANNEL_OCCUPIED, PCAN_CHANNEL_PCANVIEW.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_HARDWARE_NAME

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This parameter is used to retrieve the name of the hardware represented by a PCAN channel. This is useful when an application wants to differentiate between several models of the same device, e.g. a PCAN-USB and a PCAN-USB Pro.

Possible values: The value is a null-terminated string which contains the name of the hardware specified by the given PCAN channel. The length of this text will have a maximum length of 32 bytes (null-termination included).

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_RECEIVE_STATUS

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This parameter helps the user to allow / disallow the reception of messages within a PCAN Channel, regardless of the value of its reception filter. When the "Receive Status" is active (ON), incoming messages are forwarded to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD). If "Receive Status" is deactivated (OFF), the incoming messages are disposed from the receive queue and each call to CAN_Read/CAN_ReadFD returns PCAN_ERROR_QRCVEMPTY. The acceptance filter of the channel remains unchanged (other applications working with the same PCAN-Hardware will not be disturbed).

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Activated (PCAN_PARAMETER_ON).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS).

REMARKS: Configuring this parameter without having the channel initialized, does a so called "pre-initialization". This means that the channel will set the configured "Receive Status" after it has been successfully connected, using CAN_Initialize (class-method: Initialize). Once the channel is disconnected, further initializations of this channel are done with the default value of this parameter (ON). This is usefull to avoid receiving messages immediately after connection, or before the receive filter is configured according with the needs of each application.

PCAN_CONTROLLER_NUMBER

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This parameter is a zero-based index used to identify the CAN controllers built in a hardware. This parameter is useful when it is needed to communicate with a specific physical channel on a multichannel CAN Hardware, e.g. "0" or "1" on a PCAN-USB Pro device.

Possible values: A number in the range [0..n-1], where n is the number of physical channels on the device being used.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_TRACE_LOCATION

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This value is used to set the folder location on a computer for the PCAN-Trace file generated by the PCAN-Basic API, within a trace session. If a trace session is active (a trace file is being written), PCAN_TRACE_LOCATION instructs the API to close the current trace file and to start recording data again with the new folder information.

Possible values: This value must be a fully-qualified and valid path to an existing directory on the executing computer. There is no limit for the length of the string but it is recommended to use a length not exceeding MAX_PATH. For more information see [image] Naming Files, Paths, and Namespaces. Passing an empty string ("", NULL value) instructs the API to use the default value for this parameter.

Default value: Calling process's folder.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: Note that the name of the trace file cannot be specified. The file uses the name of the current connection (PCAN-Channel's name) plus a file counter (e.g. PCAN_PCIBUS1_1.trc), though it can be enhanced by issuing the parameter PCAN_TRACE_CONFIGURE.

PCAN_TRACE_STATUS

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This value is used to control the activity status of a trace session within the PCAN-Basic API. If the trace status is set to ON without having set a location for the trace file or without having configured the storing mode, then the session process will start with the default values. Trying to activate a trace session can fail if overwriting is not set and a file with the same name already exists.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: For messages to be written in the trace file, the receive queue must be read actively, even if the application is only sending.

PCAN_TRACE_SIZE

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This value is used to set the maximum size, in megabytes, that a single trace file can have. Trying to set the size for a trace file will fail if the trace session is active.

Possible values: A number in the range [1..100], representing the amount of megabytes. Passing a value of 0 instructs the API to use the default value for this parameter. Trying to set a size bigger than 100 will fail.

Default value: 10 megabytes.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_TRACE_CONFIGURE

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This value is used to configure the trace process and the file generated in a trace session within the PCAN-Basic API. Trying to configure a trace file will fail if the trace session is active.

Possible values: The value must be one of the following values or a combination of them:

  • TRACE_FILE_SINGLE: This value represents the default trace configuration. It defines the use of a single trace file as output. When the tracing process starts, the file will be filled out with messages until the size of the file reaches the configured maximum size (see PCAN_TRACE_SIZE). The tracing process is then automatically stopped.
  • TRACE_FILE_SEGMENTED: This value indicates the API to keep tracing information by using several files. When the trace file being used reaches the maximum configured file size (see PCAN_TRACE_SIZE), then a new file is automatically created and the tracing process continues.
  • TRACE_FILE_DATE: This value instruct the API to use the start date information within the name of the trace file. The format used is YYYYMMDD, four digits for year, the next two for the month, and the last two for the day, e.g. "20130228_PCAN_USBBUS_1" for the 28th February 2013. If both, TRACE_FILE_DATE and TRACE_FILE_TIME are configured, the file name starts always with the date: "20130228 140733_PCAN_USBBUS1_1.trc".
  • TRACE_FILE_TIME: This value instruct the API to use the start time information within the name of the trace file. The format used is HHMMSS, two digits for the hour (24 hours format), the next two for the minutes, and the last two for the seconds, e.g. "140733_PCAN_USBBUS_1" for 14:07:33 (02:07:33 PM). If both, TRACE_FILE_DATE and TRACE_FILE_TIME are configured, the file name starts always with the date: "20130228140733_PCAN_USBBUS1_1.trc".
  • TRACE_FILE_OVERWRITE: This value causes the overwriting of an existing trace file when a new trace session is started. If this value is not configured, trying to start a tracing process will fail, if the file name to generate is the same as one used by an existing file.

Default value: TRACE_FILE_SINGLE (Single file, not overwriting, with standard name).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_CHANNEL_IDENTIFYING

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This value is used to control the status of the "channel identifying procedure" on USB devices within the PCAN-Basic API. The procedure consists of blinking the LED associated to the given channel.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN-USB devices.

REMARKS: This identifying procedure is only available for USB based hardware (PCAN-USB, PCAN-USB Pro and PCAN-USB Hub). The blinking of the LED can be different according to the kind of hardware used (in color and blink rate). Only one channel's LED can blink at a time.

PCAN_CHANNEL_FEATURES

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This value is used to read the particularities of a PCAN Channel.

Possible values: The value can be one of the following values or a combination of them:

  • FEATURE_FD_CAPABLE: This value indicates that the hardware represented by a PCAN Channel is FD capable (it supports flexible data rate).
  • FEATURE_DELAY_CAPABLE: This value indicates that the hardware represented by a PCAN Channel allows the configuration of a delay between sending frames.

Default value: A value of 0, indicating "no special features".

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: FD Hardware must be initialized with CAN_InitializeFD (class-method: InitializeFD) in order to use their FD capabilities. In same way, the functions CAN_ReadFD (class-method: ReadFD) and CAN_WriteFD (class-method: WriteFD) have to be used for data transmission.

PCAN_BITRATE_ADAPTING

Access:

Channel status:

  • For Read: The channel can be initialized or uninitialized.
  • For Write: The channel must be uninitialized to be able to set this parameter.

Description: This value is used to force an initialization process to succeed, even if the PCAN-Channel is being used by a PCAN-View with a different or unknown bit rate. The initialization function will return a PCAN_ERROR_CAUTION error, when the bit rate passed as parameter was different than that being used.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: After connecting, an application can get the bit rate currently used by calling CAN_GetValue (class-method: GetValue) with the parameters PCAN_SPEED_QUERY, for standard CAN channels, or PCAN_SPEED_QUERY_FD for CAN-FD channels.

PCAN_BITRATE_INFO

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This value is used to read the currently configured communication speed, as BTR0-BTR1 value, of a PCAN Channel connected as standard CAN.

Possible values: A number in the range [0..65535] (Word Value).

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_BITRATE_INFO_FD

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This value is used to read the currently configured communication speed, as a parameterized string value (FD bit rate string), of a PCAN Channel connected as CAN FD.

Possible values: a String representing a FD bit rate. See FD Bit rate for more information.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_BUSSPEED_NOMINAL

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This value is used to read the currently configured nominal CAN Bus speed, as bits/second.

Possible values: a number representing the nominal CAN bus speed being used, as the amount of bits that can be transmitted in a second.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_BUSSPEED_DATA

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This value is used to read the currently configured CAN data speed (Bit Rate Switch), as bits/second.

Possible values: a number representing the CAN data speed configured for BRS, as the amount of bits that can be transmitted in a second.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: The speed used for data transmission is the same as the nominal speed on devices that don't support flexible data rate.

PCAN_IP_ADDRESS

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This value is used to read the address used by a device for IP communication.

Possible values: a string representing the IP address of a device, in IPv4 format.

Default value: N/A.

PCAN-Device: PCAN-LAN (PCAN-Gateway Ethernet/Wireless devices).

PCAN_LAN_SERVICE_STATUS

Access:

Channel status: N/A.

Description: This value is used to get the running status of the System-Service that is part of the Virtual PCAN-Gateway solution.

Possible values: This parameter can have one of these values: SERVICE_STATUS_RUNNING, SERVICE_STATUS_STOPPED.

Default value: N/A.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

REMARKS: This parameter is only relevant in PCAN-LAN environments (using PCAN-Gateway Ethernet/Wireless devices).

PCAN_ALLOW_STATUS_FRAMES

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter helps the user to allow / disallow the reception of messages of type "PCAN_MESSAGE_STATUS" within a PCAN Channel. When "PCAN_ALLOW_STATUS_FRAMES" is active (ON), generated Status messages are forwarded from the driver to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD). Otherwise, the reception of Status frames is deactivated within the driver for this specific user application.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Enabled (PCAN_PARAMETER_ON).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_ALLOW_RTR_FRAMES

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter helps the user to allow / disallow the reception of messages of type "PCAN_MESSAGE_RTR" within a PCAN Channel. When "PCAN_ALLOW_RTR_FRAMES" is active (ON), incoming RTR messages are forwarded to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD). Otherwise, the reception of RTR frames is deactivated within the driver for this specific user application.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Enabled (PCAN_PARAMETER_ON).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_ALLOW_ERROR_FRAMES

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter helps the user to allow / disallow the reception of messages of type "PCAN_MESSAGE_ERRFRAME" within a PCAN Channel. When "PCAN_ALLOW_ERROR_FRAMES" is active (ON), generated Error messages are forwarded from the driver to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD ). Otherwise, the reception of Error frames is deactivated within the driver for this specific user application.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_INTERFRAME_DELAY

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used to configure a delay, in microseconds, between sending frames. When this value is value is greater than 0, the driver includes that value as a pause between each written CAN frame. Otherwise, the CAN frames are sent as fast as possible.

Possible values: The parameter has a value range between [0..n], where n is the maximum value supported by the Firmware. If the maximum value supported by the firmware is lower than the entered one, the value will be truncated.

Default value: 0 (disabled).

PCAN-Device: All FPGA based PCAN devices.

PCAN_ACCEPTANCE_FILTER_11BIT

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used to configure the reception filter of a PCAN channel with a specific 11-bit acceptance code and mask, as specified for the acceptance filter of the SJA1000 CAN controller. The acceptance code and mask are coded together in a 64-bit value, each of them using 4 bytes (Intel/Little-Endian format). The acceptance code is stored at the most significant bytes.

Possible values: Both parameter parts, code and mask, have a value range between [0..16838]. This means, the maximum value of this parameter as 64-bit value is 70364449226751, that is, hexadecimal 00003FFF00003FFFh. The mask uses the bit value '1' as "don't care bit".

Default value: 00000000000007FFh (no filtering).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter is particularly adapted to the SJA1000 CAN controller. Reception filters can also be configured with the function CAN_FilterMessages(class-method: FilterMessages). Note that after a PCAN Channel is initialized, the status of its filter is fully opened. According with the current filter status, setting this parameter causes the following behavior:

  • Filter status is PCAN_FILTER_OPEN: The filter is automatically closed and then configured with the given acceptance filter.
  • Filter status is PCAN_FILTER_CLOSE: The filter is set to the given acceptance filter.
  • Filter status is PCAN_FILTER_CUSTOM: The filter is expanded with the given acceptance filter. If a different acceptance code is required instead of expanding the current one, the filter has to be closed first before setting the acceptance filter. To do this use the parameter PCAN_MESSAGE_FILTER.

PCAN_ACCEPTANCE_FILTER_29BIT

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used to configure the reception filter of a PCAN channel with a specific 29-bit acceptance code and mask, as specified for the acceptance filter of the SJA1000 CAN controller. The acceptance code and mask are coded together in a 64-bit value, each of them using 4 bytes (Intel/Little-Endian format). The acceptance code is stored at the most significant bytes.

Possible values: Both parameter parts, code and mask, have a value range between [0..4294967295]. This means, the maximum value of this parameter as 64-bit value is 18446744073709551615, that is, hexadecimal FFFFFFFFFFFFFFFFh. The mask uses the bit value '1' as "don't care bit".

Default value: 000000001FFFFFFFh (no filtering).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter is particularly adapted to the SJA1000 CAN controller. Reception filters can also be configured with the function CAN_FilterMessages(class-method: FilterMessages). Note that after a PCAN Channel is initialized, the status of its filter is fully opened. According with the current filter status, setting this parameter causes the following behavior:

  • Filter status is PCAN_FILTER_OPEN: The filter is automatically closed and then configured with the given acceptance filter.
  • Filter status is PCAN_FILTER_CLOSE: The filter is set to the given acceptance filter.
  • Filter status is PCAN_FILTER_CUSTOM: The filter is expanded with the given acceptance filter. If a different acceptance code is required instead of expanding the current one, the filter has to be closed first before setting the acceptance filter. To do this use the parameter PCAN_MESSAGE_FILTER.

PCAN_IO_DIGITAL_CONFIGURATION

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used to configure the output mode of all digital I/O pins on a PCAN-USB Chip device.

Possible values: This value can be a number in the range [0..4294967295]. Every bit of the given value represents a digital input. A bit value of 1 means that the pin works as "digital output", 0 means "digital input only". Bit0, the least significant bit, corresponds to Pin0; Bit1 corresponds to Pin1, an so on until Pin31.

Default value: 0, meaning no digital outputs are configured.

PCAN-Device: PCAN-USB devices (USB-Chip family).

REMARKS: All Pins act as digital inputs and, additionally, as digital outputs when configured as such. The current version of the PCAN-USB Chip implements 5 digital Pins. Bit values from Bit5 to Bit31 are ignored.

PCAN_IO_DIGITAL_VALUE

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used to set the values represented by all digital Pins configured as digital output of a PCAN-USB Chip device.

Possible values: This value can be a number in the range [0..4294967295]. Every bit of the given value represents a digital input. A bit value of 0 means "Low", 1 means "High". Bit0, the least significant bit, corresponds to the value of the Pin0; Bit1 corresponds to the value of the Pin1, an so on until Pin31.

Default value: 0, meaning all digital output values are set to "Low".

PCAN-Device: PCAN-USB devices (USB-Chip family).

REMARKS: All Pins act as digital inputs and, additionally, as digital outputs when configured as such. The current version of the PCAN-USB Chip implements 5 digital Pins. Bit values from Bit5 to Bit31 are ignored.

PCAN_IO_DIGITAL_SET

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter allows the setting of selected digital Pins to "High", avoiding re-configuring unwanted ones at the same time.

Possible values: This value can be a number in the range [0..4294967295]. Every bit of the given value represents a digital input. A bit value of 1 marks the Pin, which value has to be set to "High". A bit value of 0 has no effect. Bit0, the least significant bit, corresponds to Pin0; Bit1 corresponds to Pin1, an so on until Pin31.

Default value: N/A.

PCAN-Device: PCAN-USB devices (USB-Chip family).

REMARKS: All Pins act as digital inputs and, additionally, as digital outputs when configured as such. The current version of the PCAN-USB Chip implements 5 digital Pins. Bit values from Bit5 to Bit31 are ignored.

PCAN_IO_DIGITAL_CLEAR

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter allows the setting of selected digital Pins to "Low", avoiding re-configuring unwanted ones at the same time.

Possible values: This value can be a number in the range [0..4294967295]. Every bit of the given value represents a digital input. A bit value of 1 marks the Pin, which value has to be set to "Low". A bit value of 0 has no effect. Bit0, the least significant bit, corresponds to Pin0; Bit1 corresponds to Pin1, an so on until Pin31.

Default value: N/A.

PCAN-Device: PCAN-USB devices (USB-Chip family).

REMARKS: All Pins act as digital inputs and, additionally, as digital outputs when configured as such. The current version of the PCAN-USB Chip implements 5 digital Pins. Bit values from Bit5 to Bit31 are ignored.

PCAN_IO_ANALOG_VALUE

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used for reading analog voltages from the analog input Pin of a PCAN-USB Chip device.

Possible values: This value can be a number in the range [0..4294967295].

Default value: N/A.

PCAN-Device: PCAN-USB devices (USB-Chip family).

REMARKS: The current version of the PCAN-USB chip implements 1 analog pin. The returned value represents the direct value from the A / D converter, which is an unsigned integer value. This value must be converted into a signed value, taking into account the external wiring.

PCAN_FIRMWARE_VERSION

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter is used to get information about the firmware of the used PCAN device.

Possible values: The value is a null-terminated string indicating the version number of the firmware used. The returned text has the following form: x.x.x for major, minor, and release. The length of this text value will have a maximum length of 18 bytes, 5 bytes for each single version number representation, two separator characters ( , or . ) and the null-termination.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_ATTACHED_CHANNELS_COUNT

Access:

Channel status: N/A.

Description: This parameter is used to get the amount of PCAN channels attached to a system, regardless of their current availability (see PCAN_CHANNEL_AVAILABLE).

Possible values: This value can be a number in the range [0..n], where n is the sum of the maximum supported channels per device in PCAN-Basic (see Number of Channels).

Default value: N/A.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_ATTACHED_CHANNELS

Access:

Channel status: N/A.

Description: This parameter is used to get information about all existing PCAN channels on a system in a single call.

Possible values: This value is an array of TPCANChannelInformation elements with size of PCAN_AVAILABLE_CHANNELS_COUNT.

Default value: N/A.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_ALLOW_ECHO_FRAMES

Access:

Channel status: The channel must be initialized to get access to this parameter.

Description: This parameter helps the user to allow / disallow the reception of messages of type "PCAN_MESSAGE_ECHO" (self received messages) within a PCAN Channel. When "PCAN_ALLOW_ECHO_FRAMES" is active (ON), outgoing CAN messages are received again by using the CAN_Read / CAN_ReadFD functions (class-methods: Read, ReadFD ), as soon as they are physically sent. Otherwise, the reception of echo messages is deactivated within the driver for this specific user application.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_DEVICE_PART_NUMBER

Access:

Channel status: The channel can be initialized or uninitialized.

Description: This parameter is used to get the part number of the device represented by the PCAN-Channel.

Possible values: The value is a null-terminated string indicating the IPEH number of the device being used. This value can be used as reference number for ordering devices. The returned text has the following form: IPEH-xxxxxx, where xxxxxx represents the six-digit associated part number. The length of this text will have at least a length of 12 bytes (11 bytes for the IPEH number plus null-termination).

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: In the special cases a device is represented by more than one IPEH number, then those numbers are returned together, separated by a “/” character. For example, a classic PCAN-USB reports the value “IPEH-002021/002022”. It is recommended to use a buffer big enough to guarantee success in special cases like this.

See Also

CAN_GetValue (class-method: GetValue)

CAN_SetValue (class-method: SetValue)

Parameter Value Definitions

Naming Files, Paths, and Namespaces


TPCANMessageType

TPCANMessageType

Represents the type of a CAN message. According with the programming language, this type can be a group of defined values or an enumeration.

Syntax
C++
#define TPCANMessageType BYTE

#define PCAN_MESSAGE_STANDARD 0x00
#define PCAN_MESSAGE_RTR 0x01
#define PCAN_MESSAGE_EXTENDED 0x02
#define PCAN_MESSAGE_FD 0x04
#define PCAN_MESSAGE_BRS 0x08
#define PCAN_MESSAGE_ESI 0x10
#define PCAN_MESSAGE_ECHO 0x20
#define PCAN_MESSAGE_ERRFRAME 0x40
#define PCAN_MESSAGE_STATUS 0x80
Pascal OO
{$Z1}
TPCANMessageType = (
    PCAN_MESSAGE_STANDARD = $00,
    PCAN_MESSAGE_RTR = $01,
    PCAN_MESSAGE_EXTENDED = $02,
    PCAN_MESSAGE_FD = $04,
    PCAN_MESSAGE_BRS = $08,
    PCAN_MESSAGE_ESI = $10,
    PCAN_MESSAGE_ECHO = $20,
    PCAN_MESSAGE_ERRFRAME = $40,
    PCAN_MESSAGE_STATUS = $80
);
C#
[Flags]
public enum TPCANMessageType : byte
{
    PCAN_MESSAGE_STANDARD  = 0x00,
    PCAN_MESSAGE_RTR       = 0x01,
    PCAN_MESSAGE_EXTENDED  = 0x02,
    PCAN_MESSAGE_FD = 0x04,
    PCAN_MESSAGE_BRS = 0x08,
    PCAN_MESSAGE_ESI = 0x10,
    PCAN_MESSAGE_ECHO    = 0x20,
    PCAN_MESSAGE_ERRFRAME = 0x40,
    PCAN_MESSAGE_STATUS    = 0x80,
}
C++ / CLR
[Flags]
public enum class TPCANMessageType : Byte
{
    PCAN_MESSAGE_STANDARD  = 0x00,
    PCAN_MESSAGE_RTR = 0x01,
    PCAN_MESSAGE_EXTENDED  = 0x02,
    PCAN_MESSAGE_FD = 0x04,
    PCAN_MESSAGE_BRS = 0x08,
    PCAN_MESSAGE_ESI = 0x10,
    PCAN_MESSAGE_ECHO    = 0x20,
    PCAN_MESSAGE_ERRFRAME = 0x40,
    PCAN_MESSAGE_STATUS    = 0x80,
};
Visual Basic
<Flags()> _
Public Enum TPCANMessageType As Byte
    PCAN_MESSAGE_STANDARD = &H0
    PCAN_MESSAGE_RTR = &H1
    PCAN_MESSAGE_EXTENDED = &H2
    PCAN_MESSAGE_FD = &H4
    PCAN_MESSAGE_BRS = &H8
    PCAN_MESSAGE_ESI = &H10
    PCAN_MESSAGE_ECHO = &H20
    PCAN_MESSAGE_ERRFRAME = &H40
    PCAN_MESSAGE_STATUS = &H80
End Enum
Python
TPCANMessageType = c_ubyte

PCAN_MESSAGE_STANDARD = TPCANMessageType(0x00)
PCAN_MESSAGE_RTR = TPCANMessageType(0x01)
PCAN_MESSAGE_EXTENDED = TPCANMessageType(0x02)
PCAN_MESSAGE_FD = TPCANMessageType(0x04)
PCAN_MESSAGE_BRS = TPCANMessageType(0x08)
PCAN_MESSAGE_ESI = TPCANMessageType(0x10)
PCAN_MESSAGE_ECHO = TPCANMessageType(0x20)
PCAN_MESSAGE_ERRFRAME = TPCANMessageType(0x40)
PCAN_MESSAGE_STATUS = TPCANMessageType(0x80)
Remarks

Several message types can be combined (Bit mask).

Note that messages with type PCAN_MESSAGE_FD, PCAN_MESSAGE_BRS, PCAN_MESSAGE_ESI, or a combination of them, can only be sent/received using the FD functions CAN_ReadFD and CAN_WriteFD (class-methods: ReadFD, WriteFD).

Values
Name | Value | Description
PCAN_MESSAGE_STANDARD | 0 | The PCAN message is a CAN Standard Frame (11-bit identifier).
PCAN_MESSAGE_RTR | 1 | The PCAN message is a CAN Remote-Transfer-Request Frame.
PCAN_MESSAGE_EXTENDED | 2 | The PCAN message is a CAN Extended Frame (29-bit identifier).
PCAN_MESSAGE_FD | 4 | The PCAN message represents a FD frame in terms of CiA specifications.
PCAN_MESSAGE_BRS | 8 | The PCAN message represents a FD bit rate switch (CAN data at a higher bit rate).
PCAN_MESSAGE_ESI | 16 | The PCAN message represents a FD error state indicator(CAN FD transmitter was error active).
PCAN_MESSAGE_ECHO | 32 | The PCAN message represents an echo CAN Frame ( self-received message).
PCAN_MESSAGE_ERRFRAME | 64 | The PCAN message represents an error frame. See Error Frames for more information.
PCAN_MESSAGE_STATUS | 128 | The PCAN message represents a PCAN status message.
See Also

CAN_Read (class-method: Read)

CAN_ReadFD (class-method: ReadFD)

CAN_Write (class-method: Write)

CAN_WriteFD (class-method: WriteFD)


TPCANType

TPCANType

Represents the type of PCAN (not plug&play) hardware to be initialized. According with the programming language, this type can be a group of defined values or an enumeration.

Syntax
C++
#define TPCANType BYTE

#define PCAN_TYPE_ISA 0x01
#define PCAN_TYPE_ISA_SJA 0x09
#define PCAN_TYPE_ISA_PHYTEC 0x04
#define PCAN_TYPE_DNG 0x02
#define PCAN_TYPE_DNG_EPP 0x03
#define PCAN_TYPE_DNG_SJA 0x05
#define PCAN_TYPE_DNG_SJA_EPP 0x06
Pascal OO
{$Z1}
TPCANType = (
    PCAN_TYPE_ISA = $01,
    PCAN_TYPE_ISA_SJA = $09,
    PCAN_TYPE_ISA_PHYTEC = $04,
    PCAN_TYPE_DNG = $02,
    PCAN_TYPE_DNG_EPP = $03,
    PCAN_TYPE_DNG_SJA = $05,
    PCAN_TYPE_DNG_SJA_EPP = $06
);
C#
public enum TPCANType : byte
{
    PCAN_TYPE_ISA = 0x01,
    PCAN_TYPE_ISA_SJA = 0x09,
    PCAN_TYPE_ISA_PHYTEC = 0x04,
    PCAN_TYPE_DNG = 0x02,
    PCAN_TYPE_DNG_EPP = 0x03,
    PCAN_TYPE_DNG_SJA = 0x05,
    PCAN_TYPE_DNG_SJA_EPP = 0x06,
}
C++ / CLR
public enum class TPCANType : Byte
{
    PCAN_TYPE_ISA = 0x01,
    PCAN_TYPE_ISA_SJA = 0x09,
    PCAN_TYPE_ISA_PHYTEC = 0x04,
    PCAN_TYPE_DNG = 0x02,
    PCAN_TYPE_DNG_EPP = 0x03,
    PCAN_TYPE_DNG_SJA = 0x05,
    PCAN_TYPE_DNG_SJA_EPP = 0x06,
};
Visual Basic
Public Enum TPCANType As Byte
    PCAN_TYPE_ISA = &H1
    PCAN_TYPE_ISA_SJA = &H9
    PCAN_TYPE_ISA_PHYTEC = &H4
    PCAN_TYPE_DNG = &H2
    PCAN_TYPE_DNG_EPP = &H3
    PCAN_TYPE_DNG_SJA = &H5
    PCAN_TYPE_DNG_SJA_EPP = &H6
End Enum
Python
TPCANType = c_ubyte

PCAN_TYPE_ISA = TPCANType(0x01)
PCAN_TYPE_ISA_SJA = TPCANType(0x09)
PCAN_TYPE_ISA_PHYTEC = TPCANType(0x04)
PCAN_TYPE_DNG = TPCANType(0x02)
PCAN_TYPE_DNG_EPP = TPCANType(0x03)
PCAN_TYPE_DNG_SJA = TPCANType(0x05)
PCAN_TYPE_DNG_SJA_EPP = TPCANType(0x06)
Values
Name | Value | Description
PCAN_TYPE_ISA | 1 | PCAN-ISA 82C200.
PCAN_TYPE_ISA_SJA | 9 | PCAN-ISA SJA1000.
PCAN_TYPE_ISA_PHYTEC | 4 | PHYTEC ISA .
PCAN_TYPE_DNG | 2 | PCAN-Dongle 82C200.
PCAN_TYPE_DNG_EPP | 3 | PCAN-Dongle EPP 82C200.
PCAN_TYPE_DNG_SJA | 5 | PCAN-Dongle SJA1000.
PCAN_TYPE_DNG_SJA_EPP | 6 | PCAN-Dongle EPP SJA1000.
See Also

PCAN_Initialize (class-method: Initialize)


TPCANMode

TPCANMode

Represents a PCAN filter mode. According with the programming language, this type can be a group of defined values or an enumeration.

Syntax
C++
#define TPCANMode BYTE

#define PCAN_MODE_STANDARD PCAN_MESSAGE_STANDARD
#define PCAN_MODE_EXTENDED PCAN_MESSAGE_EXTENDED
Pascal OO
{$Z1}
TPCANMode = (
    PCAN_MODE_STANDARD = Byte(PCAN_MESSAGE_STANDARD),
    PCAN_MODE_EXTENDED = Byte(PCAN_MESSAGE_EXTENDED)
);
C#
public enum TPCANMode : byte
{
    PCAN_MODE_STANDARD = TPCANMessageType.PCAN_MESSAGE_STANDARD,
    PCAN_MODE_EXTENDED = TPCANMessageType.PCAN_MESSAGE_EXTENDED,
}
C++ / CLR
public enum class TPCANMode : Byte
{
    PCAN_MODE_STANDARD = TPCANMessageType::PCAN_MESSAGE_STANDARD,
    PCAN_MODE_EXTENDED = TPCANMessageType::PCAN_MESSAGE_EXTENDED,
};
Visual Basic
Public Enum TPCANMode As Byte
    PCAN_MODE_STANDARD = TPCANMessageType.PCAN_MESSAGE_STANDARD
    PCAN_MODE_EXTENDED = TPCANMessageType.PCAN_MESSAGE_EXTENDED
End Enum
Python
TPCANMode = c_ubyte

PCAN_MODE_STANDARD = PCAN_MESSAGE_STANDARD
PCAN_MODE_EXTENDED = PCAN_MESSAGE_EXTENDED
Values
Name | Value | Description
PCAN_MODE_STANDARD | 0 | Mode is Standard (11-bit identifier).
PCAN_MODE_EXTENDED | 2 | Mode is Extended (29-bit identifier).
See Also

CAN_FilterMessages (class-method: FilterMessages)


TPCANBaudrate

TPCANBaudrate

Represents a PCAN bit rate register value. According with the programming language, this type can be a group of defined values or an enumeration.

Syntax
C++
#define TPCANBaudrate WORD

#define PCAN_BAUD_1M 0x0014
#define PCAN_BAUD_800K 0x0016
#define PCAN_BAUD_500K 0x001C
#define PCAN_BAUD_250K 0x011C
#define PCAN_BAUD_125K 0x031C
#define PCAN_BAUD_100K 0x432F
#define PCAN_BAUD_95K 0xC34E
#define PCAN_BAUD_83K 0x852B
#define PCAN_BAUD_50K 0x472F
#define PCAN_BAUD_47K 0x1414
#define PCAN_BAUD_33K 0x8B2F
#define PCAN_BAUD_20K 0x532F
#define PCAN_BAUD_10K 0x672F
#define PCAN_BAUD_5K 0x7F7F
Pascal OO
{$Z2}
TPCANBaudrate = (
    PCAN_BAUD_1M = $0014,
    PCAN_BAUD_800K = $0016,
    PCAN_BAUD_500K = $001C,
    PCAN_BAUD_250K = $011C,
    PCAN_BAUD_125K = $031C,
    PCAN_BAUD_100K = $432F,
    PCAN_BAUD_95K = $C34E,
    PCAN_BAUD_83K = $852B,
    PCAN_BAUD_50K = $472F,
    PCAN_BAUD_47K = $1414,
    PCAN_BAUD_33K = $8B2F,
    PCAN_BAUD_20K = $532F,
    PCAN_BAUD_10K = $672F,
    PCAN_BAUD_5K = $7F7F
);
C#
public enum TPCANBaudrate : ushort
{
    PCAN_BAUD_1M = 0x0014,
    PCAN_BAUD_800K = 0x0016,
    PCAN_BAUD_500K = 0x001C,
    PCAN_BAUD_250K = 0x011C,
    PCAN_BAUD_125K = 0x031C,
    PCAN_BAUD_100K = 0x432F,
    PCAN_BAUD_95K = 0xC34E,
    PCAN_BAUD_83K = 0x852B,
    PCAN_BAUD_50K = 0x472F,
    PCAN_BAUD_47K = 0x1414,
    PCAN_BAUD_33K = 0x8B2F,
    PCAN_BAUD_20K = 0x532F,
    PCAN_BAUD_10K = 0x672F,
    PCAN_BAUD_5K = 0x7F7F,
}
C++ / CLR
public enum class TPCANBaudrate : UInt16
{
    PCAN_BAUD_1M = 0x0014,
    PCAN_BAUD_800K = 0x0016,
    PCAN_BAUD_500K = 0x001C,
    PCAN_BAUD_250K = 0x011C,
    PCAN_BAUD_125K = 0x031C,
    PCAN_BAUD_100K = 0x432F,
    PCAN_BAUD_95K = 0xC34E,
    PCAN_BAUD_83K = 0x852B,
    PCAN_BAUD_50K = 0x472F,
    PCAN_BAUD_47K = 0x1414,
    PCAN_BAUD_33K = 0x8B2F,
    PCAN_BAUD_20K = 0x532F,
    PCAN_BAUD_10K = 0x672F,
    PCAN_BAUD_5K = 0x7F7F,
};
Visual Basic
Public Enum TPCANBaudrate As UInt16
    PCAN_BAUD_1M = &H14
    PCAN_BAUD_800K = &H16
    PCAN_BAUD_500K = &H1C
    PCAN_BAUD_250K = &H11C
    PCAN_BAUD_125K = &H31C
    PCAN_BAUD_100K = &H432F
    PCAN_BAUD_95K = &C34E
    PCAN_BAUD_83K = &852B
    PCAN_BAUD_50K = &H472F
    PCAN_BAUD_47K = &1414
    PCAN_BAUD_33K = &8B2F
    PCAN_BAUD_20K = &H532F
    PCAN_BAUD_10K = &H672F
    PCAN_BAUD_5K = &H7F7F
End Enum
Python
TPCANBaudrate = c_ushort

PCAN_BAUD_1M = TPCANBaudrate(0x0014)
PCAN_BAUD_800K = TPCANBaudrate(0x0016)
PCAN_BAUD_500K = TPCANBaudrate(0x001C)
PCAN_BAUD_250K = TPCANBaudrate(0x011C)
PCAN_BAUD_125K = TPCANBaudrate(0x031C)
PCAN_BAUD_100K = TPCANBaudrate(0x432F)
PCAN_BAUD_95K = TPCANBaudrate(0xC34E)
PCAN_BAUD_83K = TPCANBaudrate(0x852B)
PCAN_BAUD_50K = TPCANBaudrate(0x472F)
PCAN_BAUD_47K = TPCANBaudrate(0x1414)
PCAN_BAUD_33K = TPCANBaudrate(0x8B2F)
PCAN_BAUD_20K = TPCANBaudrate(0x532F)
PCAN_BAUD_10K = TPCANBaudrate(0x672F)
PCAN_BAUD_5K = TPCANBaudrate(0x7F7F)
Values
Name | Value | Description
PCAN_BAUD_1M | 20 | 1 MBit/s.
PCAN_BAUD_800K | 22 | 800 kBit/s.
PCAN_BAUD_500K | 28 | 500 kBit/s.
PCAN_BAUD_250K | 284 | 250 kBit/s.
PCAN_BAUD_125K | 796 | 125 kBit/s.
PCAN_BAUD_100K | 17199 | 100 kBit/s.
PCAN_BAUD_95K | 49998 | 95,238 kBit/s.
PCAN_BAUD_83K | 34091 | 83,333 kBit/s.
PCAN_BAUD_50K | 18223 | 50 kBit/s.
PCAN_BAUD_47K | 5140 | 47,619 kBit/s.
PCAN_BAUD_33K | 35631 | 33,333 kBit/s.
PCAN_BAUD_20K | 21295 | 20 kBit/s.
PCAN_BAUD_10K | 26415 | 10 kBit/s.
PCAN_BAUD_5K | 32639 | 5 kBit/s.
See Also

CAN_Initialize (class-method: Initialize)


TPCANBitrateFD

TPCANBitrateFD

Represents a bit rate string with flexible data rate (FD).

Syntax
C++
#define TPCANBitrateFD LPSTR

#define PCAN_BITRATE_SAE_J2284_4     "f_clock=80000000,nom_brp=2,nom_tseg1=63,nom_tseg2=16,nom_sjw=16,data_brp=2,data_tseg1=15,data_tseg2=4,data_sjw=4"
#define PCAN_BITRATE_SAE_J2284_5     "f_clock=80000000,nom_brp=1,nom_tseg1=127,nom_tseg2=32,nom_sjw=32,data_brp=1,data_tseg1=11,data_tseg2=4,data_sjw=4"
Pascal OO
TPCANBitrateFD = String;

const PCAN_BITRATE_SAE_J2284_4: String = 'f_clock=80000000,nom_brp=2,nom_tseg1=63,nom_tseg2=16,nom_sjw=16,data_brp=2,data_tseg1=15,data_tseg2=4,data_sjw=4';
const PCAN_BITRATE_SAE_J2284_5: String = 'f_clock=80000000,nom_brp=1,nom_tseg1=127,nom_tseg2=32,nom_sjw=32,data_brp=1,data_tseg1=11,data_tseg2=4,data_sjw=4';
C#
using TPCANBitrateFD = System.String;

public const string PCAN_BITRATE_SAE_J2284_4 = "f_clock=80000000,nom_brp=2,nom_tseg1=63,nom_tseg2=16,nom_sjw=16,data_brp=2,data_tseg1=15,data_tseg2=4,data_sjw=4";
public const string PCAN_BITRATE_SAE_J2284_5 = "f_clock=80000000,nom_brp=1,nom_tseg1=127,nom_tseg2=32,nom_sjw=32,data_brp=1,data_tseg1=11,data_tseg2=4,data_sjw=4";
C++ / CLR
#define TPCANBitrateFD System::String^

static const System::String^ PCAN_BITRATE_SAE_J2284_4 = "f_clock=80000000,nom_brp=2,nom_tseg1=63,nom_tseg2=16,nom_sjw=16,data_brp=2,data_tseg1=15,data_tseg2=4,data_sjw=4";
static const System::String^ PCAN_BITRATE_SAE_J2284_5 = "f_clock=80000000,nom_brp=1,nom_tseg1=127,nom_tseg2=32,nom_sjw=32,data_brp=1,data_tseg1=11,data_tseg2=4,data_sjw=4";
Visual Basic
Imports TPCANBitrateFD = System.String

Public Const PCAN_BITRATE_SAE_J2284_4 As String = "f_clock=80000000,nom_brp=2,nom_tseg1=63,nom_tseg2=16,nom_sjw=16,data_brp=2,data_tseg1=15,data_tseg2=4,data_sjw=4"
Public Const PCAN_BITRATE_SAE_J2284_5 As String = "f_clock=80000000,nom_brp=1,nom_tseg1=127,nom_tseg2=32,nom_sjw=32,data_brp=1,data_tseg1=11,data_tseg2=4,data_sjw=4"
Python
TPCANBitrateFD = c_char_p

PCAN_BITRATE_SAE_J2284_4      = TPCANBitrateFD("f_clock=80000000,nom_brp=2,nom_tseg1=63,nom_tseg2=16,nom_sjw=16,data_brp=2,data_tseg1=15,data_tseg2=4,data_sjw=4")
PCAN_BITRATE_SAE_J2284_5      = TPCANBitrateFD("f_clock=80000000,nom_brp=1,nom_tseg1=127,nom_tseg2=32,nom_sjw=32,data_brp=1,data_tseg1=11,data_tseg2=4,data_sjw=4")
Remarks

.NET Framework programming languages:

An alias is used to represent a flexible data rate under Microsoft .NET in order to originate an homogeneity between all programming languages listed above.

Aliases are defined in the Peak.Can.Basic Namespace for C# and VB .NET. However, including a namespace does not include the defined aliases.

If it is wished to work with aliases, those must be copied to the working file, right after the inclusion of the Peak.Can.Basic Namespace. Otherwise, just use the native type, which in this case is a String.

C#:

using System;
using Peak.Can.Basic;
using TPCANBitrateFD = System.String; // Alias's declaration for System.String

Visual Basic:

Imports System
Imports Peak.Can.Basic
Imports TPCANBitrateFD = System.String ' Alias declaration for System.String
Values
Name | Description
PCAN_BITRATE_SAE_J2284_4 | SAE J2284-4: High-Speed CAN (HSC) for Vehicle Applications at 500 kbps with CAN FD Data at 2 Mbps
PCAN_BITRATE_SAE_J2284_5 | SAE J2284-5: High-Speed CAN (HSC) for Vehicle Applications at 500 kbps with CAN FD Data at 5 Mbps
See Also

FB Bit rate Parameter Definitions


TPCANTimestampFD

TPCANTimestampFD

Represents the timestamp of a CAN message with flexible data rate. The time-stamp contains the number of microseconds since the start of Windows.

Syntax
C++
#define TPCANTimestampFD UINT64
Pascal OO
TPCANTimestampFD = UInt64;
C#
using TPCANTimestampFD = System.UInt64;
C++ / CLR
#define TPCANTimestampFD System::UInt64
Visual Basic
Imports TPCANTimestampFD = System.UInt64
Python
TPCANTimestampFD = c_ulonglong
Remarks

.NET Framework programming languages:

An alias is used to represent a timestamp for flexible data rate messages under Microsoft .NET in order to originate an homogeneity between all programming languages listed above.

Aliases are defined in the Peak.Can.Basic Namespace for C# and VB .NET. However, including a namespace does not include the defined aliases.

If it is preferred to work with aliases, those must be copied to the working file, right after the inclusion of the Peak.Can.Basic Namespace. Otherwise, just use the native type, which in this case is a UInt64.

C#:

using System;
using Peak.Can.Basic;
using TPCANTimestampFD = System.UInt64; // Alias's declaration for System.UInt64

Visual Basic:

Imports System
Imports Peak.Can.Basic
Imports TPCANTimestampFD = System.UInt64 ' Alias declaration for System.UInt64


Methods

Methods

The methods defined for the classes PCANBasic and TPCANBasic are divided in 4 groups of functionality. Note that, with exception of the method version for Python, these methods are static and can be called in the name of the class, without instantiation.

Connection
Function | Description
Initialize | Initializes a PCAN Channel.
InitializeFD | Initializes a FD capable PCAN Channel.
Uninitialize | Uninitializes a PCAN Channel.
Configuration
Function | Description
SetValue | Sets a configuration or information value within a PCAN Channel.
FilterMessages | Configures the message's reception filter of a PCAN Channel.
Information
Function | Description
GetValue | Retrieves information from a PCAN Channel.
GetStatus | Retrieves the current BUS status of a PCAN Channel.
GetErrorText | Gets a descriptive text for an error code.
LookUpChannel | Finds the handle of a PCAN-Basic channel that matches the specified parameters.
Communication
Function | Description
Read | Reads a CAN message from the receive queue of a PCAN Channel.
ReadFD | Reads a CAN message from the receive queue of a FD capable PCAN Channel.
Write | Transmits a CAN message using a connected PCAN Channel.
WriteFD | Transmits a CAN message using a connected FD capable PCAN Channel.
Reset | Resets the receive and transmit queues of a PCAN Channel.


Initialize

Initialize

Initializes a PCAN Channel.

Overloads
Function | Description
Initialize(TPCANHandle, TPCANBaudrate) | Initializes a Plug-And-Play PCAN Channel.
Initialize(TPCANHandle, TPCANBaudrate, TPCANType, UInt32, UInt16) | Initializes a Not-Plug-And-Play PCAN Channel.


Initialize(TPCANHandle, TPCANBaudrate)

Initialize(TPCANHandle, TPCANBaudrate)

Initializes a PCAN Channel which represents a Plug & Play PCAN-Device.

Syntax
Pascal OO
class function Initialize(
    Channel: TPCANHandle;
    Btr0Btr1: TPCANBaudrate
    ): TPCANStatus; overload;
C#
public static extern TPCANStatus Initialize(
    TPCANHandle Channel,
    TPCANBaudrate Btr0Btr1);
C++ / CLR
static TPCANStatus Initialize(
    TPCANHandle Channel,
    TPCANBaudrate Btr0Btr1);
Visual Basic
Public Shared Function Initialize( _
    ByVal Channel As TPCANHandle, _
    ByVal Btr0Btr1 As TPCANBaudrate) As TPCANStatus
End Function
Python
def Initialize(
    self,
    Channel,
    Btr0Btr1)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Btr0Btr1 | The speed for the communication (BTR0BTR1 code).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_CAUTION:
Indicates that the channel has been initialized but at a different bit rate as the given one.
PCAN_ERROR_ILLHANDLE:
Indicates that the desired PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_ILLHW:
Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLOPERATION:
Indicates that an action cannot be executed due to the state of the hardware. Possible causes are:

  • The desired PCAN-Channel is a LAN Channel, which uses a different bit rate than the specified.

PCAN_ERROR_ILLMODE:
Indicates that the hardware is working in a different or incompatible mode than requested. Possible causes are:

  • The desired PCAN-Channel is being operated in CAN-FD mode.

PCAN_ERROR_INITIALIZE:
Indicates that the desired PCAN Channel cannot be connected because it is already in use (PCAN-Basic / PCAN-Light environment).
PCAN_ERROR_NETINUSE:
Indicates that the desired PCAN-Channel is being used with a different bit rate (PCAN-View).
PCAN_ERROR_HWINUSE:
Indicates that the desired PCAN-Channel is being used (CanApi2 connection).
PCAN_ERROR_NODRIVER:
The driver needed for connecting the desired PCAN Channel is not loaded.
Remarks

As indicated by its name, the Initialize method initiates a PCAN Channel, preparing it for communicate within the CAN bus connected to it. Calls to the other methods will fail if they are used with a Channel handle, different than PCAN_NONEBUS, that has not been initialized yet. Each initialized channel should be released when it is not needed anymore.

Initializing a PCAN Channel means:

  • to reserve the Channel for the calling application/process.
  • to allocate channel resources, like receive and transmit queues.
  • to register/connect the Hardware denoted by the channel handle.
  • to check and adapt the bus speed, if the Channel is already in use. (Only if the Channel was pre-configured as Bitrate Adapting; see: Bitrate-Adapting Parameter).
  • to set the channel in Listen-Only mode. (Only if the channel was pre-configured as Listen-Only; see: Listen-Only Parameter).
  • to open the messages filter for the application/process.
  • to set-up the default values of the different parameters (See GetValue).
  • to set the Receive Status of the channel. (Pre-configured value; see: Receive Status Parameter).

What is different from the PCAN-Light API, the Initialization process will fail if an application tries to initialize a PCAN-Channel that has been initialized already within the same process.

Take in consideration that initializing a channel causes a reset of the CAN hardware , when the bus status is other than OK. In this way errors like BUSOFF, BUSHEAVY, and BUSLIGHT, are removed.

PCAN-LAN Channels

A PCAN-LAN channel doesn't allow changing the bit rate using PCAN-Basic. In order to connect a PCAN-LAN Channel it is necessary to know the bit rate of the PCAN-Gateway device that is represented by that channel. If the bit rate is not known, the parameter Bitrate-Adapting should be used.

Python Notes

  • Class-Method: Different than the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
  • Plug-&-Play and No-Plug-&-Play hardware: In order to initialize a channel which represents a Plug-&-Play PCAN device, only the Channel-handle and bit rate parameters are needed. The other parameters will be assigned their default values. For No-Plug-&-Play devices, all parameters have to be entered.
Example

The following example shows the initialize and uninitialize processes for a Plug-And-Play channel (channel 2 of a PCAN-PCI hardware). In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C#:

TPCANStatus result;
StringBuilder strMsg;

// The Plug & Play Channel (PCAN-PCI) is initialized
//
result = PCANBasic.Initialize(PCANBasic.PCAN_PCIBUS2, TPCANBaudrate.PCAN_BAUD_500K);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = new StringBuilder(256);
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("PCAN-PCI (Ch-2) was initialized");

// All initialized channels are released
//
PCANBasic.Uninitialize(PCANBasic.PCAN_NONEBUS);

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;

// The Plug & Play Channel (PCAN-PCI) is initialized
//
result = PCANBasic::Initialize(PCANBasic::PCAN_PCIBUS2, TPCANBaudrate::PCAN_BAUD_500K);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = gcnew StringBuilder(256);
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("PCAN-PCI (Ch-2) was initialized");

// All initialized channels are released
//
PCANBasic::Uninitialize(PCANBasic::PCAN_NONEBUS);

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder

' The Plug & Play Channel (PCAN-PCI) is initialized
'
result = PCANBasic.Initialize(PCANBasic.PCAN_PCIBUS2, TPCANBaudrate.PCAN_BAUD_500K)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    strMsg = New StringBuilder(256)
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("PCAN-PCI (Ch-2) was initialized")
End If

' All initialized channels are released
'
PCANBasic.Uninitialize(PCANBasic.PCAN_NONEBUS)

Pascal OO:

var
 result : TPCANStatus;
 strMsg: array [0..256] of Char;
begin
    // The Plug & Play Channel (PCAN-PCI) is initialized
    //
    result := TPCANBasic.Initialize(TPCANBasic.PCAN_PCIBUS2, PCAN_BAUD_500K);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'PCAN-PCI (Ch-2) was initialized','Success', MB_OK);

    // All initialized channels are released
    //
    TPCANBasic.Uninitialize(TPCANBasic.PCAN_NONEBUS);
end;

Python:

# The Plug & Play Channel (PCAN-PCI) is initialized
#
objPCAN = PCANBasic()
result = objPCAN.Initialize(PCAN_PCIBUS2, PCAN_BAUD_500K)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("PCAN-PCI (Ch-2) was initialized")

# All initialized channels are released
#
objPCAN.Uninitialize(PCAN_NONEBUS)
See Also

Uninitialize

GetValue

Understanding PCAN-Basic

Plain function Version: CAN_Initialize


Initialize(TPCANHandle, TPCANBaudrate, TPCANType, UInt32, UInt16)

Initialize(TPCANHandle, TPCANBaudrate, TPCANType, UInt32, UInt16)

Initializes a PCAN Channel which represents a Not Plug & Play PCAN-Device.

Syntax
Pascal OO
class function Initialize(
    Channel: TPCANHandle;
    Btr0Btr1: TPCANBaudrate;
    HwType: TPCANType;
    IOPort: LongWord;
    Interrupt: Word
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Initialize")]
public static extern TPCANStatus Initialize(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType.U2)]
    TPCANBaudrate Btr0Btr1,
    [MarshalAs(UnmanagedType.U1)]
    TPCANType HwType,
    UInt32 IOPort,
    UInt16 Interrupt);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Initialize")]
static TPCANStatus Initialize(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType::U2)]
    TPCANBaudrate Btr0Btr1,
    [MarshalAs(UnmanagedType::U1)]
    TPCANType HwType,
    UInt32 IOPort,
    UInt16 Interrupt);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_Initialize")> _
Public Shared Function Initialize( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    <MarshalAs(UnmanagedType.U2)> _
    ByVal Btr0Btr1 As TPCANBaudrate, _
   <MarshalAs(UnmanagedType.U1)> _
   ByVal HwType As TPCANType, _
   ByVal IOPort As UInt32, _
   ByVal Interrupt As UInt16) As TPCANStatus
End Function
Python
def Initialize(
    self,
    Channel,
    Btr0Btr1,
    HwType = TPCANType(0),
    IOPort = c_uint(0),
    Interrupt = c_ushort(0))
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Btr0Btr1 | The speed for the communication (BTR0BTR1 code).
HwType | The type of hardware and operation mode (see TPCANMode).
IOPort | The I/O address for the parallel port.
Interrupt | Interrupt number of the parallel port.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_CAUTION:
Indicates that the channel has been initialized but at a different bit rate as the given one.
PCAN_ERROR_ILLHANDLE:
Indicates that the desired PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_ILLHW:
Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLOPERATION:
Indicates that an action cannot be executed due to the state of the hardware. Possible causes are:

  • The desired PCAN-Channel is a LAN Channel, which uses a different bit rate than the specified.

PCAN_ERROR_ILLMODE:
Indicates that the hardware is working in a different or incompatible mode than requested. Possible causes are:

  • The desired PCAN-Channel is being operated in CAN-FD mode.

PCAN_ERROR_REGTEST:
Indicates a problem with hardware registration, normally due to wrong values in the parameters 'HwType', 'IOPort' and 'Interrupt'.
PCAN_ERROR_INITIALIZE:
Indicates that the desired PCAN channel cannot be connected because it is already in use (PCAN-Basic / PCAN-Light environment).
PCAN_ERROR_NETINUSE:
Indicates that the desired PCAN-Channel is being used with a different bit rate (PCAN-View).
PCAN_ERROR_HWINUSE:
Indicates that the desired PCAN-Channel is being used (CanApi2 connection).
PCAN_ERROR_NODRIVER:
The driver needed for connecting the desired PCAN Channel is not loaded.
Remarks

As indicated by its name, the Initialize method initiates a PCAN Channel, preparing it for communicate within the CAN bus connected to it. Calls to the other methods will fail if they are used with a Channel handle, different than PCAN_NONEBUS, that has not been initialized yet. Each initialized channel should be released when it is not needed anymore.

Initializing a PCAN Channel means:

  • to reserve the Channel for the calling application/process.
  • to allocate channel resources, like receive and transmit queues.
  • to register/connect the Hardware denoted by the channel handle.
  • to check and adapt the bus speed, if the Channel is already in use. (Only if the Channel was pre-configured as Bitrate Adapting; see: Bitrate-Adapting Parameter).
  • to set the channel in Listen-Only mode. (Only if the channel was pre-configured as Listen-Only; see: Listen-Only Parameter).
  • to configure the filter to catch all messages being transmitted in the bus.
  • to set-up the default values of the different parameters (See GetValue).
  • to set the Receive Status of the channel. (Pre-configured value; see: Receive Status Parameter).

What is different from the PCAN-Light API, the Initialization process will fail if an application tries to initialize a PCAN-Channel that has been initialized already within the same process.

Take in consideration that initializing a channel causes a reset of the CAN hardware , when the bus status is other than OK. In this way errors like BUSOFF, BUSWARNING, and BUSPASSIVE, are removed.

PCAN-LAN Channels

A PCAN-LAN channel doesn't allow changing the bit rate using PCAN-Basic. In order to connect a PCAN-LAN Channel it is necessary to know the bit rate of the PCAN-Gateway device that is represented by that channel. If the bit rate is not known, the parameter Bitrate-Adapting should be used.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
  • Plug-&-Play and No-Plug-&-Play hardware: In order to initialize a channel which represents a Plug-&-Play PCAN device, only the Channel-handle and bit rate parameters are needed. The other parameters will be assigned their default values. For No-Plug-&-Play devices, all parameters have to be entered.
Example

The following example shows the initialize and uninitialize processes for a Not-Plug-And-Play channel (channel 1 of the PCAN-DNG). In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C#:

TPCANStatus result;
StringBuilder strMsg;

// The Not Plug & Play Channel (PCAN-DNG) is initialized
//
result = PCANBasic.Initialize(PCANBasic.PCAN_DNGBUS1, TPCANBaudrate.PCAN_BAUD_500K, TPCANType.PCAN_TYPE_DNG_SJA, 0x378, 7);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = new StringBuilder(256);
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("PCAN-DNG (Ch-1) was initialized");

// All initialized channels are released
//
PCANBasic.Uninitialize(PCANBasic.PCAN_NONEBUS);

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;

// The Not Plug & Play Channel (PCAN-DNG) is initialized
//
result = PCANBasic::Initialize(PCANBasic::PCAN_DNGBUS1, TPCANBaudrate::PCAN_BAUD_500K, TPCANType::PCAN_TYPE_DNG_SJA, 0x378, 7);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = gcnew StringBuilder(256);
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("PCAN-DNG (Ch-1) was initialized");

// All initialized channels are released
//
PCANBasic::Uninitialize(PCANBasic::PCAN_NONEBUS);

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder

' The Not Plug & Play Channel (PCAN-DNG) is initialized
'
result = PCANBasic.Initialize(PCANBasic.PCAN_DNGBUS1, TPCANBaudrate.PCAN_BAUD_500K, TPCANType.PCAN_TYPE_DNG_SJA, &H378, 7)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    strMsg = New StringBuilder(256)
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("PCAN-DNG (Ch-1) was initialized")
End If

' All initialized channels are released
'
PCANBasic.Uninitialize(PCANBasic.PCAN_NONEBUS)

Pascal OO:

var
 result : TPCANStatus;
 strMsg: array [0..256] of Char;
begin
    // The Not Plug & Play Channel (PCAN-DNG) is initialized
    //
    result := TPCANBasic.Initialize(TPCANBasic.PCAN_DNGBUS1, PCAN_BAUD_500K, PCAN_TYPE_DNG_SJA, $378, 7);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'PCAN-DNG (Ch-1) was initialized','Success', MB_OK);

    // All initialized channels are released
    //
    TPCANBasic.Uninitialize(TPCANBasic.PCAN_NONEBUS);
end;

Python:

# The Not Plug & Play Channel (PCAN-DNG) is initialized
#
objPCAN = PCANBasic()
result = objPCAN.Initialize(PCAN_DNGBUS1, PCAN_BAUD_500K, PCAN_TYPE_DNG_SJA, 0x378, 7)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("PCAN-DNG (Ch-1) was initialized")

# All initialized channels are released
#
objPCAN.Uninitialize(PCAN_NONEBUS)
See Also

Uninitialize

GetValue

Understanding PCAN-Basic

Plain function Version: CAN_Initialize


InitializeFD

InitializeFD

Initializes a FD capable PCAN Channel.

Syntax
Pascal OO
class function InitializeFD(
    Channel: TPCANHandle;
    BitrateFD: TPCANBitrateFD
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_InitializeFD")]
public static extern TPCANStatus InitializeFD(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    TPCANBitrateFD BitrateFD);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_InitializeFD")]
static TPCANStatus InitializeFD(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    TPCANBitrateFD BitrateFD);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_InitializeFD")> _
Public Shared Function InitializeFD( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    ByVal BitrateFD As TPCANBitrateFD) As TPCANStatus
End Function
Python
def InitializeFD(
    self,
    Channel,
    BitrateFD)
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
BitrateFD | The speed for the communication (FD Bitrate string).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_CAUTION:
Indicates that the channel has been initialized but at a different bit rate as the given one.
PCAN_ERROR_ILLHANDLE:
Indicates that the desired PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_ILLHW:
Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLOPERATION:
Indicates that an action cannot be executed due to the state of the hardware. Possible causes are:

  • The desired PCAN Channel is not FD capable and cannot be initialized using this method.
  • The desired PCAN-Channel is a LAN Channel, which uses a different bit rate than the specified.

PCAN_ERROR_ILLMODE:
Indicates that the hardware is working in a different or incompatible mode than requested. Possible causes are:

  • The desired PCAN-Channel is being operated in CAN 2.0 A/B mode.

PCAN_ERROR_INITIALIZE:
Indicates that the desired PCAN Channel cannot be connected because it is already in use (PCAN-Basic / PCAN-Light environment).
PCAN_ERROR_NETINUSE:
Indicates that the desired PCAN-Channel is being used with a different bit rate (PCAN-View).
PCAN_ERROR_HWINUSE:
Indicates that the desired PCAN-Channel is being used (CanApi connection).
PCAN_ERROR_NODRIVER:
The driver needed for connecting the desired PCAN Channel is not loaded.
Remarks

Note on correspondence of methods:

A Channel that is initialized using InitializeFD must use ReadFD and WriteFD for communication. Calling Read and/or Write will result in a PCAN_ERROR_ILLOPERATION error.

As indicated by its name, the InitializeFD method initiates a FD capable PCAN Channel, preparing it for communicate within the CAN bus connected to it. Calls to the API methods will fail if they are used with a Channel handle, different than PCAN_NONEBUS, that has not been initialized yet. Each initialized channel should be released when it is not needed anymore.

Initializing a PCAN Channel means:

  • to reserve the Channel for the calling application/process.
  • to allocate channel resources, like receive and transmit queues.
  • to register/connect the Hardware denoted by the channel handle.
  • to check and adapt the bus speed, if the Channel is already in use. (Only if the Channel was pre-configured as Bitrate Adapting; see: Bitrate-Adapting Parameter).
  • to set the channel in Listen-Only mode. (Only if the channel was pre-configured as Listen-Only; see: Listen-Only Parameter).
  • to open the messages filter for the application/process.
  • to set-up the default values of the different parameters (See GetValue).
  • to set the Receive Status of the channel. (Pre-configured value; see: Receive Status Parameter).

The Initialization process will fail if an application try to initialize a PCAN-Channel that has been initialized already within the same process.

Take in consideration that initializing a channel causes a reset of the CAN hardware , when the bus status is other than OK. In this way errors like BUSOFF, BUSWARNING, and BUSPASSIVE, are removed.

PCAN-LAN Channels

A PCAN-LAN channel doesn't allow changing the bit rate using PCAN-Basic. In order to connect a PCAN-LAN Channel it is necessary to know the bit rate of the PCAN-Gateway device that is represented by that channel. If the bit rate is not known, the parameter Bitrate-Adapting should be used.

Python Notes

  • Class-Method: Different than the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the initialize and uninitialize processes for a FD capable channel (channel 1 of a PCAN-USB Pro FD hardware). In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C#:

string bitrate;
TPCANStatus result;
StringBuilder strMsg;

// Defines a FD Bit rate string with nominal and data Bit rate set to 1 MB
//
bitrate = "f_clock_mhz=24, nom_brp=1, nom_tseg1=17, nom_tseg2=6, nom_sjw=1, data_brp=1, data_tseg1=16, data_tseg2=7, data_sjw=1";

// The FD capable Channel (PCAN-USB Pro FD) is initialized
//
result = PCANBasic.InitializeFD(PCANBasic.PCAN_USBBUS1, bitrate);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = new StringBuilder(256);
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("PCAN-USB Pro FD (Ch-1) was initialized");

// All initialized channels are released
//
PCANBasic.Uninitialize(PCANBasic.PCAN_NONEBUS);

C++/CLR:

String^ bitrate;
TPCANStatus result;
StringBuilder^ strMsg;

// Defines a FD Bit rate string with nominal and data Bit rate set to 1 MB
//
bitrate = "f_clock_mhz=24, nom_brp=1, nom_tseg1=17, nom_tseg2=6, nom_sjw=1, data_brp=1, data_tseg1=16, data_tseg2=7, data_sjw=1";

// The FD capable Channel (PCAN-USB Pro FD) is initialized
//
result = PCANBasic::InitializeFD(PCANBasic::PCAN_USBBUS1, bitrate);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = gcnew StringBuilder(256);
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("PCAN-USB Pro FD (Ch-1) was initialized");

// All initialized channels are released
//
PCANBasic::Uninitialize(PCANBasic::PCAN_NONEBUS);

Visual Basic:

Dim bitrate As String
Dim result As TPCANStatus
Dim strMsg As StringBuilder

' Defines a FD Bit rate string with nominal and data Bit rate set to 1 MB
'
bitrate = "f_clock_mhz=24, nom_brp=1, nom_tseg1=17, nom_tseg2=6, nom_sjw=1, data_brp=1, data_tseg1=16, data_tseg2=7, data_sjw=1"

' The FD capable Channel (PCAN-USB Pro FD) is initialized
'
result = PCANBasic.InitializeFD(PCANBasic.PCAN_USBBUS1, bitrate)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    strMsg = New StringBuilder(256)
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("PCAN-USB Pro FD (Ch-1) was initialized")
End If

' All initialized channels are released
'
PCANBasic.Uninitialize(PCANBasic.PCAN_NONEBUS)

Pascal OO:

var
 bitrate: String;
 result : TPCANStatus;
 strMsg: array [0..256] of Char;
begin
    // Defines a FD Bit rate string with nominal and data Bit rate set to 1 MB
    //
    bitrate := 'f_clock_mhz=24, nom_brp=1, nom_tseg1=17, nom_tseg2=6, nom_sjw=1, data_brp=1, data_tseg1=16, data_tseg2=7, data_sjw=1';

    // The FD capable Channel (PCAN-USB Pro FD) is initialized
    //
    result := TPCANBasic.InitializeFD(TPCANBasic.PCAN_USBBUS1, bitrate);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'PCAN-USB Pro FD (Ch-1) was initialized','Success', MB_OK);

    // All initialized channels are released
    //
    TPCANBasic.Uninitialize(TPCANBasic.PCAN_NONEBUS);
end;

Python:

# Defines a FD Bit rate ascii string with nominal and data Bit rate set to 1 MB
#
bitrate = b"f_clock_mhz=24, nom_brp=1, nom_tseg1=17, nom_tseg2=6, nom_sjw=1, data_brp=1, data_tseg1=16, data_tseg2=7, data_sjw=1"

# The FD capable Channel (PCAN-USB Pro FD) is initialized
#
objPCAN = PCANBasic()
result = objPCAN.InitializeFD(PCAN_USBBUS1, bitrate)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("PCAN-USB Pro FD (Ch-1) was initialized")

# All initialized channels are released
#
objPCAN.Uninitialize(PCAN_NONEBUS)
See Also

Uninitialize

ReadFD

WriteFD

Plain function Version: CAN_InitializeFD


Uninitialize

Uninitialize

Uninitializes a PCAN Channel.

Syntax
Pascal OO
class function Uninitialize(
    Channel: TPCANHandle
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Uninitialize")]
public static extern TPCANStatus Uninitialize(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Uninitialize")]
static TPCANStatus Uninitialize(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_Uninitialize")> _
Public Shared Function Uninitialize( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle) As TPCANStatus
End Function
Python
def Uninitialize(
    self,
    Channel)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel cannot be uninitialized because it was not found in the list of reserved channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
Remarks

A PCAN Channel can be released using one of this possibilities:

Single-Release: Given a handle of a PCAN Channel initialized before with the method Initialize. If the given channel can not be found then an error is returned.

Multiple-Release: Giving the handle value PCAN_NONEBUS which instructs the API to search for all channels initialized by the calling application and release them all. This option cause no errors if no hardware were uninitialized.

Transmit-queue at uninitialize: When a PCAN-Basic channel connection is terminated, the underlying hardware's transmit-queue will not immediately be discarded. PCAN-Basic will wait some time before finalizing, so that the hardware has time to send (or try to send) those unsent messages. When the time is up (amount 500 milliseconds), the rest of the messages in the queue (if any) are discarded.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the initialize and uninitialize (Single-Release) processes for the PCAN_PCIBUS1 channel. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: To see an example of Multiple-Release, see the Initialize method.

C#:

TPCANStatus result;
StringBuilder strMsg;

strMsg = new StringBuilder(256);

// The Plug & Play Channel (PCAN-PCI) is initialized
//
result = PCANBasic.Initialize(PCANBasic.PCAN_PCIBUS1, TPCANBaudrate.PCAN_BAUD_500K);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("PCAN-PCI (Ch-1) was initialized");

....

// The PCI Channel is released
//
result = PCANBasic.Uninitialize(PCANBasic.PCAN_PCIBUS1);

if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("PCAN-PCI (Ch-1) was released");

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;

strMsg = gcnew StringBuilder(256);

// The Plug & Play Channel (PCAN-PCI) is initialized
//
result = PCANBasic::Initialize(PCANBasic::PCAN_PCIBUS1, TPCANBaudrate::PCAN_BAUD_500K);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("PCAN-PCI (Ch-1) was initialized");

....

// The PCI Channel is released
//
result = PCANBasic::Uninitialize(PCANBasic::PCAN_PCIBUS1);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("PCAN-PCI (Ch-1) was released");

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder

strMsg = New StringBuilder(256)

' The Plug & Play Channel (PCAN-PCI) is initialized
'
result = PCANBasic.Initialize(PCANBasic.PCAN_PCIBUS1, TPCANBaudrate.PCAN_BAUD_500K)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("PCAN-PCI (Ch-1) was initialized")
End If

....

' The PCI Channel is released
'
result = PCANBasic.Uninitialize(PCANBasic.PCAN_PCIBUS1)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("PCAN-PCI (Ch-1) was released")
End If

Pascal OO:

var
 result : TPCANStatus;
 strMsg: array [0..256] of Char;
begin
    // The Plug & Play Channel (PCAN-PCI) is initialized
    //
    result := TPCANBasic.Initialize(TPCANBasic.PCAN_PCIBUS1, PCAN_BAUD_500K);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'PCAN-PCI (Ch-1) was initialized','Success', MB_OK);

....

    // The PCI Channel is released
    //
    result := TPCANBasic.Uninitialize(TPCANBasic.PCAN_PCIBUS1);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'PCAN-PCI (Ch-1) was released','Success', MB_OK);
end;

Python:

# The Plug & Play Channel (PCAN-PCI) is initialized
#
objPCAN = PCANBasic()
result = objPCAN.Initialize(PCAN_PCIBUS1, PCAN_BAUD_500K)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("PCAN-PCI (Ch-1) was initialized")

....

# The PCI Channel is released
#
result = objPCAN.Uninitialize(PCAN_PCIBUS1)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("PCAN-PCI (Ch-1) was released")
See Also

Initialize

Plain function Version: CAN_Uninitialize


Reset

Reset

Resets the receive and transmit queues of a PCAN Channel.

Syntax
Pascal OO
class function Reset(
    Channel: TPCANHandle
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Reset")]
public static extern TPCANStatus Reset(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Reset")]
static TPCANStatus Reset(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_Reset")> _
Public Shared Function Reset( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle) As TPCANStatus
End Function
Python
def Reset(
    self,
    Channel)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
Remarks

Calling this method ONLY clears the queues of a Channel. A reset of the CAN controller doesn't take place.

Normally a reset of the CAN Controller is desired when a bus-off occur. In this case an application cannot use the channel to communicate anymore, until the CAN controller is reset. Consider using the PCAN-Basic parameter PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like bus-off, bus-heavy and bus-light, is to uninitialize and initialize the used channel again. This causes a hardware reset, but only when no more clients are connected to that channel.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method Reset on the channel PCAN_PCIBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;

strMsg = new StringBuilder(256);

......

// The PCI Channel is reset
//
result = PCANBasic.Reset(PCANBasic.PCAN_PCIBUS1);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("PCAN-PCI (Ch-1) was reset");

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;

strMsg = gcnew StringBuilder(256);

......

// The PCI Channel is reset
//
result = PCANBasic::Reset(PCANBasic::PCAN_PCIBUS1);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("PCAN-PCI (Ch-1) was reset");

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder

strMsg = New StringBuilder(256)

......

' The PCI Channel is reset
'
result = PCANBasic.Reset(PCANBasic.PCAN_PCIBUS1)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("PCAN-PCI (Ch-1) was reset")
End If

Pascal OO:

var
 result : TPCANStatus;
 strMsg: array [0..256] of Char;
begin

......

    // The PCI Channel is reset
    //
    result := TPCANBasic.Reset(TPCANBasic.PCAN_PCIBUS1);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'PCAN-PCI (Ch-1) was reset','Success', MB_OK);

Python:

......

# The PCI Channel is released
#
result = objPCAN.Reset(PCAN_PCIBUS1)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("PCAN-PCI (Ch-1) was reset")
See Also

Read

Write

SetValue

Plain function Version: CAN_Reset


GetStatus

GetStatus

Gets the current BUS status of a PCAN Channel.

Syntax
Pascal OO
class function GetStatus(
    Channel: TPCANHandle
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetStatus")]
public static extern TPCANStatus GetStatus(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetStatus")]
static TPCANStatus GetStatus(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_GetStatus")> _
Public Shared Function GetStatus( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle) As TPCANStatus
End Function
Python
def GetStatus(
    self,
    Channel)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Returns

The return value is a TPCANStatus code. The typical return values are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN Channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSLIGHT: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-light status.
PCAN_ERROR_BUSHEAVY: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-heavy status.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.
PCAN_ERROR_OK: | Indicates that the status of the given PCAN Channel is OK.
Remarks

When the hardware status is bus-off, an application cannot communicate anymore. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like bus-off, bus-heavy and bus-light, is to uninitialize and initialise the used channel again. This causes a hardware reset.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method GetStatus on the channel PCAN_PCIBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;

strMsg = new StringBuilder(256);

......

// Check the status of the PCI Channel
//
result = PCANBasic.GetStatus(PCANBasic.PCAN_PCIBUS1);
switch (result)
{
    case TPCANStatus.PCAN_ERROR_BUSLIGHT:
        MessageBox.Show("PCAN-PCI (Ch-1): Handling a BUS-LIGHT status...");
        break;
    case TPCANStatus.PCAN_ERROR_BUSHEAVY:
        MessageBox.Show("PCAN-PCI (Ch-1): Handling a BUS-HEAVY status...");
        break;
    case TPCANStatus.PCAN_ERROR_BUSOFF:
        MessageBox.Show("PCAN-PCI (Ch-1): Handling a BUS-OFF status...");
        break;
    case TPCANStatus.PCAN_ERROR_OK:
        MessageBox.Show("PCAN-PCI (Ch-1): Status is OK");
        break;
    default:
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
        break;
}

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;

strMsg = gcnew StringBuilder(256);

......

// Check the status of the PCI Channel
//
result = PCANBasic::GetStatus(PCANBasic::PCAN_PCIBUS1);
switch (result)
{
    case TPCANStatus::PCAN_ERROR_BUSLIGHT:
        MessageBox::Show("PCAN-PCI (Ch-1): Handling a BUS-LIGHT status...");
        break;
    case TPCANStatus::PCAN_ERROR_BUSHEAVY:
        MessageBox::Show("PCAN-PCI (Ch-1): Handling a BUS-HEAVY status...");
        break;
    case TPCANStatus::PCAN_ERROR_BUSOFF:
        MessageBox::Show("PCAN-PCI (Ch-1): Handling a BUS-OFF status...");
        break;
    case TPCANStatus::PCAN_ERROR_OK:
        MessageBox::Show("PCAN-PCI (Ch-1): Status is OK");
        break;
    default:
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic::GetErrorText(result, 0, strMsg);
        MessageBox::Show(strMsg->ToString());
        break;
}

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder

strMsg = New StringBuilder(256)

......

' Check the status of the PCI Channel
'
result = PCANBasic.GetStatus(PCANBasic.PCAN_PCIBUS1)
Select Case result
    Case TPCANStatus.PCAN_ERROR_BUSLIGHT
        MessageBox.Show("PCAN-PCI (Ch-1): Handling a BUS-LIGHT status...")
    Case TPCANStatus.PCAN_ERROR_BUSHEAVY
        MessageBox.Show("PCAN-PCI (Ch-1): Handling a BUS-HEAVY status...")
    Case TPCANStatus.PCAN_ERROR_BUSOFF
        MessageBox.Show("PCAN-PCI (Ch-1): Handling a BUS-OFF status...")
    Case TPCANStatus.PCAN_ERROR_OK
        MessageBox.Show("PCAN-PCI (Ch-1): Status is OK")
    Case Else
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        MessageBox.Show(strMsg.ToString)
End Select

Pascal OO:

var
 result : TPCANStatus;
 strMsg: array [0..256] of Char;
begin

......

// Check the status of the PCI Channel
//
result := TPCANBasic.GetStatus(TPCANBasic.PCAN_PCIBUS1);
case result of
    PCAN_ERROR_BUSLIGHT:
        MessageBox(0,'PCAN-PCI (Ch-1): Handling a BUS-LIGHT status...','Status',MB_OK);
    PCAN_ERROR_BUSHEAVY:
        MessageBox(0,'PCAN-PCI (Ch-1): Handling a BUS-HEAVY status...','Status',MB_OK);
    PCAN_ERROR_BUSOFF:
        MessageBox(0,'PCAN-PCI (Ch-1): Handling a BUS-OFF status...','Status',MB_OK);
    PCAN_ERROR_OK:
        MessageBox(0,'PCAN-PCI (Ch-1): Status is OK','Status',MB_OK);
    else
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end;
end;

Python:

......

# Check the status of the PCI Channel
#
result = objPCAN.GetStatus(PCAN_PCIBUS1)
if result == PCAN_ERROR_BUSLIGHT:
    print ("PCAN-PCI (Ch-1): Handling a BUS-LIGHT status...")
elif result == PCAN_ERROR_BUSHEAVY:
    print ("PCAN-PCI (Ch-1): Handling a BUS-HEAVY status...")
elif result == PCAN_ERROR_BUSOFF:
    print ("PCAN-PCI (Ch-1): Handling a BUS-OFF status...")
elif result == PCAN_ERROR_OK:
    print ("PCAN-PCI (Ch-1): Status is OK")
else:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
See Also

Parameter Value Definitions

TPCANParameter

Plain function Version: CAN_GetStatus


Read

Read

Reads a CAN message from the receive queue of a PCAN Channel.

Overloads
Function | Description
Read(TPCANHandle, TPCANMsg) | Reads a CAN message from the receive queue.
Read(TPCANHandle, TPCANMsg, TPCANTimestamp) | Reads a CAN message and its time stamp from the receive queue.
Read(TPCANHandle) | Reads a CAN message and its time stamp from the receive queue.


Read(TPCANHandle, TPCANMsg)

Read(TPCANHandle, TPCANMsg)

Reads a CAN message from the receive queue of a PCAN Channel.

Syntax
Pascal OO
class function Read(
    Channel: TPCANHandle;
    var MessageBuffer: TPCANMsg
    ): TPCANStatus; overload;
C#
public static TPCANStatus Read(
    TPCANHandle Channel,
    out TPCANMsg MessageBuffer);
C++ / CLR
static TPCANStatus Read(
    TPCANHandle Channel,
    TPCANMsg %MessageBuffer);
Visual Basic
Public Shared Function Read( _
    ByVal Channel As TPCANHandle, _
    ByRef MessageBuffer As TPCANMsg) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsg buffer to store the CAN message.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsg structure.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSLIGHT: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-light status. Note: MessageBuffer is valid in this case.
PCAN_ERROR_BUSHEAVY: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-heavy status. Note: MessageBuffer is valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: MessageBuffer is valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.
Remarks

The Read method returns received messages or status messages from the receive queue. It is important to call Read repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

If the time when the message was received is needed, use the overloaded Read method.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the Read method. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the Read method in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a method directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSHEAVY, and BUSLIGTH, is to uninitialize and initialise the used channel again. This causes a hardware reset, but only when no more clients are connected to that channel.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_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.

Note that if a status message was read the return value of Read is also the error code.

Examples:

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

The following example shows the use of method Read on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized and that the following code is an OnTimer event handler method.

C#:

TPCANStatus result;
StringBuilder strMsg;
TPCANMsg msg;

strMsg = new StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic.Read(PCANBasic.PCAN_USBBUS1, out msg);
    if (result != TPCANStatus.PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox.Show("A message was received");
        ProcessMessage(msg);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus.PCAN_ERROR_QRCVEMPTY) != TPCANStatus.PCAN_ERROR_QRCVEMPTY);

C++CLR:

TPCANStatus result;
StringBuilder^ strMsg;
TPCANMsg msg;

strMsg = gcnew StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic::Read(PCANBasic::PCAN_USBBUS1, msg);
    if (result != TPCANStatus::PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox::Show("A message was received");
        ProcessMessage(msg);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic::GetErrorText(result, 0, strMsg);
        MessageBox::Show(strMsg->ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus::PCAN_ERROR_QRCVEMPTY) != TPCANStatus::PCAN_ERROR_QRCVEMPTY);

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim msg As TPCANMsg

strMsg = New StringBuilder(256)

Do
    ' Check the receive queue for new messages
    '
    result = PCANBasic.Read(PCANBasic.PCAN_USBBUS1, msg)
    If result <> TPCANStatus.PCAN_ERROR_QRCVEMPTY Then
        MessageBox.Show("A message was received")
        ProcessMessage(msg)
    Else
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        MessageBox.Show(strMsg.ToString())
        ' Here can be decided if the loop has to be  terminated (eg. the bus
        ' status is  bus-off)
        '
        HandleReadError(result)
    End If
' Try to read a message from the receive queue of the PCAN-USB, Channel 1,
' until the queue is empty
'
Loop While ((result And TPCANStatus.PCAN_ERROR_QRCVEMPTY) <> TPCANStatus.PCAN_ERROR_QRCVEMPTY)

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    msg: TPCANMsg;
begin
    repeat
        // Check the receive queue for new messages
        //
        result := TPCANBasic.Read(TPCANBasic.PCAN_USBBUS1, msg);
        If (result <> PCAN_ERROR_QRCVEMPTY) Then
        begin
            // Process the received message
            //
            MessageBox(0,'A message was received','Success', MB_OK);
            ProcessMessage(msg);
        end
        else
        begin
            // An error occurred, get a text describing the error and show it
            //
            TPCANBasic.GetErrorText(result, 0, strMsg);
            MessageBox(0, strMsg, 'Error',MB_OK);
            // Here can be decided if the loop has to be  terminated (eg. the bus
            // status is  bus-off)
            //
            HandleReadError(result);
        end;
    // Try to read a message from the receive queue of the PCAN-USB, Channel 1,
    // until the queue is empty
    //
    until ((TPCANStatus(Integer(result) AND Integer(PCAN_ERROR_QRCVEMPTY))) = PCAN_ERROR_QRCVEMPTY);
See Also

Write

Using Events

Error Frames

Plain function Version: CAN_Read


Read(TPCANHandle, TPCANMsg, TPCANTimestamp)

Read(TPCANHandle, TPCANMsg, TPCANTimestamp)

Reads a CAN message and its time stamp from the receive queue of a PCAN Channel.

Syntax
Pascal OO
class function Read(
    Channel: TPCANHandle;
    var MessageBuffer: TPCANMsg;
    var TimestampBuffer: TPCANTimestamp
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Read")]
public static extern TPCANStatus Read(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    out TPCANMsg MessageBuffer,
    ref TPCANTimestamp TimestampBuffer);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Read")]
static TPCANStatus Read(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    TPCANMsg %MessageBuffer,
    TPCANTimestamp %TimestampBuffer);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_Read")> _
Public Shared Function Read( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    ByRef MessageBuffer As TPCANMsg, _
    ByRef TimestampBuffer As TPCANTimestamp) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsg buffer to store the CAN message.
TimestampBuffer | A TPCANTimestamp buffer to get the reception time of the message.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsg structure.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSLIGHT: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-light status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSHEAVY: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-heavy status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.
Remarks

The Read method returns received messages or status messages from the receive queue. It is important to call Read repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

If the time when the message was received is not needed, use the overloaded Read method.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the Read method. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the Read method in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a method directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSHEAVY, and BUSLIGTH, is to uninitialize and initialise the used channel again. This causes a hardware reset, but only when no more clients are connected to that channel.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_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.

Note that if a status message was read the return value of Read is also the error code.

Examples:

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

The following example shows the use of method Read on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized and that the following code is an OnTimer event handler method.

C#:

TPCANStatus result;
StringBuilder strMsg;
TPCANMsg msg;
TPCANTimestamp time;

strMsg = new StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic.Read(PCANBasic.PCAN_USBBUS1, out msg, out time);
    if (result != TPCANStatus.PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox.Show("A message was received");
        ProcessMessage(msg, time);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus.PCAN_ERROR_QRCVEMPTY) != TPCANStatus.PCAN_ERROR_QRCVEMPTY);

C++CLR:

TPCANStatus result;
StringBuilder^ strMsg;
TPCANMsg msg;
TPCANTimestamp time;

strMsg = gcnew StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic::Read(PCANBasic::PCAN_USBBUS1, msg, time);
    if (result != TPCANStatus::PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox::Show("A message was received");
        ProcessMessage(msg, time);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic::GetErrorText(result, 0, strMsg);
        MessageBox::Show(strMsg->ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus::PCAN_ERROR_QRCVEMPTY) != TPCANStatus::PCAN_ERROR_QRCVEMPTY);

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim msg As TPCANMsg
Dim time As TPCANTimestamp

strMsg = New StringBuilder(256)

Do
    ' Check the receive queue for new messages
    '
    result = PCANBasic.Read(PCANBasic.PCAN_USBBUS1, msg, time)
    If result <> TPCANStatus.PCAN_ERROR_QRCVEMPTY Then
        MessageBox.Show("A message was received")
        ProcessMessage(msg, time)
    Else
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        MessageBox.Show(strMsg.ToString())
        ' Here can be decided if the loop has to be  terminated (eg. the bus
        ' status is  bus-off)
        '
        HandleReadError(result);
    End If
' Try to read a message from the receive queue of the PCAN-USB, Channel 1,
' until the queue is empty
'
Loop While ((result And TPCANStatus.PCAN_ERROR_QRCVEMPTY) <> TPCANStatus.PCAN_ERROR_QRCVEMPTY)

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    msg: TPCANMsg;
    time: TPCANTimestamp;
begin
    repeat
        // Check the receive queue for new messages
        //
        result := TPCANBasic.Read(TPCANBasic.PCAN_USBBUS1, msg, time);
        If (result <> PCAN_ERROR_QRCVEMPTY) Then
        begin
            // Process the received message
            //
            MessageBox(0,'A message was received','Success', MB_OK);
            ProcessMessage(msg, time);
        end
        else
        begin
            // An error occurred, get a text describing the error and show it
            //
            TPCANBasic.GetErrorText(result, 0, strMsg);
            MessageBox(0, strMsg, 'Error',MB_OK);
            // Here can be decided if the loop has to be  terminated (eg. the bus
            // status is  bus-off)
            //
            HandleReadError(result);
        end;
    // Try to read a message from the receive queue of the PCAN-USB, Channel 1,
    // until the queue is empty
    //
    until ((TPCANStatus(Integer(result) AND Integer(PCAN_ERROR_QRCVEMPTY))) = PCAN_ERROR_QRCVEMPTY);
See Also

Write

Using Events

Error Frames

Plain function Version: CAN_Read


Read(TPCANHandle)

Read(TPCANHandle)

Reads a CAN message and its time stamp from the receive queue of a PCAN Channel.

Syntax
Python
def Read(
    self,
    Channel)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Returns

The return value is a 3-touple. The order of the returned values is as follows:

[0]: The method's return value as a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the Message Buffer; it should represents a TPCANMsg structure.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSLIGHT: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-light status. Note: All touples are valid in this case.
PCAN_ERROR_BUSHEAVY: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-heavy status. Note: All touples are valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: All touples are valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.

[1]: A TPCANMsg structure with the CAN message read.

[2]: A TPCANTimestamp structure with the time when a message was read.

Remarks

The Read method returns received messages or status messages from the receive queue. It is important to call Read repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the Read method. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the Read method in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a method directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSHEAVY, and BUSLIGTH, is to uninitialize and initialise the used channel again. This causes a hardware reset, but only when no more clients are connected to that channel.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_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.

Note that if a status message was read the return value of Read is also the error code.

Examples:

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

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of method Read on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized and that the following code is executed periodically.

Python:

readResult = PCAN_ERROR_OK,
while (readResult[0] & PCAN_ERROR_QRCVEMPTY) != PCAN_ERROR_QRCVEMPTY:
    # Check the receive queue for new messages
    #
    readResult = objPCAN.Read(PCAN_USBBUS1)
    if readResult[0] != PCAN_ERROR_QRCVEMPTY:
        # Process the received message
        #
        print ("A message was received")
        ProcessMessage(result[1],result[2]) # Possible processing function, ProcessMessage(msg,timestamp)
    else:
        # An error occurred, get a text describing the error and show it
        #
        result = objPCAN.GetErrorText(readResult[0])
        print (result[1])
        HandleReadError(readResult[0]) # Possible errors handling function, HandleError(function_result)
See Also

Write

Using Events

Error Frames

Plain function Version: CAN_Read


ReadFD

ReadFD

Reads a CAN message from the receive queue of a FD capable PCAN Channel.

Overloads
Function | Description
ReadFD(TPCANHandle, TPCANMsgFD) | Reads a CAN message from the receive queue .
ReadFD(TPCANHandle, TPCANMsgFD, TPCANTimestampFD) | Reads a CAN message and its time stamp from the receive queue.
ReadFD(TPCANHandle) | Reads a CAN message and its time stamp from the receive queue.


ReadFD(TPCANHandle, TPCANMsgFD)

ReadFD(TPCANHandle, TPCANMsgFD)

Reads a CAN message from the receive queue of a FD capable PCAN Channel.

Syntax
Pascal OO
class function ReadFD(
    Channel: TPCANHandle;
    var MessageBuffer: TPCANMsgFD
    ):TPCANStatus; overload;
C#
public static TPCANStatus ReadFD(
    TPCANHandle Channel,
    out TPCANMsgFD MessageBuffer)
C++ / CLR
static TPCANStatus ReadFD(
    TPCANHandle Channel,
    TPCANMsgFD %MessageBuffer);
Visual Basic
Public Shared Function ReadFD( _
    ByVal Channel As TPCANHandle, _
    ByRef MessageBuffer As TPCANMsgFD) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsgFD buffer to store the CAN message.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsgFD structure.
PCAN_ERROR_ILLOPERATION: | Indicates that the PCAN Channel passed to the method was not initialized using InitializeFD (plain function: CAN_InitializeFD).
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSWARNING: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-warning status. Note: MessageBuffer is valid in this case.
PCAN_ERROR_BUSPASSIVE: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-passive status. Note: MessageBuffer is valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: MessageBuffer is valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.
Remarks

The use of Read and ReadFD are mutually exclusive. The PCAN Channel passed to this method must be initialized using InitializeFD (plain function: CAN_InitializeFD). Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

If the time when the message was received is needed, use the overloaded ReadFD method.

The ReadFD method returns received messages or status messages from the receive queue. It is important to call ReadFD repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the ReadFD method. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the ReadFD method in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSWARNING, and BUSPASSIVE, is to uninitialize and initialise the used channel again. This causes a hardware reset.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, FD, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_STATUS is set in the TPCANMsg.MSGTYPE field, the message is a Status message. The ID and DLC 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.

Note that if a status message was read the return value of ReadFD is also the error code.

Examples:

Data0 | Data1 | Data2 | Data3 | Error | Error Code | Description
00h | 00h | 00h | 00h | PCAN_ERROR_OK | 0000h | CAN controller has been successfully activated.
00h | 00h | 00h | 02h | PCAN_ERROR_OVERRUN | 0002h | CAN controller has been read out too late.
00h | 00h | 00h | 08h | PCAN_ERROR_BUSWARNING | 0008h | Bus error: An error counter reached the 'warning' limit.
00h | 04h | 00h | 00h | PCAN_ERROR_BUSPASSIVE | 40000h | Bus error: the CAN controller is error passive.
00h | 00h | 00h | 10h | PCAN_ERROR_BUSOFF | 0010h | Bus error: CAN Controller is in 'Bus Off' state.
Example

The following example shows the use of method ReadFD on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized using the method InitializeFD and that the following code is an OnTimer event handler method.

C#:

TPCANStatus result;
StringBuilder strMsg;
TPCANMsgFD msg;

strMsg = new StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic.ReadFD(PCANBasic.PCAN_USBBUS1, out msg);
    if (result != TPCANStatus.PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox.Show("A message was received");
        ProcessMessage(msg);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus.PCAN_ERROR_QRCVEMPTY) != TPCANStatus.PCAN_ERROR_QRCVEMPTY);

C++CLR:

TPCANStatus result;
StringBuilder^ strMsg;
TPCANMsgFD msg;

strMsg = gcnew StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic::ReadFD(PCANBasic::PCAN_USBBUS1, msg);
    if (result != TPCANStatus::PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox::Show("A message was received");
        ProcessMessage(msg);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic::GetErrorText(result, 0, strMsg);
        MessageBox::Show(strMsg->ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus::PCAN_ERROR_QRCVEMPTY) != TPCANStatus::PCAN_ERROR_QRCVEMPTY);

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim msg As TPCANMsgFD

strMsg = New StringBuilder(256)

Do
    ' Check the receive queue for new messages
    '
    result = PCANBasic.ReadFD(PCANBasic.PCAN_USBBUS1, msg)
    If result <> TPCANStatus.PCAN_ERROR_QRCVEMPTY Then
        ' Process the received message
        '
        MessageBox.Show("A message was received")
        ProcessMessage(msg)
    Else
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        MessageBox.Show(strMsg.ToString())
        ' Here can be decided if the loop has to be  terminated (eg. the bus
        ' status is  bus-off)
        '
        HandleReadError(result)
    End If
' Try to read a message from the receive queue of the PCAN-USB, Channel 1,
' until the queue is empty
'
Loop While ((result And TPCANStatus.PCAN_ERROR_QRCVEMPTY) <> TPCANStatus.PCAN_ERROR_QRCVEMPTY)

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    msg: TPCANMsgFD;
begin
    repeat
        // Check the receive queue for new messages
        //
        result := TPCANBasic.ReadFD(TPCANBasic.PCAN_USBBUS1, msg);
        If (result <> PCAN_ERROR_QRCVEMPTY) Then
        begin
            // Process the received message
            //
            MessageBox(0,'A message was received','Success', MB_OK);
            ProcessMessage(msg);
        end
        else
        begin
            // An error occurred, get a text describing the error and show it
            //
            TPCANBasic.GetErrorText(result, 0, strMsg);
            MessageBox(0, strMsg, 'Error',MB_OK);
            // Here can be decided if the loop has to be  terminated (eg. the bus
            // status is  bus-off)
            //
            HandleReadError(result);
        end;
    // Try to read a message from the receive queue of the PCAN-USB, Channel 1,
    // until the queue is empty
    //
    until ((TPCANStatus(Integer(result) AND Integer(PCAN_ERROR_QRCVEMPTY))) = PCAN_ERROR_QRCVEMPTY);
See Also

WriteFD

Using Events

Error Frames

Plain function Version: CAN_ReadFD


ReadFD(TPCANHandle, TPCANMsgFD, TPCANTimestampFD)

ReadFD(TPCANHandle, TPCANMsgFD, TPCANTimestampFD)

Reads a CAN message and its time stamp from the receive queue of a FD capable PCAN Channel.

Syntax
Pascal OO
class function ReadFD(
    Channel: TPCANHandle;
    var MessageBuffer: TPCANMsgFD;
    var TimestampBuffer: TPCANTimestampFD
    ):TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_ReadFD")]
public static extern TPCANStatus ReadFD(
     [MarshalAs(UnmanagedType.U1)]
     TPCANHandle Channel,
     out TPCANMsgFD MessageBuffer,
     out TPCANTimestampFD TimestampBuffer);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_ReadFD")]
static TPCANStatus ReadFD(
     [MarshalAs(UnmanagedType::U1)]
     TPCANHandle Channel,
     TPCANMsgFD %MessageBuffer,
     TPCANTimestampFD %TimestampBuffer);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_ReadFD")> _
Public Shared Function ReadFD( _
     <MarshalAs(UnmanagedType.U1)> _
     ByVal Channel As TPCANHandle, _
     ByRef MessageBuffer As TPCANMsgFD, _
     ByRef TimestampBuffer As TPCANTimestampFD) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsgFD buffer to store the CAN message.
TimestampBuffer | A TPCANTimestampFD buffer to get the reception time of the message.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsgFD structure.
PCAN_ERROR_ILLOPERATION: | Indicates that the PCAN Channel passed to the method was not initialized using InitializeFD (plain function: CAN_InitializeFD).
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSWARNING: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-warning status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSPASSIVE: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-passive status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.
Remarks

The use of Read and ReadFD are mutually exclusive. The PCAN Channel passed to this method must be initialized using InitializeFD (plain function: CAN_InitializeFD). Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

If the time when the message was received is not needed, use the overloaded ReadFD method.

The ReadFD method returns received messages or status messages from the receive queue. It is important to call ReadFD repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the ReadFD method. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the ReadFD method in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSWARNING, and BUSPASSIVE, is to uninitialize and initialise the used channel again. This causes a hardware reset.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, FD, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_STATUS is set in the TPCANMsg.MSGTYPE field, the message is a Status message. The ID and DLC 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.

Note that if a status message was read the return value of ReadFD is also the error code.

Examples:

Data0 | Data1 | Data2 | Data3 | Error | Error Code | Description
00h | 00h | 00h | 02h | PCAN_ERROR_OK | 0000h | CAN controller has been successfully activated.
00h | 00h | 00h | 02h | PCAN_ERROR_OVERRUN | 0002h | CAN controller has been read out too late.
00h | 00h | 00h | 08h | PCAN_ERROR_BUSWARNING | 0008h | Bus error: An error counter reached the 'warning' limit.
00h | 04h | 00h | 00h | PCAN_ERROR_BUSPASSIVE | 40000h | Bus error: the CAN controller is error passive.
00h | 00h | 00h | 10h | PCAN_ERROR_BUSOFF | 0010h | Bus error: CAN Controller is in 'Bus Off' state.
Example

The following example shows the use of method ReadFD on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized using the method InitializeFD and that the following code is an OnTimer event handler method.

C#:

TPCANStatus result;
StringBuilder strMsg;
TPCANMsgFD msg;
TPCANTimestampFD time;

strMsg = new StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic.ReadFD(PCANBasic.PCAN_USBBUS1, out msg, out time);
    if (result != TPCANStatus.PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox.Show("A message was received");
        ProcessMessage(msg);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus.PCAN_ERROR_QRCVEMPTY) != TPCANStatus.PCAN_ERROR_QRCVEMPTY);

C++CLR:

TPCANStatus result;
StringBuilder^ strMsg;
TPCANMsgFD msg;
TPCANTimestampFD time;

strMsg = gcnew StringBuilder(256);

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic::ReadFD(PCANBasic::PCAN_USBBUS1, msg, time);
    if (result != TPCANStatus::PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox::Show("A message was received");
        ProcessMessage(msg);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic::GetErrorText(result, 0, strMsg);
        MessageBox::Show(strMsg->ToString());
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & TPCANStatus::PCAN_ERROR_QRCVEMPTY) != TPCANStatus::PCAN_ERROR_QRCVEMPTY);

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim msg As TPCANMsgFD
Dim time As TPCANTimestampFD

strMsg = New StringBuilder(256)

Do
    ' Check the receive queue for new messages
    '
    result = PCANBasic.ReadFD(PCANBasic.PCAN_USBBUS1, msg, time)
    If result <> TPCANStatus.PCAN_ERROR_QRCVEMPTY Then
        MessageBox.Show("A message was received")
        ProcessMessage(msg)
    Else
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        MessageBox.Show(strMsg.ToString())
        ' Here can be decided if the loop has to be  terminated (eg. the bus
        ' status is  bus-off)
        '
        HandleReadError(result)
    End If
' Try to read a message from the receive queue of the PCAN-USB, Channel 1,
' until the queue is empty
'
Loop While ((result And TPCANStatus.PCAN_ERROR_QRCVEMPTY) <> TPCANStatus.PCAN_ERROR_QRCVEMPTY)

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    msg: TPCANMsgFD;
    time: TPCANTimestampFD;
begin
    repeat
        // Check the receive queue for new messages
        //
        result := TPCANBasic.ReadFD(TPCANBasic.PCAN_USBBUS1, msg, time);
        If (result <> PCAN_ERROR_QRCVEMPTY) Then
        begin
            // Process the received message
            //
            MessageBox(0,'A message was received','Success', MB_OK);
            ProcessMessage(msg);
        end
        else
        begin
            // An error occurred, get a text describing the error and show it
            //
            TPCANBasic.GetErrorText(result, 0, strMsg);
            MessageBox(0, strMsg, 'Error',MB_OK);
            // Here can be decided if the loop has to be  terminated (eg. the bus
            // status is  bus-off)
            //
            HandleReadError(result);
        end;
    // Try to read a message from the receive queue of the PCAN-USB, Channel 1,
    // until the queue is empty
    //
    until ((TPCANStatus(Integer(result) AND Integer(PCAN_ERROR_QRCVEMPTY))) = PCAN_ERROR_QRCVEMPTY);
See Also

WriteFD

Using Events

Error Frames

Plain function Version: CAN_ReadFD


ReadFD(TPCANHandle)

ReadFD(TPCANHandle)

Reads a CAN message and its time stamp from the receive queue of a FD capable PCAN Channel.

Syntax
Python
def ReadFD(
    self,
    Channel)
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
Returns

The return value is a 3-touple. The order of the returned values is as follows:

[0]: The method's return value as a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the the Message Buffer; it should represents a TPCANMsgFD structure.
PCAN_ERROR_ILLOPERATION: | Indicates that the PCAN Channel passed to the method was not initialized using InitializeFD (plain function: CAN_InitializeFD).
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSWARNING: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-warning status. Note: All touples are valid in this case.
PCAN_ERROR_BUSPASSIVE: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-passive status. Note: All touples are valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: All touples are valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.

[1]: A TPCANMsgFD structure with the CAN message read.

[2]: A TPCANTimestampFD value with the time when a message was read.

Remarks

The use of Read and ReadFD are mutually exclusive. The PCAN Channel passed to this method must be initialized using InitializeFD (plain function: CAN_InitializeFD). Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

The ReadFD method returns received messages or status messages from the receive queue. It is important to call ReadFD repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the ReadFD method. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the ReadFD method in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSWARNING, and BUSPASSIVE, is to uninitialize and initialise the used channel again. This causes a hardware reset.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, FD, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_STATUS is set in the TPCANMsg.MSGTYPE field, the message is a Status message. The ID and DLC 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.

Note that if a status message was read the return value of ReadFD is also the error code.

Examples:

Data0 | Data1 | Data2 | Data3 | Error | Error Code | Description
00h | 00h | 00h | 00h | PCAN_ERROR_OK | 0000h | CAN controller has been successfully activated.
00h | 00h | 00h | 02h | PCAN_ERROR_OVERRUN | 0002h | CAN controller has been read out too late.
00h | 00h | 00h | 08h | PCAN_ERROR_BUSWARNING | 0008h | Bus error: An error counter reached the 'warning' limit.
00h | 04h | 00h | 00h | PCAN_ERROR_BUSPASSIVE | 40000h | Bus error: the CAN controller is error passive.
00h | 00h | 00h | 10h | PCAN_ERROR_BUSOFF | 0010h | Bus error: CAN Controller is in 'Bus Off' state.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of method ReadFD on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized using the method InitializeFD and that the following code is executed periodically.

Python:

readResult = PCAN_ERROR_OK,
while (readResult[0] & PCAN_ERROR_QRCVEMPTY) != PCAN_ERROR_QRCVEMPTY:
    # Check the receive queue for new messages
    #
    readResult = objPCAN.ReadFD(PCAN_USBBUS1)
    if readResult[0] != PCAN_ERROR_QRCVEMPTY:
        # Process the received message
        #
        print ("A message was received")
        ProcessMessage(result[1],result[2]) # Possible processing function, ProcessMessage(msg,timestamp)
    else:
        # An error occurred, get a text describing the error and show it
        #
        result = objPCAN.GetErrorText(readResult[0])
        print (result[1])
        HandleReadError(readResult[0]) # Possible errors handling function, HandleError(function_result)
See Also

WriteFD

Using Events

Error Frames

Plain function Version: CAN_ReadFD


Write

Write

Transmits a CAN message.

Syntax
Pascal OO
class function Write(
    Channel: TPCANHandle;
    var MessageBuffer: TPCANMsg
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Write")]
public static extern TPCANStatus Write(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    ref TPCANMsg MessageBuffer);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_Write")]
static TPCANStatus Write(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    TPCANMsg %MessageBuffer);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_Write")> _
Public Shared Function Write( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    ByVal MessageBuffer As TPCANMsg) As TPCANStatus
End Function
Python
def Write(
    self,
    Channel,
    MessageBuffer)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsg buffer containing the CAN message to be sent.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsg structure.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.
PCAN_ERROR_QXMTFULL: | Indicates that the transmit queue of the Channel is full.
Remarks

If a bus-off error occur, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a method directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like BUSOFF, BUSHEAVY, and BUSLIGTH, is to uninitialize and initialise the used channel again. This causes a hardware reset.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method Write on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;
TPCANMsg msg;

strMsg = new StringBuilder(256);

// A CAN message is created. The Data field (8 bytes)
// of the message must also be created
//
msg = new TPCANMsg();
msg.DATA = new Byte[8];

// A CAN message is configured
//
msg.ID = 0x100;
msg.MSGTYPE = TPCANMessageType.PCAN_MESSAGE_STANDARD;
msg.LEN = 3;
msg.DATA[0] = 1;
msg.DATA[1] = 2;
msg.DATA[2] = 3;

// The message is sent using the PCAN-USB Channel 1
//
result = PCANBasic.Write(PCANBasic.PCAN_USBBUS1, ref msg);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("Message sent successfully");

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
TPCANMsg^ msg;

strMsg = gcnew StringBuilder(256);

// A CAN message is created. The Data field (8 bytes)
// of the message must also be created
//
msg = gcnew TPCANMsg();
msg->DATA = gcnew array<Byte>(8);

// A CAN message is configured
//
msg->ID = 0x100;
msg->MSGTYPE = TPCANMessageType::PCAN_MESSAGE_STANDARD;
msg->LEN = 3;
msg->DATA[0] = 1;
msg->DATA[1] = 2;
msg->DATA[2] = 3;

// The message is sent using the PCAN-USB Channel 1
//
result = PCANBasic::Write(PCANBasic::PCAN_USBBUS1, *msg);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("Message sent successfully");

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim msg As TPCANMsg

strMsg = New StringBuilder(256)

' A CAN message is created. The Data field (8 bytes)
' of the message must also be created
'
msg = New TPCANMsg
msg.DATA = CType(Array.CreateInstance(GetType(Byte), 8), Byte())

' A CAN message is configured
'
msg.ID = &H100
msg.MSGTYPE = TPCANMessageType.PCAN_MESSAGE_STANDARD
msg.LEN = 3
msg.DATA(0) = 1
msg.DATA(1) = 2
msg.DATA(2) = 3

' The message is sent using the PCAN-USB Channel 1
'
result = PCANBasic.Write(PCANBasic.PCAN_USBBUS1, msg)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("Message sent successfully")
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    msg: TPCANMsg;
begin
    // A CAN message is configured
    //
    msg.ID := $100;
    msg.MSGTYPE := PCAN_MESSAGE_STANDARD;
    msg.LEN := 3;
    msg.DATA[0] := 1;
    msg.DATA[1] := 2;
    msg.DATA[2] := 3;

    // The message is sent using the PCAN-USB Channel 1
    //
    result := TPCANBasic.Write(TPCANBasic.PCAN_USBBUS1,msg);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'Message sent successfully','Success', MB_OK);

Python:

# A CAN message is configured
#
msg = TPCANMsg()
msg.ID = 0x100
msg.MSGTYPE = PCAN_MESSAGE_STANDARD
msg.LEN = 3
msg.DATA[0] = 1
msg.DATA[1] = 2
msg.DATA[2] = 3

#  The message is sent using the PCAN-USB Channel 1
#
result = objPCAN.Write(PCAN_USBBUS1,msg)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("Message sent successfully")
See Also

Read

SetValue

Plain function Version: CAN_Write


WriteFD

WriteFD

Transmits a CAN message using a FD capable PCAN Channel.

Syntax
Pascal OO
class function WriteFD(
    Channel: TPCANHandle;
    var MessageBuffer: TPCANMsgFD
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_WriteFD")]
public static extern TPCANStatus WriteFD(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    ref TPCANMsgFD MessageBuffer);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_WriteFD")]
static TPCANStatus WriteFD(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    TPCANMsgFD %MessageBuffer);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_WriteFD")> _
Public Shared Function WriteFD( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    ByRef MessageBuffer As TPCANMsgFD) As TPCANStatus
End Function
Python
def WriteFD(
    self,
    Channel,
    MessageBuffer)
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsgFD buffer containing the CAN message to be sent.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsgFD structure.
PCAN_ERROR_ILLOPERATION: | Indicates that the PCAN Channel passed to the method was not initialized using InitializeFD (plain function: CAN_InitializeFD).
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.
PCAN_ERROR_QXMTFULL: | Indicates that the transmit queue of the Channel is full.
Remarks

The use of Write and WriteFD are mutually exclusive. The PCAN Channel passed to this method must be initialized using InitializeFD (plain function: CAN_InitializeFD). Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

If a bus-off error occur, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a method directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like BUSOFF, BUSWARNING, and BUSPASSIVE, is to uninitialize and initialise the used channel again. This causes a hardware reset.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method WriteFD on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized using the method InitializeFD.

C#:

TPCANStatus result;
StringBuilder strMsg;
TPCANMsgFD msg;

strMsg = new StringBuilder(256);

// A CAN message is created. The Data field (64 bytes)
// of the message must also be created
//
msg = new TPCANMsgFD();
msg.DATA = new Byte[64];

// A CAN message is configured
//
msg.ID = 0x100;
msg.MSGTYPE = TPCANMessageType.PCAN_MESSAGE_STANDARD | TPCANMessageType.PCAN_MESSAGE_FD;

// DLC 9 means 12 data bytes
//
msg.DLC = 9;
for(byte i=0; i < 12; i++)
    msg.DATA[i] = i;

// The message is sent using the PCAN-USB Channel 1
//
result = PCANBasic.WriteFD(PCANBasic.PCAN_USBBUS1, ref msg);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("Message sent successfully");

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
TPCANMsgFD^ msg;

strMsg = gcnew StringBuilder(256);

// A CAN message is created. The Data field (64 bytes)
// of the message must also be created
//
msg = gcnew TPCANMsgFD();
msg->DATA = gcnew array<Byte>(64);

// A CAN message is configured
//
msg->ID = 0x100;
msg->MSGTYPE = TPCANMessageType::PCAN_MESSAGE_STANDARD | TPCANMessageType::PCAN_MESSAGE_FD;

// DLC 9 means 12 data bytes
//
msg->DLC = 9;
for(Byte i=0; i < 12; i++)
    msg->DATA[i] = i;

// The message is sent using the PCAN-USB Channel 1
//
result = PCANBasic::WriteFD(PCANBasic::PCAN_USBBUS1, *msg);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("Message sent successfully");

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim msg As TPCANMsgFD

strMsg = New StringBuilder(256)

' A CAN message is created. The Data field (64 bytes)
' of the message must also be created
'
msg = New TPCANMsgFD
msg.DATA = CType(Array.CreateInstance(GetType(Byte), 64), Byte())

' A CAN message is configured
'
msg.ID = &H100
msg.MSGTYPE = TPCANMessageType.PCAN_MESSAGE_STANDARD Or TPCANMessageType.PCAN_MESSAGE_FD

' DLC 9 means 12 data bytes
'
msg.DLC = 9
For i As Byte = 0 To 11
    msg.DATA(i) = i
Next

' The message is sent using the PCAN-USB Channel 1
'
result = PCANBasic.WriteFD(PCANBasic.PCAN_USBBUS1, msg)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("Message sent successfully")
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    msg: TPCANMsgFD;
    I: Integer;
begin
    // A CAN message is configured
    //
    msg.ID := $100;
    msg.MSGTYPE := TPCANMessageType(Byte(PCAN_MESSAGE_STANDARD) OR Byte(PCAN_MESSAGE_FD));

    // DLC 9 means 12 data bytes
    //
    msg.DLC := 9;
    for I:=0 To 11 do
        msg.DATA[I] := I;

    // The message is sent using the PCAN-USB Channel 1
    //
    result := TPCANBasic.WriteFD(TPCANBasic.PCAN_USBBUS1,msg);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'Message sent successfully','Success', MB_OK);

Python:

# A CAN message is configured
#
msg = TPCANMsgFD()
msg.ID = 0x100
msg.MSGTYPE = PCAN_MESSAGE_STANDARD.value | PCAN_MESSAGE_FD.value

# DLC 9 means 12 data bytes
#
msg.DLC = 9
for i in range(12):
    msg.DATA[i] = i

#  The message is sent using the PCAN-USB Channel 1
#
result = objPCAN.WriteFD(PCAN_USBBUS1,msg)
if result[0] != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result[0])
    print (result[1])
else:
    print ("Message sent successfully")
See Also

ReadFD

SetValue

Plain function Version: CAN_WriteFD


GetValue

GetValue

Retrieves information from a PCAN Channel.

Overloads
Function | Description
GetValue(TPCANHandle, TPCANParameter, String, UInt32) | Retrieves information from a PCAN Channel in text form.
GetValue(TPCANHandle, TPCANParameter, UInt32, UInt32) | Retrieves information from a PCAN Channel in numeric form (32-Bit).
GetValue(TPCANHandle, TPCANParameter, UInt64, UInt32) | Retrieves information from a PCAN Channel in numeric form (64-Bit).
GetValue(TPCANHandle, TPCANParameter, String, TPCANChannelInformation[]) | Retrieves an array of TPCANChannelInformation with information about the hardware currently attached to the system.
GetValue(TPCANHandle,TPCANParameter) | Retrieves information from a PCAN Channel.


GetValue(TPCANHandle, TPCANParameter, String, UInt32)

GetValue(TPCANHandle, TPCANParameter, String, UInt32)

Retrieves information from a PCAN Channel in text form.

Syntax
Pascal OO
class function GetValue(
    Channel: TPCANHandle;
    Parameter: TPCANParameter;
    StringBuffer: PChar;
    BufferLength: LongWord
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetValue")]
public static extern TPCANStatus GetValue(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType.U1)]
    TPCANParameter Parameter,
    StringBuilder StringBuffer,
    UInt32 BufferLength);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetValue")]
static TPCANStatus GetValue(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType::U1)]
    TPCANParameter Parameter,
    StringBuilder^ StringBuffer,
    UInt32 BufferLength);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_GetValue")> _
Public Shared Function GetValue( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Parameter As TPCANParameter, _
    ByVal StringBuffer As StringBuilder, _
    ByVal BufferLength As UInt32) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the information to be retrieved (see TPCANParameter).
StringBuffer | The buffer to return the required string value.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'StringBuffer'; it should point to a valid null-terminated string buffer.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be read.
Remarks

Use the method GetValue to get information about PCAN environment as parameters like the Message Filter and values like the availability of a PCAN-Channel. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be read can be found in Parameter Value Definitions.

Example

The following example shows the use of the method GetValue on the channel PCAN_USBBUS1 to get the PCAN-Channel version text. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized InitializeFD.

C#:

TPCANStatus result;
StringBuilder strMsg;

strMsg = new StringBuilder(256);

// The version of the PCAN-USB Channel 1 is asked.
//
result = PCANBasic.GetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_CHANNEL_VERSION,strMsg, 256 );
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    // Show the version message
    //
    MessageBox.Show(strMsg.ToString());

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;

strMsg = gcnew StringBuilder(256);

// The version of the PCAN-USB Channel 1 is asked.
//
result = PCANBasic::GetValue(PCANBasic::PCAN_USBBUS1, TPCANParameter::PCAN_CHANNEL_VERSION, strMsg, 256);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    // Show the version message
    //
    MessageBox::Show(strMsg->ToString());

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder

strMsg = New StringBuilder(256)

' The version of the PCAN-USB Channel 1 is asked.
'
result = PCANBasic.GetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_CHANNEL_VERSION, strMsg, 256)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString())
Else
    ' Show the version message
    '
    MessageBox.Show(strMsg.ToString())
End If

Pascal OO:

var
    result: TPCANStatus;
    strMsg: array [0..256] of Char;
begin

    // The version of the PCAN-USB Channel 1 is asked.
    //
    result := TPCANBasic.GetValue(TPCANBasic.PCAN_USBBUS1, PCAN_CHANNEL_VERSION, strMsg, 256);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        // Show the version message
        //
        MessageBox(0, strMsg, 'Success',MB_OK);
See Also

SetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_GetValue


GetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)

GetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)

Retrieves information from a PCAN Channel in numeric form.

Syntax
Pascal OO
class function GetValue(
    Channel: TPCANHandle;
    Parameter: TPCANParameter;
    NumericBuffer: PLongWord;
    BufferLength: LongWord
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetValue")]
public static extern TPCANStatus GetValue(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType.U1)]
    TPCANParameter Parameter,
    out UInt32 NumericBuffer,
    UInt32 BufferLength);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetValue")]
static TPCANStatus GetValue(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType::U1)]
    TPCANParameter Parameter,
    UInt32 %NumericBuffer,
    UInt32 BufferLength);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_GetValue")> _
Public Shared Function GetValue( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Parameter As TPCANParameter, _
    ByRef NumericBuffer As UInt32, _
    ByVal BufferLength As UInt32) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the information to be retrieved (see TPCANParameter).
NumericBuffer | The buffer to return the required numeric value.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'NumericBuffer'; it should point to an integer buffer.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be read.
Remarks

Use the method GetValue to get information about PCAN environment as parameters like the Message Filter and values like the availability of a PCAN-Channel. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be read can be found in Parameter Value Definitions.

Example

The following example shows the use of the method GetValue on the channel PCAN_USBBUS1 to check if the Message Filter is fully opened. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;
UInt32 iBuffer;

strMsg = new StringBuilder(256);

// The status of the message filter of the PCAN-USB Channel 1 is asked
//
result = PCANBasic.GetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_MESSAGE_FILTER, out iBuffer, sizeof(UInt32));
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    // A text is shown giving information about the current status of the filter
    //
    switch(iBuffer)
    {
        case PCANBasic.PCAN_FILTER_OPEN:
            MessageBox.Show("The message filter for the PCAN-USB, channel 1, is completely opened.");
            break;
        case PCANBasic.PCAN_FILTER_CLOSE:
            MessageBox.Show("The message filter for the PCAN-USB, channel 1, is closed.");
            break;
        case PCANBasic.PCAN_FILTER_CUSTOM:
            MessageBox.Show("The message filter for the PCAN-USB, channel 1, is custom configured.");
            break;
    }

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
UInt32 iBuffer;

strMsg = gcnew StringBuilder(256);

// The status of the message filter of the PCAN-USB Channel 1 is asked
//
result = PCANBasic::GetValue(PCANBasic::PCAN_USBBUS1, TPCANParameter::PCAN_MESSAGE_FILTER, iBuffer, sizeof(iBuffer));
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    // A text is shown giving information about the current status of the filter
    //
    switch(iBuffer)
    {
        case PCANBasic::PCAN_FILTER_OPEN:
            MessageBox::Show("The message filter for the PCAN-USB, channel 1, is completely opened.");
            break;
        case PCANBasic::PCAN_FILTER_CLOSE:
            MessageBox::Show("The message filter for the PCAN-USB, channel 1, is closed.");
            break;
        case PCANBasic::PCAN_FILTER_CUSTOM:
            MessageBox::Show("The message filter for the PCAN-USB, channel 1, is custom configured.");
            break;
    }

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim iBuffer As UInt32

strMsg = New StringBuilder(256)

' The status of the message filter of the PCAN-USB Channel 1 is asked
'
result = PCANBasic.GetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_MESSAGE_FILTER, iBuffer, CType(System.Runtime.InteropServices.Marshal.SizeOf(iBuffer), UInteger))
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString())
Else
    ' A text is shown giving information about the current status of the filter
    '
    Select Case iBuffer
        Case PCANBasic.PCAN_FILTER_OPEN
            MessageBox.Show("The message filter for the PCAN-USB, channel 1, is completely opened.")
        Case PCANBasic.PCAN_FILTER_CLOSE
            MessageBox.Show("The message filter for the PCAN-USB, channel 1, is closed.")
        Case PCANBasic.PCAN_FILTER_CUSTOM
            MessageBox.Show("The message filter for the PCAN-USB, channel 1, is custom configured.")
    End Select
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    iBuffer: LongWord;
begin
    // The status of the message filter of the PCAN-USB Channel 1 is asked
    //
    result := TPCANBasic.GetValue(TPCANBasic.PCAN_USBBUS1, PCAN_MESSAGE_FILTER, PLongWord(@iBuffer), sizeof(iBuffer));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
    begin
        // A text is shown giving information about the current status of the filter
        //
        if iBuffer = TPCANBasic.PCAN_FILTER_OPEN then
                MessageBox(0, 'The message filter for the PCAN-USB, channel 1, is completely opened.', 'Success',MB_OK);
        if iBuffer = TPCANBasic.PCAN_FILTER_CLOSE then
                MessageBox(0, 'The message filter for the PCAN-USB, channel 1, is closed.', 'Success',MB_OK);
        if iBuffer = TPCANBasic.PCAN_FILTER_CUSTOM then
                MessageBox(0, 'The message filter for the PCAN-USB, channel 1, is custom configured.', 'Success',MB_OK);
    end;
See Also

SetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_GetValue


GetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)

GetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)

Retrieves information from a PCAN Channel in numeric form.

Pascal OO
class function GetValue(
    Channel: TPCANHandle;
    Parameter: TPCANParameter;
    NumericBuffer: PUInt64;
    BufferLength: LongWord
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetValue")]
public static extern TPCANStatus GetValue(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType.U1)]
    TPCANParameter Parameter,
    out UInt64 NumericBuffer,
    UInt32 BufferLength);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetValue")]
static TPCANStatus GetValue(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType::U1)]
    TPCANParameter Parameter,
    UInt64 %NumericBuffer,
    UInt32 BufferLength);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_GetValue")> _
Public Shared Function GetValue( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Parameter As TPCANParameter, _
    ByRef NumericBuffer As UInt64, _
    ByVal BufferLength As UInt32) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the information to be retrieved (see TPCANParameter).
NumericBuffer | The buffer to return the required 64-bit numeric value.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'NumericBuffer'; it should point to a 64-bit integer buffer.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be read.
Remarks

Use the method GetValue to get information about PCAN environment as parameters like an Acceptance Filter. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be read can be found in Parameter Value Definitions.

Example

The following example shows the use of the method GetValue on the channel PCAN_USBBUS1 to retrieve the configured message filter as 11-bit acceptance code and mask. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;
UInt64 i64Buffer;
UInt32 iCode, iMask;

strMsg = new StringBuilder(256);

// The 11-bit acceptance filter of the PCAN-USB Channel 1 is asked
//
result = PCANBasic.GetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_ACCEPTANCE_FILTER_11BIT, out i64Buffer, sizeof(UInt64));
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
{
    // Code and mask are extracted from the 64-bit numeric value
    //
    iCode = Convert.ToUInt32((i64Buffer >> 32);
    iMask = Convert.ToUInt32(i64Buffer & UInt32.MaxValue);

    // A text is shown giving information about the 11-bit mask and code of the acceptance filter
    //
    MessageBox.Show(string.Format("Configured 11-bit acceptance filter: Code: {0:X8} | Mask: {1:X8}", iCode, iMask));
}

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
UInt64 i64Buffer;
UInt32 iCode, iMask;

strMsg = gcnew StringBuilder(256);

// The 11-bit acceptance filter of the PCAN-USB Channel 1 is asked
//
result = PCANBasic::GetValue(PCANBasic::PCAN_USBBUS1, TPCANParameter::PCAN_ACCEPTANCE_FILTER_11BIT, i64Buffer, sizeof(i64Buffer));
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
{
    // Code and mask are extracted from the 64-bit numeric value
    //
    iCode = Convert::ToUInt32((i64Buffer >> 32);
    iMask = Convert::ToUInt32(i64Buffer & UInt32::MaxValue);

    // A text is shown giving information about the 11-bit mask and code of the acceptance filter
    //
    MessageBox::Show(String::Format("Configured 11-bit acceptance filter: Code: {0:X8} | Mask: {1:X8}", iCode, iMask));
}

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim i64Buffer As UInt64
Dim iCode As UInt32
Dim iMask As UInt32

strMsg = New StringBuilder(256)

' The 11-bit acceptance filter of the PCAN-USB Channel 1 is asked
'
result = PCANBasic.GetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_ACCEPTANCE_FILTER_11BIT, i64Buffer, CType(System.Runtime.InteropServices.Marshal.SizeOf(i64Buffer), UInteger))
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString())
Else
    ' Code and mask are extracted from the 64-bit numeric value
    '
    iCode = Convert.ToUInt32(i64Buffer >> 32)
    iMask = Convert.ToUInt32(i64Buffer And UInt32.MaxValue)

    ' A text is shown giving information about the 11-bit mask and code of the acceptance filter
    '
    MessageBox.Show(String.Format("Configured 11-bit acceptance filter: Code: {0:X8} | Mask: {1:X8}", iCode, iMask))
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    i64Buffer: UInt64;
    iCode, iMask: LongWord;
begin
    // The 11-bit acceptance filter of the PCAN-USB Channel 1 is asked
    //
    result := TPCANBasic.GetValue(TPCANBasic.PCAN_USBBUS1, PCAN_ACCEPTANCE_FILTER_11BIT, PUInt64(@i64Buffer), sizeof(i64Buffer));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
    begin
        // Code and mask are extracted from the 64-bit numeric value
        //
        iCode := i64Buffer shr 32;
        iMask := (i64Buffer And $FFFFFFFF);

        // A text is shown giving information about the 11-bit mask and code of the acceptance filter
        //
        MessageBox(0, PChar(Format('Configured 11-bit acceptance filter: Code: %.8X | Mask: %.8X', [iCode, iMask])), 'Success',MB_OK);
    end;
end;
See Also

SetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_GetValue


GetValue(TPCANHandle, TPCANParameter, String, TPCANChannelInformation[])

GetValue(TPCANHandle, TPCANParameter, String, TPCANChannelInformation[])

Retrieves an array of TPCANChannelInformation with information about the hardware currently attached to the system.

Syntax
Pascal OO
class function GetValue(
    Channel: TPCANHandle;
    Parameter: TPCANParameter;
    ChannelsBuffer: PTPCANChannelInformation;
    BufferLength: LongWord
    ): TPCANStatus; overload;
C#
public static TPCANStatus GetValue(
    TPCANHandle Channel,
    TPCANParameter Parameter,
    TPCANChannelInformation ChannelsBuffer);
C++ / CLR
static TPCANStatus GetValue(
    TPCANHandle Channel,
    TPCANParameter Parameter,
    array<TPCANChannelInformation> ^ChannelsBuffer);
Visual Basic
Public Shared Function GetValue( _
    ByVal Channel As TPCANHandle, _
    ByVal Parameter As TPCANParameter, _
    ByRef ChannelsBuffer() As TPCANChannelInformation) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the information to be retrieved (see TPCANParameter).
ChannelsBuffer | The buffer to return the required value.
BufferLength | The length in bytes of the given buffer. Note: Only valid for Pascal OO. When using a .NET language, the size is automatically calculated using the length of the ChannelsBuffer array.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'ChannelsBuffer'; it should point to an array of TPCANChannelInformation.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Only PCAN_NONEBUS is allowed.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be read.
Example

The following example shows the use of the method GetValue on the channel PCAN_NONEBUS to retrieve information about the current attached channels to the PC. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C#:

StringBuilder strMsg = new StringBuilder(256);

// The amount of channels available is requested
//
TPCANStatus stsResult = PCANBasic.GetValue(PCANBasic.PCAN_NONEBUS, TPCANParameter.PCAN_ATTACHED_CHANNELS_COUNT, out uint iChannelsCount, sizeof(uint));

if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(stsResult, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
{
    // A buffer to store the information is created
    //
    TPCANChannelInformation[] ciChannelInformation = new TPCANChannelInformation[iChannelsCount];

    // The information about attached channels is retrieved
    //
    stsResult = PCANBasic.GetValue(PCANBasic.PCAN_NONEBUS, TPCANParameter.PCAN_ATTACHED_CHANNELS, ciChannelInformation);

    // The information about the attached channels is shown
    //
    if (stsResult == TPCANStatus.PCAN_ERROR_OK)
    {
        Console.WriteLine("-----------------------------------------------------------------------------------------");
        Console.WriteLine("Get PCAN_ATTACHED_CHANNELS:");

        foreach (TPCANChannelInformation currentChannelInformation in ciChannelInformation)
        {
            Console.WriteLine("---------------------------");
            Console.WriteLine("channel_handle:      " + currentChannelInformation.channel_handle);
            Console.WriteLine("device_type:         " + currentChannelInformation.device_type);
            Console.WriteLine("controller_number:   " + currentChannelInformation.controller_number);
            Console.WriteLine("device_features:     " + currentChannelInformation.device_features);
            Console.WriteLine("device_name:         " + currentChannelInformation.device_name);
            Console.WriteLine("device_id:           " + currentChannelInformation.device_id);
            Console.WriteLine("channel_condition:   " + currentChannelInformation.channel_condition);
        }
        Console.WriteLine();
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(stsResult, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
    }
}

C++/CLR:

StringBuilder^ strMsg = gcnew StringBuilder(256);

// The amount of channels available is requested
//
UInt32 iChannelsCount;
TPCANStatus stsResult = PCANBasic::GetValue(PCANBasic::PCAN_NONEBUS, TPCANParameter::PCAN_ATTACHED_CHANNELS_COUNT, iChannelsCount, sizeof(UInt32));

if (stsResult != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(stsResult, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
{
    // A buffer to store the information is created
    //
    array<TPCANChannelInformation>^ ciChannelInformation = gcnew array<TPCANChannelInformation>(iChannelsCount);

    // The information about attached channels is retrieved
    //
    stsResult = PCANBasic::GetValue(PCANBasic::PCAN_NONEBUS, TPCANParameter::PCAN_ATTACHED_CHANNELS, ciChannelInformation);

    // The information about the attached channels is shown
    //
    if (stsResult == TPCANStatus::PCAN_ERROR_OK)
    {
        Console::WriteLine("-----------------------------------------------------------------------------------------");
        Console::WriteLine("Get PCAN_ATTACHED_CHANNELS:");

        for each (TPCANChannelInformation^ currentChannelInformation in ciChannelInformation)
        {
            Console::WriteLine("---------------------------");
            Console::WriteLine("channel_handle:      " + currentChannelInformation->channel_handle);
            Console::WriteLine("device_type:         " + currentChannelInformation->device_type);
            Console::WriteLine("controller_number:   " + currentChannelInformation->controller_number);
            Console::WriteLine("device_features:     " + currentChannelInformation->device_features);
            Console::WriteLine("device_name:         " + currentChannelInformation->device_name);
            Console::WriteLine("device_id:           " + currentChannelInformation->device_id);
            Console::WriteLine("channel_condition:   " + currentChannelInformation->channel_condition);
        }
        Console::WriteLine();
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(stsResult, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
    }
}

Visual Basic:

Dim strMsg As StringBuilder = New StringBuilder(256)
Dim stsResult As TPCANStatus

' The amount of channels available is requested
'
Dim iChannelsCount As UInt32
stsResult = PCANBasic.GetValue(PCANBasic.PCAN_NONEBUS, TPCANParameter.PCAN_ATTACHED_CHANNELS_COUNT, iChannelsCount, CType(System.Runtime.InteropServices.Marshal.SizeOf(iChannelsCount), UInteger))

If stsResult <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(stsResult, 0, strMsg)
    MessageBox.Show(strMsg.ToString())
Else
    ' A buffer to store the information is created
    '
    Dim ciChannelInformation(iChannelsCount - 1) As TPCANChannelInformation

    ' The information about attached channels is retrieved
    '
    stsResult = PCANBasic.GetValue(PCANBasic.PCAN_NONEBUS, TPCANParameter.PCAN_ATTACHED_CHANNELS, ciChannelInformation)

    ' The information about the attached channels is shown
    '
    If (stsResult = TPCANStatus.PCAN_ERROR_OK) Then
        Console.WriteLine("-----------------------------------------------------------------------------------------")
        Console.WriteLine("Get PCAN_ATTACHED_CHANNELS:")

        For Each currentChannelInformation As TPCANChannelInformation In ciChannelInformation
            Console.WriteLine("---------------------------")
            Console.WriteLine("channel_handle:      " + currentChannelInformation.channel_handle)
            Console.WriteLine("device_type:         " + currentChannelInformation.device_type.ToString())
            Console.WriteLine("controller_number:   " + currentChannelInformation.controller_number.ToString())
            Console.WriteLine("device_features:     " + currentChannelInformation.device_features)
            Console.WriteLine("device_name:         " + currentChannelInformation.device_name)
            Console.WriteLine("device_id:           " + currentChannelInformation.device_id.ToString())
            Console.WriteLine("channel_condition:   " + currentChannelInformation.channel_condition)
        Next
        Console.WriteLine()
    Else
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(stsResult, 0, strMsg)
        MessageBox.Show(strMsg.ToString())
    End If
End If

Pascal OO:

var
  stsResult : TPCANStatus;
  iChannelsCount: Integer;
  ciChannelInformation: array of TPCANChannelInformation;
  I: Integer;
begin
  // The amount of channels available is requested
  //
  ciChannelInformation := nil;
  stsResult := TPCANBasic.GetValue(TPCANBasic.PCAN_NONEBUS, PCAN_ATTACHED_CHANNELS_COUNT, PLongWord(@iChannelsCount), SizeOf(iChannelsCount));

  If (stsResult <> PCAN_ERROR_OK) Then
  begin
    // An error occurred, get a text describing the error and show it
    //
    TPCANBasic.GetErrorText(stsResult, 0, strMsg);
    MessageBox(0, strMsg, 'Error',MB_OK);
  end
  else
  begin
    // A buffer to store the information is configured
    //
    SetLength(ciChannelInformation, iChannelsCount);

    // The information about attached channels is retrieved
    //
    stsResult := TPCANBasic.GetValue(TPCANBasic.PCAN_NONEBUS, PCAN_ATTACHED_CHANNELS, PTPCANChannelInformation(ciChannelInformation), SizeOf(TPCANChannelInformation) * iChannelsCount);

    // The information about the attached channels is shown
    //
    if (stsResult = TPCANStatus.PCAN_ERROR_OK) then
    begin
      writeln('-----------------------------------------------------------------------------------------');
      writeln('Get PCAN_ATTACHED_CHANNELS:');

      for I := 0 To iChannelsCount - 1 do
      begin
        writeln('---------------------------');
        writeln('channel_handle:      ' + IntToStr(ciChannelInformation[I].channel_handle));
        writeln('device_type:         ' + IntToStr(ciChannelInformation[I].device_type));
        writeln('controller_number:   ' + IntToStr(int64(ciChannelInformation[I].controller_number)));
        writeln('device_features:     ' + IntToStr(ciChannelInformation[I].device_features));
        writeln('device_name:         ' + ciChannelInformation[I].device_name);
        writeln('device_id:           ' + IntToStr(int64(ciChannelInformation[I].device_id)));
        writeln('channel_condition:   ' + IntToStr(ciChannelInformation[I].channel_condition));
      end;
    end;
  end
  else
  begin
    // An error occurred, get a text describing the error and show it
    //
    TPCANBasic.GetErrorText(stsResult, 0, strMsg);
    MessageBox(0, strMsg, 'Error',MB_OK);
  end;
end;
See Also

SetValue

TPCANParameter

TPCANChannelInformation

Plain function Version: CAN_GetValue


GetValue(TPCANHandle,TPCANParameter)

GetValue(TPCANHandle,TPCANParameter)

Retrieves information from a PCAN Channel.

Syntax
Python
def GetValue(
    self,
    Channel,
    Parameter)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the information to be retrieved (see TPCANParameter).
Returns

The return value is a 2-touple. The order of the returned values is as follows:

[0]: The method's return value as a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'NumericBuffer'; it should point to an integer buffer.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be read.

[1]: The requested parameter value (the type of the value depends on the TPCANParameter requested).

Remarks

Use the method GetValue to get information about PCAN environment as parameters like the Message Filter and values like the availability of a PCAN-Channel. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be read can be found in Parameter Value Definitions.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method GetValue on the channel PCAN_USBBUS1 to check if the Message Filter is fully opened. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

Python:

# The status of the message filter of the PCAN-USB Channel 1 is asked
#
result = objPCAN.GetValue(PCAN_USBBUS1,PCAN_MESSAGE_FILTER)
if result[0] != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result[0])
    print (result[1])
else:
    # A text is shown giving information about the current status of the filter
    #
    if result[1] == PCAN_FILTER_OPEN:
        print ("The message filter for the PCAN-USB, channel 1, is completely opened.")
    elif result[1] == PCAN_FILTER_CLOSE:
        print ("The message filter for the PCAN-USB, channel 1, is closed.")
    elif result[1] == PCAN_FILTER_CUSTOM:
        print ("The message filter for the PCAN-USB, channel 1, is custom configured.")
See Also

SetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_GetValue


SetValue

SetValue

Sets a configuration or information value within a PCAN Channel.

Overloads
Function | Description
SetValue(TPCANHandle, TPCANParameter, String, UInt32) | Sets a configuration or information string value within a PCAN Channel.
SetValue(TPCANHandle, TPCANParameter, UInt32, UInt32) | Sets a configuration or information numeric value within a PCAN Channel (32-Bit).
SetValue(TPCANHandle, TPCANParameter, UInt64, UInt32) | Sets a configuration or information numeric value within a PCAN Channel (64-Bit).
SetValue(TPCANHandle, TPCANParameter, Object) | Sets a configuration or information value within a PCAN Channel.


SetValue(TPCANHandle, TPCANParameter, String, UInt32)

SetValue(TPCANHandle, TPCANParameter, String, UInt32)

Sets a configuration or information string value within a PCAN Channel.

Syntax
Pascal OO
class function SetValue(
    Channel: TPCANHandle;
    Parameter: TPCANParameter;
    StringBuffer: PChar;
    BufferLength: LongWord
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_SetValue")]
public static extern TPCANStatus SetValue(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType.U1)]
    TPCANParameter Parameter,
    [MarshalAs(UnmanagedType.LPStr,SizeParamIndex=3)]
    string StringBuffer,
    UInt32 BufferLength);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_SetValue")]
static TPCANStatus SetValue(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType::U1)]
    TPCANParameter Parameter,
    [MarshalAs(UnmanagedType::LPStr,SizeParamIndex=3)]
    String^ StringBuffer,
    UInt32 BufferLength);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_SetValue")> _
Public Shared Function SetValue( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Parameter As TPCANParameter, _
    <MarshalAs(UnmanagedType.LPStr, SizeParamIndex:=3)> _
    ByVal StringBuffer As String, _
    ByVal BufferLength As UInt32) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the value to be set (see TPCANParameter).
StringBuffer | The buffer containing the string value to be set.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'StringBuffer'; it should point to a valid null-terminated string buffer.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be set.
PCAN_ERROR_ILLOPERATION: | An underlying process that is generated by a call to this method with the current parameters, is temporarily not allowed. The configuration in relation to the used TPCANParameter must be checked.
Remarks

Use the method SetValue to set configuration information or environment values of a PCAN Channel as parameters like the Message Filter and values like a custom entry in the log file of PCAN-Basic. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be set can be found in Parameter Value Definitions.

Example

The following example shows the use of the method SetValue on the channel PCAN_NONEBUS to set (and activate) the path for the log file of a PCAN-Basic's debug session. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is not needed to have an initialized PCAN channel for using the Log functionality.

C#:

TPCANStatus result;
StringBuilder strMsg;
string strBuffer;

strMsg = new StringBuilder(256);

// The path for the Log file is set.
// Note that this parameter is set using the
// default Channel (PCAN_NONEBUS)
//
strBuffer = "C:\\Users\\Admin\\Desktop";
result = PCANBasic.SetValue(PCANBasic.PCAN_NONEBUS, TPCANParameter.PCAN_LOG_LOCATION, strBuffer, (UInt32)strBuffer.Length);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("Log path was successfully set");

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
String^ strBuffer;

strMsg = gcnew StringBuilder(256);

// The path for the Log file is set.
// Note that this parameter is set using the
// default Channel (PCAN_NONEBUS)
//
strBuffer = "C:\\Users\\Admin\\Desktop";
result = PCANBasic::SetValue(PCANBasic::PCAN_NONEBUS, TPCANParameter::PCAN_LOG_LOCATION, strBuffer, strBuffer->Length);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("Log path was successfully set");

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim strBuffer As String

strMsg = New StringBuilder(256)

' The path for the Log file is set.
' Note that this parameter is set using the
' default Channel (PCAN_NONEBUS)
'
strBuffer = "C:\Users\Admin\Desktop"
result = PCANBasic.SetValue(PCANBasic.PCAN_NONEBUS, TPCANParameter.PCAN_LOG_LOCATION, strBuffer, CType(System.Runtime.InteropServices.Marshal.SizeOf(i64Buffer), UInteger))
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString())
Else
    MessageBox.Show("Log path was successfully set")
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    strBuffer: string;
begin
    // The path for the Log file is set.
    // Note that this parameter is set using the
    // default Channel (PCAN_NONEBUS)
    //
    strBuffer := 'C:\\Users\Keneth\Desktop';
    result := TPCANBasic.SetValue(TPCANBasic.PCAN_NONEBUS, PCAN_LOG_LOCATION, PChar(strBuffer), Length(strBuffer));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0, 'Log path was successfully set', 'Success',MB_OK);
See Also

GetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_SetValue


SetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)

SetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)

Sets a configuration or information numeric value within a PCAN Channel.

Syntax
Pascal OO
class function SetValue(
    Channel: TPCANHandle;
    Parameter: TPCANParameter;
    NumericBuffer: PLongWord;
    BufferLength: LongWord
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_SetValue")]
public static extern TPCANStatus SetValue(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType.U1)]
    TPCANParameter Parameter,
    ref UInt32 NumericBuffer,
    UInt32 BufferLength);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_SetValue")]
static TPCANStatus SetValue(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType::U1)]
    TPCANParameter Parameter,
    UInt32 %NumericBuffer,
    UInt32 BufferLength);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_SetValue")> _
Public Shared Function SetValue( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Parameter As TPCANParameter, _
    ByRef NumericBuffer As UInt32, _
    ByVal BufferLength As UInt32) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the value to be set (see TPCANParameter).
NumericBuffer | The buffer containing the numeric value to be set.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'NumericBuffer'; it should point to an integer buffer.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be set.
PCAN_ERROR_ILLOPERATION: | An underlying process that is generated by a call to this method with the current parameters, is temporarily not allowed. The configuration in relation to the used TPCANParameter must be checked.
Remarks

Use the method SetValue to set configuration information or environment values of a PCAN Channel as parameters like the Message Filter and values like a custom entry in the log file of PCAN-Basic. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be set can be found in Parameter Value Definitions.

Example

The following example shows the use of the method SetValue on the channel PCAN_USBBUS1 to close the message filter. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;
UInt32 iBuffer;

strMsg = new StringBuilder(256);

// The message filter is closed
//
iBuffer = PCANBasic.PCAN_FILTER_CLOSE;
result = PCANBasic.SetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_MESSAGE_FILTER, ref iBuffer, sizeof(UInt32));
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("The filter was successfully closed");

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
UInt32 iBuffer;

strMsg = gcnew StringBuilder(256);

// The message filter is closed
//
iBuffer = PCANBasic::PCAN_FILTER_CLOSE;
result = PCANBasic::SetValue(PCANBasic::PCAN_USBBUS1,TPCANParameter::PCAN_MESSAGE_FILTER, iBuffer, sizeof(iBuffer));
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("The filter was successfully closed");

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim iBuffer As UInt32

strMsg = New StringBuilder(256)

' The message filter is closed
'
iBuffer = PCANBasic.PCAN_FILTER_CLOSE
result = PCANBasic.SetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_MESSAGE_FILTER, iBuffer, CType(System.Runtime.InteropServices.Marshal.SizeOf(i64Buffer), UInteger))
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("The filter was successfully closed")
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    iBuffer: LongWord;
begin
    // The message filter is closed
    //
    iBuffer := TPCANBasic.PCAN_FILTER_CLOSE;
    result := TPCANBasic.SetValue(TPCANBasic.PCAN_USBBUS1,PCAN_MESSAGE_FILTER, PLongWord(@iBuffer), sizeof(iBuffer));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0, 'The filter was successfully closed', 'Success',MB_OK);
See Also

GetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_SetValue


SetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)

SetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)

Sets a configuration or information numeric value within a PCAN Channel.

Syntax
Pascal OO
class function SetValue(
    Channel: TPCANHandle;
    Parameter: TPCANParameter;
    NumericBuffer: PUInt64;
    BufferLength: LongWord
    ): TPCANStatus; overload;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_SetValue")]
public static extern TPCANStatus SetValue(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType.U1)]
    TPCANParameter Parameter,
    ref UInt64 NumericBuffer,
    UInt32 BufferLength);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_SetValue")]
static TPCANStatus SetValue(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    [MarshalAs(UnmanagedType::U1)]
    TPCANParameter Parameter,
    UInt64 %NumericBuffer,
    UInt32 BufferLength);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_SetValue")> _
Public Shared Function SetValue( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Parameter As TPCANParameter, _
    ByRef NumericBuffer As UInt64, _
    ByVal BufferLength As UInt32) As TPCANStatus
End Function
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the value to be set (see TPCANParameter).
NumericBuffer | The buffer containing the 64-bit numeric value to be set.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'NumericBuffer'; it should point to a 64-bit integer buffer.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be set.
PCAN_ERROR_ILLOPERATION: | An underlying process that is generated by a call to this method with the current parameters, is temporarily not allowed. The configuration in relation to the used TPCANParameter must be checked.
Remarks

Use the method SetValue to set configuration information or environment values of a PCAN Channel as parameters like an Acceptance Filter. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be set can be found in Parameter Value Definitions.

Example

The following example shows the use of the method SetValue on the channel PCAN_USBBUS1 to set a message filter as a 11-bit acceptance code and mask, allowing only IDs from 0x100 to 0x103. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;
UInt64 i64Buffer;

strMsg = new StringBuilder(256);

// The acceptance code and mask are packed as 64-bit value
//
i64Buffer = 0x100;  // Acceptance code
i64Buffer <<= 32;
i64Buffer |= 0x003; // Acceptance mask
result = PCANBasic.SetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_ACCEPTANCE_FILTER_11BIT, ref i64Buffer, sizeof(UInt64));
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("The 11-bit acceptance filter was configured successfully");

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
UInt64 i64Buffer;

strMsg = gcnew StringBuilder(256);

// The acceptance code and mask are packed as 64-bit value
//
i64Buffer = 0x100;  // Acceptance code
i64Buffer <<= 32;
i64Buffer |= 0x003; // Acceptance mask
result = PCANBasic::SetValue(PCANBasic::PCAN_USBBUS1, TPCANParameter::PCAN_ACCEPTANCE_FILTER_11BIT, i64Buffer, sizeof(i64Buffer));
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("The 11-bit acceptance filter was configured successfully");

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim i64Buffer As UInt64

strMsg = New StringBuilder(256)

' The acceptance code and mask are packed as 64-bit value
'
i64Buffer = &H100             ' Acceptance code
i64Buffer <<= 32
i64Buffer = i64Buffer Or &H3 ' Acceptance mask
result = PCANBasic.SetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_ACCEPTANCE_FILTER_11BIT, i64Buffer, CType(System.Runtime.InteropServices.Marshal.SizeOf(i64Buffer), UInteger))
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("The 11-bit acceptance filter was configured successfully")
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    i64Buffer: UInt64;
begin
    // The acceptance code and mask are packed as 64-bit value
    //
    i64Buffer := $100;             // Acceptance code
    i64Buffer := i64Buffer shl 32;
    i64Buffer := i64Buffer Or $3;  // Acceptance mask
    result := TPCANBasic.SetValue(TPCANBasic.PCAN_USBBUS1,PCAN_ACCEPTANCE_FILTER_11BIT, PUInt64(@i64Buffer), sizeof(i64Buffer));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0, 'The 11-bit acceptance filter was configured successfully', 'Success',MB_OK);
end;
See Also

GetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_SetValue


SetValue(TPCANHandle, TPCANParameter, Object)

SetValue(TPCANHandle, TPCANParameter, Object)

Sets a configuration or information value within a PCAN Channel.

Syntax
Python
def SetValue(
    self,
    Channel,
    Parameter,
    Buffer)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the value to be set (see TPCANParameter).
Buffer | The buffer containing the value to be set.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the method are invalid. Check the parameter 'Buffer'; it should point to a buffer of a type which is accepted by the parameter being configured.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be set.
PCAN_ERROR_ILLOPERATION: | An underlying process that is generated by a call to this method with the current parameters, is temporarily not allowed. The configuration in relation to the used TPCANParameter must be checked.
Remarks

Use the method SetValue to set configuration information or environment values of a PCAN Channel as parameters like the Message Filter and values like a custom entry in the log file of PCAN-Basic. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be set can be found in Parameter Value Definitions.

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method SetValue on the channel PCAN_NONEBUS to set (and activate) the path for the log file of a PCAN-Basic's debug session. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is not needed to have an initialized PCAN channel for using the Log functionality.

Python:

# The path for the Log file is set.
# Note that this parameter is set using the
# default Channel (PCAN_NONEBUS)
#
strBuffer = "C:\Users\Admin\Desktop"
result = objPCAN.SetValue(PCAN_NONEBUS,PCAN_LOG_LOCATION,strBuffer)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    print ("Log path was successfully set")
See Also

GetValue

TPCANParameter

Parameter Value Definitions

Plain function Version: CAN_SetValue


FilterMessages

FilterMessages

Configures the reception filter.

Syntax
Pascal OO
class function FilterMessages(
    Channel: TPCANHandle;
    FromID: LongWord;
    ToID: LongWord;
    Mode: TPCANMode
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_FilterMessages")]
public static extern TPCANStatus FilterMessages(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    UInt32 FromID,
    UInt32 ToID,
    [MarshalAs(UnmanagedType.U1)]
    TPCANMode Mode);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_FilterMessages")]
static TPCANStatus FilterMessages(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    UInt32 FromID,
    UInt32 ToID,
    [MarshalAs(UnmanagedType::U1)]
    TPCANMode Mode);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_FilterMessages")> _
Public Shared Function FilterMessages( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    ByVal FromID As UInt32, _
    ByVal ToID As UInt32, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Mode As TPCANMode) As TPCANStatus
End Function
Python
def FilterMessages(
    self,
    Channel,
    FromID,
    ToID,
    Mode)
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
FromID | The lowest CAN ID wanted to be received.
ToID | The highest CAN ID wanted to be received.
Mode | The kind of filter being set (see TPCANMode).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
Remarks

Note that after a PCAN Channel is initialized, the status of its filter is fully opened. According with the current filter status, calling this method causes the following behavior:

  • Filter status is PCAN_FILTER_OPEN: The filter is automatically closed and then configured with the given range of IDs passed to this function [FromID, ToID] .
  • Filter status is PCAN_FILTER_CLOSE: The filter is set to the given range of IDs passed to this function [FromID, ToID] .
  • Filter status is PCAN_FILTER_CUSTOM: The filter is expanded with the given range of Ids [FromID, ToID]. If a smaller or different range is required than a range that has been configured before, the filter has to be closed first before calling the method FilterMessages. To do this use the method SetValue.

The parameter 'Mode' indicates which kind of ID is being used to register the new filter range. There are two possible values, Standard (11-bit identifier) or Extended (29-bit identifier). 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.

Take in account that configuring the message filter cause the CAN controller to enter the reset state. This will affect other applications that communicate with the same PCAN hardware.

Notes:

  1. There is only one filter for standard and extended CAN messages. It seems that the ID from a standard message uses the most significant 11 bits (bit 18 to 28) of the 29 bits. I.e. the standard ID 400h is also received by indicating an extended ID 10000000h. For this reason, it is not recommended to mix standard and extended filters, since it can increase the risk of receiving unwanted messages.
  2. Multiple calls of FilterMessages expand the reception filter.
  3. It is not guaranteed that an application only receives CAN messages in the range of FromID to ToID. This is caused by the operating principle of the SJA1000's acceptance filter. See also Philips Data Sheet "SJA1000 Stand-alone CAN-controller".

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method FilterMessages on the channel PCAN_USBBUS1 to receive a custom range of IDs. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C#:

TPCANStatus result;
StringBuilder strMsg;
UInt32 iBuffer;

strMsg = new StringBuilder(256);

// The message filter is closed first to ensure the reception of the new range of IDs.
//
iBuffer = PCANBasic.PCAN_FILTER_CLOSE;
result = PCANBasic.SetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_MESSAGE_FILTER, ref iBuffer, sizeof(UInt32));

if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
{
    // The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
    //
    result = PCANBasic.FilterMessages(PCANBasic.PCAN_USBBUS1, 2, 5, TPCANMode.PCAN_MODE_STANDARD);
    if (result != TPCANStatus.PCAN_ERROR_OK)
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox.Show(strMsg.ToString());
    }
    else
        MessageBox.Show("Filter successfully configured for IDs 2,3,4 and 5");
}

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
UInt32 iBuffer;

strMsg = gcnew StringBuilder(256);

// The message filter is closed first to ensure the reception of the new range of IDs.
//
iBuffer = PCANBasic::PCAN_FILTER_CLOSE;
result = PCANBasic::SetValue(PCANBasic::PCAN_USBBUS1,TPCANParameter::PCAN_MESSAGE_FILTER, iBuffer, sizeof(iBuffer));
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
{
    // The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
    //
    result = PCANBasic::FilterMessages(PCANBasic::PCAN_USBBUS1, 2, 5, TPCANMode::PCAN_MODE_STANDARD);
    if (result != TPCANStatus::PCAN_ERROR_OK)
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic::GetErrorText(result, 0, strMsg);
        MessageBox::Show(strMsg->ToString());
    }
    else
        MessageBox::Show("Filter successfully configured for IDs 2,3,4 and 5");
}

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim iBuffer As UInt32

strMsg = New StringBuilder(256)

'  The message filter is closed first to ensure the reception of the new range of IDs.
'
iBuffer = PCANBasic.PCAN_FILTER_CLOSE
result = PCANBasic.SetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_MESSAGE_FILTER, iBuffer, Convert.ToUInt32(Len(iBuffer)))
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    ' The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
    '
    result = PCANBasic.FilterMessages(PCANBasic.PCAN_USBBUS1, 2, 5, TPCANMode.PCAN_MODE_STANDARD)
    If result <> TPCANStatus.PCAN_ERROR_OK Then
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        MessageBox.Show(strMsg.ToString)
    Else
        MessageBox.Show("Filter successfully configured for IDs 2,3,4 and 5")
    End If
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    iBuffer: LongWord;
begin
    //  The message filter is closed first to ensure the reception of the new range of IDs.
    //
    iBuffer := TPCANBasic.PCAN_FILTER_CLOSE;
    result := TPCANBasic.SetValue(TPCANBasic.PCAN_USBBUS1,PCAN_MESSAGE_FILTER, PLongWord(@iBuffer), sizeof(iBuffer));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
    begin
        // The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
        //
        result := TPCANBasic.FilterMessages(TPCANBasic.PCAN_USBBUS1,2,5,PCAN_MODE_STANDARD);
        If (result <> PCAN_ERROR_OK) Then
        begin
            // An error occurred, get a text describing the error and show it
            //
            TPCANBasic.GetErrorText(result, 0, strMsg);
            MessageBox(0, strMsg, 'Error',MB_OK);
        end
        else
            MessageBox(0,'Filter successfully configured for IDs 2,3,4 and 5','Success', MB_OK);
    end;

Python:

#  The message filter is closed first to ensure the reception of the new range of IDs.
#
result = objPCAN.SetValue(PCAN_USBBUS1,PCAN_MESSAGE_FILTER,PCAN_FILTER_CLOSE)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print (result[1])
else:
    # The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
    #
    result = objPCAN.FilterMessages(PCAN_USBBUS1,2,5,PCAN_MODE_STANDARD)
    if result != PCAN_ERROR_OK:
        # An error occurred, get a text describing the error and show it
        #
        result = objPCAN.GetErrorText(result)
        print (result[1])
    else:
        print ("Filter successfully configured for IDs 2,3,4 and 5")
See Also

SetValue

Plain function Version: CAN_FilterMessages


GetErrorText

GetErrorText

Gets a descriptive text for an error code.

Overloads
Function | Description
GetErrorText(TPCANStatus,UInt16,String) | Gets a descriptive text for an error code.
GetErrorText(TPCANStatus, int) | Gets a descriptive text for an error code.


GetErrorText(TPCANStatus,UInt16,String)

GetErrorText(TPCANStatus,UInt16,String)

Gets a descriptive text for an error code.

Syntax
Pascal OO
class function GetErrorText(
    AnError: TPCANStatus;
    Language: Word;
    StringBuffer: PChar
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetErrorText")]
public static extern TPCANStatus GetErrorText(
    [MarshalAs(UnmanagedType.U4)]
    TPCANStatus AnError,
    UInt16 Language,
    StringBuilder StringBuffer);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_GetErrorText")]
static TPCANStatus GetErrorText(
    [MarshalAs(UnmanagedType::U4)]
    TPCANStatus AnError,
    UInt16 Language,
    StringBuilder^ StringBuffer);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_GetErrorText")> _
Public Shared Function GetErrorText( _
    <MarshalAs(UnmanagedType.U4)> _
    ByVal AnError As TPCANStatus, _
    ByVal Language As UInt16, _
    ByVal StringBuffer As StringBuilder) As TPCANStatus
End Function
Parameters
Parameters | Description
AnError | A TPCANStatus error code.
Language | Indicates a "Primary language ID".
StringBuffer | A null-terminated char array buffer with a length of 256.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL:
Indicates that the parameters passed to the method are invalid. Check the parameter 'Buffer'; it should point to a char array, big enough to allocate the text for the given error code.
Remarks

The "Primary language IDs" are codes used by Windows OS from Microsoft, to identify a human language. The PCAN-Basic API currently support the following languages:

Language | Primary Language ID
Neutral (System dependant) | 00h (0)
English | 09h (9)
German | 07h (7)
French | 0Ch (12)
Italian | 10h (16)
Spanish | 0Ah (10)

Note: Even when only short texts are being currently returned, a text within this method can have a maximum of 255 characters plus termination. For this reason, the length of the buffer must be at least 256 bytes.

Example

The following example shows the use of the method GetErrorText to get the description of an error. The language of the description's text will be the same used by the operating system (if its language is supported; otherwise English is used).

C#:

TPCANStatus result;
StringBuilder strMsg;

strMsg = new StringBuilder(256);

// Gets the description text for PCAN_ERROR_INITIALIZE using the Neutral language
//
result = PCANBasic.GetErrorText(TPCANStatus.PCAN_ERROR_INITIALIZE, 0, strMsg);
if (result != TPCANStatus.PCAN_ERROR_OK)
    // An error occurred, show a message indicating it
    //
    MessageBox.Show("Error when recovering Error-Code's description");
else
    MessageBox.Show(strMsg.ToString());

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;

strMsg = gcnew StringBuilder(256);

// Gets the description text for PCAN_ERROR_INITIALIZE using the Neutral language
//
result = PCANBasic::GetErrorText(TPCANStatus::PCAN_ERROR_INITIALIZE, 0, strMsg);
if (result != TPCANStatus::PCAN_ERROR_OK)
    // An error occurred, show a message indicating it
    //
    MessageBox::Show("Error when recovering Error-Code's description");
else
    MessageBox::Show(strMsg->ToString());

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder

strMsg = New StringBuilder(256)

' Gets the description text for PCAN_ERROR_INITIALIZE using the Neutral language
'
result = PCANBasic.GetErrorText(TPCANStatus.PCAN_ERROR_INITIALIZE, 0, strMsg)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, show a message indicating it
    '
    MessageBox.Show("Error when recovering Error-Code's description")
Else
    MessageBox.Show(strMsg.ToString)
End If

Pascal OO:

var
     result : TPCANStatus;
     strMsg: array [0..256] of Char;
begin

 // Gets the description text for PCAN_ERROR_INITIALIZE using the Neutral language
 //
result := TPCANBasic.GetErrorText(PCAN_ERROR_INITIALIZE, 0, strMsg);
If (result <> PCAN_ERROR_OK) Then
     // An error occurred, show a message indicating it
     //
     MessageBox(0, Error when recovering Error-Code's description','Error',MB_OK)
 else
     MessageBox(0,strMsg,'Success', MB_OK);
See Also

Primary Language ID

Plain function Version: CAN_GetErrorText


GetErrorText(TPCANStatus, int)

GetErrorText(TPCANStatus, int)

Gets a descriptive text for an error code.

Syntax
Python
def GetErrorText(
    self,
    Error,
    Language = 0)
Parameters
Parameters | Description
Error | A TPCANStatus error code.
Language | Indicates a "Primary language ID".
Returns

The return value is a 2-touple. The order of the returned values is as follows:

[0]: The method's return value as a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL:
Indicates that the parameters passed to the method are invalid. Check the parameter 'Buffer'; it should point to a char array, big enough to allocate the text for the given error code.

[1]: The text corresponding to the given TPCANStatus code.

Remarks

The "Primary language IDs" are codes used by Windows OS from Microsoft, to identify a human language. The PCAN-Basic API currently support the following languages:

Language | Primary Language ID
Neutral (System dependant) | 00h (0)
English | 09h (9)
German | 07h (7)
French | 0Ch (12)
Italian | 10h (16)
Spanish | 0Ah (10)

Python Notes

  • Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
  • Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.
Example

The following example shows the use of the method GetErrorText to get the description of an error. The language of the description's text will be in Spanish.

Python:

# Gets the description text for PCAN_ERROR_INITIALIZE using the language ID for Spanish
#
objPCAN = PCANBasic()
result = objPCAN.GetErrorText(PCAN_ERROR_INITIALIZE, 10)
if result[0] != PCAN_ERROR_OK:
    # An error occurred, show a message indicating it
    #
    print ("Error when recovering Error-Code's description")
else:
    print (result[1])
See Also

Primary Language ID

Plain function Version: CAN_GetErrorText


LookUpChannel

LookUpChannel

Finds the handle of a PCAN-Basic channel that matches the specified parameters.

Overloads
Function | Description
LookUpChannel(String,TPCANHandle) | Finds the handle of a PCAN-Basic channel that matches the specified parameters.
LookUpChannel(String) | Finds the handle of a PCAN-Basic channel that matches the specified parameters.


LookUpChannel(String,TPCANHandle)

LookUpChannel(String,TPCANHandle)

Finds the handle of a PCAN-Basic channel that matches the specified parameters.

Syntax
Pascal OO
class function LookUpChannel(
    Parameters: PAnsiChar,
    FoundChannel: PTPCANHandle
    ): TPCANStatus;
C#
[DllImport("PCANBasic.dll", EntryPoint = "CAN_LookUpChannel")]
public static extern TPCANStatus LookUpChannel(
    String Parameters,
    out TPCANHandle FoundChannel);
C++ / CLR
[DllImport("PCANBasic.dll", EntryPoint = "CAN_LookUpChannel")]
static TPCANStatus LookUpChannel(
    String^ Parameters,
    TPCANHandle %FoundChannel);
Visual Basic
<DllImport("PCANBasic.dll", EntryPoint:="CAN_LookUpChannel")>
Public Shared Function LookUpChannel(
    ByVal Parameters As String,
    ByRef FoundChannel As TPCANHandle) As TPCANStatus
End Function
Parameters
Parameters | Description
Parameters | A comma separated lookup-parameters string, that is, pairs of name/value to be matched within a PCAN-Basic channel.
FoundChannel | Buffer for returning the PCAN-Basic channel, when found. It contains the value PCAN_NONEBUS if not found.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL:
Indicates that the parameters passed to the function are invalid.
Remarks

The 'Parameters' string must contain name/value pairs separated with a '='.

Each pair of name/value must be separated with a ','.

The current supported parameters and their value ranges are described in LookUp Parameter Definition.

Example

The following example shows the use of the method LookUpChannel to get the handle of an USB device with ID 7. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C#:

TPCANStatus result;
StringBuilder strMsg;
TPCANHandle channelHandle;

strMsg = new StringBuilder(256);

// Try to find a PCAN-USB device with ID 7
//
result = PCANBasic.LookUpChannel("devicetype=pcan_usb, deviceid=7", out channelHandle);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
{
    if(channelHandle != PCANBasic.PCAN_NONEBUS)
        MessageBox.Show("The channel handle for the PCAN-USB with ID=7 was found");
    else
        MessageBox.Show("A PCAN-USB device with ID=7 is not available");
}

C++/CLR:
TPCANStatus result;
StringBuilder^ strMsg;
TPCANHandle channelHandle;

strMsg = gcnew StringBuilder(256);

// Try to find a PCAN-USB device with ID 7
//
result = PCANBasic::LookUpChannel("devicetype=pcan_usb, deviceid=7", channelHandle);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
{
    if (channelHandle != PCANBasic::PCAN_NONEBUS)
        MessageBox::Show("The channel handle for the PCAN-USB with ID=7 was found");
    else
        MessageBox::Show("A PCAN-USB device with ID=7 is not available");
}

Visual Basic:
Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim channelHandle As TPCANHandle

strMsg = New StringBuilder(256)

' Try to find a PCAN-USB device with ID 7
'
result = PCANBasic.LookUpChannel("devicetype=pcan_usb, deviceid=7", channelHandle)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error And show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    If channelHandle <> PCANBasic.PCAN_NONEBUS Then

        MessageBox.Show("The channel handle for the PCAN-USB with ID=7 was found")
    Else

        MessageBox.Show("A PCAN-USB device with ID=7 is not available")
    End If
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    channelHandle: TPCANHandle;
begin

    // Try to find a PCAN-USB device with ID 7
    //
    result := TPCANBasic.LookUpChannel('devicetype=pcan_usb, deviceid=7', PTPCANHAndle(@channelHandle));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, PAnsiChar(@strMsg));
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        If (channelHandle <> TPCANBasic.PCAN_NONEBUS) Then
            MessageBox(0,'The channel handle for the PCAN-USB with ID=7 was found','Success', MB_OK)
        else
            MessageBox(0,'A PCAN-USB device with ID=7 is not available','Success', MB_OK)

  See Also

LookUp Parameter Definition

Plain function Version: CAN_LookUpChannel


LookUpChannel(String)

LookUpChannel(String)

Finds the handle of a PCAN-Basic channel that matches the specified parameters.

Syntax
Python
def LookUpChannel(
        self,
        Parameter)
Parameters
Parameters | Description
Parameters | A comma separated lookup-parameters string, that is, pairs of name/value to be matched within a PCAN-Basic channel.
Returns

The return value is a 2-touple. The order of the returned values is as follows:

[0]: The method's return value as a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL:
Indicates that the parameters passed to the function are invalid.

[1]: The PCAN-Basic channel, when found, or PCAN_NONEBUS if not.

Remarks

The 'Parameters' string must contain name/value pairs separated with a '='.

Each pair of name/value must be separated with a ','.

The current supported parameters and their value ranges are described in LookUp Parameter Definition.

Example

The following example shows the use of the method LookUpChannel to get the handle of an USB device with ID 7. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Python:

# Try to find a PCAN-USB device with ID 7
#
result = objPCAN.LookUpChannel(b"devicetype=pcan_usb, deviceid=7")
if result[0] != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result[0])
    print (result[1])
else:
    if result[1].value != PCAN_NONEBUS.value:
        print ("The channel handle for the PCAN-USB with ID=7 was found")
    else:
        print ("A PCAN-USB device with ID=7 is not available")
See Also

LookUp Parameter Definition

Plain function Version: CAN_LookUpChannel


Functions

Functions

The functions of the PCAN-Basic API are divided in 4 groups of functionality:

Connection
Function | Description
CAN_Initialize | Initializes a PCAN Channel.
CAN_InitializeFD | Initializes a FD capable PCAN Channel.
CAN_Uninitialize | Uninitializes a PCAN Channel.
Configuration
Function | Description
CAN_SetValue | Sets a configuration or information value within a PCAN Channel.
CAN_FilterMessages | Configures the message's reception filter of a PCAN Channel.
Information
Function | Description
CAN_GetValue | Retrieves information from a PCAN Channel.
CAN_GetStatus | Retrieves the current BUS status of a PCAN Channel.
CAN_GetErrorText | Returns a descriptive text for an error code.
CAN_LookUpChannel | Finds the handle of a PCAN-Basic channel that matches the specified parameters.
Communication
Function | Description
CAN_Read | Reads a CAN message from the receive queue of a PCAN Channel.
CAN_ReadFD | Reads a CAN message from the receive queue of a FD capable PCAN Channel.
CAN_Write | Transmits a CAN message using a connected PCAN Channel.
CAN_WriteFD | Transmits a CAN message using a connected FD capable PCAN Channel.
CAN_Reset | Resets the receive and transmit queues of a PCAN Channel.


CAN_Initialize

CAN_Initialize

Initializes a PCAN Channel.

Syntax
C++
#ifdef __cplusplus
#define _DEF_ARG =0   // Using of default arguments
#else
#define _DEF_ARG
#endif

TPCANStatus __stdcall CAN_Initialize(
        TPCANHandle Channel,
        TPCANBaudrate Btr0Btr1,
        TPCANType HwType _DEF_ARG,
        DWORD IOPort _DEF_ARG,
        WORD Interrupt _DEF_ARG
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Btr0Btr1 | The speed for the communication (BTR0BTR1 code).
HwType | The type of the Non-Plug-and-Play hardware and its operation mode.
IOPort | The I/O address for the parallel port of the Non-Plug-and-Play hardware.
Interrupt | The Interrupt number of the parallel port of the Non-Plug-and-Play hardware.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_CAUTION:
Indicates that the channel has been initialized but at a different bit rate as the given one.
PCAN_ERROR_ILLHANDLE:
Indicates that the desired PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_ILLHW:
indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLOPERATION:
Indicates that an action cannot be executed due to the state of the hardware. Possible causes are:

  • The desired PCAN-Channel is a LAN Channel, which uses a different bit rate than the specified.

PCAN_ERROR_ILLMODE:
Indicates that the hardware is working in a different or incompatible mode than requested. Possible causes are:

  • The desired PCAN-Channel is being operated in CAN-FD mode.

PCAN_ERROR_REGTEST:
(Not-Plug-And-Play Only) Indicates a problem with hardware registration, normally due to wrong values in the parameters 'HwType', 'IOPort' and 'Interrupt'.
PCAN_ERROR_INITIALIZE:
Indicates that the desired PCAN channel cannot be connected because it is already in use (PCAN-Basic / PCAN-Light environment).
PCAN_ERROR_NETINUSE:
Indicates that the desired PCAN-Channel is being used with a different bit rate (PCAN-View).
PCAN_ERROR_HWINUSE:
Indicates that the desired PCAN-Channel is being used (CanApi2 connection).
PCAN_ERROR_NODRIVER:
The driver needed for connecting the desired PCAN Channel is not loaded.
Remarks

Note on correspondence of Functions:

A Channel that is initialized using CAN_Initialize must use CAN_Read and CAN_Write for communication. Calling CAN_ReadFD and/or CAN_WriteFD will result in a PCAN_ERROR_ILLOPERATION error.

As indicated by its name, the CAN_Initialize function initiates a PCAN Channel, preparing it for communicate within the CAN bus connected to it. Calls to the API functions will fail if they are used with a Channel handle, different than PCAN_NONEBUS, that has not been initialized jet. Each initialized channel should be released when it is not needed anymore.

Initializing a PCAN Channel means:

  • to reserve the Channel for the calling application/process.
  • to allocate channel resources, like receive and transmit queues.
  • to register/connect the Hardware denoted by the channel handle.
  • to check and adapt the bus speed, if the Channel is already in use. (Only if the Channel was pre-configured as Bitrate Adapting; see: Bitrate-Adapting Parameter).
  • to set the channel in Listen-Only mode. (Only if the channel was pre-configured as Listen-Only; see: Listen-Only Parameter).
  • to open the messages filter for the application/process.
  • to set-up the default values of the different parameters (See CAN_GetValue).
  • to set the Receive Status of the channel. (Pre-configured value; see: Receive Status Parameter).

What is different from the PCAN-Light API, the Initialization process will fail if an application tries to initialize a PCAN-Channel that has been initialized already within the same process.

The PCAN-Basic API use the same function for initializations of both, Plug-And-Play and Not-Plug-And-Play hardware. The CAN_Initialize function has three additional parameters that are only for the connection of Non-Plug-And-Play hardware. With Plug-And-Play hardware, however, only two parameters are to be supplied. The remaining three are not evaluated.

Take in consideration that initializing a channel causes a reset of the CAN hardware , when the bus status is other than OK. In this way errors like BUSOFF, BUSHEAVY, and BUSLIGHT, are removed.

PCAN-LAN Channels

A PCAN-LAN channel doesn't allow changing the bit rate using PCAN-Basic. In order to connect a PCAN-LAN Channel it is necessary to know the bit rate of the PCAN-Gateway device that is represented by that channel. If the bit rate is not known, the parameter Bitrate-Adapting should be used.

Example

The following example shows the initialize and uninitialize processes for a Plug-And-Play channel (channel 2 of a PCAN-PCI hardware) and for a Not-Plug-And-Play channel (channel 1 of the PCAN-DNG). In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C++:

TPCANStatus result;
char strMsg[256];

// The Plug & Play Channel (PCAN-PCI) is initialized
//
result = CAN_Initialize(PCAN_PCIBUS2,PCAN_BAUD_500K);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("PCAN-PCI (Ch-2) was initialized");

// The Not Plug & Play Channel (PCAN-Dongle) is initialized
//
result = CAN_Initialize(PCAN_DNGBUS1, PCAN_BAUD_500K, PCAN_TYPE_DNG, 0x378, 7);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("PCAN-Dongle (Ch-1) was initialized");

....

// All initialized channels are released
//
CAN_Uninitialize(PCAN_NONEBUS);
See Also

CAN_Uninitialize

CAN_GetValue

Understanding PCAN-Basic

Class-method Version: Initialize


CAN_InitializeFD

CAN_InitializeFD

Initializes a FD capable PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_InitializeFD(
    TPCANHandle Channel,
    TPCANBitrateFD BitrateFD);
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
BitrateFD | The speed for the communication (FD Bitrate string).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_CAUTION:
Indicates that the channel has been initialized but at a different bit rate as the given one.
PCAN_ERROR_ILLHANDLE:
Indicates that the desired PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_ILLHW:
Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLOPERATION:
Indicates that an action cannot be executed due to the state of the hardware. Possible causes are:

  • The desired PCAN Channel is not FD capable and cannot be initialized using this method.
  • The desired PCAN-Channel is a LAN Channel, which uses a different bit rate than the specified.

PCAN_ERROR_ILLMODE:
Indicates that the hardware is working in a different or incompatible mode than requested. Possible causes are:

  • The desired PCAN-Channel is being operated in CAN 2.0 A/B mode.

PCAN_ERROR_INITIALIZE:
Indicates that the desired PCAN channel cannot be connected because it is already in use (PCAN-Basic / PCAN-Light environment).
PCAN_ERROR_NETINUSE:
Indicates that the desired PCAN-Channel is being used with a different bit rate (PCAN-View).
PCAN_ERROR_HWINUSE:
Indicates that the desired PCAN-Channel is being used (CanApi connection).
PCAN_ERROR_NODRIVER:
The driver needed for connecting the desired PCAN Channel is not loaded.
Remarks

Note on correspondence of functions:

A Channel that is initialized using CAN_InitializeFD must use CAN_ReadFD and CAN_WriteFD for communication. Calling CAN_Read and/or CAN_Write will result in a PCAN_ERROR_ILLOPERATION error.

As indicated by its name, the CAN_InitializeFD function initiates a FD capable PCAN Channel, preparing it for communicate within the CAN bus connected to it. Calls to the API functions will fail if they are used with a Channel handle, different than PCAN_NONEBUS, that has not been initialized yet. Each initialized channel should be released when it is not needed anymore.

Initializing a PCAN Channel means:

  • to reserve the Channel for the calling application/process.
  • to allocate channel resources, like receive and transmit queues.
  • to register/connect the Hardware denoted by the channel handle.
  • to check and adapt the bus speed, if the Channel is already in use. (Only if the Channel was pre-configured as Bitrate Adapting; see: Bitrate-Adapting Parameter).
  • to set the channel in Listen-Only mode. (Only if the channel was pre-configured as Listen-Only; see: Listen-Only Parameter).
  • to open the messages filter for the application/process.
  • to set-up the default values of the different parameters (See CAN_GetValue).
  • to set the Receive Status of the channel. (Pre-configured value; see: Receive Status Parameter).

The Initialization process will fail if an application try to initialize a PCAN-Channel that has been initialized already within the same process.

Take in consideration that initializing a channel causes a reset of the CAN hardware , when the bus status is other than OK. In this way errors like BUSOFF, BUSWARNING, and BUSPASSIVE, are removed.

PCAN-LAN Channels

A PCAN-LAN channel doesn't allow changing the bit rate using PCAN-Basic. In order to connect a PCAN-LAN Channel it is necessary to know the bit rate of the PCAN-Gateway device that is represented by that channel. If the bit rate is not known, the parameter Bitrate-Adapting should be used.

Example

The following example shows the initialize and uninitialize processes for a FD capable channel (channel 1 of a PCAN-USB Pro FD hardware). In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C++:

TPCANStatus result;
char strMsg[256];
TPCANBitrateFD bitrate;

// Defines a FD Bit rate string with nominal and data Bit rate set to 1 MB
//
bitrate = "f_clock_mhz=24, nom_brp=1, nom_tseg1=17, nom_tseg2=6, nom_sjw=1, data_brp=1, data_tseg1=16, data_tseg2=7, data_sjw=1";

// The FD capable Channel (PCAN-USB Pro FD) is initialized
//
result = CAN_InitializeFD(PCAN_USBBUS1,bitrate);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("PCAN-USB Pro FD (Ch-1) was initialized");
See Also

CAN_Uninitialize

CAN_ReadFD

CAN_WriteFD

Class-method Version: InitializeFD


CAN_Uninitialize

CAN_Uninitialize

Uninitializes a PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_Uninitialize(
        TPCANHandle Channel
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel cannot be uninitialized because it was not found in the list of reserved channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
Remarks

A PCAN Channel can be released using one of this possibilities:

Single-Release: Given a handle of a PCAN Channel initialized before with CAN_Initialize. If the given channel can not be found then an error is returned.

Multiple-Release: Giving the handle value PCAN_NONEBUS which instructs the API to search for all channels initialized by the calling application and release them all. This option cause no errors if no hardware were uninitialized.

Transmit-queue at uninitialize: When a PCAN-Basic channel connection is terminated, the underlying hardware's transmit-queue will not immediately be discarded. PCAN-Basic will wait some time before finalizing, so that the hardware has time to send (or try to send) those unsent messages. When the time is up (amount 500 milliseconds), the rest of the messages in the queue (if any) are discarded.

Example

The following example shows the initialize and uninitialize (Single-Release) processes for the PCAN_PCIBUS1 channel. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: To see an example of Multiple-Release, see the CAN_Initialize function.

C++:

TPCANStatus result;
char strMsg[256];

// The PCI Channel is initialized
//
result = CAN_Initialize(PCAN_PCIBUS1,PCAN_BAUD_500K);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("PCAN-PCI (Ch-1) was initialized");

....

// The PCI Channel is released
//
result = CAN_Uninitialize(PCAN_PCIBUS1);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("PCAN-PCI (Ch-1) was released");
See Also

CAN_Initialize

Class-method Version: Uninitialize


CAN_Reset

CAN_Reset

Resets the receive and transmit queues of a PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_Reset(
        TPCANHandle Channel
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
Remarks

Calling this function ONLY clears the queues of a Channel. A reset of the CAN controller doesn't take place.

Normally a reset of the CAN Controller is desired when a bus-off occur. In this case an application cannot use the channel to communicate anymore, until the CAN controller is reset. Consider using the PCAN-Basic parameter PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like bus-off, bus-heavy and bus-light, is to uninitialize and initialize the used channel again. This causes a hardware reset, but only when no more clients are connected to that channel.

Example

The following example shows the use of CAN_Reset on the channel PCAN_PCIBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C++:

TPCANStatus result;
char strMsg[256];

// The PCI Channel is reset
//
result = CAN_Reset(PCAN_PCIBUS1);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("PCAN-PCI (Ch-1) was reset");
See Also

CAN_Read

CAN_Write

CAN_SetValue

Class-method Version: Reset


CAN_GetStatus

CAN_GetStatus

Gets the current BUS status of a PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_GetStatus(
        TPCANHandle Channel
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Returns

The return value is a TPCANStatus code. The typical return values are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN Channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSLIGHT: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-light status.
PCAN_ERROR_BUSHEAVY: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-heavy status.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.
PCAN_ERROR_OK: | Indicates that the status of the given PCAN Channel is OK.
Remarks

When the hardware status is bus-off, an application cannot communicate anymore. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like bus-off, bus-heavy and bus-light, is to uninitialize and initialise the used channel again. This causes a hardware reset.

Example

The following example shows the use of CAN_GetStatus on the channel PCAN_PCIBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C++:

TPCANStatus result;
char strMsg[256];

// Check the status of the PCI Channel
//
result = CAN_GetStatus(PCAN_PCIBUS1);
switch(result)
{
    case PCAN_ERROR_BUSLIGHT:
        MessageBox("PCAN-PCI (Ch-1): Handling a BUS-LIGHT status...");
        break;
    case PCAN_ERROR_BUSHEAVY:
        MessageBox("PCAN-PCI (Ch-1): Handling a BUS-HEAVY status...");
        break;
    case PCAN_ERROR_BUSOFF:
        MessageBox("PCAN-PCI (Ch-1): Handling a BUS-OFF status...");
        break;
    case PCAN_ERROR_OK:
        MessageBox("PCAN-PCI (Ch-1): Status is OK");
        break;
    default:
        // An error occurred, get a text describing the error and show it
        //
        CAN_GetErrorText(result, 0, strMsg);
        MessageBox(strMsg);
        break;
}
See Also

Parameter Value Definitions

TPCANParameter

Class-method Version: GetStatus


CAN_Read

CAN_Read

Reads a CAN message from the receive queue of a PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_Read(
        TPCANHandle Channel,
        TPCANMsg* MessageBuffer,
        TPCANTimestamp* TimestampBuffer
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsg buffer to store the CAN message.
TimestampBuffer | A TPCANTimestamp buffer to get the reception time of the message.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsg structure.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSLIGHT: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-light status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSHEAVY: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-heavy status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.
Remarks

Specifying the value of NULL for the parameter TimetampBuffer causes reading a message without timestamp, when the reception time is not desired. An "Illegal Parameter Value" error will be returned when the MessageBuffer is wrong or the TimestampBuffer contains a value different than NULL and provokes an internal error, eg. accessing its memory.

CAN_Read and CAN_ReadFD are mutually exclusive. The PCAN Channel passed to this function must be initialized using CAN_Initialize (class-method: Initialize). Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

The CAN_Read function returns received messages or status messages from the receive queue. It is important to call CAN_Read repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the CAN_Read function. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the CAN_Read function in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSHEAVY, and BUSLIGTH, is to uninitialize and initialise the used channel again. This causes a hardware reset.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_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.

Note that if a status message was read the return value of CAN_Read is also the error code.

Examples:

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

The following example shows the use of CAN_Read on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized and that the following code is an OnTimer event handler function.

C++:

TPCANMsg msg;
TPCANTimestamp timestamp;
TPCANStatus result;
char strMsg[256];

do
{
    // Check the receive queue for new messages
    //
    result = CAN_Read(PCAN_USBBUS1,&msg,&timestamp);
    if(result != PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox("A message was received");
        ProcessMessage(msg)
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        // and handle the error
        //
        CAN_GetErrorText(result, 0, strMsg);
        MessageBox(strMsg);
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & PCAN_ERROR_QRCVEMPTY) != PCAN_ERROR_QRCVEMPTY);
See Also

CAN_Write

Using Events

Error Frames

Class-method Version: Read


CAN_ReadFD

CAN_ReadFD

Reads a CAN message from the receive queue of a FD capable PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_ReadFD(
    TPCANHandle Channel,
    TPCANMsgFD* MessageBuffer,
    TPCANTimestampFD *TimestampBuffer);
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsgFD buffer to store the CAN message.
TimestampBuffer | A TPCANTimestampFD buffer to get the reception time of the message.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsgFD structure.
PCAN_ERROR_ILLOPERATION: | Indicates that the PCAN Channel passed to the function was not initialized using CAN_InitializeFD (class-method: InitializeFD).
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSWARNING: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-warning status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSPASSIVE: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-passive status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status. Note: MessageBuffer and TimestampBuffer are valid in this case.
PCAN_ERROR_QRCVEMPTY: | Indicates that the receive queue of the Channel is empty.
PCAN_ERROR_ILLDATA: | Indicates that the message that has been read is not permitted due to the current settings and has been discarded.
Remarks

Specifying the value of NULL for the parameter TimetampBuffer causes reading a message without timestamp, when the reception time is not desired. An "Illegal Parameter Value" error will be returned when the MessageBuffer is wrong or the TimestampBuffer contains a value different than NULL and provokes an internal error, eg. accessing its memory.

CAN_Read and CAN_ReadFD are mutually exclusive. The PCAN Channel passed to this function must be initialized using CAN_InitializeFD (class-method: InitializeFD). Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

The CAN_ReadFD function returns received messages or status messages from the receive queue. It is important to call CAN_ReadFD repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information.

The receive queue can contain up to 32767 messages.

There are two possibilities for reading messages from the receive queue of a Channel:

Time-Triggered Reading: Consists in periodically calls to the CAN_ReadFD function. Typically, an application starts a timer that every 50 or 100 milliseconds check for messages, calling the CAN_ReadFD function in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached.

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events.

About bus errors / Status messages

If a bus-off error occurs, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to reset the CAN controller when a bus-off state is detected automatically.

Another way to reset errors like BUSOFF, BUSWARNING, and BUSPASSIVE, is to uninitialize and initialise the used channel again. This causes a hardware reset.

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, FD, RTR, Error, or Status message. This value should be checked every time a message has been read successfully.

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames).

If the bit PCAN_MESSAGE_STATUS is set in the TPCANMsg.MSGTYPE field, the message is a Status message. The ID and DLC 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.

Note that if a status message was read the return value of CAN_ReadFD is also the error code.

Examples:

Data0 | Data1 | Data2 | Data3 | Error | Error Code | Description
00h | 00h | 00h | 00h | PCAN_ERROR_OK | 0000h | CAN controller has been successfully activated.
00h | 00h | 00h | 02h | PCAN_ERROR_OVERRUN | 0002h | CAN controller has been read out too late.
00h | 00h | 00h | 08h | PCAN_ERROR_BUSWARNING | 0008h | Bus error: An error counter reached the 'warning' limit.
00h | 04h | 00h | 00h | PCAN_ERROR_BUSPASSIVE | 40000h | Bus error: the CAN controller is error passive.
00h | 00h | 00h | 10h | PCAN_ERROR_BUSOFF | 0010h | Bus error: CAN Controller is in 'Bus Off' state.
Example

The following example shows the use of CAN_ReadFD on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized using CAN_InitializeFD and that the following code is an OnTimer event handler function.

C++:

TPCANMsgFD msg;
TPCANTimestampFD timestamp;
TPCANStatus result;
char strMsg[256];

do
{
    // Check the receive queue for new messages
    //
    result = CAN_ReadFD(PCAN_USBBUS1,&msg,&timestamp);
    if(result != PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox("A message was received");
        ProcessMessage(msg)
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        // and handle the error
        //
        CAN_GetErrorText(result, 0, strMsg);
        MessageBox(strMsg);
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & PCAN_ERROR_QRCVEMPTY) != PCAN_ERROR_QRCVEMPTY);
See Also

CAN_InitializeFD

CAN_WriteFD

Using Events

Error Frames

Class-method Version: ReadFD


CAN_Write

CAN_Write

Transmits a CAN message.

Syntax
C++
TPCANStatus __stdcall CAN_Write(
        TPCANHandle Channel,
        TPCANMsg* MessageBuffer
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsg buffer containing the CAN message to be sent.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsg structure.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.
PCAN_ERROR_QXMTFULL: | Indicates that the transmit queue of the Channel is full.
Remarks

If a bus-off error occur, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like BUSOFF, BUSHEAVY, and BUSLIGTH, is to uninitialize and initialise the used channel again. This causes a hardware reset, but only when no more clients are connected to that channel.

Example

The following example shows the use of CAN_Write on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C++:

TPCANMsg msg;
TPCANStatus result;
char strMsg[256];

// A CAN message is configured
//
msg.ID = 0x100;
msg.MSGTYPE = PCAN_MESSAGE_STANDARD;
msg.LEN = 3;
msg.DATA[0] = 1;
msg.DATA[1] = 2;
msg.DATA[2] = 3;

// The message is sent using the PCAN-USB Channel 1
//
result = CAN_Write(PCAN_USBBUS1, &msg);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("Message sent successfully");
See Also

CAN_Read

CAN_SetValue

Class-method Version: Write


CAN_WriteFD

CAN_WriteFD

Transmits a CAN message using a connected FD capable PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_WriteFD(
    TPCANHandle Channel,
    TPCANMsgFD* MessageBuffer);
Parameters
Parameters | Description
Channel | The handle of a FD capable PCAN Channel (see TPCANHandle).
MessageBuffer | A TPCANMsgFD buffer containing the CAN message to be sent.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid. Check the value of the MessageBuffer; it should point to a TPCANMsgFD structure.
PCAN_ERROR_ILLOPERATION: | Indicates that the PCAN Channel passed to the function was not initialized using CAN_InitializeFD (class-method: InitializeFD).
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
PCAN_ERROR_BUSOFF: | Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.
PCAN_ERROR_QXMTFULL: | Indicates that the transmit queue of the Channel is full.
Remarks

The use of CAN_Write and CAN_WriteFD are mutually exclusive. The PCAN Channel passed to this function must be initialized using CAN_InitializeFD (class-method: InitializeFD). Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

If a bus-off error occur, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like BUSOFF, BUSWARNING, and BUSPASSIVE, is to uninitialize and initialise the used channel again. This causes a hardware reset.

Example

The following example shows the use of CAN_WriteFD on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized using CAN_InitializeFD.

C++:

TPCANMsgFD msg;
TPCANStatus result;
char strMsg[256];

// A CAN FD message is configured
//
msg.ID = 0x100;
msg.MSGTYPE = PCAN_MESSAGE_STANDARD | PCAN_MESSAGE_FD;

// DLC 9 means 12 data bytes
//
msg.DLC = 9;
for(int i=0; i < 12; i++)
    msg.DATA[i] = i;

// The message is sent using the PCAN-USB Channel 1
//
result = CAN_WriteFD(PCAN_USBBUS1, &msg);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("Message sent successfully");
See Also

CAN_InitializeFD

CAN_ReadFD

Class-method Version: WriteFD


CAN_GetValue

CAN_GetValue

Retrieves information from a PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_GetValue(
        TPCANHandle Channel,
        TPCANParameter Parameter,
        void* Buffer,
        WORD BufferLength
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the information to be retrieved (see TPCANParameter).
Buffer | The buffer to return the required value.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid. Check the parameter 'Buffer'; it should point to a valid data container for the requested value.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be read.
Remarks

Use the function CAN_GetValue to get information about PCAN environment as parameters like the Message Filter and values like the availability of a PCAN-Channel. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be read can be found in Parameter Value Definitions.

Example

The following example shows the use of CAN_GetValue on the channel PCAN_USBBUS1 to check if the Message Filter is fully opened. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C++:

int iBuffer;
TPCANStatus result;
char strMsg[256];

// The status of the message filter of the PCAN-USB Channel 1 is asked
//
result = CAN_GetValue(PCAN_USBBUS1, PCAN_MESSAGE_FILTER, &iBuffer, sizeof(iBuffer));
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
{
    // A text is shown giving information about the current status of the filter
    //
    switch(iBuffer)
    {
        case PCAN_FILTER_OPEN:
            MessageBox("The message filter for the PCAN-USB, channel 1, is completely opened.");
            break;
        case PCAN_FILTER_CLOSE:
            MessageBox("The message filter for the PCAN-USB, channel 1, is closed.");
            break;
        case PCAN_FILTER_CUSTOM:
            MessageBox("The message filter for the PCAN-USB, channel 1, is custom configured.");
            break;
    }
}
See Also

CAN_SetValue

TPCANParameter

Parameter Value Definitions

Class-method Version: GetValue


CAN_SetValue

CAN_SetValue

Sets a configuration or information value within a PCAN Channel.

Syntax
C++
TPCANStatus __stdcall CAN_SetValue(
        TPCANHandle Channel,
        TPCANParameter Parameter,
        void* Buffer,
        WORD BufferLength
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
Parameter | The code of the value to be set (see TPCANParameter).
Buffer | The buffer containing the value to be set.
BufferLength | The length in bytes of the given buffer.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid. Check the parameter 'Buffer'; it should point to a valid data container for the requested value.
PCAN_ERROR_CAUTION: | The configuration of a parameter failed due to a no more existing channel. The parameter has been reset on all existing channels.
PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHW: | Indicates that the desired PCAN Channel is not available.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid (check the list of valid Channels), or is not supported by the specified parameter.
PCAN_ERROR_ILLPARAMTYPE: | Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be set.
PCAN_ERROR_ILLOPERATION: | An underlying process that is generated by a call to this function with the current parameters, is temporarily not allowed. The configuration in relation to the used TPCANParameter must be checked.
Remarks

Use the function CAN_SetValue to set configuration information or environment values of a PCAN Channel as parameters like the Message Filter and values like a custom entry in the log file of PCAN-Basic. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be set can be found in Parameter Value Definitions.

Example

The following example shows the use of CAN_SetValue on the channel PCAN_USBBUS1 to insert a text into the PCAN-Basic log file. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is not needed to have an initialized PCAN channel for using the Log functionality.

C++:

TPCANStatus result;
char strMsg[256];

// Sets a text to be included in the Log file of the PCAN-Basic
//
strcpy(strMsg, "This is a custom text from an application included in PCAN-BASIC's Log File");

// Inserts the given text into the Log file of the PCAN-Basic.
// Note: If the Log functionality is disabled, this call will automatically
//activate the log process.
//
result = CAN_SetValue(PCAN_NONEBUS, PCAN_LOG_TEXT, strMsg, strlen(strMsg));
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("The text was successfully logged in the PCAN-Basic's Log file.");
See Also

CAN_GetValue

TPCANParameter

Parameter Value Definitions

Class-method Version: SetValue


CAN_FilterMessages

CAN_FilterMessages

Configures the reception filter.

Syntax
C++
TPCANStatus __stdcall CAN_FilterMessages(
        TPCANHandle Channel,
        DWORD FromID,
        DWORD ToID,
        TPCANMode Mode
);
Parameters
Parameters | Description
Channel | The handle of a PCAN Channel (see TPCANHandle).
FromID | The lowest CAN ID wanted to be received.
ToID | The highest CAN ID wanted to be received.
Mode | The kind of filter being set (see TPCANMode).
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_INITIALIZE: | Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLHANDLE: | Indicates that the given PCAN Channel is not valid. Check the list of valid Channels.
Remarks

Note that after a PCAN Channel is initialized, the status of its filter is fully opened. According with the current filter status, calling this function causes the following behavior:

  • Filter status is PCAN_FILTER_OPEN: The filter is automatically closed and then configured with the given range of IDs passed to this function [FromID, ToID] .
  • Filter status is PCAN_FILTER_CLOSE: The filter is set to the given range of IDs passed to this function [FromID, ToID] .
  • Filter status is PCAN_FILTER_CUSTOM: The filter is expanded with the given range of Ids [FromID, ToID]. If a smaller or different range is required than a range that has been configured before, the filter has to be closed first before calling the CAN_FilterMessages function. To do this use the function CAN_SetValue.

The parameter 'Mode' indicates which kind of ID is being used to register the new filter range. There are two possible values, Standard (11-bit identifier) or Extended (29-bit identifier). 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.

Take in account that configuring the message filter cause the CAN controller to enter the reset state. This will affect other applications that communicate with the same PCAN hardware.

Notes:

  1. There is only one filter for standard and extended CAN messages. It seems that the ID from a standard message uses the most significant 11 bits (bit 18 to 28) of the 29 bits. I.e. the standard ID 400h is also received by indicating an extended ID 10000000h. For this reason, it is not recommended to mix standard and extended filters, since it can increase the risk of receiving unwanted messages.
  2. Multiple calls of CAN_FilterMessages expand the reception filter.
  3. It is not guaranteed that an application only receives CAN messages in the range of FromID to ToID. This is caused by the operating principle of the SJA1000's acceptance filter. See also Philips Data Sheet "SJA1000 Stand-alone CAN-controller".
Example

The following example shows the use of CAN_FilterMessages on the channel PCAN_USBBUS1 to receive a custom range of IDs. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is assumed that the channel was already initialized.

C++:

TPCANStatus result;
char strMsg[256];
DWORD iBuffer;

// The message filter is closed first to ensure the reception of the new range of IDs.
//
iBuffer = PCAN_FILTER_CLOSE;
result = CAN_SetValue(PCAN_USBBUS1,PCAN_MESSAGE_FILTER,&iBuffer, sizeof(iBuffer));

if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
{
    // The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
    //
    result = CAN_FilterMessages(PCAN_USBBUS1, 2, 5, PCAN_MESSAGE_STANDARD);
    if(result != PCAN_ERROR_OK)
    {
        // An error occurred, get a text describing the error and show it
        //
        CAN_GetErrorText(result, 0, strMsg);
        MessageBox(strMsg);
    }
    else
        MessageBox("Filter successfully configured for IDs 2,3,4 and 5");
}
See Also

CAN_SetValue

Class-method Version: FilterMessages


CAN_GetErrorText

CAN_GetErrorText

Returns a descriptive text for an error code.

Syntax
C++
TPCANStatus __stdcall CAN_GetErrorText(
        TPCANStatus Error,
        WORD Language,
        LPSTR Buffer
);
Parameters
Parameters | Description
Error | A TPCANStatus error code.
Language | Indicates a "Primary language ID".
Buffer | A null-terminated char array buffer with a length of 256.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid. Check the parameter 'Buffer'; it should point to a char array, big enough to allocate the text for the given error code.
PCAN_ERROR_ILLHANDLE: | Indicates that the desired PCAN Channel is not valid. Check the list of valid Channels.
Remarks

The "Primary language IDs" are codes used by Windows OS from Microsoft, to identify a human language. The PCAN-Basic API currently support the following languages:

Language | Primary Language ID
Neutral (English) | 00h (0)
English | 09h (9)
German | 07h (7)
French | 0Ch (12)
Italian | 10h (16)
Spanish | 0Ah (10)

Note: Even when only short texts are being currently returned, a text within this function can have a maximum of 255 characters plus termination. For this reason, the length of the buffer must be at least 256 bytes.

Example

The following example shows the use of CAN_GetErrorText to get the description of an error. The language of the description's text will be the same used by the operating system.

C++:

TPCANStatus result;
char strMsg[256];

// Gets the description text for PCAN_ERROR_INITIALIZE using the Neutral language
//
result = CAN_GetErrorText(PCAN_ERROR_INITIALIZE, 0, strMsg);
if(result != PCAN_ERROR_OK)
    // An error occurred, get a text describing the error and show it
    //
    MessageBox("Error when recovering Error-Code's description");
else
    MessageBox(strMsg);
See Also

Primary Language ID

Class-method Version: GetErrorText


CAN_LookUpChannel

CAN_LookUpChannel

Finds the handle of a PCAN-Basic channel that matches the specified parameters.

Syntax
C++
TPCANStatus __stdcall CAN_LookUpChannel(
    LPSTR Parameters,
    TPCANHandle* FoundChannel
);
Parameters
Parameters | Description
Parameters | A comma separated lookup-parameters string, that is, pairs of name/value to be matched within a PCAN-Basic channel.
FoundChannel | Buffer for returning the PCAN-Basic channel, when found. It contains the value PCAN_NONEBUS if not found.
Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL: | Indicates that the parameters passed to the function are invalid.
PCAN_ERROR_ILLHANDLE: | Indicates that the desired PCAN Channel is not valid. Check the list of valid Channels.
Remarks

The 'Parameters' string must contain name/value pairs separated with a '='.

Each pair of name/value must be separated with a ','.

The current supported parameters and their value ranges are described in LookUp Parameter Definition.

Example

The following example shows the use of CAN_LookUpChannel to get the handle of an USB device with ID 7. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

C++:

TPCANStatus result;
char strMsg[256];
TPCANHandle channelHandle;

// Try to find a PCAN-USB device with ID 7
//
result = CAN_LookUpChannel("devicetype=pcan_usb, deviceid=7", &channelHandle);
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
{
    if(channelHandle != PCAN_NONENBUS)
        MessageBox("The channel handle for the PCAN-USB with ID=7 was found");
    else
        MessageBox("A PCAN-USB device with ID=7 is not available");
}
See Also

LookUp Parameter Definition

Class-method Version: LookUpChannel


Definitions

Definitions

The PCAN-Basic API defines the following values:

Name | Description
PCAN Handle Definitions | Defines the handles for the different PCAN Channels.
Parameter Value Definitions | Defines the possible values for setting and getting PCAN's environment information with the functions CAN_SetValue and CAN_GetValue.
FD Bit rate Parameter Definitions | Defines the different configuration parameters used to create a Flexible Data rate string for FD capable PCAN-Channels initialization.
LookUp Parameter Definition | Defines the different parameters used to search for PCAN-Basic channels.


PCAN Handle Definitions

PCAN Handle Definitions

Defines the handles for the different PCAN buses (Channels) within a class. These values are used as parameter where a TPCANHandle is needed.

Default handle value:

Type | Constant | Value | Description
TPCANHandle | PCAN_NONEBUS | 0 | Represents a standard PCAN channel. This channel cannot be initialized.

Handles for the ISA Bus (Not Plug & Play):

Type | Constant | Value | Description
TPCANHandle | PCAN_ISABUS1 | 0x21 | PCAN-ISA interface, channel 1.
TPCANHandle | PCAN_ISABUS2 | 0x22 | PCAN-ISA interface, channel 2.
TPCANHandle | PCAN_ISABUS3 | 0x23 | PCAN-ISA interface, channel 3.
TPCANHandle | PCAN_ISABUS4 | 0x24 | PCAN-ISA interface, channel 4.
TPCANHandle | PCAN_ISABUS5 | 0x25 | PCAN-ISA interface, channel 5.
TPCANHandle | PCAN_ISABUS6 | 0x26 | PCAN-ISA interface, channel 6.
TPCANHandle | PCAN_ISABUS7 | 0x27 | PCAN-ISA interface, channel 7.
TPCANHandle | PCAN_ISABUS8 | 0x28 | PCAN-ISA interface, channel 8.

Handles for the Dongle Bus (Not Plug & Play):

Type | Constant | Value | Description
TPCANHandle | PCAN_DNGBUS1 | 0x31 | PCAN-Dongle/LPT interface, channel 1.

Handles for the PCI Bus:

Type | Constant | Value | Description
TPCANHandle | PCAN_PCIBUS1 | 0x41 | PCAN-PCI interface, channel 1.
TPCANHandle | PCAN_PCIBUS2 | 0x42 | PCAN-PCI interface, channel 2.
TPCANHandle | PCAN_PCIBUS3 | 0x43 | PCAN-PCI interface, channel 3.
TPCANHandle | PCAN_PCIBUS4 | 0x44 | PCAN-PCI interface, channel 4.
TPCANHandle | PCAN_PCIBUS5 | 0x45 | PCAN-PCI interface, channel 5.
TPCANHandle | PCAN_PCIBUS6 | 0x46 | PCAN-PCI interface, channel 6.
TPCANHandle | PCAN_PCIBUS7 | 0x47 | PCAN-PCI interface, channel 7.
TPCANHandle | PCAN_PCIBUS8 | 0x48 | PCAN-PCI interface, channel 8.
TPCANHandle | PCAN_PCIBUS9 | 0x409 | PCAN-PCI interface, channel 9.
TPCANHandle | PCAN_PCIBUS10 | 0x40A | PCAN-PCI interface, channel 10.
TPCANHandle | PCAN_PCIBUS11 | 0x40B | PCAN-PCI interface, channel 11.
TPCANHandle | PCAN_PCIBUS12 | 0x40C | PCAN-PCI interface, channel 12.
TPCANHandle | PCAN_PCIBUS13 | 0x40D | PCAN-PCI interface, channel 13.
TPCANHandle | PCAN_PCIBUS14 | 0x40E | PCAN-PCI interface, channel 14.
TPCANHandle | PCAN_PCIBUS15 | 0x40F | PCAN-PCI interface, channel 15.
TPCANHandle | PCAN_PCIBUS16 | 0x410 | PCAN-PCI interface, channel 16.

Handles for the USB Bus:

Type | Constant | Value | Description
TPCANHandle | PCAN_USBBUS1 | 0x51 | PCAN-USB interface, channel 1.
TPCANHandle | PCAN_USBBUS2 | 0x52 | PCAN-USB interface, channel 2.
TPCANHandle | PCAN_USBBUS3 | 0x53 | PCAN-USB interface, channel 3.
TPCANHandle | PCAN_USBBUS4 | 0x54 | PCAN-USB interface, channel 4.
TPCANHandle | PCAN_USBBUS5 | 0x55 | PCAN-USB interface, channel 5.
TPCANHandle | PCAN_USBBUS6 | 0x56 | PCAN-USB interface, channel 6.
TPCANHandle | PCAN_USBBUS7 | 0x57 | PCAN-USB interface, channel 7.
TPCANHandle | PCAN_USBBUS8 | 0x58 | PCAN-USB interface, channel 8.
TPCANHandle | PCAN_USBBUS9 | 0x509 | PCAN-USB interface, channel 9.
TPCANHandle | PCAN_USBBUS10 | 0x50A | PCAN-USB interface, channel 10.
TPCANHandle | PCAN_USBBUS11 | 0x50B | PCAN-USB interface, channel 11.
TPCANHandle | PCAN_USBBUS12 | 0x50C | PCAN-USB interface, channel 12.
TPCANHandle | PCAN_USBBUS13 | 0x50D | PCAN-USB interface, channel 13.
TPCANHandle | PCAN_USBBUS14 | 0x50E | PCAN-USB interface, channel 14.
TPCANHandle | PCAN_USBBUS15 | 0x50F | PCAN-USB interface, channel 15.
TPCANHandle | PCAN_USBBUS16 | 0x510 | PCAN-USB interface, channel 16.

Handles for the PC_Card Bus:

Type | Constant | Value | Description
TPCANHandle | PCAN_PCCBUS1 | 0x61 | PCAN-PC Card interface, channel 1.
TPCANHandle | PCAN_PCCBUS2 | 0x62 | PCAN-PC Card interface, channel 2.

Handles for the LAN Bus:

Type | Constant | Value | Description
TPCANHandle | PCAN_LANBUS1 | 0x801 | PCAN-LAN interface, channel 1.
TPCANHandle | PCAN_LANBUS2 | 0x802 | PCAN-LAN interface, channel 2.
TPCANHandle | PCAN_LANBUS3 | 0x803 | PCAN-LAN interface, channel 3.
TPCANHandle | PCAN_LANBUS4 | 0x804 | PCAN-LAN interface, channel 4.
TPCANHandle | PCAN_LANBUS5 | 0x805 | PCAN-LAN interface, channel 5.
TPCANHandle | PCAN_LANBUS6 | 0x806 | PCAN-LAN interface, channel 6.
TPCANHandle | PCAN_LANBUS7 | 0x807 | PCAN-LAN interface, channel 7.
TPCANHandle | PCAN_LANBUS8 | 0x808 | PCAN-LAN interface, channel 8.
TPCANHandle | PCAN_LANBUS9 | 0x809 | PCAN-LAN interface, channel 9.
TPCANHandle | PCAN_LANBUS10 | 0x80A | PCAN-LAN interface, channel 10.
TPCANHandle | PCAN_LANBUS11 | 0x80B | PCAN-LAN interface, channel 11.
TPCANHandle | PCAN_LANBUS12 | 0x80C | PCAN-LAN interface, channel 12.
TPCANHandle | PCAN_LANBUS13 | 0x80D | PCAN-LAN interface, channel 13.
TPCANHandle | PCAN_LANBUS14 | 0x80E | PCAN-LAN interface, channel 14.
TPCANHandle | PCAN_LANBUS15 | 0x80F | PCAN-LAN interface, channel 15.
TPCANHandle | PCAN_LANBUS16 | 0x810 | PCAN-LAN interface, channel 16.
Remarks

The PCAN_NONEBUS is a value used as default channel value. It is used for general purposes as using and configuring the Log capabilities of the PCAN-Basic API. It can also be used to remove all channel connections made by an application.

These definitions are constants values in an object oriented environment (Delphi, .NET Framework) and declared as defines in C++ (plain API).

Hardware Type and Channels:

Not Plug & Play: The hardware channels of this kind are used as registered. This mean, for example, it is allowed to register the PCAN_ISABUS3 without having registered PCAN_ISA1 and PCAN_ISA2. It is a decision of each user, how to associate a PCAN-Channel (logical part) and a port/interrupt pair (physical part).

Plug & Play: For hardware handles of PCI, USB and PC-Card, the availability of the channels is determined by the count of hardware connected to a computer in a given moment, in conjunction with their internal handle. This mean, that having four PCAN-USB connected to a computer will let the user connect to the channels PCAN_USBBUS1 to PCAN_USBBUS4. The association of each channel with a hardware is managed internally using the handle of a hardware.

Python:

The definitions of these values have the following form: TPCANHandle(handle) where handle is the value contained in the column with the same name. e.g. PCAN_PCCBUS1 is defined as TPCANHandle(0x61).

See Also

Parameter Value Definitions


Parameter Value Definitions

Parameter Value Definitions

Defines the possible values for setting and getting PCAN's environment information with the functions CAN_SetValue and CAN_GetValue.

Activation values:

Type | Constant | Value | Description
Int32 | PCAN_PARAMETER_OFF | 0 | The PCAN parameter is not set (inactive).
Int32 | PCAN_PARAMETER_ON | 1 | The PCAN parameter is set (active).

Filter values:

Type | Constant | Value | Description
Int32 | PCAN_FILTER_CLOSE | 0 | The PCAN filter is closed. No messages will be received.
Int32 | PCAN_FILTER_OPEN | 1 | The PCAN filter is fully opened. All messages will be received.
Int32 | PCAN_FILTER_CUSTOM | 2 | The PCAN filter is custom configured. Only registered messages will be received.

Channel Availability values:

Type | Constant | Value | Description
Int32 | PCAN_CHANNEL_UNAVAILABLE | 0 | The PCAN-Channel handle i.e. its associated hardware is not available.
Int32 | PCAN_CHANNEL_AVAILABLE | 1 | The PCAN-Channel handle is valid to connect/initialize. Furthermore, for plug&play hardware, this means that the hardware is plugged-in.
Int32 | PCAN_CHANNEL_OCCUPIED | 2 | The PCAN-Channel handle is valid, and is currently being used.
Int32 | PCAN_CHANNEL_PCANVIEW | PCAN_CHANNEL_AVAILABLE Or PCAN_CHANNEL_OCCUPIED | The PCAN-Channel handle is currently being used by a PCAN-View application and is valid to connect.

Log-Configuration values*:

Type | Constant | Value | Description
Int32 | LOG_FUNCTION_DEFAULT | 0x00 | Logs system exceptions and errors. Custom log texts are also included.
Int32 | LOG_FUNCTION_ENTRY | 0x01 | Logs the entries to the PCAN-Basic API functions.
Int32 | LOG_FUNCTION_PARAMETERS | 0x02 | Logs the parameters passed to the PCAN-Basic API functions.
Int32 | LOG_FUNCTION_LEAVE | 0x04 | Logs the exits from the PCAN-Basic API functions.
Int32 | LOG_FUNCTION_WRITE | 0x08 | Logs the CAN messages passed to the CAN_Write function.
Int32 | LOG_FUNCTION_READ | 0x10 | Logs the CAN messages received within the CAN_Read function.
Int32 | LOG_FUNCTION_ALL | 0xFFFF | Logs all possible information within the PCAN-Basic API functions.

*These values can be combined using the bitwise inclusive OR operator

Trace-Configuration values*:

Type | Constant | Value | Description
Int32 | TRACE_FILE_SINGLE | 0x00 | Stores messages in a single file until the configured file size is reached.
Int32 | TRACE_FILE_SEGMENTED | 0x01 | Stores messages distributed in several files.
Int32 | TRACE_FILE_DATE | 0x02 | Includes date information into the name of the trace file.
Int32 | TRACE_FILE_TIME | 0x04 | Includes the time information into the name of the trace file.
Int32 | TRACE_FILE_OVERWRITE | 0x08 | Forces the overwriting of available traces (same name).

*These values can be combined using the bitwise inclusive OR operator

Feature values*:

Type | Constant | Value | Description
Int32 | FEATURE_FD_CAPABLE | 1 | The PCAN Channel represents a device that supports flexible data rate (CAN-FD).
Int32 | FEATURE_DELAY_CAPABLE | 2 | The PCAN Channel represents a device that supports the configuration of a delay between sending frames (FPGA devices only)
Int32 | FEATURE_IO_CAPABLE | 4 | The PCAN Channel represents a device that supports the configuration of digital and/or analogue IOs (input/output) for using with electronic circuits.

*These values can be combined using the bitwise inclusive OR operator

Service-Status values:

Type | Constant | Value | Description
Int32 | SERIVCE_STATUS_STOPPED | 1 | The service is not running.
Int32 | SERVICE_STATUS_RUNNING | 4 | The service is running.
Remarks

These definitions are constants values in an object oriented environment (Delphi, .NET Framework) and declared as defines in C++ (plain API).

Python:

The definitions of these values have the following form: TPCANParameter(value) where value is the value contained in the column with the same name. e.g. LOG_FUNCTION_ENTRY is defined as TPCANParameter(0x01).

See Also

PCAN Handle Definitions


FD Bit rate Parameter Definitions

FD Bit rate Parameter Definitions

Defines the different configuration parameters used to create a Flexible Data rate string for FD capable PCAN-Channels initialization. These values are used as parameter with CAN_InitializeFD (class-method: InitializeFD).

Clock Frequency parameters:

Type | Constant | Value | Description
String | PCAN_BR_CLOCK | "f_clock" | Clock frequency in Hertz (80000000, 60000000, 40000000, 30000000, 24000000, 20000000).
String | PCAN_BR_CLOCK_MHZ | "f_clock_mhz" | Clock frequency in Megahertz (80, 60, 40, 30, 24, 20).

Nominal Bit rate parameters:

Type | Constant | Value | Description
String | PCAN_BR_NOM_BRP | "nom_brp" | Clock prescaler for nominal time quantum (1..1024).
String | PCAN_BR_NOM_TSEG1 | "nom_tseg1" | TSEG1 segment for nominal bit rate in time quanta (1..256).
String | PCAN_BR_NOM_TSEG2 | "nom_tseg2" | TSEG2 segment for nominal bit rate in time quanta (1..128).
String | PCAN_BR_NOM_SJW | "nom_sjw" | Synchronization Jump Width for nominal bit rate in time quanta (1..128).

Data Bit rate parameters:

Type | Constant | Value | Description
String | PCAN_BR_DATA_BRP | "data_brp" | Clock prescaler for fast data time quantum (1..1024).
String | PCAN_BR_DATA_TSEG1 | "data_tseg1" | TSEG1 segment for fast data bit rate in time quanta (1..32).
String | PCAN_BR_DATA_TSEG2 | "data_tseg2" | TSEG2 segment for fast data bit rate in time quanta (1..16).
String | PCAN_BR_DATA_SJW | "data_sjw" | Synchronization Jump Width for fast data bit rate in time quanta (1..16).
Remarks

These definitions are constants values in an object oriented environment (Delphi, .NET Framework) and declared as defines in C++ (plain API).

Following points are to be respected in order to construct a valid FD Bit rate string:

  • The string must contain only one of the two possible "Clock Frequency" parameters, depending on the unit used (Hz, or MHz).
  • The frequency to use must be one of the 6 listed within the "Clock Frequency" parameters.
  • The value for each parameter must be separated with a '='. Example: "data_brp=1"
  • Each pair of parameter/value must be separated with a ','. Blank spaces are allowed but are not necessary. Example: "f_clock_mhz=24, nom_brp=1,"
  • Both Bit rates, or only the nominal one, must be defined within the string (PCAN_BR_DATA_* and PCAN_BR_NOM_*, or only PCAN_BR_NOM_*).

Example with nominal Bit rate only:

A valid string representing 1 Mbit/sec for both, nominal and data Bit rates:

"f_clock_mhz=20, nom_brp=5, nom_tseg1=2, nom_tseg2=1, nom_sjw=1"

Example with nominal and data Bit rate:

A valid string representing 1 Mbit/sec for nominal Bit rate, and 2 Mbit/sec for data Bit rate:

"f_clock_mhz=20, nom_brp=5, nom_tseg1=2, nom_tseg2=1, nom_sjw=1, data_brp=2, data_tseg1=3, data_tseg2=1, data_sjw=1"

Parameter Value Ranges:

Parameter | Value Range
f_clock | [80000000, 60000000, 40000000, 30000000, 24000000, 20000000]
f_clock_mhz | [80, 60, 40, 30, 24, 20]
nom_brp | 1 .. 1024
nom_tseg1 | 1 .. 256
nom_tseg2 | 1 .. 128
nom_sjw | 1 .. 128
data_brp | 1 .. 1024
data_tseg1 | 1 .. 32
data_tseg2 | 1 .. 16
data_sjw | 1 .. 16

Python:

The definitions of these values have the following form: TPCANBitrateFD(string) where string is the value contained in the "value" column, as ascii literal, e.g. PCAN_BR_CLOCK is defined as TPCANBitrateFD(b"f_clock").

See Also

CAN_InitializeFD (class-method: InitializeFD)


LookUp Parameter Definition

LookUp Parameter Definition

Defines the different parameters used to search for PCAN-Basic channels. These values are used as parameter with CAN_LookUpChannel (class-method: LookUpChannel).

LookUp Channel values:

Type | Constant | Value | Description
String | LOOKUP_DEVICE_TYPE | "devicetype" | Lookup channel by Device type (e.g. PCAN_USB).
String | LOOKUP_DEVICE_ID | "deviceid" | Lookup channel by device id.
String | LOOKUP_CONTROLLER_NUMBER | "controllernumber" | Lookup channel by CAN controller 0-based index.
String | LOOKUP_IP_ADDRESS | "ipaddress" | Lookup channel by IP address (LAN channels only).
Remarks

These definitions are constants values in an object oriented environment (Delphi, .NET Framework) and declared as defines in C++ (plain API).

Following rules are to be taken into account in order to construct a valid lookup parameter string:

  • The value for each parameter must be separated with a '='. Example: "deviceid=1"
  • Each pair of parameter/value must be separated with a ','. Blank spaces are allowed but are not necessary. Example: "devicetype=pcan_usb, deviceid=1,"
  • Non-existent parameters are ignored instead of causing the function call to fail. Example, this would work well: "devicetype=pcan_usb,unknownparam=4"
  • Numeric parameter values that are out of the current supported range just return no results instead of causing the function to fail. Example: "controllernumber=2500"
  • Repeated parameters within the string don't cause the function to fail. Only the last occurrences of repeated parameters are evaluated. Example, only PCI devices are looked up: "devicetype=pcan_usb, devicetype=pcan_pci"
  • When more than one channel is found, the first of them is returned. Example: "devicetype=pcan_usb" (having more than one USB device attached)
  • The order of evaluation is fixed, regardless of the position of the parameters within the string. The order is:
    1. Device Type
    2. Device ID
    3. CAN Controller Number
    4. IP-Address

Parameters and Value Ranges:

Parameter | Value Range
LOOKUP_DEVICE_TYPE | A TPCANDevice value. The input can be numeric, in hexadecimal or decimal format, or as string denoting a TPCANDevice value name (case insensitive). Examples: "devicetype=1" "devicetype=pcan_usb" "devicetype=PCAN_USB"
LOOKUP_DEVICE_ID | Value in range of a double word (0 .. 4294967295), in hexadecimal or decimal format. Examples: "deviceid=10" "deviceid=Ah" "deviceid=0xA"
LOOKUP_CONTROLLER_NUMBER | A zero-based index value in range of a double word (0 .. 4294967295), in hexadecimal or decimal format. Currently, a maximum of 6 channels per device are supported (controller index in range [0 .. 5]). Examples: "controllernumber=1" "controllernumber=1h" "controllernumber=0x1"
LOOKUP_IP_ADDRESS | A valid Internet Protocol address string. Example: "ipaddress=192.168.2.1"
See Also

CAN_LookUpChannel (class-method: LookUpChannel)


Additional Information

Additional Information

PCAN is the platform for PCAN-Basic. In the following topics there is an overview of PCAN and the fundamental practice with the interface DLL CanApi4 (PCAN-API)

In this Chapter

Topics | Description
PCAN Fundamentals | This section contains an introduction to PCAN.
PCAN-API | This section compares the PCAN-Basic and CanApi4 interfaces, with a function description of CanApi4.
Error Frames | This section contains information about CAN Error frames.
Log File Generation | This section contains information about logging debug data within PCAN-Basic.


PCAN Fundamentals

PCAN Fundamentals

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 using 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

Understanding PCAN-Basic


PCAN-API

PCAN-API

The professional programming interface PCAN-API, also called CanApi4 interface, makes it possible to create complex Windows® applications with CAN and CAN FD support. The API (Application Programming Interface) provides an extensive function library using interface DLLs for 32-bit and 64-bit systems.

Unlike PCAN-Basic, the CAN communication is handled by Clients and offers significant advantages. Thus, not only a single but multiple applications can access a physical CAN channel. Furthermore, it works even without hardware: Via virtual connections, Clients establish a simulated CAN communication among Windows® applications.

Important differences to PCAN-Basic at a glance:

  • Allow transmitting CAN messages at a fixed point of time (sending with timestamp).
  • Several applications can be connected to the same PCAN device at the same time.
  • Works with virtual hardware and internal nets.
  • Connection to the hardware is done over a client and a net, instead of using a pseudo channel.

See Also

PCAN-Developer 4


Error Frames

Error Frames

Error Frames can be received if the connected PCAN-Channel configured the parameter PCAN_ALLOW_ERROR_FRAMES using the function CAN_SetValue (class-method: SetValue) to activate the error frames.

The error frame data will be placed into a TPCANMsg or TPCANMsgFD structure, according to the kind of initialization used, and its MSGTYPE field will have the PCAN_MESSAGE_ERRFRAME bit set.

The following list shows the elements of an error frame:

Field | Information from... | Contents
ID | ECC register SJA1000 (Error Code Capture), bits 6 and 7 (ERRC0, ERRC1) | 0: The message only transports updated Error Counter values 1: Bit error 2: Form error 4: Stuff error 8: Other type of error
DATA [0] | ECC register, bit 5 (DIR) | 0: Error has occured during transmission 1: Error has occured during reception
DATA [1] | ECC register, bits 0 to 4 (SEG0 to SEG4) | Current position of the bit stream processor: 2: ID.28 to ID.21 3: Start of frame 4: Bit SRTR 5: Bit IDE 6: ID.20 to ID.18 7: ID.17 to ID.13 8: CRC Sequence 9: Reserved Bit 0 10: Data Field 11: Data Length Code 12: Bit RTR 13: Reserved Bit 1 14: ID.4 to ID.0 15: ID.12 to ID.5 17: Active Error Flag 18: Intermission 19: Tolerate Dominant Bits 23: Error Delimiter 24: CRC Delimiter 25: Acknowledge Slot 26: End of Frame 27: Acknowledge Limiter 28: Overload Flag
DATA [2] | RX Error Counter Register (RXERR) | Current value of the Receive Error counter
DATA [3] | TX Error Counter Register (TXERR) | Current value of the Transmit Error counter
Remarks

For further information about this, see Philips Data Sheet "SJA1000 Stand-alone CAN controller".


Log File Generation

Log File Generation

In order to support debugging of problems, that can arise during CAN communication, PCAN-Basic can generate a log file, containing a protocol of all API function calls. There are two different ways to configure and activate this logging functionality:

  • Using the API.
  • Using the Windows Registry.
Log configuration using API

In order to configure the Log functionality, PCAN-Basic API provides 3 parameters that can be configured with the function CAN_SetValue (class-method: SetValue). These parameters are:

  • PCAN_LOG_LOCATION, to set the location of the log file.
  • PCAN_LOG_CONFIGURE, to configure the content of the log file.
  • PCAN_LOG_STATUS, to enable/disable logging.
Example:

Within the following example, the PCAN-Basic is configured to log all possible information (LOG_FUNCTION_ALL = 0xFFFF), as well as to store the log file on the desktop of an user called "admin".

C++:

TPCANStatus result;
char strMsg[MAX_PATH];

// Configures the data in the log file.
//
iBuffer = LOG_FUNCTION_ALL;
result = CAN_SetValue(PCAN_NONEBUS, PCAN_LOG_CONFIGURE, (void*)&iBuffer, sizeof(iBuffer));
if(result != PCAN_ERROR_OK)
{
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}

// Configures the path of the log file.
//
char *buffer = "C:\\users\\admin\\desktop";
result = CAN_SetValue(PCAN_NONEBUS, PCAN_LOG_LOCATION,buffer,strlen(buffer));
if(result != PCAN_ERROR_OK)
{
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}

// Configures the status of the log file
//
int iBuffer = PCAN_PARAMETER_ON;
result = CAN_SetValue(PCAN_NONEBUS, PCAN_LOG_STATUS, (void*)&iBuffer, sizeof(iBuffer));
if(result != PCAN_ERROR_OK)
{
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
Log configuration using Windows Registry

In order to enable the log file generation, the following registry key must be created:

HKEY_CURRENT_USER\SOFTWARE\PEAK-System\PCAN-Basic\Log

The existence of this key is analogous to use the function CAN_SetValue (class-method: SetValue) to set the parameter PCAN_LOG_STATUS to "on". If this key is not present, then no log file is generated.

Configuration:

If no further configuration is made, then the default values for PCAN_LOG_LOCATION, and PCAN_LOG_CONFIGURE are used. In order to configure the location and content of the log file, two registry values are used:

Flags: This is a DWORD value, that represents a logical OR operation between the values LOG_FUNCTION_* that are wanted to be included within the logging data. The value LOG_FUNCTION_ALL causes logging all possible information.

Path: This is a String value, that represents the path to a folder in the computer, where the log file will be created.

Example:

Within the following example, the PCAN-Basic is configured to log function entries (LOG_FUNCTION_ENTRY = 1), function parameters (LOG_FUNCTION_PARAMETERS = 2), and function outs (LOG_FUNCTION_LEAVE = 4), as well as to store the log file on the desktop of a user called "admin".

[HKEY_CURRENT_USER\SOFTWARE\PEAK-System\PCAN-Basic\Log]
"Flags"=dword:00000007
"Path"="C:\\Users\\admin\\desktop"
Remarks:

The registry key should be deleted (or renamed) after a debug session is done. If the key is leaved, all PCAN-Basic applications running under the same user account will remain writing data to their log files, generating in this way huge text files that consume hard-disk space unnecessarily.


Contents

Contents
Introduction
Understanding PCAN-Basic
Using Events
License Regulations
Contact Information
Reference
Namespaces
Peak.Can.Basic
Modules
PCANBasic Module
Units
PCANBasic Unit
Classes
PCANBasic
TPCANBasic
Structures
TPCANMsg
TPCANTimestamp
TPCANMsgFD
TPCANChannelInformation
Types
TPCANHandle
TPCANStatus
TPCANDevice
TPCANParameter
TPCANMessageType
TPCANType
TPCANMode
TPCANBaudrate
TPCANBitrateFD
TPCANTimestampFD
Methods
Initialize
Initialize(TPCANHandle, TPCANBaudrate)
Initialize(TPCANHandle, TPCANBaudrate, TPCANType, UInt32, UInt16)
InitializeFD
Uninitialize
Reset
GetStatus
Read
Read(TPCANHandle, TPCANMsg)
Read(TPCANHandle, TPCANMsg, TPCANTimestamp)
Read(TPCANHandle)
ReadFD
ReadFD(TPCANHandle, TPCANMsgFD)
ReadFD(TPCANHandle, TPCANMsgFD, TPCANTimestampFD)
ReadFD(TPCANHandle)
Write
WriteFD
GetValue
GetValue(TPCANHandle, TPCANParameter, String, UInt32)
GetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)
GetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)
GetValue(TPCANHandle, TPCANParameter, String, TPCANChannelInformation[])
GetValue(TPCANHandle,TPCANParameter)
SetValue
SetValue(TPCANHandle, TPCANParameter, String, UInt32)
SetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)
SetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)
SetValue(TPCANHandle, TPCANParameter, Object)
FilterMessages
GetErrorText
GetErrorText(TPCANStatus,UInt16,String)
GetErrorText(TPCANStatus, int)
LookUpChannel
LookUpChannel(String,TPCANHandle)
LookUpChannel(String)
Functions
CAN_Initialize
CAN_InitializeFD
CAN_Uninitialize
CAN_Reset
CAN_GetStatus
CAN_Read
CAN_ReadFD
CAN_Write
CAN_WriteFD
CAN_GetValue
CAN_SetValue
CAN_FilterMessages
CAN_GetErrorText
CAN_LookUpChannel
Definitions
PCAN Handle Definitions
Parameter Value Definitions
FD Bit rate Parameter Definitions
LookUp Parameter Definition
Additional Information
PCAN Fundamentals
PCAN-API
Error Frames
Log File Generation


Index

Index
A | C | D | E | F | G | I | L | M | N | P | R | S | T | U | W
A
Additional Information
C
CAN_FilterMessages
CAN_GetErrorText
CAN_GetStatus
CAN_GetValue
CAN_Initialize
CAN_InitializeFD
CAN_LookUpChannel
CAN_Read
CAN_ReadFD
CAN_Reset
CAN_SetValue
CAN_Uninitialize
CAN_Write
CAN_WriteFD
Classes
Contact Information
D
Definitions
E
Error Frames
F
FD Bit rate Parameter Definitions
FilterMessages
Functions
G
GetErrorText
GetErrorText(TPCANStatus, int)
GetErrorText(TPCANStatus,UInt16,String)
GetStatus
GetValue
GetValue(TPCANHandle, TPCANParameter, String, TPCANChannelInformation[])
GetValue(TPCANHandle, TPCANParameter, String, UInt32)
GetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)
GetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)
GetValue(TPCANHandle,TPCANParameter)
I
Initialize
Initialize(TPCANHandle, TPCANBaudrate)
Initialize(TPCANHandle, TPCANBaudrate, TPCANType, UInt32, UInt16)
InitializeFD
Introduction
L
License Regulations
Log File Generation
LookUp Parameter Definition
LookUpChannel
LookUpChannel(String)
LookUpChannel(String,TPCANHandle)
M
Methods
Modules
N
Namespaces
P
Parameter Value Definitions
PCAN Fundamentals
PCAN Handle Definitions
PCAN-API
PCANBasic
PCAN-Basic Documentation
PCANBasic Module
PCANBasic Unit
Peak.Can.Basic
R
Read
Read(TPCANHandle)
Read(TPCANHandle, TPCANMsg)
Read(TPCANHandle, TPCANMsg, TPCANTimestamp)
ReadFD
ReadFD(TPCANHandle)
ReadFD(TPCANHandle, TPCANMsgFD)
ReadFD(TPCANHandle, TPCANMsgFD, TPCANTimestampFD)
Reference
Reset
S
SetValue
SetValue(TPCANHandle, TPCANParameter, Object)
SetValue(TPCANHandle, TPCANParameter, String, UInt32)
SetValue(TPCANHandle, TPCANParameter, UInt32, UInt32)
SetValue(TPCANHandle, TPCANParameter, UInt64, UInt32)
Structures
T
TPCANBasic
TPCANBaudrate
TPCANBitrateFD
TPCANChannelInformation
TPCANDevice
TPCANHandle
TPCANMessageType
TPCANMode
TPCANMsg
TPCANMsgFD
TPCANParameter
TPCANStatus
TPCANTimestamp
TPCANTimestampFD
TPCANType
Types
U
Understanding PCAN-Basic
Uninitialize
Units
Using Events
W
Write
WriteFD


Welcome to the documentation of PCAN-Basic,

the new small Version of the PCAN-API from PEAK-System.

Introduction [image] DLL API Reference [image] Additional Information

Last Update: 26.07.2022