Getting started with kvmlib

  • September 16, 2018
  • Magnus Carlsson

This is the first post in a 4-part series about configuring and reading logged data using a Kvaser Memorator 2nd Generation device through kvmlib:

This first post will give an overview on how to configure the Kvaser device using Python. Part two adds some complexity to the configuration, while part three will go deeper and show how to use kvmlib at the C API level. The last part shows how to configure the device while only having access to the removable SD card. Full program listings are available on GitHub.

1.1 Introduction

Configuration of newer Kvaser Memorator devices are normally done using the Kvaser Memomorator Config Tool, which is a Windows GUI tool. But you may also configure these devices programmatically using the Kvaser Memorator library (kvmlib) which is part of the Kvaser CANlib SDK.1

Our device of choice today is the Kvaser Memorator Pro 5xHS2 which runs firmware version 3.113. We will also be using v1.6 of the Python canlib package and v5.23 of the Kvaser CANlib SDK, the latest versions are available from www.kvaser.com/downloads.


1.2 Initialize the SD card

It’s not enough to just format the SD card in our operating system’s file manager, we also need to initialize the SD card using our Kvaser Memorator device. After having inserted the SD card into our Kvaser Memorator device, we connect the Kvaser Memorator device to a free USB port on our computer and run our first bit of code to format the SD card.

# 01_init_sdcard.py
from canlib import EAN
from canlib.device import Device
from canlib import kvmlib

# Find our connected Kvaser Memorator Pro 5xHS with EAN 73-30130-00778-9
ean = EAN('73-30130-00778-9')
dev = Device.find(ean=ean)

# Ask the device for some info, and print that
print(dev.probe_info())

# Open the memorator for configuration using the CANlib channel number we
# found it on. The LED will start a slow "running light" indicating that
# it is opened for configuration.

# We will use a context manager in order to make sure that we correctly
# close the internal memorator handle when we are done.
with kvmlib.openDevice(dev.channel_number()) as memo:
    # Initialize the SD card with default values. The CAN LEDs will flash
    # quickly during disk initialization.
    print('Formatting disk...', end='')
    memo.format_disk()
    print(' done!')

Listing 1: Initializing the SD card inside a Kvaser Memorator device.

When running this we can confirm that our device is indeed running firmware v3.11, and the device is currently connected to canlib channel 0.

CANlib Channel: 0
Card Number   : 0
Device        : Kvaser Memorator Pro 5xHS (channel 0)
Driver Name   : kcany0a
EAN           : 73-30130-00778-9
Firmware      : 3.11.0.557
Serial Number : 1023
Formatting disk... done!

1.3 Create a configuration

Now we have to create a configuration which we do by writing a piece of XML code4. Let us take a simple example that just uses channel 0 and 1. We will set the bit rate on these two channels to 1 Mbit/s and log everything while in silent mode.

<?xml version="1.0" ?>
<!-- loggall.xml -->
<!DOCTYPE KVASER>
<KVASER>
  <VERSION>2.0</VERSION>
  <BINARY_VERSION>6.0</BINARY_VERSION>
  <SETTINGS>
    <MODE fifo_mode="NO" log_all="YES"/>
  </SETTINGS>
  <CAN_BUS>
    <PARAMETERS bitrate="1000000" channel="0" silent="YES" sjw="1"
       tseg1="5" tseg2="2"/>
    <PARAMETERS bitrate="1000000" channel="1" silent="YES" sjw="1"
       tseg1="5" tseg2="2"/>
  </CAN_BUS>
  <TRIGGERBLOCK/>
  <SCRIPTS/>
</KVASER>

Listing 2: Simple XML configuration sample.

The current version of the XML configuration is v2.0 and our device, running v3.11 of the firmware, expects binary (configuration) version 6.0.

In the next article, where we increase the complexity of the configuration, we will look into how to explicitly validate the configuration before trying to download it. For now we just make sure we enter the XML without any errors.


1.4 Download the configuration

We are now almost ready to start logging, we just need to place the configuration on the device. We will do this by reading in the XML file we just created, convert this XML configuration to a binary configuration and download the binary configuration to the device.

# 02_config_device.py
from canlib import EAN, Device
from canlib import kvamemolibxml
from canlib import kvmlib

# Look for our connected Kvaser Memorator Pro 5xHS
# Tip: It is enough to write the last 6 digits.
dev = Device.find(ean=EAN('00778-9'))

# Read in the XML configuration file
with open("logall.xml", 'r') as myfile:
    config_xml = myfile.read()

