# canlib.kvadblib

Wrapper for the Kvaser kvaDbLib library

A CAN database contains information about messages. Each message has (among other attributes) an identifier, a name and one or several signals. The kvaDbLib library is an API for these CAN databases.

class `canlib.kvadblib.``Attribute`(db, handle)

  Bases: `object`

  Factory for creating different types of attributes.

  This class is also the base class and thus contains all common properties.

  `name`

    Name of attribute.

    Type: | `str`

  `value`

    Attribute value

class `canlib.kvadblib.``AttributeDefinition`(db, handle)

  Bases: `object`

  Factory for creating different types of attribute definitions.

  This class is also the base class and thus contains all common properties.

  `name`

    Name of attribute definition.

    Type: | `str`

  `owner`

    Return attribute owner

    Type: | `AttributeOwner`

class `canlib.kvadblib.``AttributeOwner`

  Bases: `canlib.cenum.CEnum`

  `DB` = 1
  `ENV` = 5
  `INVALID` = 0
  `MESSAGE` = 2
  `NODE` = 3
  `SIGNAL` = 4

class `canlib.kvadblib.``AttributeType`

  Bases: `canlib.cenum.CEnum`

  `ENUM` = 4
  `FLOAT` = 3
  `INTEGER` = 1
  `INVALID` = 0
  `STRING` = 5

class `canlib.kvadblib.``BoundMessage`(message, frame)

  Bases: `object`

  A CAN data object that manipulates data through signals.

class `canlib.kvadblib.``BoundSignal`(signal, frame)

  Bases: `object`

  `is_enum`

    Whether this signal is an enum-signal

    New in version 1.7.

    Type: | `bool`

  `name`

    Signal’s name string

    Type: | `str`

  `phys`

    Signal’s physical value

    Type: | `int` or `float`

  `raw`

    Signal’s raw value

    Type: | `int`

  `unit`

    Signal’s unit string

    Type: | `str`

  `value`

    Signal’s value

    If the signal is an enum-signal, then the enum name is returned. Otherwise, the signals physical value (`phys`) is returned.

    New in version 1.7.

