Handling CAN databases in Python

This is the first post in a 2-part series about how to manage DBC databases using the Kvaser database library (kvadblib) and Python:

1. Handling CAN databases in Python
2. Send and receive database signals

With the release of CANlib SDK v5.22, the database library (kvaDbLib) has been overhauled and the Python canlib wrapper package (v1.5) have added support for database handling through the kvadblib module. The kvaDbLib library is used for creating, writing, reading and modifying DBC databases.¹ We will in this first post take a look at how to create and examine a DBC database using the Python canlib wrapper package. The Python canlib package is released as a Python Wheel for easy installing using pip install. If you don’t have it installed yet, take a look at the blog post Python samples are now bundled in a package² for more information on the subject.

A database is used to translate raw CAN data into human readable signals. In this example we’ll work with a hypothetical vehicle database.

Let us get started right away by creating a database from scratch. We begin with importing kvadblib from the canlib python package and create a new database named “Histogram”³ , add a message with id “402”, dlc “8” and name the message “LIM_002”.

The next step is to add a signal to the message we just created. Let us add a float signal named “Load” with some unit and comment text.

There are a lot of information that is specified when creating a signal, so let us quickly go through those options:

name A unique string identifying the signal. This name must be unique across all signals in the database.

type A signal can be specified as SIGNED, UNSIGNED, (DOUBLE⁴ ), or FLOAT. The signal may also be an enumerated type, and in that case we set the type as ENUM_SIGNED or ENUM_UNSIGNED in the Python wrapper.

byte_order The signal byte order can be either INTEL or MOTOROLA, defaults to INTEL.

mode The default mode for a signal is MUX_INDEPENDENT, which means that this signal is a normal signal.⁵ In a CAN message a signal can be defined as a multiplexor by setting mode to MUX_SIGNAL. This multiplexor now selects which multiplexed signal is transmitted in the same frame. The multiplexed signals should set mode to the (positive integer) multiplexed value the multiplexor should have for the multiplexed signal to be used. Only simple multiplexing is currently supported in kvadblib. For simple multiplexing only one multiplexor signal can be defined in a message, and for each multiplexed signal only one multiplexor value can be defined.

size The position of the signal’s first bit (aka as the startbit), and the length of the signal in number of bits.

scaling The scaling consists of a factor and an offset. A raw CAN value will be multiplied by the factor and then incremented with the offset to be converted to a physical value.

limits The minimum and maximum values of this signal’s physical value.

unit A string representation of the signal’s unit.

comment A string that can be used to document the signal.

Let us finish up the database by defining three more messages and signals.

The last step is to save our new database to a file and close it.

Let us now take a look at the DBC database we just created. We start by just printing the contents from Python:

The textwrap module is used here to get a nice width of 80 characters on the printout:

Hopefully there were no surprises there, so let us finish this part of this blog series by also see how our database looks in the Kvaser Database Editor.

Figure 1: Looking at our newly created database in the Kvaser Database Editor.

In the middle panel of Kvaser Database Editor, we can see our four defined messages. In Figure ¹, the message “LIM_002” is selected and the content of the message is shown below the message. In our case we have a single signal named “Load” with e.g. unit set to “metric ton”. In the right pane, a layout (with shadowed cells) of the current messsage’s data bits is shown. In Figure ¹, we can see that the selected signal spans from bit 0 in the first byte through bit 7 in the third byte, this corresponds to the start position 0 and length 32 that was given.

Thus ends our first part which described how to create a database. In the next part we will take a look at how use the database while sending and receiving signals

1 The DBC database describes the properties of the CAN network, the nodes connected, and the CAN messages and signals.

2 https://www.kvaser.com/

3 If you have been browsing around the t samples in the CANlib SDK, you might have come across this particular database before since it can be found in the folder Samples\tScript\Learn more\Misc\histogram.

4 The signal type DOUBLE is currently not implemented in kvadblib.

5 We will only cover normal (non-multiplexed) signals in this article.