Developer Blog

13/02/2017 by Magnus Carlsson

Writer formats and properties

This is the first post in a 3-part series about using the Converter Library (kvlclib) in CANlib SDK:

  1. Writer formats and properties (1 of 3)
  2. Converting to plain ASCII (2 of 3)
  3. Special converter conditions (3 of 3)

The converter included in the Kvaser Memorator Config Tool is also available as a separate converter library called kvlclib. If you have used the “Extract and convert files” wizard in Kvaser Memorator Config Tool, you have already been accessing the kvlclib and seen what it can do.

writer formats1

Figure 1: Starting “Extract and convert files” wizard from the menu.

In this article we take a look at how to use the Kvaser Converter Library, kvlclib, from Python using version 1.7 of the canlib package. The latest version of both the Python canlib package and the Kvaser CANlib SDK can be downloaded from www.kvaser.com/download.

The converter library has two functions, kvlclib.writer_formats and kvlclib.reader_formats, that can be used to list all supported formats.

Our first program uses these two functions to print all supported formats.

# 01_list_kvlclib_formats.py
from canlib import kvlclib

print("Supported Writer formats:")
print("  Id   Name  (Extension),  Description\n" + '=' * 50)
for fmt in kvlclib.writer_formats():
    print(fmt)

print("\nSupported Reader formats:")
print("  Id   Name  (Extension),  Description\n" + '=' * 50)
for fmt in kvlclib.reader_formats():
    print(fmt)

Running our code gives as the result a list1 of all the supported writer (i.e. output) and reader (i.e. input) formats.

Supported Writer formats:
  Id   Name  (Extension),  Description
==================================================
   4: CSV Frame (.csv) Reader , CAN frames in CSV format
 100: CSV Signal (.csv) Reader , Selected signals in CSV format
 200: CSV CCP/XCP (.csv) Reader , CCP/XCP calibration in CSV format
 102: Matlab (.mat) Reader , Selected signals in Matlab format for ATI Vision
   1: KME 2.4 (.kme) Reader , Kvaser binary format (KME 2.4) - used for Vector CANalyzer
   2: KME 2.5 (.kme25) Reader , Kvaser binary format (KME 2.5)
   7: KME 4.0 (.kme40) Reader , Kvaser binary format (KME 4.0)
   9: KME 5.0 (.kme50) Reader , Kvaser binary format (KME 5.0)
   5: Plain text (.txt) Reader , CAN frames in plain text format
 105: FAMOS (.dat) Reader , Selected signals in FAMOS format
 201: FAMOS CCP/XCP (.dat) Reader , CCP/XCP calibration in FAMOS format
   3: Vector ASCII (.asc) Reader , CAN frames in Vector ASCII format
   8: Vector BLF (.blf) Reader , CAN frames in Vector BLF format
1000: Debug output (.dbg) Reader , RAW Debug output
 101: MDF (.log) Reader , CAN frames in Vector Mdf
 107: MDF v4.1 (.mf4) Reader , CAN frames in MDF v4.1 for Vector CANalyzer
 106: MDF Signal (.mdf) Reader , Selected signals in MDF format for Vector CANalyzer
 108: MDF v4.1 Signal (.mf4) Reader , Selected signals in MDF v4.1 for Vector CANalyzer
 103: ASCII J1587 (.asc) Reader , Vector ASCII J1587

Supported Reader formats:
  Id   Name  (Extension),  Description
==================================================
   1: KME 2.4 (.mke) Reader , Kvaser binary format (KME 2.4)
   2: KME 2.5 (.kme25) Reader , Kvaser binary format (KME 2.5)
   7: KME 4.0 (.kme40) Reader , Kvaser binary format (KME 4.0)
   9: KME 5.0 (.kme50) Reader , Kvaser binary format (KME 5.0)
 101: MDF (.log) Reader , CAN frames in Vector Mdf
 107: MDF v4.1 (.mf4) Reader , CAN frames in MDF v4.1 for Vector CANalyzer
   5: Plain text (.txt) Reader , CAN frames in plain text format
   3: Vector ASCII (.asc) Reader , CAN frames in Vector ASCII format
   4: CSV Frame (.csv) Reader , CAN frames in CSV format
   6: Kvaser Memorator (.memo) Reader , Kvaser Memorator

Each writer format has a number of properties that controls how the resulting file should look, and by using the function isPropertySupported(), we can find out if an individual property is supported by a specific format. E.g. the property ATTACHMENTS indicates if we can attach files to the output file or not.

# 02_print_sample_properties.py
from canlib import kvlclib

# output format
fmt = kvlclib.WriterFormat(kvlclib.FileFormat.PLAIN_ASC)

