CAN_InitializeFD

PCAN-Basic

previous page next page

PCAN-Basic Documentation

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_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");