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)[source]

Bases: object

Factory for creating different types of attributes.

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

name

str – Name of attribute.

value

Attribute value

class canlib.kvadblib.AttributeDefinition(db, handle)[source]

Bases: object

Factory for creating different types of attribute definitions.

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

name

str – Name of attribute definition.

owner

AttributeOwner – Return attribute owner

class canlib.kvadblib.AttributeOwner[source]

Bases: canlib.cenum.CEnum

DB = 1
ENV = 5
INVALID = 0
MESSAGE = 2
NODE = 3
SIGNAL = 4
class canlib.kvadblib.AttributeType[source]

Bases: canlib.cenum.CEnum

ENUM = 4
FLOAT = 3
INTEGER = 1
INVALID = 0
STRING = 5
class canlib.kvadblib.BoundMessage(message, frame)[source]

Bases: object

A CAN data object that manipulates data through signals.

class canlib.kvadblib.BoundSignal(signal, frame)[source]

Bases: object

name

str – Signal’s name string

phys

int or float – Signal’s physical value

raw

int – Signal’s raw value

unit

str – Signal’s unit string

class canlib.kvadblib.Dbc(filename=None, name=None, protocol=None)[source]

Bases: object

Holds the root database handle.

attribute_definitions()[source]

Return a generator over all database attribute definitions.

attributes()[source]

Return a generator over all database attributes.

New in version 1.6.

close()[source]

Close an open database handle.

delete_attribute(name)[source]

Delete attribute from database.

New in version 1.6.

delete_message(message)[source]

Delete message from database.

Parameters:message (Message) – message to be deleted
delete_node(node)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Find node by name

Parameters:name (str) – node name to look for
Returns:Node
Raises:KvdNoNode – If no match was found.
interpret(frame)[source]

Interprets a given Frame object, returning a BoundMessage

messages()[source]

Return a generator of all database messages.

name

str – The current database name (read-only)

new_attribute_definition(name, owner, type, definition)[source]

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)[source]

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)[source]

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)[source]

Check if signal has been added to node.

Returns:True – signals contains node False: otherwise
nodes()[source]

Return a generator containing all database nodes.

protocol

ProtocolType – The database protocol

set_attribute_value(name, value)[source]

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)[source]

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)[source]

Bases: canlib.kvadblib.attributedef.AttributeDefinition

Definition of an enum attribute.

add_enum_definition(enums)[source]

Add enum definitions.

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

EnumDefaultDefinition – Return attribute definition

Changed in version 1.6.

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={})[source]

Bases: canlib.kvadblib.signal.Signal

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

add_enum_definition(enums)[source]

Add enums dictionary to definition.

enums

dict – Signal enum definition dictionary

class canlib.kvadblib.Error[source]

Bases: canlib.cenum.CEnum

DATABASE_INTERNAL = -8
DB_FILE_OPEN = -7
FAIL = -1
INTERNAL = -6
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)[source]

Bases: canlib.kvadblib.attributedef.AttributeDefinition

Definition of a float attribute.

definition

MinMaxDefinition – Attribute definition

class canlib.kvadblib.FrameBox(db, messages=())[source]

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)[source]

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()[source]

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

message(name)[source]

Retrieves a message by name

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

messages()[source]

Iterator over all messages that this FrameBox is aware of

signal(name)[source]

Retrieves a signal by name

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

signals()[source]

Iterator over all signals that this FrameBox is aware of

class canlib.kvadblib.IntegerDefinition(db, handle, definition=None)[source]

Bases: canlib.kvadblib.attributedef.AttributeDefinition

Definition of an integer attribute.

definition

MinMaxDefinition – Return attribute definition

exception canlib.kvadblib.KvdErrInParameter[source]

Bases: canlib.kvadblib.exceptions.KvdError

status = -3
exception canlib.kvadblib.KvdError[source]

Bases: canlib.exceptions.DllException

exception canlib.kvadblib.KvdNoAttribute[source]

Bases: canlib.kvadblib.exceptions.KvdNotFound

status = -10
exception canlib.kvadblib.KvdNoMessage[source]

Bases: canlib.kvadblib.exceptions.KvdNotFound

