Developer Blog

11/10/2016 by 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 “-“.

ccNameKvHwEmpty
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.

ccNameKvHwBackbone
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

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

2 Writing Custom Channel Name is not supported under Linux.

Author Image

Magnus Carlsson

Magnus Carlsson is a Software Developer for Kvaser AB and has developed firmware and software for Kvaser products since 2007. He has also written a number of articles for Kvaser’s Developer Blog dealing with the popular Python language.