# check if format supports the CHANNEL_MASK property
if fmt.isPropertySupported(kvlclib.Property.CHANNEL_MASK):

    # print default value (in binary format)
    print("Default value for CHANNEL_MASK is %s" %
          bin(fmt.getPropertyDefault(kvlclib.Property.CHANNEL_MASK)))

Running the code shows us that the writer property CHANNEL_MASK is supported by the writer format PLAIN_ASC, and that the default value is 0x1F (0b11111 in binary format) which means that the five first channels (channel 0 to channel 4) will be included when writing with this formatter.2

Default value for CHANNEL_MASK is 0b11111

Once we have instantiated a writer format, the default value for an individual property can be examined using getPropertyDefault(). To actually set and read a property, we need to create a converter using kvlclib.Converter(), and then most (but not all) writer properties may be read and written using getProperty() and setProperty().3

# 03_set_get_sample_properties.py
from canlib import kvlclib


# use plain ASCII output format
fmt = kvlclib.WriterFormat(kvlclib.FileFormat.PLAIN_ASC)

# set resulting output file name taking advantage of the extension
# defined in the format.
outfile = 'myresult.' + fmt.extension

# create converter
cnv = kvlclib.Converter(outfile, fmt)

# check if converter supports the CHANNEL_MASK property
if cnv.format.isPropertySupported(kvlclib.Property.CHANNEL_MASK):

    # get the current (default) value (in binary format)
    value = bin(cnv.getProperty(kvlclib.Property.CHANNEL_MASK))
    print('Current value for CHANNEL_MASK is:', value )

    # set a new value
    cnv.setProperty(kvlclib.Property.CHANNEL_MASK, 1)
    value = bin(cnv.getProperty(kvlclib.Property.CHANNEL_MASK))
    print('New value for CHANNEL_MASK is:', value)

    # it is also possible to specifically read the default value from the
    # converter
    value = bin(cnv.format.getPropertyDefault(kvlclib.Property.CHANNEL_MASK))
    print('Default value for CHANNEL_MASK is:', value)

Running the code gives us the following output:

Current value for CHANNEL_MASK is: 0b11111
New value for CHANNEL_MASK is: 0b1
Default value for CHANNEL_MASK is: 0b11111
This ends the first part, where we have looked into writer formats and properties. In the next blog article, we will do our first actual conversion.

Footnotes

1 Due to implementation details, the result is returned in an arbitrary order.

2 The property CHANNEL_MASK is set to a bitmask of the channels that should be used during conversion.

3 Beside ATTACHMENTS, the properties SIGNAL_BASED and SHOW_SIGNAL_SELECT are only usable with the function isPropertySupported().



This article has been updated. To view the original, click on the box below.

Original Article

This blog uses now deprecated functions, see blog “Improved API in Python canlib v1.5” for more information.

This is the first post in a 3-part series about using the Converter Library (kvlclib) in CANlib SDK:

  1. Writer formats and properties (1 of 3)
  2. Converting to plain ASCII (2 of 3)
  3. Special converter conditions (3 of 3)

The converter included in the Kvaser Memorator Config Tool is released as a separate converter library called kvlclib in CANlib SDK v5.19.[1] If you have used the Extract and convert files wizard in Kvaser Memorator Config Tool, you have already been accessing the Converter Library and seen what it can do.

writer formats1

Figure 1: Starting “Extract and convert files” wizard from the menu.

In this blog article we take a look at how to use the converter library from Python. The Python wrapper for the Converter Library (kvlclib) is included in the CANlib SDK as well as available as a separate download.[2] For a short introduction on how to install and use the Python package, take a look at the blog article.

The converter library has two C functions, kvlcGetFirstWriterFormat() and kvlcGetNextWriterFormat(), that can be used to list all supported converter formats.[3] These two functions are wrapped in the Python code as kvlc.getFirstWriterFormat() and kvlc.getNextWriterFormat().[4]

Our first program in Listing 1 uses these two functions to print all supported formats.

import canlib.kvlclib as kvlc

print("Supported formats:")
print(" Id Name (Extension), Description\n" + '=' * 50)

# Ask kvlclib for the first supported writer format
id = kvlc.WriterFormat.getFirstWriterFormat()
while True:
    fmt = kvlc.WriterFormat(id)
    print(str(fmt)) 11

    # Ask kvlclib for the next supported writer format
    id = kvlc.WriterFormat.getNextWriterFormat(fmt.id_)

    # If no more writer formats were supported, we get id 0.
    if id == 0:
    break

Listing 1: Print supported formats using the Converter Library.

Running our code from Listing 1 gives us a list of all the supported writer (i.e. output) formats available:[5]

Supported formats:
  Id   Name  (Extension),  Description
