This is the first post in a 3-part series about using the Converter Library (kvlclib) in CANlib SDK:
- Writer formats and properties (1 of 3)
- Converting to plain ASCII (2 of 3)
- Special converter conditions (3 of 3)
Writer formats and properties
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.
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 MemoratorEach 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: 0b11111This 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
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().
Original Article
This is the first post in a 3-part series about using the Converter Library (kvlclib) in CANlib SDK:
- Writer formats and properties (1 of 3)
- Converting to plain ASCII (2 of 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.
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 J1587Each 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 supportedOnce 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 0b11This 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().
