canlib.kvmlib

Wrapper for the Kvaser kvmlib library

The kvmlib is used to interact with Kvaser Memorator devices that can record CAN messages (E.g. Kvaser Memorator Professional 5xHS). You can download configuration data (e.g. triggers, filters, scripts) allowing you to disconnect the device from your computer, connect the device to a CAN bus and let it record the traffic autonomously. When done, you can reconnect the device with your computer and use kvmlib to get the recorded data.

class canlib.kvmlib.Device[source]

Bases: canlib.cenum.CEnum

kvmDEVICE_xxx

Device type, used to connect to a Memorator device.

MHYDRA = 0
MHYDRA_EXT = 1
class canlib.kvmlib.Error[source]

Bases: canlib.cenum.CEnum

CONFIG_ERROR = -41
CRC_ERROR = -21
DEVICE_COMM_ERROR = -37
DISKFULL_DATA = -26
DISKFULL_DIR = -25
DISK_ERROR = -24
EOF = -12
FAIL = -1
FATAL_ERROR = -31
FILE_ERROR = -23
FILE_NOT_FOUND = -33
FILE_SYSTEM_CORRUPT = -28
FIRMWARE = -40
ILLEGAL_REQUEST = -32
LOGFILEOPEN = -8
LOGFILEREAD = -14
LOGFILEWRITE = -11
NOLOGMSG = -10
NOSTARTTIME = -9
NOT_FORMATTED = -34
NOT_IMPLEMENTED = -30
NO_DISK = -13
OCCUPIED = -38
PARAM = -3
QUEUE_FULL = -20
SECTOR_ERASED = -22
SEQ_ERROR = -27
TIMEOUT = -36
UNSUPPORTED_VERSION = -29
USER_CANCEL = -39
WRITE_PROT = -42
WRONG_DISK_TYPE = -35
class canlib.kvmlib.FileType[source]

Bases: canlib.cenum.CEnum

kvmFILE_xxx

KME file type, a binary file format representing log data.

KME24 = 0
KME25 = 1
KME40 = 2
KME50 = 3
class canlib.kvmlib.Kme(handle)[source]

Bases: object

A kme file

A class representing a KME file. The main use is twofold:

Either we create a KME file using canlib.kvmlib.createKme and would like to write events using canlib.kvmlib.Kme.write_event:

with kvmlib.createKme('out/data.kme50') as kme:
    ...
    kme.write_event(my_logevent)

Or we read events from an existing KME file:

with kvmlib.readKme('in/data.kme50') as kme:
    event = kme.read_event()
    ...
    print(event)

Note that only KME files of type KME50 may currently be written to.

New in version 1.7.

close()[source]
estimate_events()[source]

Estimate how many events the KME file contains

Returns:
int: Approximate number of events in KME file.

New in version 1.7.

events()[source]
read_event()[source]

Read logevent from KME file

Returns:
kvmlib.events. memoLogEventEx

New in version 1.7.

write_event(logevent)[source]
class canlib.kvmlib.Kmf(handle, ldf_version)[source]

Bases: canlib.kvmlib.kmf.KmfSystem

A kmf file opened with kvmlib.openKmf

The main use of this class is using its log attribute, which is a MountedLog object (see its documentation for how to use it).

Also see the base class kvmlib.KmfSystem for inherited functionality.

Variables:log (MountedLog) – Object representing the log of log files within the kmf container-file.

New in version 1.6.

class canlib.kvmlib.KmfSystem(handle)[source]

Bases: object

The base class of Kmf and Memorator

The Kmf and Memorator classes are very similar, they are different ways of reading log files (LogFile) created by a memorator. This class represents the common ground between all ways of accessing log files.

All subclasses should have a log attribute which is an UnmountedLog or subclass thereof.

This class automatically closes its internal handle when garbage collected.

New in version 1.6.

class DiskUsage(used, total)

Bases: tuple

total

Alias for field number 1

used

Alias for field number 0

close()[source]

Close the internal handle

Warning

This invalidates the object.

disk_usage

The disk usage

The tuple has one used and one total field (in that order), which reference disk space in megabytes.

Type:KmfSystem.DiskUsage
exception canlib.kvmlib.KvmDiskError[source]

Bases: canlib.kvmlib.exceptions.KvmError

General disk error

status = -24
exception canlib.kvmlib.KvmDiskNotFormated[source]

Bases: canlib.kvmlib.exceptions.KvmDiskError

Disk not formatted

status = -34
exception canlib.kvmlib.KvmError[source]

Bases: canlib.exceptions.DllException

Base class for exceptions raised by the kvmlib dll

exception canlib.kvmlib.KvmNoDisk[source]

Bases: canlib.kvmlib.exceptions.KvmDiskError

No disk found

status = -13
exception canlib.kvmlib.KvmNoLogMsg[source]

