PCANBasicInitialize(UInt16, TPCANBaudrate) Method

public static TPCANStatus Initialize(
	ushort Channel,
	TPCANBaudrate Btr0Btr1
)

Public Shared Function Initialize ( 
	Channel As UShort,
	Btr0Btr1 As TPCANBaudrate
) As TPCANStatus

public:
static TPCANStatus Initialize(
	unsigned short Channel, 
	TPCANBaudrate Btr0Btr1
)

Parameters

Channel  UInt16

The handle of a PCAN Channel (see PCAN Handle Definitions).

Btr0Btr1  TPCANBaudrate

The speed for the communication (BTR0BTR1 code).

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

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 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_BUSHEAVY, and PCAN_ERROR_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 PCAN_BITRATE_ADAPTING should be used.

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

TPCANStatus result;
System.Text.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 System.Text.StringBuilder(256);
    PCANBasic.GetErrorText(result, 0, strMsg);
    Console.WriteLine(strMsg.ToString());
}
else
    Console.WriteLine("PCAN-PCI (Ch-2) was initialized");

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

Dim result As TPCANStatus
Dim strMsg As System.Text.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 System.Text.StringBuilder(256)
    PCANBasic.GetErrorText(result, 0, strMsg)
    Console.WriteLine(strMsg.ToString)
Else
    Console.WriteLine("PCAN-PCI (Ch-2) was initialized")
End If

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

TPCANStatus result;
System::Text::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 System::Text::StringBuilder(256);
    PCANBasic::GetErrorText(result, 0, strMsg);
    Console::WriteLine(strMsg->ToString());
}
else
    Console::WriteLine("PCAN-PCI (Ch-2) was initialized");

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

Reference

Other Resources