class `canlib.kvadblib.``Dbc`(filename=None, name=None, protocol=None)

  Bases: `object`

  Holds the root database handle.

  `attribute_definitions`()

    Return a generator over all database attribute definitions.

  `attributes`()

    Return a generator over all database attributes.

    New in version 1.6.

  `close`()

    Close an open database handle.

  `delete_attribute`(name)

    Delete attribute from database.

    New in version 1.6.

  `delete_attribute_definition`(name)

    Delete attribute definition from database.

    New in version 1.7.

  `delete_message`(message)

    Delete message from database.

    Parameters: | message (`Message`) – message to be deleted

  `delete_node`(node)

    Delete node from database.

    Parameters: | node (`Node`) – node to be deleted

  `flags`

    Get the database flags.

    E.g. DATABASE_FLAG_J1939

  `get_attribute_definition_by_name`(name)

    Find attribute definition using name.

    Parameters: | name (str) – name of attribute definition

    Returns an attribute definition object depending on type, e.g. if the type is AttributeType.INTEGER, an `IntegerAttributeDefinition` is returned.

  `get_attribute_value`(name)

    Return attribute value

    If the attribute is not set on the database, we return the attribute definition default value.

    New in version 1.6.

  `get_message`(id=None, name=None)

    Find message by id or name

    If both id and name is given, both most match.

    Parameters: | id (str) – message id to look for name (str) – message name to look for
    Returns: | `Message`
    Raises: | `KvdNoMessage` – If no match was found, or if none of `id` and `name` were given.

  `get_message_by_id`(id)

    Find message by id

    Parameters: | id (str) – message id to look for
    Returns: | `Message`
    Raises: | `KvdNoMessage` – If no match was found.

  `get_message_by_name`(name)

    Find message by name

    Parameters: | name (str) – message name to look for
    Returns: | `Message`
    Raises: | `KvdNoMessage` – If no match was found.

  `get_node_by_name`(name)

    Find node by name

    Parameters: | name (str) – node name to look for
    Returns: | `Node`
    Raises: | `KvdNoNode` – If no match was found.

  `interpret`(frame)

    Interprets a given Frame object, returning a BoundMessage

  `messages`(show_all=True)

    Return a generator of all database messages.

    If you would like to omit the special message ‘VECTOR__INDEPENDENT_SIG_MSG’, which is used to collect removed signals under, set show_all to False or use the Dbc iterator directly:

        db = kvadblib.Dbc(filename='mydb.dbc')
        for message in db:
            print(msg)

    Parameters: | show_all (`bool`) – If true, all messages, including any special message such as ‘VECTOR__INDEPENDENT_SIG_MSG’ will be returned

    Changed in version 1.8: Added argument show_all.

  `name`

    The current database name (read-only)

    Type: | `str`

  `new_attribute_definition`(name, owner, type, definition)

    Create a new attribute definition in the database.

    The owner specify where the attribute is applicable, e.g. `AttributeOwner.MESSAGE` specifies that this attribute is only applicable on messages (`Message`).

    Parameters: | name (str) – a unique name. owner (`AttributeOwner`) – the owner type
    Returns: | `AttributeDefinition`

  `new_message`(name, id, flags=0, dlc=None, comment=None)

    Create a new message in the database.

    Parameters: | name (str) – name of message id (int) – message id flags (int, optional) – message flags, e.g. MESSAGE_EXT
    Returns: | `canlib.kvadblib.message.Message`

  `new_node`(name, comment=None)

    Create a new node in the database.

    Parameters: | name (str) – name of message comment (str, optional) – message comment
    Returns: | `Node`

  `node_in_signal`(node, signal)

    Check if signal has been added to node.

    Returns: | True – signals contains node False: otherwise

  `nodes`()

    Return a generator containing all database nodes.

  `protocol`

    The database protocol

    Type: | `ProtocolType`

  `set_attribute_value`(name, value)

    Set value of attribute ‘name’ on database.

    If no attribute called ‘name’ is set on database, attach a database attribute from the database attribute definition first.

    New in version 1.6.

  `write_file`(filename)

    Write a database to file.

    Parameters: | filename (str) – file to write database to

class `canlib.kvadblib.``DefaultDefinition`(default)

  Bases: `tuple`

  Attribute definition for attributes defined using only default.

  `default`

    Alias for field number 0

class `canlib.kvadblib.``EnumDefaultDefinition`(default, enums)

  Bases: `tuple`

  Attribute definition for enumeration attributes.

  Holds a definition using default and key-value pairs.

  `default`

    Alias for field number 0

  `enums`

    Alias for field number 1

class `canlib.kvadblib.``EnumDefinition`(db, handle, definition=None)

  Bases: `canlib.kvadblib.attributedef.AttributeDefinition`

  Definition of an enum attribute.

  `add_enum_definition`(enums)

    Add enum definitions.

    Parameters: | enums (dict) – key - value pair(s), example: {‘empty’: 0}

  `definition`

    Return attribute definition

    Changed in version 1.6.

    Type: | `EnumDefaultDefinition`

class `canlib.kvadblib.``EnumSignal`(db, message, sh, name=None, type=None, byte_order=<SignalByteOrder.INTEL: 0>, mode=<SignalMultiplexMode.SIGNAL: 0>, size=None, scaling=ValueScaling(factor=1, offset=0), limits=None, unit=None, comment=None, enums={})

  Bases: `canlib.kvadblib.signal.Signal`

  Database signal of type enum, holds meta data about a signal.

  `add_enum_definition`(enums)

    Add enums dictionary to definition.

  `enums`

    Signal enum definition dictionary

    Type: | `dict`