Bases: canlib.kvmlib.exceptions.KvmError

No log message found

status = -10
exception canlib.kvmlib.LockedLogError[source]

Bases: exceptions.RuntimeError

Raised when trying to mount a log file to a locked log

Only one log file can be “mounted” internally at time. When a LogFile object requires its log file to be kept mounted for an extended period of time (such as when iterating over it) it will lock its containing MountedLog object. If during this time an attempt is made to mount a log file, this error will be raised.

class canlib.kvmlib.LogEvent(timestamp=None)[source]

Bases: object

class canlib.kvmlib.LogFile(container, index)[source]

Bases: object

A log file read from a MountedLog object

This class is normally not directly instantiated but retrieved from a MountedLog object.

The most common use of this class is iterating through it to get the individual events as LogEvent subclasses:

for event in logfile:
    ...

Note

While iterating over a LogFile, accessing any other LogFile is will result in a LockedLogError. Make sure to finish the loop (or when using iteration objects directly call the close method) before interacting with any other log files.

A fast approximation of the number of events is given by event_count_estimation, the exact number of events can be calculated using:

num_events = len(list(logfile))

Finally this class has several read-only properties for getting information about the log file itself.

Note

Before any data is fetched from the dll, this class will make sure that the correct file has been mounted on the underlying kvmHandle.

Manually mounting or unmounting log files by calling the dll directly is not supported.

New in version 1.6.

creator_serial

The serial number of the interface that created the log file

Type:int
end_time

The time of the last event in the log file

Type:datetime.datetime
event_count_estimation()[source]

Returns an approximation of the number of events

The number is a rough estimation because it is calculated from the number of blocks allocated by the log file on the disk as an optimization.

New in version 1.7.

start_time

The time of the first event in the log file

Type:datetime.datetime
class canlib.kvmlib.LoggerDataFormat[source]

Bases: canlib.cenum.CEnum

kvmLDF_MAJOR_xxx

Logged data format (LDF) version.

MAJOR_CAN = 3
MAJOR_CAN64 = 5
class canlib.kvmlib.Memorator(handle, channel_number, device_type)[source]

Bases: canlib.kvmlib.kmf.KmfSystem

A Memorator device opened with openDevice

This class should not be instantiated directly, instead call openDevice.

A device opened as memorator can be configured from XML using canlib.kvamemolibxml and write_config:

# Read the original XML file (config.xml)
config = kvamemolibxml.load_xml_file("config.xml")

# Validate the XML
errors, warnings = config.validate()
if errors or warnings:
    print(errors)
    print(warnings)
    raise Exception("One or more errors/warnings in xml configuration")

# Write the configuration in binary
memorator.write_config(config.lif)

The configuration can then be read back (in binary):

dev.read_config()

The log files on the device can be accessed via the log attribute. By default, the log area is not mounted so only a few operations are allowed, such as getting the number of log files:

num_log_files = len(memorator.log)

For a full list of allowed operations, see canlib.kvmlib.UnmountedLog (the type of .log before a mount).

The log area can be mounted either with openDevice’s mount argument set to True, or later with the Memorator.mount function. Once this is done the log attribute is a canlib.kvmlib.MountedLog which supports getting log files as canlib.kvmlib.LogFile objects:

# We can index the Memorator object if we know what file we want
log_file_number_two = memorator.log[2]

# Although usually we want to loop through all log files
for log_file in memorator.log:
    ...

See the documentation of canlib.kvmlib.MountedLog for all available operations.

Variables:
  • channel_number (int) – The channel number that was used to connect to this memorator.
  • device_type (canlib.kvmlib.Device) – The device type that was used to connect to this memorator.
  • mounted (bool) – Whether the device’s memory card has been mounted.

New in version 1.6.

config_version_needed

The version of param.lif that the connected device expects

Type:canlib.versionnumber.VersionNumber
disk_size

The disk size in megabytes

Warning

This is not necessarily the amount of space available for allocation; memo.format_disk(reserved_space=memo.disk_size) is not guaranteed to succeed.

The most reliable way of calculating reserved space is to first format the disk with reserved_space set to 0, and then use memo.disk_usage.total.

Type:int
driver_version

The used driver version information

Type:canlib.versionnumber.VersionNumber
firmware_version

The device firmware version information

Type:canlib.versionnumber.VersionNumber
flash_leds()[source]

Flash all LEDs on the Memorator

format_disk(reserved_space=10, database_space=2, fat32=True)[source]

Format the SD memory card in the Memorator

Parameters:
  • reserved_space (int) – Space to reserve for user files, in MB.
  • database_space (int) – Space to reserve for database files, in MB.
  • fat32 (bool) – Whether the filesystem should be formatted as fat32 (defaults to True)
kvmlib_version

Returns the version of kvmlib

Type:canlib.versionnumber.VersionNumber
mount()[source]