==================================================
   4: CSV Frame (.csv), CAN frames in CSV format
 100: CSV Signal (.csv), Selected signals in CSV format
 200: CSV CCP/XCP (.csv), CCP/XCP calibration in CSV format
 102: Matlab (.mat), Selected signals in Matlab format for ATI Vision
   1: KME 2.4 (.kme), Kvaser binary format (KME 2.4) - used for Vector CANalyzer
   2: KME 2.5 (.kme25), Kvaser binary format (KME 2.5)
   7: KME 4.0 (.kme40), Kvaser binary format (KME 4.0)
   9: KME 5.0 (.kme50), Kvaser binary format (KME 5.0)
   5: Plain text (.txt), CAN frames in plain text format
 105: FAMOS (.dat), Selected signals in FAMOS format
 201: FAMOS CCP/XCP (.dat), CCP/XCP calibration in FAMOS format
   3: Vector ASCII (.asc), CAN frames in Vector ASCII format
   8: Vector BLF (.blf), CAN frames in Vector BLF format
1000: Debug output (.dbg), RAW Debug output
 101: MDF (.log), CAN frames in Vector Mdf
 107: MDF v4.1 (.mf4), CAN frames in MDF v4.1 for Vector CANalyzer
 106: MDF Signal (.mdf), Selected signals in MDF format for Vector CANalyzer
 108: MDF v4.1 Signal (.mf4), Selected signals in MDF v4.1 for Vector CANalyzer
 103: ASCII J1587 (.asc), Vector ASCII J1587

Each writer format has a number of properties and using the function kvlcIsPropertySupported(), we can find out if an individual property is supported by a specific writer format. E.g. the property KVLC_PROPERTY_ATTACHMENTS indicates if we can attach files to the output file or not.

import canlib.kvlclib as kvlc

# Set output format
fmt = kvlc.WriterFormat(kvlc.FILE_FORMAT_PLAIN_ASC)

# check if format supports KVLC_PROPERTY_ATTACHMENTS
if fmt.isPropertySupported(kvlc.PROPERTY_ATTACHMENTS):
    print("PROPERTY_ATTACHMENTS is supported")
else:
    print("PROPERTY_ATTACHMENTS is not supported")

Listing 2: Sample code to check presence of writer format property.

Running the code in Listing 2 shows us that the writer property KVLC_PROPERTY_ATTACHMENTS is not supported by the writer format KVLC_FILE_FORMAT_PLAIN_ASC.

PROPERTY_ATTACHMENTS is not supported

Once we have instantiated a converter, most (but not all) writer properties may be read and written using kvlcSetProperty() and kvlcGetProperty().[6] The default value for an individual property can also be examined using kvlcGetWriterPropertyDefault(). E.g. the property KVLC_PROPERTY_CHANNEL_MASK is set to a bitmask of the channels that should be used during conversion.

import canlib.kvlclib as kvlc

# set output format
fmt = kvlc.WriterFormat(kvlc.FILE_FORMAT_PLAIN_ASC)

# set resulting output filename taking advantage of the extension defined in
# the format.
outfile = "myresult." + fmt.extension
# create converter
kc = kvlc.Kvlclib(outfile, fmt)

# check if converter supports KVLC_PROPERTY_CHANNEL_MASK
if kc.isPropertySupported(kvlc.PROPERTY_CHANNEL_MASK):

    # print the current (default) value (in binary format)
    print("Original value for CHANNEL_MASK is %s" % bin(kc.getProperty(kvlc.PROPERTY_CHANNEL_MASK)))

    # set a new value
    kc.setProperty(kvlc.PROPERTY_CHANNEL_MASK, 1)
    # print the current value
    print("New value for CHANNEL_MASK is %s" % bin(kc.getProperty(kvlc.PROPERTY_CHANNEL_MASK)))

    # print default value (in binary format)
    print("Default value for CHANNEL_MASK is %s" % bin(kc.getPropertyDefault(kvlc.PROPERTY_CHANNEL_MASK)))

Listing 3: Sample code to read and write converter properties.

Running the code in Listing 3 gives us the following output:

Original value for CHANNEL_MASK is 0b11
New value for CHANNEL_MASK is 0b1
Default value for CHANNEL_MASK is 0b11

This blog article looked into writer formats and properties, next time we will do our first actual conversion.


Footnotes

[1] The converter library, kvlclib, is currently only available on Windows OS.

[2] Both the CANlib SDK and the separate download of the Python package is available from www.kvaser.com/download.

[3] I will try and consistently write the C format of function names and definitions in the running text in these blog articles.
[4] In our code, we import the converter wrapper library using import canlib.kvlclib as kvlc which makes this simple naming scheme work.

[5] Due to implementation details, the result is returned in a arbitrary order.

[6] Beside KVLC_PROPERTY_ATTACHMENTS, the properties KVLC_PROPERTY_SIGNAL_BASED and KVLC_PROPERTY_SHOW_SIGNAL_SELECT are only usable with the function kvlcIsPropertySupported().

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.