# Convert the XML configuration to a binary configuration
config_lif = kvamemolibxml.kvaXmlToBuffer(config_xml)

# Open the memorator and write the binary configuration
with kvmlib.openDevice(dev.channel_number()) as memo:
    memo.write_config(config_lif)

Listing 3: Downloading configuration to Kvaser device.

Now we are all set to disconnect our configured device from the computer and instead connect our device to an existing CAN bus and start logging by applying power to the device’s CAN 1 bus connector.


1.5 Read logged messages

After we have logged some messages, we once again connect our Kvaser Memorator device to a free USB port on our computer and read out the result.

# 03_read_logged.py
from canlib import EAN, Device
from canlib import kvmlib

# Connect to our Kvaser Memorator Pro 5xHS with EAN 73-30130-00778-9
# and mount the log area
dev = Device.find(ean=EAN('00778-9'))
memo = kvmlib.openDevice(dev.channel_number(), mount=True)

fileCount = len(memo.log)
print('Found {} file{} on card.'.format(
    fileCount,
    "s" if fileCount > 1 else "")
)

# Loop through all logfiles and write their contents to stdout
for i, logfile in enumerate(memo.log):
    print('Reading file {}:'.format(i))
    print("Logging started at", logfile.start_time.isoformat(' '))

    for event in logfile:
        print(event)

# memo.log.delete_all()   # Optionally, delete all logfiles

# Close the memorator
memo.close()

Listing 4: Read logged messages and print to stdout.

Note that the deletion of log files on line 24 in Listing 4 is commented out so that we may run the script multiple times without the need to redo the logging on the CAN bus.

Found 1 file on card.
Reading file 0:
Logging started at 2018-05-22 11:08:56
*t:             - EAN:73-30130-00778-9  s/n:1023  FW:v3.11.557  LIO:v5.0
 t:   0.236734012  DateTime: 2018-05-22 11:08:56
 t:   0.236734012 Log Trigger Event (type: 0x1, trigno: 0x00, pre-trigger: 0, post-trigger: -1)

 t:   4.453331987  ch:0 f:    2 id: 490 dlc: 2 d:5d d6
 t:   4.453332025  ch:1 f:    2 id: 490 dlc: 2 d:5d d6
 t:   4.453731112  ch:0 f:    2 id: 284 dlc: 2 d:a8 b1
 t:    4.45373115  ch:1 f:    2 id: 284 dlc: 2 d:a8 b1
 t:   4.454201237  ch:0 f:    2 id: 739 dlc: 2 d:7a 4b
 t:   4.454201275  ch:1 f:    2 id: 739 dlc: 2 d:7a 4b
 t:   4.454729362  ch:0 f:    2 id: 622 dlc: 6 d:8d b9 69 8a 98 e1
 t:     4.4547294  ch:1 f:    2 id: 622 dlc: 6 d:8d b9 69 8a 98 e1
 t:   4.455189487  ch:0 f:    2 id: 559 dlc: 1 d:78
 t:   4.455189525  ch:1 f:    2 id: 559 dlc: 1 d:78
 t:   4.455685612  ch:0 f:    2 id: 33a dlc: 1 d:0d
 t:    4.45568565  ch:1 f:    2 id: 33a dlc: 1 d:0d
 t:   4.456254737  ch:0 f:    2 id: 463 dlc: 6 d:14 eb d6 ae ed 46
 t:   4.456254775  ch:1 f:    2 id: 463 dlc: 6 d:14 eb d6 ae ed 46
 t:   4.456754862  ch:0 f:    2 id: 59b dlc: 6 d:7f a9 28 3a f2 5d
 t:     4.4567549  ch:1 f:    2 id: 59b dlc: 6 d:7f a9 28 3a f2 5d
 t:   4.457269987  ch:0 f:    2 id: 103 dlc: 8 d:4e 0d 1a dd 8d b2 19 ab
 t:   4.457270025  ch:1 f:    2 id: 103 dlc: 8 d:4e 0d 1a dd 8d b2 19 ab
 t:  10.220507812  DateTime: 2018-05-22 11:09:06

That’s it for this time. We have now seen how to configure and read back logged data using kvmlib. In the next part, we will branch out and look at adding some complexity to the configuration.


Footnotes

1 For an overview of all the Kvaser SDK libraries, please read the blog post about how to Get more from your hardware with Kvaser SDK libraries.

The product number of Kvaser Memorator Pro 5xHS is 73-30130-00778-9

Firmware for Kvaser Memorator Pro 5xHS is bundled in the Kvaser Firmware Update Tool which can be downloaded here.