Mount the Memorator’s log area

This replaces the object log attribute with a MountedLog, which allows access to log files.

If the log has already been mounted (self.mounted == True), this is a no-op.

mounted = None
read_config()[source]

Read the configuration of the Memorator

The configuration is returned as a bytes object with the binary configuration data (param.lif).

If a canlib.kvamemolibxml.Configuration is desired, the returned bytes can be parsed using canlib.kvamemolibxml.load_lif:

config_object = kvamemolibxml.load_lif(memorator.read_config())
reopen(device_type=None, mount=False)[source]

Closes and then reopens the internal handle

rtc

The value of the real-time clock

Type:datetime.datetime
serial_number

The serial number of the Memorator

Type:int
write_config(config_lif)[source]

Writes configuration to the Memorator

The configuration should be given as a bytes object with the binary configuration data (param.lif).

Given a canlib.kvamemolibxml.Configuration object, pass its lif attribute to this function:

memorator.write_config(config_object.lif)
class canlib.kvmlib.MessageEvent(id=None, channel=None, dlc=None, flags=None, data=None, timestamp=None)[source]

Bases: canlib.kvmlib.events.LogEvent

A CAN message recorded by a Memorator

asframe()[source]

Convert this event to a canlib.Frame

Creates a new canlib.Frame object with the same contents as this event.

class canlib.kvmlib.MountedLog(memorator, ldf_version)[source]

Bases: canlib.kvmlib.log.UnmountedLog

The log area of a Memorator once mounted

Once a canlib.kvmlib.Memorator object has been mounted, its log attribute is set to an instance of this class. This is the preferred way of using this class.

For canlib.kvmlib.Kmf objects, the log attribute is always an instance of this class as they are by definition mounted.

In the following examples container can be either a canlib.kvmlib.Memorator object that has been mounted, or a canlib.kvmlib.Kmf object.

The files within the log can be accessed via indexing:

container.log[index]

or all files can be iterated over:

for log_file in container.log:
    ...

The log area can also be validated:

container.log.validate()

Also see the super class canlib.kvmlib.UnmountedLog for functionality this class has inherited.

New in version 1.6.

validate()[source]

Raises the corresponding exception if any errors are detected

class canlib.kvmlib.RTCEvent(calendartime=None, timestamp=None)[source]

Bases: canlib.kvmlib.events.LogEvent

An real-time clock message recorded by a Memorator

class canlib.kvmlib.TriggerEvent(type=None, timestamp=None, pretrigger=None, posttrigger=None, trigno=None)[source]

Bases: canlib.kvmlib.events.LogEvent

A trigger message recorded by a Memorator

class canlib.kvmlib.UnmountedLog(memorator)[source]

Bases: object

The log area of a Memorator before mounting

Before the log area of a canlib.kvmlib.Memorator object has been mounted, its log attribute is set to an instance of this class.

This class has all the functionality available even when the log area has not been mounted – this functionality is still present after the log area has been mounted (or if the area is always mounted – see canlib.kvmlib.Kmf).

The number of log files can be read as the len() of this object (container is either a canlib.kvmlib.Memorator or canlib.kvmlib.Kmf object):

num_log_files = len(container.log)

All log files can also be deleted:

container.log.delete_all()

New in version 1.6.

delete_all()[source]

Delete all log files

class canlib.kvmlib.VersionEvent(lioMajor, lioMinor, fwMajor, fwMinor, fwBuild, serialNumber, eanHi, eanLo)[source]

Bases: canlib.kvmlib.events.LogEvent

A version message recorded by a Memorator

canlib.kvmlib.createKme(path, filetype=<FileType.KME50: 3>)[source]

Create a KME file on the host computer

Parameters:
  • path (str) – The full filepath for the .KME file (e.g. "data/mylog.kme50").
  • filetype (canlib.kvmlib.FileType) – The KME file type
Returns:

canlib.kvmlib.Kme

New in version 1.7.

canlib.kvmlib.dlc_to_bytes(dlc, canFd=False)[source]

Convert DLC to number of bytes

New in version 1.7.

canlib.kvmlib.dllversion()[source]

Get the kvmlib version number as a VersionNumber

canlib.kvmlib.kme_file_type(path)[source]

Scan KME file and report version

Open and read the file path and try to decode what version of KME it contains. Returns type as kvmFILE_xxx.

Parameters:path (str) – The full filepath for the .KME file (e.g. "data/mylog.kme").
Returns:canlib.kvmlib.FileType – The KME file type

New in version 1.7.

canlib.kvmlib.kvmDiskError

alias of canlib.kvmlib.exceptions.KvmDiskError

canlib.kvmlib.kvmDiskNotFormated

alias of canlib.kvmlib.exceptions.KvmDiskNotFormated

canlib.kvmlib.kvmError

