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 usingcanlib.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.
-
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.
-
-
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 aMountedLog
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
andMemorator
The
Kmf
andMemorator
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 anUnmountedLog
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
-
-
disk_usage
¶ The disk usage
The tuple has one
used
and onetotal
field (in that order), which reference disk space in megabytes.Type: KmfSystem.DiskUsage
-
class
-
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 containingMountedLog
object. If during this time an attempt is made to mount a log file, this error will be raised.
-
class
canlib.kvmlib.
LogFile
(container, index)[source]¶ Bases:
object
A log file read from a
MountedLog
objectThis 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 otherLogFile
is will result in aLockedLogError
. Make sure to finish the loop (or when using iteration objects directly call theclose
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 usingcanlib.kvamemolibxml
andwrite_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
’smount
argument set toTrue
, or later with theMemorator.mount
function. Once this is done thelog
attribute is acanlib.kvmlib.MountedLog
which supports getting log files ascanlib.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 to0
, and then usememo.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
-
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 toTrue
)
- reserved_space (
-
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 aMountedLog
, 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 returnedbytes
can be parsed usingcanlib.kvamemolibxml.load_lif
:config_object = kvamemolibxml.load_lif(memorator.read_config())
-
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 itslif
attribute to this function:memorator.write_config(config_object.lif)
- channel_number (
-
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
-
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, itslog
attribute is set to an instance of this class. This is the preferred way of using this class.For
canlib.kvmlib.Kmf
objects, thelog
attribute is always an instance of this class as they are by definition mounted.In the following examples
container
can be either acanlib.kvmlib.Memorator
object that has been mounted, or acanlib.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.
-
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, itslog
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 acanlib.kvmlib.Memorator
orcanlib.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.
-
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: New in version 1.7.
- path (
-
canlib.kvmlib.
dlc_to_bytes
(dlc, canFd=False)[source]¶ Convert DLC to number of bytes
New in version 1.7.
-
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 typeNew 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 renamedMessageEvent
, 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¶
-
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 renamedLogEvent
, 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 tocanlib.kvmlib.Device.MHYDRA_EXT
)
Returns: New in version 1.6.
- channel_number (
-
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: New in version 1.7.
- path (
-
canlib.kvmlib.
openKmf
(path, device_type=<Device.MHYDRA_EXT: 1>)[source]¶ Open a kmf file from disk
Parameters: - path (
str
) – The filepath to the .KMF file (e.g."data/kmf/LOG00000.KMF"
). - device_type (
canlib.kvmlib.Device
) – The type of the memorator that created the .KMF file(s) (defaults tocanlib.kvmlib.Device.MHYDRA_EXT
)
Returns: New in version 1.6.
- path (
-
class
canlib.kvmlib.
rtcMsg
(*args, **kwargs)¶ Bases:
canlib.kvmlib.events.RTCEvent
,object
Deprecated name for
RTCEvent
rtcMsg
has been renamedRTCEvent
, 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 renamedTriggerEvent
, 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 renamedVersionEvent
, using the old name (verMsg
) is deprecated.