class `canlib.kvadblib.``Error`

  Bases: `canlib.cenum.CEnum`

  `DATABASE_INTERNAL` = -8
  `DB_FILE_OPEN` = -7
  `FAIL` = -1
  `INTERNAL` = -6
  `IN_USE` = -13
  `NO_ATTRIB` = -10
  `NO_DATABASE` = -2
  `NO_MSG` = -4
  `NO_NODE` = -9
  `NO_SIGNAL` = -5
  `ONLY_ONE_ALLOWED` = -11
  `PARAM` = -3
  `WRONG_OWNER` = -12

class `canlib.kvadblib.``FloatDefinition`(db, handle, definition=None)

  Bases: `canlib.kvadblib.attributedef.AttributeDefinition`

  Definition of a float attribute.

  `definition`

    Attribute definition

    Type: | `MinMaxDefinition`

class `canlib.kvadblib.``FrameBox`(db, messages=())

  Bases: `object`

  Helper class for sending signals

  This class allows sending signals without worrying about what message they are defined in. It does this by binding a message and all its signals to the same `Frame` object.

  Objects are created by giving them a `Dbc` database, and optionally a list of messages (either names or `canlib.kvadblib.Message` objects):

      db = Dbc(...)
      framebox = FrameBox(db, messages=('Msg0','Msg1'))

  Messages can also be added after instantiation with `add_message`:

      framebox.add_message('Msg0', 'Msg1')

  Then setting signal values for any added message is done with:

      framebox.signal('Sig0').phys = 7
      framebox.signal('Sig1').phys = 20

  Once all values are set, they can easily be sent via the channel `channel` with:

      for frame in framebox.frames():
        channel.write(frame)

  Any `Framebox` methods that return messages requires the message to have been added to the framebox, either with the `messages` constructor argument or with `add_message`. Likewise, any methods that return signals require the signal’s message to have been added.

  `add_message`(message)

    Add a message to the framebox

    The message will be available for all future uses of `FrameBox.message` and `FrameBox.messages`, and all its signals will be available for uses of `FrameBox.signal` and `FrameBox.signals`.

    The `message` argument can either be a message name, or a `canlib.kvadblib.Message` object.

  `frames`()

    Iterate over all frames of the signals/messages from this `FrameBox`

  `message`(name)

    Retrieves a message by name

    Returns a `BoundMessage` that shares its `Frame` object with its child signals.

  `messages`()

    Iterator over all messages that this `FrameBox` is aware of

  `signal`(name)

    Retrieves a signal by name

    Returns a `BoundSignal` that shares its `Frame` object with its parent message and sibling signals.

  `signals`()

    Iterator over all signals that this `FrameBox` is aware of

class `canlib.kvadblib.``IntegerDefinition`(db, handle, definition=None)

  Bases: `canlib.kvadblib.attributedef.AttributeDefinition`

  Definition of an integer attribute.

  `definition`

    Return attribute definition

    Type: | `MinMaxDefinition`

exception `canlib.kvadblib.``KvdErrInParameter`

  Bases: `canlib.kvadblib.exceptions.KvdError`

  `status` = -3

exception `canlib.kvadblib.``KvdError`

  Bases: `canlib.exceptions.DllException`

  Base class for exceptions raised by the kvadblib dll

exception `canlib.kvadblib.``KvdInUse`

  Bases: `canlib.kvadblib.exceptions.KvdError`

  `status` = -13

exception `canlib.kvadblib.``KvdNoAttribute`

  Bases: `canlib.kvadblib.exceptions.KvdNotFound`

  `status` = -10

exception `canlib.kvadblib.``KvdNoMessage`

  Bases: `canlib.kvadblib.exceptions.KvdNotFound`

  `status` = -4

exception `canlib.kvadblib.``KvdNoNode`

  Bases: `canlib.kvadblib.exceptions.KvdNotFound`

  `status` = -9

exception `canlib.kvadblib.``KvdNotFound`

  Bases: `canlib.kvadblib.exceptions.KvdError`

