ApiGetStatus Method

Retrieves the current status of the CAN controller of the hardware represented by a PCAN Channel.

Definition

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

public static PcanStatus GetStatus(
	PcanChannel channel
)

Public Shared Function GetStatus ( 
	channel As PcanChannel
) As PcanStatus

C++

public:
static PcanStatus GetStatus(
	PcanChannel channel
)

Parameters

channel PcanChannel: The handle of a PCAN Channel.

Return Value

PcanStatus

OK is returned if the CAN controller of the hardware represented by the given PCAN Channel is in a normal state. The typical errors in case of failure are:

Initialize: Indicates that the channel cannot be terminated because it was not found in the list of reserved Channels of the calling application.
IllegalHardwareHandle: Indicates that the hardware represented by channel was removed or deactivated.
IllegalHandle: Indicates that the channel contains an invalid value.
BusHeavyIndicates a bus error within the CAN controller of the hardware represented by the given PCAN Channel. An error counter reached the 'heavy' limit.
BusLightIndicates a bus error within the CAN controller of the hardware represented by the given PCAN Channel. An error counter reached the 'light' limit.
BusPassiveIndicates a bus error within the CAN controller of the hardware represented by the given PCAN Channel. The CAN controller is in error passive state.
BusWarningIndicates a bus error within the CAN controller of the hardware represented by the given PCAN Channel. An error counter reached the 'warning' limit.
BusOffIndicates a bus error within the CAN controller of the hardware represented by the given PCAN Channel. The CAN controller is in bus-off state.

Remarks

When the hardware status is bus-off, an application cannot communicate anymore. Consider using the BusOffAutoReset parameter, which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset bus errors like BusOff, BusPassive, and others:

Performing an uninitialize / initialize cycle: This causes a hardware reset, but only when no more clients are connected to that channel.
Using the parameter HardResetStatus: It instructs this method to explicitly perform a hardware reset regardless of whether other clients are connected to that channel.

Example

The following example shows the use of the GetStatus method using the USB interface (first PCAN-USB hardware). A Channel is initialized and used to send 255 messages in about 4 seconds. After each sending the status of the CAN controller is checked.

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.

private static void GetStatusExample()
{            
    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 on connection is shown.
        //
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.");

        // Start a thread for a writing messages and wait until it is finished
        //
        var worker = new System.Threading.Thread(DoWriteProcess);
        worker.Start(channel);
        worker.Join();

        // 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.");
    }

}

private static void DoWriteProcess(object channelToUse)
{
    // Channel to use for message reading
    //
    PcanChannel channel = (PcanChannel)channelToUse;
    PcanStatus result;

    // Message to be send
    PcanMessage toSend = new PcanMessage(0x100, MessageType.Standard, 1, new byte[1]);            

    // 255 messages are send, using the first data byte as a message counter
    //
    for (byte i=0; i < byte.MaxValue; i++)
    {
        // Send the message
        //
        toSend.Data[0] = (byte)(i + 1);
        result = Api.Write(channel, toSend);

        // Check for any unexpected error
        //
        if ((result == PcanStatus.Initialize) || (result == PcanStatus.IllegalHandle) 
            || (result == PcanStatus.InvalidOperation) || (result == PcanStatus.InvalidValue))
        {
            // An unexpected error occurred
            //
            Api.GetErrorText(result, out var errorText);
            Console.WriteLine(errorText);
            break;
        }

        // The status of the Channel is checked and outputted 
        // 
        result = Api.GetStatus(channel);
        switch (result)
        {
            case PcanStatus.BusLight:
                Console.WriteLine($"An error counter of the Channel {channel} has reached the bus-light limit by sending the message number {i + 1}.");
                break;
            case PcanStatus.BusHeavy:
                Console.WriteLine($"An error counter of the Channel {channel} has reached the bus-heavy limit by sending the message number {i + 1}.");
                break;
            case PcanStatus.BusOff:
                Console.WriteLine($"An error counter of the Channel {channel} has reached the bus-off state by sending the message number {i + 1}.");
                break;
            case PcanStatus.OK:
                Console.WriteLine($"Status of Channel {channel} after sending message {i + 1} is 'OK'.");
                break;
            default:
                // An unexpected error occurred
                //
                Api.GetErrorText(result, out var errorText);
                Console.WriteLine(errorText);
                break;
        }

        // Wait some milliseconds to slow down things 
        //
        System.Threading.Thread.Sleep(15);
    }
}

Public Sub GetStatusExample()
    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 = Nothing
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        ' A success message on connection is shown.
        '
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.")

        ' Start a thread for a writing messages and wait until it is finished
        '
        Dim worker = New System.Threading.Thread(New System.Threading.ParameterizedThreadStart(AddressOf DoWriteProcess))
        worker.Start(channel)
        worker.Join()

        ' 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 = Nothing
            Api.GetErrorText(result, errorText)
            Console.WriteLine(errorText)
        Else
            Console.WriteLine($"The hardware represented by the handle {channel} was successfully finalized.")
        End If
    End If
