Magnus Carlsson

Custom Channel Name

One of the new features in CANlib v5.17 is the addition of Custom Channel Name. On supported devices1, this gives you an opportunity to identify a specific device’s channel. When starting Kvaser Hardware, a new row is shown as can be seen in Figure 1. We have not yet assigned any Custom Channel Name, and thus Kvaser Hardware shows “-“.

Figure 1: Kvaser Hardware is now showing the Custom Channel Name.

To assign a new Custom Channel Name, the tool setchannelname.exe is used2. This tool can be found in the Bin directory where you installed the CANlib SDK. I installed CANlib SDK in D:\CanlibSDK\CanlibSDK_5.17 so the
tool is placed at D:\CanlibSDK\CanlibSDK_5.17\Bin\setchannelname.exe. Running the tool with the -h argument prints the usage help.

d:\>D:\CanlibSDK\CanlibSDK_5.17\Bin\setchannelname.exe --help
Channel naming utility for Kvaser AB products.
-h         --help    | Print this information.
-channel=X           | CANlib channel index
-name="ABc de"       | Name for selected channel.
-v                   | Verbose mode.
         setchannelname -channel=4 -name="Test unit 1"

So let us set a Custom Channel Name for device channel 1. As can be seen in Figure 1, device channel 1 is accessible using CANlib Channel 0. Let us set this Custom Channel Name to “Backbone 2”.

D:\CanlibSDK\CanlibSDK_5.17\Bin\setchannelname.exe -channel=0 -name="Backbone 2"

The maximum length of the Custom Channel Name varies between devices, but at least 24 bytes (including the null terminator) is available.

Figure 2: The Custom Channel Name is now set to “Backbone 2”.

In order to read the Custom Channel Name in CANlib we call the function canGetChannelData() using canCHANNELDATA_CUST_CHANNEL_NAME. See Line 39 in Listing 1 below.

#include <stdio.h>
#include <canlib.h>

void Check(char* id, canStatus stat)
  if (stat != canOK) {
    char buf[50];
    buf[0] = '\0';
    canGetErrorText(stat, buf, sizeof(buf));
    printf("%s: failed, stat=%d (%s)\n", id, (int)stat, buf);

void main(int argc, char* argv[])
  canStatus stat;
  int i, chanCount;


  stat = canGetNumberOfChannels(&chanCount);
  Check("canGetNumberOfChannels", stat);
  if (chanCount<0 || chanCount > 1000) {
    printf("ChannelCount = %d but I don't believe it.\n", chanCount);
  } else {
    printf("%d channels.\n", chanCount);

  for (i=0; i<chanCount; i++) {
    char name[64];

    printf("== Channel %d ===============================\n", i);

    stat = canGetChannelData(i, canCHANNELDATA_CHANNEL_NAME, name, sizeof(name));
    Check("canCHANNELDATA_CHANNEL_NAME", stat);
    printf("Channel name =          '%s'\n", name);

    stat = canGetChannelData(i, canCHANNELDATA_CUST_CHANNEL_NAME, name, sizeof(name));
    if (stat != canOk) {
      name[0] = '\0';
    printf("Custom Channel name =   '%s'\n", name);

Listing 1: A short example program that reads the Custom Channel Name.

Running the program above gives the following output:

4 channels.
== Channel 0 ===============================
Channel name = 'Kvaser Memorator 2xHS v2 #1 (Channel 0)'
Custom Channel name = 'Backbone 2'
== Channel 1 ===============================
Channel name = 'Kvaser Memorator 2xHS v2 #1 (Channel 1)'
Custom Channel name = ''
== Channel 2 ===============================
Channel name = 'Virtual #0 (Channel 0)'
canCHANNELDATA_CUST_CHANNEL_NAME: failed, stat=-32 (Not implemented)
Custom Channel name = ''
== Channel 3 ===============================
Channel name = 'Virtual #0 (Channel 1)'
canCHANNELDATA_CUST_CHANNEL_NAME: failed, stat=-32 (Not implemented)
Custom Channel name = ''


1All newer devices such as the Kvaser Memorator 2xHS v2 supports Custom Channel Name.

2Writing Custom Channel Name is not supported under Linux.