status = -4
exception canlib.kvadblib.KvdNoNode[source]

Bases: canlib.kvadblib.exceptions.KvdNotFound

status = -9
exception canlib.kvadblib.KvdNotFound[source]

Bases: canlib.kvadblib.exceptions.KvdError

exception canlib.kvadblib.KvdOnlyOneAllowed[source]

Bases: canlib.kvadblib.exceptions.KvdError

status = -11
exception canlib.kvadblib.KvdWrongOwner[source]

Bases: canlib.kvadblib.exceptions.KvdNotFound

status = -12
class canlib.kvadblib.Message(db, handle, name=None, id=None, flags=None, dlc=None, comment=None)[source]

Bases: object

Database message, holds signals.

asframe()[source]

Creates a Frame object with empty data matching this message

attributes()[source]

Return a generator over all message attributes.

bind(frame=None)[source]

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

str – Comment message

delete_attribute(name)[source]

Delete attribute from message.

delete_signal(signal)[source]

Delete signal from message.

Parameters:signal (Signal) – signal to be deleted
dlc

int – The message dlc

flags

MessageFlag – The message flags

get_attribute_value(name)[source]

Return attribute value

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

get_signal(name)[source]

Find signal in message by name.

get_signal_by_name(name)[source]

Find signal in message by name.

id

int – The message identifier

name

str – The message name

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={})[source]

Create and add a new signal to the message.

qualified_name

str – The qualified message name

Returns database and message names separated by a dot.

send_node

Node – The send node for this message.

set_attribute_value(name, value)[source]

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()[source]

Return a generator of all signals in message.

class canlib.kvadblib.MessageFlag[source]

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)[source]

Bases: object

Database Node

attributes()[source]

Return a generator over all message attributes.

comment

str – The node’s comment

delete_attribute(name)[source]

Delete attribute from node.

get_attribute_value(name)[source]

Return attribute value

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

name

str – The node’s name

set_attribute_value(name, value)[source]

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[source]

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)[source]

Bases: object

Database signal, holds meta data about a signal

add_node(node)[source]

Add receiving node to signal.

attributes()[source]

Return a generator over all signal attributes.

bind(frame=None)[source]

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

SignalByteOrder – Get the signal byte order encoding.

comment

str – Get the signal comment.

data_from(can_data, phys=None, raw=None)[source]

Convert a raw or physical value into CAN data bytes.

delete_attribute(name)[source]

Delete attribute from signal.

get_attribute_value(name)[source]

Return attribute value

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

limits

ValueLimits – Get message min and max values

mode
name

str – Get the signal name.

nodes()[source]

Return a generator over all receiving nodes of the signal.

phys_from(can_data)[source]

Return signals physical value from data

qualified_name

str – Get the qualified signal name.

Returns database, message and signal names separated by dots.

raw_from(can_data)[source]

Return signals raw value from data

remove_node(node)[source]

Remove receiving node from signal.

scaling

ValueScaling – Get the signals factor and offset

set_attribute_value(name, value)[source]

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

ValueSize – Get the signals startbit and length

type

SignalType – Get the signal representation type.

unit

str – Get the signal unit

class canlib.kvadblib.SignalByteOrder[source]

Bases: canlib.cenum.CEnum

INTEL = 0
MOTOROLA = 1
class canlib.kvadblib.SignalMultiplexMode[source]

Bases: canlib.cenum.CEnum

MUX_INDEPENDENT = -1
MUX_SIGNAL = -2
SIGNAL = 0
class canlib.kvadblib.SignalType[source]

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)[source]

Bases: canlib.kvadblib.attributedef.AttributeDefinition

Definition of a string attribute.

definition

DefaultDefinition – Return attribute definition

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)[source]

Convert number of bytes to DLC for given protocol.

canlib.kvadblib.dlc_to_bytes(dlc, protocol)[source]

Convert DLC to number of bytes for given protocol.

canlib.kvadblib.dllversion()[source]

Get the kvaDbLib DLL version number as a VersionNumber

canlib.kvadblib.get_protocol_properties(prot)[source]

Get the signal protocol_properties.