exception `canlib.kvadblib.``KvdOnlyOneAllowed`

  Bases: `canlib.kvadblib.exceptions.KvdError`

  `status` = -11

exception `canlib.kvadblib.``KvdWrongOwner`

  Bases: `canlib.kvadblib.exceptions.KvdNotFound`

  `status` = -12

class `canlib.kvadblib.``Message`(db, handle, name=None, id=None, flags=None, dlc=None, comment=None)

  Bases: `object`

  Database message, holds signals.

  `asframe`()

    Creates a Frame object with empty data matching this message

  `attributes`()

    Return a generator over all message attributes.

  `bind`(frame=None)

    Bind this message to a frame

    Creates a new BoundMessage object representing this message bound to the given Frame object, or a new Frame object if `frame` is `None`.

  `comment`

    Comment message

    Type: | `str`

  `delete_attribute`(name)

    Delete attribute from message.

  `delete_signal`(signal)

    Delete signal from message.

    Parameters: | signal (`Signal`) – signal to be deleted

  `dlc`

    The message dlc

    Type: | `int`

  `flags`

    The message flags

    Type: | `MessageFlag`

  `get_attribute_value`(name)

    Return attribute value

    If the attribute is not set on the message, we return the attribute definition default value.

  `get_signal`(name)

    Find signal in message by name.

  `get_signal_by_name`(name)

    Find signal in message by name.

  `id`

    The message identifier

    Type: | `int`

  `name`

    The message name

    Type: | `str`

  `new_signal`(name, type=<SignalType.UNSIGNED: 2>, byte_order=<SignalByteOrder.INTEL: 0>, mode=<SignalMultiplexMode.SIGNAL: 0>, representation=None, size=None, scaling=ValueScaling(factor=1, offset=0), limits=None, unit=None, comment=None, enums={})

    Create and add a new signal to the message.

  `qualified_name`

    The qualified message name

    Returns database and message names separated by a dot.

    Type: | `str`

  `send_node`

    The send node for this message.

    Type: | `Node`

  `set_attribute_value`(name, value)

    Set value of attribute ‘name’ on message.

    If no attribute called ‘name’ is set on message, attach a message attribute from the database attribute definition first.

  `signals`()

    Return a generator of all signals in message.

class `canlib.kvadblib.``MessageFlag`

  Bases: `object`

  `EXT` = 2147483648L
  `J1939` = 1
  `WAKEUP` = 2

class `canlib.kvadblib.``MinMaxDefinition`(default, min, max)

  Bases: `tuple`

  Attribute definition for attributes defined using default, min and max.

  `default`

    Alias for field number 0

  `max`

    Alias for field number 2

  `min`

    Alias for field number 1

class `canlib.kvadblib.``Node`(db, handle, name=None, comment=None)

  Bases: `object`

  Database Node

  `attributes`()

    Return a generator over all message attributes.

  `comment`

    The node’s comment

    Type: | `str`

  `delete_attribute`(name)

    Delete attribute from node.

  `get_attribute_value`(name)

    Return attribute value

    If the attribute is not set on the message, we return the attribute definition default value.

  `name`

    The node’s name

    Type: | `str`

  `set_attribute_value`(name, value)

    Set value of attribute ‘name’ on node.

    If no attribute called ‘name’ is set on node, attach a node attribute from the database attribute definition first.

class `canlib.kvadblib.``ProtocolType`

  Bases: `canlib.cenum.CEnum`

  `AFDX` = 7
  `BEAN` = 5
  `CAN` = 0
  `CANFD` = 9
  `ETHERNET` = 6
  `FLEXRAY` = 4
  `J1708` = 8
  `LIN` = 2
  `MOST` = 3
  `UNKNOWN` = 10
  `VAN` = 1

