# 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`

  Bases: `canlib.cenum.CEnum`

  kvmDEVICE_xxx

  Device type, used to connect to a Memorator device.

  `MHYDRA` = 0
  `MHYDRA_EXT` = 1

class `canlib.kvmlib.``Error`

  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`

  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)

  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`()
  `estimate_events`()

    Estimate how many events the KME file contains

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

    New in version 1.7.

  `events`()
  `read_event`()

    Read logevent from KME file

    > Returns:
    >   `kvmlib.events. memoLogEventEx`

    New in version 1.7.

  `write_event`(logevent)

class `canlib.kvmlib.``Kmf`(handle, ldf_version)

  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)

  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`()

    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`

  Bases: `canlib.kvmlib.exceptions.KvmError`

  General disk error

  `status` = -24

exception `canlib.kvmlib.``KvmDiskNotFormated`

  Bases: `canlib.kvmlib.exceptions.KvmDiskError`

  Disk not formatted

  `status` = -34

exception `canlib.kvmlib.``KvmError`

  Bases: `canlib.exceptions.DllException`

  Base class for exceptions raised by the kvmlib dll

exception `canlib.kvmlib.``KvmNoDisk`

  Bases: `canlib.kvmlib.exceptions.KvmDiskError`

  No disk found

  `status` = -13

exception `canlib.kvmlib.``KvmNoLogMsg`

  Bases: `canlib.kvmlib.exceptions.KvmError`

  No log message found

  `status` = -10

exception `canlib.kvmlib.``LockedLogError`

  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)

  Bases: `object`

class `canlib.kvmlib.``LogFile`(container, index)

  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`()

    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`

  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)

  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`()

    Flash all LEDs on the Memorator

  `format_disk`(reserved_space=10, database_space=2, fat32=True)

    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`()

    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`()

    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)

    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)

    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)

  Bases: `canlib.kvmlib.events.LogEvent`

  A CAN message recorded by a Memorator

  `asframe`()

    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)

  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`()

    Raises the corresponding exception if any errors are detected

class `canlib.kvmlib.``RTCEvent`(calendartime=None, timestamp=None)

  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)

  Bases: `canlib.kvmlib.events.LogEvent`

  A trigger message recorded by a Memorator

class `canlib.kvmlib.``UnmountedLog`(memorator)

  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`()

    Delete all log files

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

  Bases: `canlib.kvmlib.events.LogEvent`

  A version message recorded by a Memorator

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

  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)

  Convert DLC to number of bytes

  New in version 1.7.

`canlib.kvmlib.``dllversion`()

  Get the kvmlib version number as a `VersionNumber`

`canlib.kvmlib.``kme_file_type`(path)

  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`

  Bases: `_ctypes.Structure`

  `MEMOLOG_TYPE_CLOCK` = 1
  `MEMOLOG_TYPE_INVALID` = 0
  `MEMOLOG_TYPE_MSG` = 2
  `MEMOLOG_TYPE_TRIGGER` = 3
  `MEMOLOG_TYPE_VERSION` = 4
  `createMemoEvent`()
  `event`

    Structure/Union member

class `canlib.kvmlib.``memoLogMrtEx`

  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`

  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`

  Bases: `_ctypes.Structure`

  `data`

    Structure/Union member

  `evType`

    Structure/Union member

class `canlib.kvmlib.``memoLogRtcClockEx`

  Bases: `_ctypes.Structure`

  `calendarTime`

    Structure/Union member

  `evType`

    Structure/Union member

  `padding`

    Structure/Union member

  `timeStamp`

    Structure/Union member

class `canlib.kvmlib.``memoLogTriggerEx`

  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`

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

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

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

  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 to `canlib.kvmlib.Device.MHYDRA_EXT`)
  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.