The XML configuration format is described in the document Specification of Kvaser Memorator Device configuration XML format, which is available here.



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

Original Article

Original article published March 29, 2016.

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 4-part series about configuring and reading logged data using a Kvaser Memorator 2nd Generation device through kvmlib:

This first post will give an overview on how to configure the Kvaser device using Python. Part two adds some complexity to the configuration, while part three will go deeper and show how to use kvmlib at the C API level. The last part shows how to configure the device while only having access to the removable SD card. Full program listings are available on GitHub.

Update 2017-02-17: Updated sample code to work with Python 3 as well as using the Python canlib package introduced in CANlib SDK v5.17.

1.1 Introduction

Configuration of Kvaser Memorator 2nd Generation devices are normally done using the Kvaser Memomorator Config Tool, which is a GUI tool. But you may also configure these devices progammatically using kvmlib which is included in the CANlib SDK.1 Here we will show how to use kvmlib to configure a Kvaser Memorator Pro 5xHS.2

For an overview of the Kvaser SDK libraries, please read the blog post about how to get more from your hardware with Kvaser SDK libraries.

We are running on a Windows system, so initially we need to download and install the CANlib SDK. This article will access kvmlib using Python3, so you might want to start by reading the blog post about Accessing CANlib from Python if you haven’t done so already.

The code snippets in this blog post are omitting the following import statements for brevity:4

import datetime

import canlib.kvaMemoLibXml as kvaMemoLibXml
import canlib.kvDevice as kvDevice
import canlib.kvmlib as kvmlib

Listing 1: Import statements that should be included in all code snippets.

We will be using a Kvaser Memorator Pro 5xHS which runs firmware version 3.0.5 If you have an older firmware, please update before continuing.

1.2 Initialize the SD card

It’s not enough to just format the SD card in our operating system’s file manager, we also need to initialize the SD card using our Kvaser Memorator device. After having inserted the SD card into our Kvaser Memorator device, we connect the Kvaser Memorator device to a free USB port on our computer and run our first bit of code to let us see that the device is alive.

# Connect to our Kvaser Memorator Pro 5xHS with EAN 00778-9
dev = kvDevice.kvDevice(ean="73-30130-00778-9")
print(dev)

Listing 2: Connecting to a Kvaser device using the kvDevice module.

Device: Kvaser Memorator Pro 5xHS (channel 0)
EAN : 73-30130-00778-9
S/N : 1023
FW : v3.0.546
Card : 0
Drv : kcany0a
Card channel : 0
Canlib channel: 0

Here we note that we are able to connect to the device and that we indeed have firmware version 3.0. Now let us open the device and initialize the SD card using default values.

# Open the device
dev.memoOpen()

# Initialize the SD card with default values
dev.memo.deviceFormatDisk()

# Close the device
dev.memoClose()

Listing 3: Initializing SD card in Kvaser device.

1.3 Create a configuration

Now we have to create a configuration which we do by writing a piece of XML code.6 For more information, the latest version of the XML format is described in the document Specification of Kvaser Memorator Device configuration XML format. Let us take a simple example that just uses channel 1 and 2. We will set the bit rate on these two channels to 1 Mbit/s and log everything while in silent mode.

<?xml version="1.0" ?>
<!DOCTYPE KVASER>
<KVASER>
  <VERSION>2.0</VERSION>
  <BINARY_VERSION>6.0</BINARY_VERSION>
  <SETTINGS>
    <MODE fifo_mode="NO" log_all="YES"/>
  </SETTINGS>
  <CAN_BUS>
    <PARAMETERS bitrate="1000000" channel="0" silent="YES" sjw="1" tseg1="5" tseg2="2"/>
    <PARAMETERS bitrate="1000000" channel="1" silent="YES" sjw="1" tseg1="5" tseg2="2"/>
  </CAN_BUS>
  <TRIGGERBLOCK/>
  <SCRIPTS/>
</KVASER>

Listing 4: Simple XML configuration sample.

The current version of the XML is v2.0 and our device, running v3.0 of the firmware, expects binary version 6.0.

In the next article, where we increase the complexity of the configuration, we will look into how to explicitly validate the configuration before trying to download it. For now we just make sure we enter the XML without any errors.

1.4 Download the configuration

We are now almost ready to start logging, we just need to place the configuration on the device. We will do this by reading in the XML file we just created, convert this XML configuration to a binary configuration and download the binary configuration to the device.

xl = kvaMemoLibXml.kvaMemoLibXml()

