How-To's and Q&A's

There are some new possibilities to write code for CAN communication when using PCAN-Basic.NET. The most asked questions are answered next.

1. What is PCAN-Basic.NET?

2. I have already a project using a PCAN-Basic header file. Do I have to re-write everything?

3. Do I need to learn how to use a new API?

4. Which benefits offers PCAN-Basic.NET in comparison to the header files?

5. How do I get the PCAN-Basic.NET assembly?

6. Are the native libraries delivered within the NuGet package?

7. How do I install the assembly using Visual Studio?

8. How do I install the assembly using dotnet-CLI (Visual Studio Code)?

9. How can I use the assembly without changing old .NET code?

10. How can I get notified on new received CAN messages?

11. How can I send CAN messages periodically?

12. Can I mix old and new PCAN-Basic code in a project?

13. What can I use more than one queue for?

14. How many reception queues are used in PCAN-Basic.NET?

15. Does the filtering system of the "Worker" class have the same SJA1000 filter limitations?

16. Does the class “Worker” restring the filter in the CAN controller when setting different filters?

PCAN-Basic.NET is a .NET library compiled targeting the .NET Standard 2.0. It is the new way to access the native library PCAN-Basic from the managed Microsoft programming environment. Using PCAN-Basic header files (PCANBasic.cs/PCANBasic.vb/PCANBasicCLR.h) has been deprecated.

No. PCAN-Basic.NET has a Peak.Can.Basic.BackwardCompatibility namespace. Using this, the code remains unchanged. API Calls are internally redirected.

Not really. PCAN-Basic.NET offers a similar API usage as with the old header files (PCANBasic.cs/PCANBasic.vb/PCANBasicCLR.h). This was though enhanced, i.e., calls were simplified, and new data types were created, making it use easier and more intuitive. The way to use and access the API is the same, i.e., using a static class, Api, for accessing the available API functionality.

Added to this traditional way to access and work with the PCAN-Basic library in the .NET environment, the PCAN-Basic.NET assembly offers also a new way to do CAN communication. Using the new Worker class, you can more easily read/write CAN messages from/to the CAN bus.

• The Api class, the re-worked API-access class (replaces the PCANBasic class), is more comfortable to use.

  1. Using StringBuilder object for getting string parameters is not needed anymore.

  2. Passing buffer size on calls to GetValue/SetValue is not needed anymore.

  3. The new type DataBytes manages the data field for any CAN or CAN FD message. It is no more needed to initialize the Data field of a message after creating it.

  4. The Api class makes use of function overloading. Instead of having two sets of functions for CAN and CAN-FD, for instance Initialize and InitializeFD, you have only one function, Initialize that can be used for both purposes.

  5. New data types were created for API values that were defined as standard data types. This makes the code more readable and understandable. For example, there is a new ParameterValue class, that encapsulates valid values for PCAN-Basic parameters used with the GetValue/SetValue methods.

• The assembly introduces a more comfortable way to do CAN communication using the new Worker class. Following features are supported:

  1. Automatic reading of CAN messages using event notification. An application can register to the MessageAvailable event to get notified on the reception of new CAN messages.

  2. Automatic writing of CAN message using a broadcast table, having an accuracy of up to one millisecond. Operations like having a "keep-alive" message can be easily done.

  3. A more exhaustive filtering system. Message filtering allows mixing different filter criteria like:

     • Single standard CAN ID.

     • Single extended CAN ID.

     • Standard CAN ID range.

     • Extended CAN ID range.

     • Standard mask and code.

     • Extended mask and code.

     • Filtering of CAN message type (RTR, Error Frame, Data, Status, etc.).

     • Each filter criterion can be configured to operate as "include" or "exclude" filter.

  4. Handling of several reception queues. An application can use a queue and its messages for dedicated/separated tasks.

  5. Filtering is implemented for a queue, not for the object, so that messages can be automatically sorted in different queues on reception time.

• The assembly contains additional useful classes like the PerformanceTimer, useful for operations that require a fast reaction time (up to one millisecond accuracy).

• The code becomes portable: since .NET Standard 2.0 is used, the same code can be used for .Net-Core, .NET Framework, and others.

