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

Name of attribute.

Type:str
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

Name of attribute definition.

Type:str
owner

Return attribute owner

Type:AttributeOwner
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

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

Delete attribute definition from database.

New in version 1.7.

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

The current database name (read-only)

Type:str
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

The database protocol

Type:ProtocolType
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

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

Signal enum definition dictionary

Type:dict
class canlib.kvadblib.Error[source]

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

Bases: canlib.kvadblib.attributedef.AttributeDefinition

Definition of a float attribute.

definition

Attribute definition

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

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

Return attribute definition

Type:MinMaxDefinition
exception canlib.kvadblib.KvdErrInParameter[source]

Bases: canlib.kvadblib.exceptions.KvdError

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

Bases: canlib.exceptions.DllException

exception canlib.kvadblib.KvdInUse[source]

Bases: canlib.kvadblib.exceptions.KvdError

status = -13
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

Comment message

Type:str
delete_attribute(name)[source]

Delete attribute from message.

delete_signal(signal)[source]

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

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

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

The node’s comment

Type:str
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

The node’s name

Type:str
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

Get the signal byte order encoding.

Type:SignalByteOrder
comment

Get the signal comment.

Type:str
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

Get message min and max values

Type:ValueLimits
mode
name

Get the signal name.

Type:str
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

Get the qualified signal name.

Returns database, message and signal names separated by dots.

Type:str
raw_from(can_data)[source]

Return signals raw value from data

remove_node(node)[source]

Remove receiving node from signal.

scaling

Get the signals factor and offset

Type:ValueScaling
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

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

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