class `canlib.kvadblib.``Signal`(db, message, sh, name=None, type=None, byte_order=None, mode=None, representation=None, size=None, scaling=None, limits=None, unit=None, comment=None)

  Bases: `object`

  Database signal, holds meta data about a signal

  `add_node`(node)

    Add receiving node to signal.

  `attributes`()

    Return a generator over all signal attributes.

  `bind`(frame=None)

    Bind this signal to a frame

    Creates a new BoundSignal object representing this signal bound to the given Frame object, or a new Frame object if `frame` is `None`..

  `byte_order`

    Get the signal byte order encoding.

    Type: | `SignalByteOrder`

  `comment`

    Get the signal comment.

    Type: | `str`

  `data_from`(can_data, phys=None, raw=None)

    Convert a raw or physical value into CAN data bytes.

  `delete_attribute`(name)

    Delete attribute from signal.

  `get_attribute_value`(name)

    Return attribute value

    If the attribute is not set on the signal, we return the attribute definition default value.

  `limits`

    Get message min and max values

    Type: | `ValueLimits`

  `mode`
  `name`

    Get the signal name.

    Type: | `str`

  `nodes`()

    Return a generator over all receiving nodes of the signal.

  `phys_from`(can_data)

    Return signals physical value from data

  `qualified_name`

    Get the qualified signal name.

    Returns database, message and signal names separated by dots.

    Type: | `str`

  `raw_from`(can_data)

    Return signals raw value from data

  `remove_node`(node)

    Remove receiving node from signal.

  `scaling`

    Get the signals factor and offset

    Type: | `ValueScaling`

  `set_attribute_value`(name, value)

    Set value of attribute ‘name’ on signal.

    If no attribute called ‘name’ is set on signal, attach a signal attribute from the database attribute definition first.

  `size`

    Get the signals startbit and length

    Type: | `ValueSize`

  `type`

    Get the signal representation type.

    Type: | `SignalType`

  `unit`

    Get the signal unit

    Type: | `str`

class `canlib.kvadblib.``SignalByteOrder`

  Bases: `canlib.cenum.CEnum`

  `INTEL` = 0
  `MOTOROLA` = 1

class `canlib.kvadblib.``SignalMultiplexMode`

  Bases: `canlib.cenum.CEnum`

  `MUX_INDEPENDENT` = -1
  `MUX_SIGNAL` = -2
  `SIGNAL` = 0

class `canlib.kvadblib.``SignalType`

  Bases: `canlib.cenum.CEnum`

  `DOUBLE` = 4
  `ENUM_SIGNED` = 101
  `ENUM_UNSIGNED` = 102
  `FLOAT` = 3
  `INVALID` = 0
  `SIGNED` = 1
  `UNSIGNED` = 2

class `canlib.kvadblib.``StringDefinition`(db, handle, definition=None)

  Bases: `canlib.kvadblib.attributedef.AttributeDefinition`

  Definition of a string attribute.

  `definition`

    Return attribute definition

    Type: | `DefaultDefinition`

class `canlib.kvadblib.``ValueLimits`(min, max)

  Bases: `tuple`

  `max`

    Alias for field number 1

  `min`

    Alias for field number 0

class `canlib.kvadblib.``ValueScaling`(factor, offset)

  Bases: `tuple`

  `factor`

    Alias for field number 0

  `offset`

    Alias for field number 1

class `canlib.kvadblib.``ValueSize`(startbit, length)

  Bases: `tuple`

  `length`

    Alias for field number 1

  `startbit`

    Alias for field number 0

`canlib.kvadblib.``bytes_to_dlc`(num_bytes, protocol)

  Convert number of bytes to DLC for given protocol.

`canlib.kvadblib.``dlc_to_bytes`(dlc, protocol)

  Convert DLC to number of bytes for given protocol.

`canlib.kvadblib.``dllversion`()

  Get the kvaDbLib DLL version number as a `VersionNumber`

`canlib.kvadblib.``get_protocol_properties`(prot)

  Get the signal protocol_properties.