alias of canlib.kvmlib.exceptions.KvmError

canlib.kvmlib.kvmNoDisk

alias of canlib.kvmlib.exceptions.KvmNoDisk

canlib.kvmlib.kvmNoLogMsg

alias of canlib.kvmlib.exceptions.KvmNoLogMsg

canlib.kvmlib.kvmlib

alias of canlib.kvmlib.deprecated.KvmLib

class canlib.kvmlib.logMsg(*args, **kwargs)

Bases: canlib.kvmlib.events.MessageEvent, object

Deprecated name for MessageEvent

logMsg has been renamed MessageEvent, using the old name (logMsg) is deprecated.

class canlib.kvmlib.memoLogEventEx[source]

Bases: _ctypes.Structure

MEMOLOG_TYPE_CLOCK = 1
MEMOLOG_TYPE_INVALID = 0
MEMOLOG_TYPE_MSG = 2
MEMOLOG_TYPE_TRIGGER = 3
MEMOLOG_TYPE_VERSION = 4
createMemoEvent()[source]
event

Structure/Union member

class canlib.kvmlib.memoLogMrtEx[source]

Bases: _ctypes.Union

msg

Structure/Union member

raw

Structure/Union member

rtc

Structure/Union member

trig

Structure/Union member

ver

Structure/Union member

class canlib.kvmlib.memoLogMsgEx[source]

Bases: _ctypes.Structure

channel

Structure/Union member

data

Structure/Union member

dlc

Structure/Union member

evType

Structure/Union member

flags

Structure/Union member

id

Structure/Union member

timeStamp

Structure/Union member

class canlib.kvmlib.memoLogRaw[source]

Bases: _ctypes.Structure

data

Structure/Union member

evType

Structure/Union member

class canlib.kvmlib.memoLogRtcClockEx[source]

Bases: _ctypes.Structure

calendarTime

Structure/Union member

evType

Structure/Union member

padding

Structure/Union member

timeStamp

Structure/Union member

class canlib.kvmlib.memoLogTriggerEx[source]

Bases: _ctypes.Structure

evType

Structure/Union member

padding

Structure/Union member

postTrigger

Structure/Union member

preTrigger

Structure/Union member

timeStampHi

Structure/Union member

timeStampLo

Structure/Union member

trigNo

Structure/Union member

type

Structure/Union member

class canlib.kvmlib.memoLogVersionEx[source]

Bases: _ctypes.Structure

eanHi

Structure/Union member

eanLo

Structure/Union member

evType

Structure/Union member

fwBuild

Structure/Union member

fwMajor

Structure/Union member

fwMinor

Structure/Union member

lioMajor

Structure/Union member

lioMinor

Structure/Union member

serialNumber

Structure/Union member

class canlib.kvmlib.memoMsg(*args, **kwargs)

Bases: canlib.kvmlib.events.LogEvent, object

Deprecated name for LogEvent

memoMsg has been renamed LogEvent, using the old name (memoMsg) is deprecated.

canlib.kvmlib.openDevice(channel_number, mount=False, device_type=<Device.MHYDRA_EXT: 1>)[source]

Open a Memorator device

Parameters:
  • channel_number (int) – A channel number of the Memorator to be opened.
  • mount (bool) – Whether the memorator log area should be mounted before returned.
  • device_type (canlib.kvmlib.Device) – The type of the memorator to be opened (defaults to canlib.kvmlib.Device.MHYDRA_EXT)
Returns:

Memorator

New in version 1.6.

canlib.kvmlib.openKme(path, filetype=<FileType.KME50: 3>)[source]

Open a KME file on the host computer

Parameters:
  • path (str) – The full filepath for the .KME file (e.g. "data/mylog.kme50").
  • filetype (canlib.kvmlib.FileType) – The KME file type
Returns:

canlib.kvmlib.Kme

New in version 1.7.

canlib.kvmlib.openKmf(path, device_type=<Device.MHYDRA_EXT: 1>)[source]

Open a kmf file from disk

Parameters:
Returns:

Kmf

New in version 1.6.

class canlib.kvmlib.rtcMsg(*args, **kwargs)

Bases: canlib.kvmlib.events.RTCEvent, object

Deprecated name for RTCEvent

rtcMsg has been renamed RTCEvent, using the old name (rtcMsg) is deprecated.

class canlib.kvmlib.trigMsg(*args, **kwargs)

Bases: canlib.kvmlib.events.TriggerEvent, object

Deprecated name for TriggerEvent

trigMsg has been renamed TriggerEvent, using the old name (trigMsg) is deprecated.

class canlib.kvmlib.verMsg(*args, **kwargs)

Bases: canlib.kvmlib.events.VersionEvent, object

Deprecated name for VersionEvent

verMsg has been renamed VersionEvent, using the old name (verMsg) is deprecated.