• The code becomes multi-platform: Since PCAN-Basic and .NET (C#) are available for Linux and Windows, applications written using the PCAN-Basic.NET assembly can compile and run on both systems.

The assembly is delivered as a NuGet package (.nupkg). This file can be installed directly from NuGet.org (online installation). Additionally, it is also contained in the download package of the PCAN-Basic API (local installation).

No. The underlying native library (“PCANBasic.dll” on Windows and “libpcanbasic.so” on Linux) must be present and reachable on the system in which the assembly is intended to be used.

Please check the following page: Install and use a package in Visual Studio.

To look for packages locally, it is needed to configure a source for the NuGet Manager. For this, see the following page: Install and manage packages in Visual Studio using the NuGet Package Manager.

Please check the following page: Install and use a package using the dotnet CLI.

To look for packages locally, it is needed to configure a source for the NuGet Manager. For this, see the following page: dotnet nuget add source

The PCAN-Basic.NET assembly contains a Peak.Can.Basic.BackwardCompatibility namespace for this case. just follow these steps to include and use the assembly in a .NET project that was written using a PCAN-Basic header file (PCANBasic.cs/PCANBasic.vb/PCANBasicCLR.h):

1. Remove the PCAN-Basic header file from your project.

2. Install the PCANBasic.NET NuGet package.

3. Look for the using statement in your code “Peak.Can.Basic” and change it to be Peak.Can.Basic.BackwardCompatibility

With the class Worker you can be notified on message reception. After creating an object of this type, you can register to its MessageAvailable event to get informed that a message was received. After connecting an object of type Worker, reading is started automatically, if this standard configuration was not changed. The event is fired within its own thread, so synchronization is needed when interacting with UI elements.

// Create a "Worker" object
//
Worker myWorker = new Worker();

// Register for the event “MesasgeAvailable”. Configure this event
// handler to dequeue messages
//
myWorker.MessageAvailable += OnMessageAvailable;

// Activate the connection of the “Worker” object
myWorker.Start();

// Event handler
//
...
private static void OnMessageAvailable(object sender, MessageAvailableEventArgs e)
{
    PcanMessage msg;
    ulong timestamp;
    while (myWorker.Dequeue(out msg, out timestamp))
    ProcessYourMessage(msg, timestamp);
}
...

' Create a "Worker" object using the "WithEvents" modifier
'
Dim WithEvents myWorker As Worker = New Worker()

' Register for the event “MesasgeAvailable”. Configure this event
' handler to dequeue messages
'
...
Private Sub HandlerMessages() Handles myWorker.MessageAvailable
Dim msg As PcanMessage
Dim timestamp As ULong

While (myWorker.Dequeue(msg, timestamp))
ProcessYourMessage(msg, timestamp)
End While
End Sub
...

' Activate the connection of the “Worker” object
'
myWorker.Start()

// Create a "Worker" object
//
Worker^ myWorker = gcnew Worker();

// Register for the event “MesasgeAvailable”.Configure this event
// handler to dequeue messages
//
myWorker->MessageAvailable += gcnew System::EventHandler<MessageAvailableEventArgs^>(&OnMessageAvailable);

// Activate the connection of the “Worker” object
//
myWorker->Start(false, false, false);            

// Event handler
...
void OnMessageAvailable(System::Object^ sender, Peak::Can::Basic::MessageAvailableEventArgs^ e)
{             
    PcanMessage^ msg;
    UInt64 timestamp;

    while (myWorker->Dequeue(msg, timestamp))
        ProcessYourMessage(msg, timestamp);
}    
...

With the class Worker it is possible to configure up to MaximumBroadcastCount broadcast messages. After creating a Worker object, you can use its method “AddBroadcast” to configure the automatic sending of messages. After connecting the object, broadcasting is started automatically, if this standard configuration was not changed.

// Create a "Worker" object
//
Worker myWorker = new Worker();

// Create a message to broadcast
//
PcanMessage msg = new PcanMessage() 
{ 
    ID = 1, 
    DLC = 8, 
    MsgType = MessageType.Standard, 
    Data = new byte[] { 8, 7, 6, 5, 4, 3, 2, 1 } 
};

// Configure a broadcast (message and send-interval) within the “Worker” object
//
myWorker.AddBroadcast(msg, 250);

// Activate the connection of the “Worker” object
//
myWorker.Start();

' Create a "Worker" object
'
Dim myWorker As Worker = New Worker()

' Create a message to broadcast
'
Dim msg As PcanMessage = New PcanMessage() With
{
    .ID = 1,
    .DLC = 8,
    .MsgType = MessageType.Standard,
    .Data = New Byte() {8, 7, 6, 5, 4, 3, 2, 1}
}

' Configure a broadcast (message and send-interval) within the “Worker” object
'
myWorker.AddBroadcast(msg, 250)

' Activate the connection of the “Worker” object
'
myWorker.Start()

// Create a "Worker" object
//
Worker^ myWorker = gcnew Worker();

// Create a message to broadcast
//
PcanMessage^ msg = gcnew PcanMessage(
    1,
    MessageType::Standard,
    8,
    gcnew array<Byte>{ 8, 7, 6, 5, 4, 3, 2, 1}
);

// Configure a broadcast (message and send-interval) within the “Worker” object
//
myWorker->AddBroadcast(msg, 250);

// Activate the connection of the “Worker” object
//
myWorker->Start(false, false, false);

Yes, it is possible. Note that old code needs the Peak.Can.Basic.BackwardCompatibility namespace to work. To use the new PCAN-Basic features you need the Peak.Can.Basic namespace. To use other utility classes, please use the Peak.Classes.* namespace.

The Worker class reads the underlying, native, reception queue actively. Each message received is passed then to each of the queues managed by this class. Since each queue has its own filter, messages can be sorted out at reception time, for example, you can have one queue for standard messages only, and another for extended messages.

Using the standard interface, the Api class, there is only one reception queue, the one created by the native library, which is also filtered using the old mechanism (SJA1000 filter). When using an object of type Worker on the other hand, there are so many message queues available as stated by the ReceiveQueuesCount field of the Worker class.

Per default only the first queue has a filter configured to pass all messages. The others are configured to discard all messages. Methods for accessing the receive queues are overloaded to assume index 0, when only one queue is used, or to accept the index associated to it as parameter.

No. The queues of the Worker class implement a software filter on top, this is, messages being received by the underlying PCAN-Basic API are passed and checked for the filters of each receive queue. This allows for instance configuring standard and extended filters together, which is not possible using the native API. Received messages that do not match any filter of the active queues are just discarded.

No. The native filter is configured to pass all messages. The actual filtering is done within the reception queues of the Worker class.