PCANBasicInitializeXL Method

public static TPCANStatus InitializeXL(
	ushort Channel,
	string BitrateXL
)

Public Shared Function InitializeXL ( 
	Channel As UShort,
	BitrateXL As String
) As TPCANStatus

public:
static TPCANStatus InitializeXL(
	unsigned short Channel, 
	String^ BitrateXL
)

Parameters

Channel  UInt16

The handle of an XL capable PCAN Channel (see PCAN Handle Definitions).

BitrateXL  String

The speed for the communication (see XL Bit rate Parameter Definitions).

Return Value

The return value is a TPCANStatus value. 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.
• 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 CAN-XL 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.
  • 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 (PcanApi connection).
• PCAN_ERROR_NODRIVER: The driver needed for connecting the desired PCAN Channel is not loaded.

As indicated by its name, the InitializeXL 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 configured to adapt an available bit rate; see: PCAN_BITRATE_ADAPTING parameter).
• to set the channel in Listen-Only mode. (Only if the channel was configured to work in Listen-Only mode; see: PCAN_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 method GetValue).
• to set the Receive Status of the channel. (See: PCAN_RECEIVE_STATUS parameter).

Other than in 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 PCAN_ERROR_BUSOFF, PCAN_ERROR_BUSWARNING, and PCAN_ERROR_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 PCAN_BITRATE_ADAPTING should be used.

The following example shows the initialization and uninitialization processes for a CAN-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.

string bitrate;
TPCANStatus result;
System.Text.StringBuilder strMsg;

// Defines an XL Bit rate string with 500 kBit/s nominal bit rate, 2 MBit/s flexible data rate, and 8 MBit/s extended field-data rate
//
bitrate = "f_clock=160000000, brp=1, nom_tseg1=255, nom_tseg2=64, nom_sjw=64, fd_tseg1=63, fd_tseg2=16, fd_sjw=16, fd_ssp_offset=0, xl_tseg1=10, xl_tseg2=9, xl_sjw=9, xl_ssp_offset=10, xl_error_signaling=1, xl_transceiver_mode_switch=0";

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

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

Dim bitrate As String
Dim result As TPCANStatus
Dim strMsg As System.Text.StringBuilder

' Defines an XL Bit rate string with 500 kBit/s nominal bit rate, 2 MBit/s flexible data rate, and 8 MBit/s extended field-data rate
'
bitrate = "f_clock=160000000, brp=1, nom_tseg1=255, nom_tseg2=64, nom_sjw=64, fd_tseg1=63, fd_tseg2=16, fd_sjw=16, fd_ssp_offset=0, xl_tseg1=10, xl_tseg2=9, xl_sjw=9, xl_ssp_offset=10, xl_error_signaling=1, xl_transceiver_mode_switch=0"

' The XL capable Channel (PCAN-USB XL) is initialized
'
result = PCANBasic.InitializeXL(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 System.Text.StringBuilder(256)
    PCANBasic.GetErrorText(result, 0, strMsg)
    Console.WriteLine(strMsg.ToString)
Else
    Console.WriteLine("PCAN-USB XL (Ch-1) was initialized")
End If

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

String^ bitrate;
TPCANStatus result;
System::Text::StringBuilder^ strMsg;

// Defines an XL Bit rate string with 500 kBit/s nominal bit rate, 2 MBit/s flexible data rate, and 8 MBit/s extended field-data rate
//
bitrate = "f_clock=160000000, brp=1, nom_tseg1=255, nom_tseg2=64, nom_sjw=64, fd_tseg1=63, fd_tseg2=16, fd_sjw=16, fd_ssp_offset=0, xl_tseg1=10, xl_tseg2=9, xl_sjw=9, xl_ssp_offset=10, xl_error_signaling=1, xl_transceiver_mode_switch=0";

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

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

Reference

Other Resources