InitializeFD

PCAN-Basic

previous page next page

PCAN-Basic Documentation

InitializeFD

Initializes a FD capable PCAN Channel.

Syntax

Pascal OO

class function InitializeFD(
    Channel: TPCANHandle;
    BitrateFD: TPCANBitrateFD
    ): TPCANStatus;

[DllImport("PCANBasic.dll", EntryPoint = "CAN_InitializeFD")]
public static extern TPCANStatus InitializeFD(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    TPCANBitrateFD BitrateFD);

C++ / CLR

[DllImport("PCANBasic.dll", EntryPoint = "CAN_InitializeFD")]
static TPCANStatus InitializeFD(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    TPCANBitrateFD BitrateFD);

Visual Basic

<DllImport("PCANBasic.dll", EntryPoint:="CAN_InitializeFD")> _
Public Shared Function InitializeFD( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    ByVal BitrateFD As TPCANBitrateFD) As TPCANStatus
End Function

Python

def InitializeFD(
    self,
    Channel,
    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 methods:

A Channel that is initialized using InitializeFD must use ReadFD and WriteFD for communication. Calling Read and/or Write will result in a PCAN_ERROR_ILLOPERATION error.

As indicated by its name, the InitializeFD method initiates a FD capable PCAN Channel, preparing it for communicate within the CAN bus connected to it. Calls to the API 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 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 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.

Python Notes

Class-Method: Different than the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.

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#:

string bitrate;
TPCANStatus result;
StringBuilder strMsg;

// 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 = PCANBasic.InitializeFD(PCANBasic.PCAN_USBBUS1, bitrate);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = new StringBuilder(256);
    PCANBasic.GetErrorText(result, 0, strMsg);
    MessageBox.Show(strMsg.ToString());
}
else
    MessageBox.Show("PCAN-USB Pro FD (Ch-1) was initialized");

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

C++/CLR:

String^ bitrate;
TPCANStatus result;
StringBuilder^ strMsg;

// 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 = PCANBasic::InitializeFD(PCANBasic::PCAN_USBBUS1, bitrate);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    strMsg = gcnew StringBuilder(256);
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(strMsg->ToString());
}
else
    MessageBox::Show("PCAN-USB Pro FD (Ch-1) was initialized");

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

Visual Basic:

Dim bitrate As String
Dim result As TPCANStatus
Dim strMsg As StringBuilder

' 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 = PCANBasic.InitializeFD(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 StringBuilder(256)
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(strMsg.ToString)
Else
    MessageBox.Show("PCAN-USB Pro FD (Ch-1) was initialized")
End If

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

Pascal OO:

var
 bitrate: String;
 result : TPCANStatus;
 strMsg: array [0..256] of Char;
begin
    // 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 := TPCANBasic.InitializeFD(TPCANBasic.PCAN_USBBUS1, bitrate);
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
        MessageBox(0,'PCAN-USB Pro FD (Ch-1) was initialized','Success', MB_OK);

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

Python:

# 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
#
objPCAN = PCANBasic()
result = objPCAN.InitializeFD(PCAN_USBBUS1, bitrate)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print result[1]
else:
    print "PCAN-USB Pro FD (Ch-1) was initialized"

# All initialized channels are released
#
objPCAN.Uninitialize(PCAN_NONEBUS)