ApiInitialize(PcanChannel, Bitrate) Method

public static PcanStatus Initialize(
	PcanChannel channel,
	Bitrate bitrate
)

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

public:
static PcanStatus Initialize(
	PcanChannel channel, 
	Bitrate bitrate
)

Parameters

channel  PcanChannel

The handle of a PCAN Channel.

bitrate  Bitrate

The speed for the communication (BTR0/BTR1 code). Default is 500 kBit/s (Pcan500).

Return Value

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

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 other methods will fail if they are used with a Channel handle, different than None, 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: BitrateAdapting parameter).
• to set the Channel in Listen-Only mode - only if the Channel was configured to work in Listen-Only mode (see: ListenOnly parameter).
• to open the filter, i.e., configure the filter to capture all messages that are transmitted on the bus.
• to set-up the default values of the different parameters (see method GetValue).
• to activate the receive status for the Channel. (See: ReceiveStatus parameter).

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, BusLight, and BusHeavy, 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 CAN controller on the PCAN-Gateway device that is represented by that Channel. To initialize the Channel without having to specify the correct bit rate, the parameter BitrateAdapting can be used.

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 bit rate (BTR0/BTR1 0x001C)
//
PcanStatus result = Api.Initialize(channel,  Bitrate.Pcan500);
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 bit rate (BTR0/BTR1 0x001C)
'
Dim result As PcanStatus = Api.Initialize(channel, Bitrate.Pcan500)
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

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

    // The hardware represented by the given handle is initialized with 500 kBit/s bit rate (BTR0/BTR1 0x001C)
    //
    PcanStatus result = Api::Initialize(channel, Bitrate::Pcan500);
    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);
    }

Reference