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.
Example:
         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"
echo

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;

  canInitializeLibrary();

  stat = canGetNumberOfChannels(&chanCount);
  Check("canGetNumberOfChannels", stat);
  if (chanCount<0 || chanCount > 1000) {
    printf("ChannelCount = %d but I don't believe it.\n", chanCount);
    exit(1);
  } 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 = ''

To erase the Custom Channel Name, you just write a new one.

Hopefully this short overview has given you some insight in order to take advantage of the Custom Channel Name feature.

Bug reports, contributions, suggestions for improvements, and similar things are much appreciated and can be sent by e-mail to support@kvaser.com.

Footnotes

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

2Writing Custom Channel Name is not supported under Linux.

Feedback