# Read in the XML configuration file
with open("logall.xml", 'r') as myfile:
    config_xml = myfile.read()

# Convert the XML configuration to a binary configuration
config_lif = xl.kvaXmlToBuffer(config_xml)

# Open the device and write the configuration
dev.memoOpen()
dev.memo.kmfWriteConfig(config_lif)

# Close the device
dev.memoClose()

Listing 5: Downloading configuration to Kvaser device.

Now we are all set to disconnect our configured device from the computer and instead connect our device to an existing CAN bus and start logging by applying power to the device’s CAN 1 bus connector.

1.5 Read logged messages

After we have logged some messages, we once again connect our Kvaser Memorator device to a free USB port on our computer and read out the result.

# Connect to our Kvaser Memorator Pro 5xHS with EAN 00778-9
dev = kvDevice.kvDevice(ean="73-30130-00778-9")
dev.open()
dev.memoOpen()
fileCount = dev.memo.logFileGetCount()
print("Found %d file%s on card:" % (fileCount, "s" if fileCount > 1 else ""))

# Loop through all logfiles and write their contents to stdout
for fileIndx in range(fileCount):
    myEvents = dev.memoReadEvents(fileIndx)
    for event in myEvents:
        print(event)
    print("\n")

# Delete all logfiles
dev.memo.logFileDeleteAll()

# Close device
dev.memoClose()
dev.close()

Listing 6: Read logged messages and print to stdout.

Found 1 file on card:
*t:          - EAN:73-30130-00778-9 s/n:1023 FW:v3.0.546 LIO:v0.0
t: 0.249998387 DateTime: 2016-02-23 06:56:04
t: 0.249998387 Log Trigger Event (type: 0x1, trigno: 0x00, pre-trigger: 0, post-trigger: -1)

t: 9.479176975 DateTime: 2016-02-23 06:56:13
t: 13.29719495 ch:0 f: 2 id: 490 dlc: 2 d:5d d6
t: 13.29719495 ch:1 f: 2 id: 490 dlc: 2 d:5d d6
t: 13.298196175 ch:0 f: 2 id: 284 dlc: 2 d:a8 b1
t: 13.298196175 ch:1 f: 2 id: 284 dlc: 2 d:a8 b1
t: 13.299137412 ch:0 f: 2 id: 739 dlc: 2 d:7a 4b
t: 13.299137412 ch:1 f: 2 id: 739 dlc: 2 d:7a 4b
t: 13.300282637 ch:0 f: 2 id: 622 dlc: 6 d:8d b9 69 8a 98 e1
t: 13.300282637 ch:1 f: 2 id: 622 dlc: 6 d:8d b9 69 8a 98 e1
t: 13.301156875 ch:0 f: 2 id: 559 dlc: 1 d:78
t: 13.301156875 ch:1 f: 2 id: 559 dlc: 1 d:78
t:   13.3022261 ch:0 f: 2 id: 33a dlc: 1 d:0d
t:   13.3022261 ch:1 f: 2 id: 33a dlc: 1 d:0d
t: 13.303279325 ch:0 f: 2 id: 463 dlc: 6 d:14 eb d6 ae ed 46
t: 13.303279325 ch:1 f: 2 id: 463 dlc: 6 d:14 eb d6 ae ed 46
t: 13.304230562 ch:0 f: 2 id: 59b dlc: 6 d:7f a9 28 3a f2 5d
t: 13.304230562 ch:1 f: 2 id: 59b dlc: 6 d:7f a9 28 3a f2 5d
t: 13.305248787 ch:0 f: 2 id: 103 dlc: 8 d:4e 0d 1a dd 8d b2 19 ab

That’s it for this time. We have now seen how to configure and read back logged data using kvmlib. In the next part, we will branch out and look at adding some complexity to the configuration.

Footnotes

1 The CANlib SDK can be downloaded from www.kvaser.com/developer/canlib-sdk.

2 EAN 73-30130-00778-9

3 As of Python canlib package v1.2.163 (included in CANlib SDK v5.19), the Python wrappers should work in both Python v3.4+ as well as under Python v2.7.

4 The full program listings are available on github.com/Kvaser/developer-blog.

5 The firmware for Kvaser Memorator Pro 5xHS is bundled in the Kvaser Firmware
Update Tool which can be downloaded from www.kvaser.com/downloads.

6 The latest version of the XML format is described in the document Specification of Kvaser Memorator Device configuration XML format.

Author Image

Magnus Carlsson

Magnus Carlsson is a Software Developer for Kvaser AB and has developed firmware and software for Kv...