ApiInitialize(PcanChannel, BitrateXL) Method

Initializes a PCAN Channel for CAN communication supporting Extended Data-Field Length.

Definition

Namespace: Peak.Can.Basic
Assembly: PCANBasic.NET (in PCANBasic.NET.dll) Version: 5.1.0

public static PcanStatus Initialize(
	PcanChannel channel,
	BitrateXL bitrate
)

Public Shared Function Initialize ( 
	channel As PcanChannel,
	bitrate As BitrateXL
) As PcanStatus

C++

public:
static PcanStatus Initialize(
	PcanChannel channel, 
	BitrateXL^ bitrate
)

Parameters

channel PcanChannel: The handle of an XL capable PCAN Channel.
bitrate BitrateXL: The speed for the communication as a CAN XL bit rate object (see BitrateXL).

Return Value

PcanStatus

OK is returned on success. The typical errors in case of failure are:

Caution: Indicates that the channel has been initialized but at a different bit rate than the specified in bitrate.
IllegalHandle: Indicates that the channel contains an invalid value.
IllegalHardwareHandle: Indicates that the channel is not available.
InvalidOperation: Indicates that an action cannot be executed due to the state of the hardware. Possible causes are:
- The channel is not CAN XL capable and cannot be initialized using this method.
- The channel is a PcanLan Channel, which uses a different bit rate than the specified.
IllegalMode: Indicates that the hardware is working in a different or incompatible mode than requested. Possible causes are:
- The channel is being operated in classic CAN 2.0 A/B mode.
- The channel is being operated in CAN FD mode.
Initialize: Indicates that the channel cannot be connected because it is already in use (PCAN-Basic / PCAN-Light environment).
NetInUse: Indicates that the channel is being used with a different bit rate (PCAN-View).
HardwareInUse: Indicates that the channel is being already used (PcanApi connection).
NoDriver: Indicates that the device driver needed for connecting the channel is not loaded.

Example

The following example shows the initialization and uninitialization processes using the USB interface (first PCAN-USB 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.

PcanChannel channel = PcanChannel.Usb01;

// The hardware represented by the given handle is initialized with 500 kBit/s nominal bit rate, 2 MBit/s flexible data rate, and 8 MBit/s extended field-data rate
// 
PcanStatus result = Api.Initialize(channel, (BitrateXL)"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");
if (result != PcanStatus.OK)
{
    // An error occurred
    //
    Api.GetErrorText(result, out var errorText);
    Console.WriteLine(errorText);
}
else
{
    // A success message is shown
    //
    Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.");
    // The connection to the hardware is finalized when it is no longer needed
    //
    result = Api.Uninitialize(channel);
    if (result != PcanStatus.OK)
    {
        // An error occurred
        //
        Api.GetErrorText(result, out var errorText);
        Console.WriteLine(errorText);
    }
    else
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully finalized.");
}

Dim channel As PcanChannel = PcanChannel.Usb01

' The hardware represented by the given handle is initialized with 500 kBit/s nominal bit rate, 2 MBit/s flexible data rate, and 8 MBit/s extended field-data rate
'
Dim result As PcanStatus = Api.Initialize(channel, CType("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", BitrateXL))
If (result <> PcanStatus.OK) Then
    ' An error occurred
    '
    Dim errorText As String = String.Empty
    Api.GetErrorText(result, errorText)
    Console.WriteLine(errorText)
Else
    ' A success message is shown
    '
    Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.")
    ' The connection to the hardware is finalized when it is no longer needed
    '
    result = Api.Uninitialize(channel)
    If (result <> PcanStatus.OK) Then
        ' An error occurred
        '
        Dim errorText As String = String.Empty
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully finalized.")
    End If
End If

C++

String^ errorText;
PcanChannel channel = PcanChannel::Usb01;

// The hardware represented by the given handle is initialized with 500 kBit/s nominal bit rate, 2 MBit/s flexible data rate, and 8 MBit/s extended field-data rate
//
PcanStatus result = Api::Initialize(channel, (BitrateXL^)"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");
if (result != PcanStatus::OK)
{
    // An error occurred
    //
    Api::GetErrorText(result, errorText);
    Console::WriteLine(errorText);
}
else
{
    // A success message is shown
    //
    Console::WriteLine("The hardware represented by the handle {0} was successfully initialized.", channel);
    // The connection to the hardware is finalized when it is no longer needed
    //
    result = Api::Uninitialize(channel);
    if (result != PcanStatus::OK)
    {
        // An error occurred
        //
        Api::GetErrorText(result, errorText);
        Console::WriteLine(errorText);
    }
    else
        Console::WriteLine("The hardware represented by the handle {0} was successfully finalized.", channel);
}

Exceptions

DllNotFoundException	The underlying PCANBasic.dll library could not be found.
PcanBasicException	The execution of a PCAN-Basic related check operation ended with an unexpected result. Typically, this exception is triggered when a device driver is not installed or is not up to date.