End Sub

Private Sub DoWriteProcess(channelToUse As Object)
    Dim channel As PcanChannel = CType(channelToUse, PcanChannel)
    Dim result As PcanStatus
    Dim errorText = Nothing

    ' Channel to use for message reading
    '
    Dim toSend As PcanMessage = New PcanMessage(&H100, MessageType.Standard, 1, New Byte(0) {})

    ' 255 messages are send, using the first data byte as a message counter
    '
    For i As Byte = 0 To Byte.MaxValue - 1
        ' Send the message
        '
        toSend.Data(0) = CByte((i + 1))
        result = Api.Write(channel, toSend)

        ' Check for any unexpected error
        '
        If (result = PcanStatus.Initialize) OrElse (result = PcanStatus.IllegalHandle) OrElse
            (result = PcanStatus.InvalidOperation) OrElse (result = PcanStatus.InvalidValue) Then
            ' An unexpected error occurred
            '
            Api.GetErrorText(result, errorText)
            Console.WriteLine(errorText)
            Exit For
        End If

        ' The status of the Channel is checked and outputted 
        '
        result = Api.GetStatus(channel)

        Select Case result
            Case PcanStatus.BusLight
                Console.WriteLine($"An error counter of the Channel {channel} has reached the bus-light limit by sending the message number {i + 1}.")
            Case PcanStatus.BusHeavy
                Console.WriteLine($"An error counter of the Channel {channel} has reached the bus-heavy limit by sending the message number {i + 1}.")
            Case PcanStatus.BusOff
                Console.WriteLine($"An error counter of the Channel {channel} has reached the bus-off state by sending the message number {i + 1}.")
            Case PcanStatus.OK
                Console.WriteLine($"Status of Channel {channel} after sending message {i + 1} is 'OK'.")
            Case Else
                ' An unexpected error occurred
                '
                Api.GetErrorText(result, errorText)
                Console.WriteLine(errorText)
        End Select

        ' Wait some milliseconds to slow down things
        '
        System.Threading.Thread.Sleep(15)
    Next
End Sub

C++

void GetStatusExample()
{
    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 on connection is shown.
        //
        Console::WriteLine("The hardware represented by the handle {0} was successfully initialized.", channel);

        // Start a thread for a writing messages and wait until it is finished
        //
        System::Threading::Thread^ worker = gcnew System::Threading::Thread(gcnew System::Threading::ParameterizedThreadStart(DoWriteProcess));
        worker->Start(channel);
        worker->Join();

        // 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);
    }

}

void DoWriteProcess(Object^ channelToUse)
{
    // Channel to use for message reading
    //
    PcanChannel channel = (PcanChannel)channelToUse;
    PcanStatus result;
    String^ errorText;

    // Message to be send
    PcanMessage^ toSend = gcnew PcanMessage(0x100, MessageType::Standard, 1, gcnew array<Byte>(1), false);

    // 255 messages are send, using the first data byte as a message counter
    //
    for (Byte i = 0; i < Byte::MaxValue; i++)
    {
        // Send the message
        //
        toSend->Data[0] = (Byte)(i + 1);
        result = Api::Write(channel, toSend);

        // Check for any unexpected error
        //
        if ((result == PcanStatus::Initialize) || (result == PcanStatus::IllegalHandle)
            || (result == PcanStatus::InvalidOperation) || (result == PcanStatus::InvalidValue))
        {
            // An unexpected error occurred
            //
            Api::GetErrorText(result, errorText);
            Console::WriteLine(errorText);
            break;
        }

        // The status of the Channel is checked and outputted 
        // 
        result = Api::GetStatus(channel);
        switch (result)
        {
        case PcanStatus::BusLight:
            Console::WriteLine("An error counter of the Channel {0} has reached the bus-light limit by sending the message number {1}.", channel, i + 1);
            break;
        case PcanStatus::BusHeavy:
            Console::WriteLine("An error counter of the Channel {0} has reached the bus-heavy limit by sending the message number {1}.", channel, i + 1);
            break;
        case PcanStatus::BusOff:
            Console::WriteLine("An error counter of the Channel {0} has reached the bus-off state by sending the message number {1}.", channel, i + 1);
            break;
        case PcanStatus::OK:
            Console::WriteLine("Status of Channel {0} after sending message {1} is 'OK'.", channel, i + 1);
            break;
        default:
            // An unexpected error occurred
            //
            Api::GetErrorText(result, errorText);
            Console::WriteLine(errorText);
            break;
        }

        // Wait some milliseconds to slow down things 
        //
        System::Threading::Thread::Sleep(15);
    }
}

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.