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

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/downloads.

[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().

Feedback