This is the first of two articles introducing Kvaser CANlib SDK and the Python package canlib.
In this part of the guide we will go through the setup needed to begin understanding and working with the Python CANlib Wrapper. This includes downloading the required software, connecting the necessary hardware and the basic coding used while sending messages with Kvaser interfaces.
Writer: Anton Carlsson, Software Developer
Cowriter: L-G Fredriksson, Field Application Engineer
Version: 2021-08-09A
With this step-by-step tutorial, we will guide you through sending and receiving messages using Python, Kvaser CAN interfaces and the Python package lib. Kvaser CANlib allows you to control most aspects of any Kvaser CAN interface. The canlib package is a Python wrapper that allows the user to use Kvaser CANlib with Python. This guide will be limited to Windows and Linux where Kvaser CANlib is supported.
A command-line application will often be used, and in this guide we will use Windows PowerShell, which is automatically installed on Windows 7 SP1 and Windows Server 2008 R2 SP1 or any later versions. If you want to use another application instead of PowerShell, you are welcome to do so.
This guide has been written for those who want to set up and use a Kvaser CAN interface with CANlib and the Python CANlib package/wrapper.
To use this guide, the user needs to be somewhat familiar with (or able to look up) the following:
To complete the first step of this guide, sending and receiving a CAN message, we need the following hardware:
We will need to make changes to the computer and download software. The following changes need to be done to the computer:
If you are using the Windows operating system, the following section will describe how to download the required software specifically for Windows. If you have the Linux OS, go to the next section.
The first step is to install Python. For a detailed guide on how to install Python, visit RealPython.com installing python. The following is a concise version of how to install Python for Windows:
Before installing Python, check if it is already installed. Open PowerShell (by selecting the windows key and search for “powershell”) and type either:
> py –version
Or
> py -V
(–version and -V are interchangeable)
If Python is already installed the output will show (Python 3.9.5 is the latest version as of 06-15-2021):
Python 3.9.5
If Python is not installed, the output will be something like:
Python was not found; run without arguments to install from the Microsoft Store, or disable this shortcut from Settings > Manage App Execution Aliases.
Or
‘Py’ is not recognized as an internal or external command, operable program or batch file.
If Python was not installed or too old a version was installed, then we need to install a newer version. If an acceptable version of Python (3.7+) is already installed, skip the next section.
The Python version we need is v3.7 or above. In this guide we will only explore one way to install Python.
First download the installer (For more details on installing Python for Windows visit realpython.com):
When the installer has finished downloading, run it by double-clicking it. A dialog box will appear. There are four things to notice about the box:
You have now installed Python.
To make sure the installation was successful, run the following command in PowerShell:
> py –version
Which should result in something like:
Python 3.9.5
To easily run Python, a virtual environment is recommended. For a more detailed description of what the virtual environment is, why it is needed and how to install it visit RealPython.com python virtual environments. Virtual environments are needed to help with storing directories and receiving site packages such as canlib.
To create a virtual environment in windows run the following in powershell:
> py -3 -m venv .venv –prompt .
“py -3“ dictates that Windows will launch the latest version of Python 3, for more information about the launcher check the documentation. “-m” dictates that you want to run a module and “venv” is the name of the module. “.venv” decides the name of the directory where the virtual environment will be created. “–prompt” changes the name of the virtual environment when it is activated and “.” dictates that the name should be the same as the current directory.
To activate the virtual environment run the following in powershell, this will result in something like:
> .\.venv\Scripts\activate
(pyproj)>
This code runs the activate script (a script is a file with Python code). The script is located in the Scripts directory in the .venv directory. If we are running in PowerShell and get the error message:
cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
Then we need to give ourself permission to run scripts. Either we can run:
> Set-ExecutionPolicy Unrestricted -Scope Process
In powershell to gain permission for this session, or we can run:
> Set-ExecutionPolicy Unrestricted -Scope CurrentUser
In powershell to gain permission for the current user over all later sessions.
Now we can use the environment, its packages and resources in isolation. To deactivate the virtual environment type the following in powershell:
> deactivate
On Windows, firstly we need to install the CANlib driver by downloading and running “Kvaser Drivers for Windows” which can be found on the Kvaser Download page or directly from kvaser_drivers_setp.exe.
Kvaser CANlib SDK also needs to be downloaded from the same Kvaser page or directly from canlib.exe and installed if more than just the basic canlib library will be used. This will install the rest of the supported library dll’s.
The two packages, “Kvaser Drivers for Windows” and “Kvaser CANlib SDK”, contain both 32 and 64 bit versions of the included dll’s.
To make sure the driver was installed correctly, press the windows button and search for Kvaser Device Guide. If Kvaser Device Guide exists the installation was successful.
If you are using the Linux operating system, the following sections will explain how to download the software specifically needed for Linux. If you have the Windows operating system, go to the previous section.
The first step is to install Python. For a detailed guide on different methods to install Python, visit RealPython.com installing python. The following is a short insight into how to install Python for Linux:
Before installing Python on Linux check if it is already installed and which version. Open a terminal and try the following:
$ python –version
$ python3 –version # Used by most Linux system to invoke python v3+
If Python is installed, one or both of these commands will return the following (Python 3.9.5 is the latest version as off 06-15-2021):
Python 3.9.5
If Python was not installed or a too old version was installed, go to the next section for installing a newer version of Python.
If an acceptable version of Python (3.7+) is already installed, skip this section, otherwise install Python. In this guide we will use the operating system’s package manager. Note that some operating systems do not have a package manager – to read more visit realpython.com. We will only go through how to install on Ubuntu 18.04, Ubuntu 20.04 and above. For further instructions on the different operating systems, visit RealPython installing Python on linux.
For Ubuntu, first run the following to determine the local Ubuntu version:
$ lsb_release -a
Then if the release number is 18.04 or 20.04 and above do the following:
$ sudo apt-get update
$ sudo apt-get install python3 python3-pip
Once installation is complete, run Python with python3 command and pip with pip3 command. Run Python3 –version again to make sure the installation was successful.
To easily run Python, a virtual environment is recommended. For a more detailed description of what the virtual environment is, why it is needed and how to install it visit RealPython.com python virtual environments. Virtual environments are needed to help with storing directories and receiving site packages such as canlib.
Before creating a virtual environment, we need to create a file/directory where we want our virtual environment and projects that will use the environment. In this example the name of the file created is env.
Firstly, make a new directory and go into it using:
$ mkdir python-virtual-environments && cd python-virtual-environments
Then install the python virtual environment with:
$ sudo apt-get install python3-venv
To create a virtual environment in Linux run the following:
$ python3 -m venv .venv –prompt pyproj
“python3” dictates that Linux will launch the latest version of Python 3, “-m” dictates that we want to run a module and “venv” is the name of the module. “.venv” decides the name of the directory where the virtual environment will be created. “–prompt” changes the name of the virtual environment prompt when it is activated and “pyproj” dictates that the name should be “pyproj”.
To activate the virtual environment we need to run the following:
$ source .venv/bin/activate
(pyproj) $
This is a path that dictates the source through .venv to bin and lastly activate.
Now we can use the environment, its packages and resources in isolation. To deactivate the virtual environment, type:
(pyproj) $ deactivate
In Linux, first install CANlib by downloading and installing “Kvaser LINUX Driver and SDK” which can be found on the Kvaser Download page or directly from linuxcan.tar.gz.
If more than just the basic canlib library will be used, the rest of the supported libraries will be available by downloading and installing “Linux SDK library” kvlibsdk.tar.gz. To check it is correctly installed run listChannels which should result in something like:
(pyproj)$ /usr/doc/canlib/examples/listChannels
CANlib version 5.36
Found 4 channel(s).
ch 0: Kvaser USBcan Pro 2xHS v2 73-30130-00752-9, s/n 13406, v3.25.753 (mhydra v8.36.575)
ch 1: Kvaser USBcan Pro 2xHS v2 73-30130-00752-9, s/n 13406, v3.25.753 (mhydra v8.36.575)
ch 2: Kvaser Virtual CAN 0-00000-00000-0, s/n 1, v0.0.0 (kvvirtualcan v8.36.575)
ch 3: Kvaser Virtual CAN 0-00000-00000-0, s/n 1, v0.0.0 (kvvirtualcan v8.36.575)
To install the Python package canlib using pip, activate the virtual environment via PowerShell and run the following command:
.\.venv\Scripts\activate
(pyproj)> pip install canlib
To make sure that canlib was installed correctly, run the following code in a Python interpreter. To open a Python interpreter simply type python or py into PowerShell. To read more about Python interpreters visit Python documentation:
(pyproj)> python
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May 3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type “help”, “copyright”, “credits” or “license” for more information.
>>> from canlib import canlib
>>> canlib.prodversion()
Which should result in something like:
VersionNumber(major=5, minor=36, release=None, build=None)
After canlib has been downloaded, if the following message is shown:
WARNING: You are using pip version 21.1.1; however, version 21.1.2 is available.
You should consider upgrading via the ‘ C:\Users\extac\Pyproj\.venv\scripts\python.exe -m pip install –upgrade pip’ command.
Simply run the command in PowerShell as suggested:
C:\Users\extac\Pyproj\.venv\scripts\python.exe -m pip install –upgrade pip
This will upgrade the pip version to the latest version.
(It is possible to use any single, dual or quad Kvaser CAN interface. A Kvaser Memorator can also be used in interface mode.)
The hardware used in this guide includes a Kvaser USBcan Pro 2xHS v2 and a Kvaser T-cannector v2. Before plugging the hardware together, make sure that the T-cannector is set to 60 ohm (using the switch on the box). The internal termination needed depends on the number of nodes. A load of 60 Ohm will result in a proper recessive level for any number nodes connected to the bus. To read more about termination visit Kvaser.com termination.
To install the USBcan, simply plug it into the computer and the hardware will do the rest. Both CAN contacts need to be plugged into the T-cannector, otherwise channels will not be able to send messages between each other. After the message is sent, any CAN controller that received the message correctly adds an acknowledgement bit at the end of the message. If the message is not acknowledged, the sender will resend the message until it is acknowledged. Therefore, to be able to correctly send a message, it needs to be received. To read more about acknowledgement and CAN messages visit Kvaser.com can messages.
If no hardware is available, then virtual interfaces can be used for the first part of this guide. Two virtual channels are installed automatically on Windows when installing the Kvaser drivers. If you want to read more on how to install additional virtual channels visit Kvaser.com canlib help. In Linux, to download virtual devices, go to linuxcan\virtualcan\virtualcan.h and edit the define statements:
#define NR_CHANNELS 2
#define NR_VIRTUAL_DEV 1
You can read more about installing virtual interfaces at Kvaser.com install Linux, if you want to read more about virtual busses in general, visit Kvaser.com virtual device channel. How to use the virtual interface will be presented later in the guide.
To test that all of the software and hardware has been installed correctly, write the following code in the code editor of your choice, making sure the file is located in the same directory as the virtual environment.
If you do not have a code editor, idle will have been installed with Python on Windows. To use idle with the virtual environment run the following command in PowerShell:
(pyproj)> python -m idlelib
This will open an idle window in which you can open your code file and run the code with f5, or via the run tab. If we instead open idle by right-clicking the .py file and choosing edit with idle, we will not be able to run the code directly with f5 or via the run tab.
The script we need to run within the virtual environment is check_ch and includes the following code:
# check_ch
# Firstly import canlib so that it can be used in the script.
from canlib import canlib
# .getNumberOfChannels() is used to detect the number of channels and
# the number is saved in the variable num_channels.
num_channels = canlib.getNumberOfChannels()
# num_channels is printed out as text so that the user can see how many
# channels were found.
print(f"Found {num_channels} channels")
# Next a for loop is created. This loop will repeat the code within for each
# channel that was detected.
for ch in range(num_channels):
# The data of each specific channel is saved in chd.
chd = canlib.ChannelData(ch)
# Lastly the channel, channel name, product number, serial number, and local
# channel number on the device are printed.
print(f"{ch}. {chd.channel_name} ({chd.card_upc_no.product()}:{chd.card_serial_no}/{chd.chan_no_on_card})")
To run the code from PowerShell, go to the directory where the file and virtual environment are located. Start the virtual environment and launch the script called check_ch.py with:
.\.venv\Scripts\activate
(pyproj)> py check_ch.py
This should result in
Found 4 channels
0. Kvaser USBcan Pro 2xHS v2 (channel 0) (00752-9:13406/0)
1. Kvaser USBcan Pro 2xHS v2 (channel 1) (00752-9:13406/1)
2. Kvaser Virtual CAN Driver (channel 0) (00000-0:0/0)
3. Kvaser Virtual CAN Driver (channel 1) (00000-0:0/1)
Assuming that all of the software and hardware was installed correctly, 0-3 are the channels available on the CANusb. In this example, we will only use channel 0 and 1. On Linux there will be no virtual channel by default.
The Kvaser Device Guide can also be used. Simply open the application and we should see something like the following:
In this window we can see that the Kvaser USBcan Pro 2xHS v2 we plugged in appears at the top of the list.
To send a basic CAN message, create a script named send_msg.py containing the following code (make sure that the script is located within the same folder as the virtual environment):
#send_msg
# The CANlib library is initialized when the canlib module is imported. To be
# able to send a message, Frame also needs to be installed.
from canlib import canlib, Frame
# Firstly, open two CAN channels, one to send the message and one to receive.
# Note that there needs to be a channel to receive, as otherwise the message
# can not be sent. In this example the channels are named ch_a and ch_b. To
# open the channels call on the openChannel method inside of canlib and, as an
# input put in channel=0 and channel=1. Where 0 and 1 represents the two
# CANlib channels 0 and 1.
ch_a = canlib.openChannel(channel=0)
ch_b = canlib.openChannel(channel=1)
# After opening the channel, we need to set the bus parameters. Some
# interfaces keep their params from previous programs. This can cause problems
# if the params are different between the interfaces/channels. For now we will
# use setBusParams() to set the canBitrate to 250K.
ch_a.setBusParams(canlib.canBITRATE_250K)
ch_b.setBusParams(canlib.canBITRATE_250K)
# The next step is to Activate the CAN chip for each channel (ch_a and ch_b in
# this example) use .busOn() to make them ready to receive and send messages.
ch_a.busOn()
ch_b.busOn()
# To transmit a message with (11-bit) CAN id = 123 and contents (decimal) 72,
# 69, 76, 76, 79, 33, first create the CANFrame (CANmessage) and name it. In
# this example, the CANFrame is named frame. Then send the message by calling on
# the channel that will act as the sender and use .write() with the CANFrame
# as input. In this example ch_a will act as sender.
frame = Frame(id_=123, data=[72, 69, 76, 76, 79, 33], flags=canlib.MessageFlag.STD )
ch_a.write(frame)
# To make sure the message was sent we will attempt to read the message. Using
# timeout, only 500 ms will be spent waiting to receive the CANFrame. If it takes
# longer the program will encounter a timeout error. read the CANFrame by calling
# .read() on the channel that receives the message, ch_b in this example. To
# then read the message we will use print() and send msg as the input.
msg = ch_b.read(timeout=500)
print(msg)
# After the message has been sent, received and read it is time to inactivate
# the CAN chip. To do this call .busOff() on both channels that went .busOn()
ch_a.busOff()
ch_b.busOff()
# Lastly, close all channels with close() to finish up.
ch_a.close()
ch_b.close()
# Depending on the situation it is not always necessary or preferable to go of
# the bus with the channels and, instead only use close(). But this will be
# talked more about later.
To run the previous program, activate your virtual environment and run the script using powershell. Running the program will result in something like the following:
> .\.venv\Scripts\activate
(pyproj)> py send_msg.py
Frame(id=123, data=bytearray(b'HELLO!'), dlc=6, flags=<MessageFlag.STD: 2>, timestamp=9)If we want to use the virtual interface and the virtual channels, we need to change the openchannel commands. Firstly we need to change the numbers from 0 and 1 to 2 and 3 to represent the virtual channels. Then we need to add a flag (another input) that says ACCEPT_VIRTUAL to define that a virtual channel will be used and accepted. The command will now look like:
canlib.openChannel(channel=2, flags=canlib.open.ACCEPT_VIRTUAL)
If we do not add the ACCEPT_VIRTUAL flag we will receive a Specified device not found (-3). It is also important to note that a virtual channel can only communicate with another virtual channel.
The code used in send a CAN message is a very standard and straightforward way to write the script we want. Using Python, however, we can write the code in a more “Pythonic way”. This will lead to the following script names send_msg_pyt.py:
# send_msg_pyt
from canlib import canlib, Frame
# instead of opening the two channels and closing them one by one, we will use a
# with statement. Using the with statement to open one or more channels with
# canlib.openChannel(i) as ch_x. Within this with statement we will write the
# rest of the code.
with canlib.openChannel(2) as ch_a, canlib.openChannel(3) as ch_b:
# Instead of going on bus with "copy-paste" for each channel, we will use a
# for-loop. Within this loop we will go through a list of all channels opened
# using the with statement. Currently we only have two channels, which makes
# the for-loop somewhat unnecessary. However, when we start using more
# channels the for-loop will be preferred.
for ch in [ch_a, ch_b]:
ch.busOn()
frame = Frame(id_=123, data=[72, 69, 76, 76, 79, 33])
ch_a.write(frame)
msg = ch_b.read(timeout=500)
print(msg)
# After we run out of code within the with statement and exit it, we don't
# need to manually close it or go off bus. The channels that were open using
# the with statement will be automatically closed, and with the channels being
# closed they also went off the bus.
While writing several messages, we might want to confirm that they were sent properly. To do this we will make use of the command writeWait(). writeWait does the same as write when it comes to sending a message, but it also gives a timeout limit for how long it will wait for the message to be sent. The command may look like writeWait(frame, timeout=500), which will send a message with the details given by frame and wait 500 milliseconds for it to be sent before returning an error message Timeout occurred (-7). WriteWait can be used when sending one or several messages. When sending several messages we can use writeWait on every message, but this will take some time to execute and is not very efficient. Instead we can use write on all messages apart from the last one which will be writeWait. If one message fails to be sent properly, all after will fail and the timeout error Timeout occured (-7) will be raised by writeWait.
To test writeWait we will make two scripts called send_msg_wait.py and send_msgs_wait.py which will be based on the send message code but with some changes. The first script send_msg_wait.py will send a message using writeWait to send one successful message and one unsuccessful message:
# send_msg_wait
from canlib import canlib, Frame
# We will now open three channels, two from the USBcan and one on
# the leaf pro which we will not connect to the T-cannector. We will use the
# leaf pro channel ch_c to send errorframes.
with canlib.openChannel(2) as ch_a, canlib.openChannel(3) as ch_b, canlib.openChannel(4) as ch_c:
for ch in [ch_a, ch_b, ch_c]:
ch.busOn()
frame = Frame(id_=123, data=[72, 69, 76, 76, 79, 33])
# Instead of using write we will now use writeWait(). We will attempt to send
# a message for 500 milliseconds, if the message is not sent we will receive a
# Timeout occured error.
ch_a.writeWait(frame, timeout=500)
# We will now try to send a message with the channel not connected to the
# T-cannector. This should result in a Timeout occurred error.
ch_c.writeWait(frame, timeout=500)
msg = ch_b.read(timeout=500)
print(msg)
In the next script send_msgs_wait-py we will send multiple messages and using waitWrite to make sure that the messages were sent:
# send_msgs_wait
from canlib import canlib, Frame
# We will now open three channels, two from the USBcan and one on the
# leaf pro which we will not connect to the T-cannector. We will use the
# leaf pro channel ch_c to send errorframes.
with canlib.openChannel(2) as ch_a, canlib.openChannel(3) as ch_b, canlib.openChannel(4) as ch_c:
for ch in [ch_a, ch_b, ch_c]:
ch.busOn()
frame = Frame(id_=123, data=[72, 69, 76, 76, 79, 33])
# We will now send 199 messages in a for-loop and after the loop use writeWait
# to send a last message, to make sure all previous messages were sent.
for i in range(199):
ch_a.write(frame)
ch_a.writeWait(frame, timeout=500)
msg = ch_b.read(timeout=500)
print(msg)
# We will now do the same with the ch_c channel not connected to the
# T-cannector. This should result in a timeout error.
for i in range(199):
ch_c.write(frame)
ch_c.writeWait(frame, timeout=100)
msg = ch_b.read(timeout=500)
print(msg)
While working with Python canlib and CAN interfaces, there are multiple errors and problems we can be faced with. We will now go through a couple of common error messages and problems:
To fix this, firstly go offbus with the channel that received the error to stop the blinking red light. Then make sure there are at least two channels connected to the T-cannector and on bus in normal mode, one to send the message and one to receive it.
There are multiple ways to find information about CANlib. The best source of information about canlib and commands used with canlib is pycanlib.readthedocs.io. If readthedocs does not work, then there are multiple blogs that explain different aspects of canlib on Kvaser’s website, Kvaser.com.. On the Kvaser website we can also find more information under the support heading and in the canlib webhelp. For example, there are basic resources to get started with Kvaser hardware, documentation such as user guides, developer tools and lastly calculators for calculating bitrate. If you do not find what you are looking for, support is always available. Simply email your issues, problems and questions to SUPPORT@KVASER.COM.
For example, in the previous script we want to read a message. But we do not want to move on to the next line until the message has been properly received and read. Furthermore we also want the program to stop and return an error message if the message could not be read. To find the best way to accomplish this, see the documentation at pycanlib.readthedocs.
To find the right documentation we first expand the “Using canlib” tab, since we are using canlib. Next step is how we are using it and what for. Currently we want to send a message and luckily there is a tab called “Send and Receive”, so this can be expanded. Next we see that Reading Messages is also a heading so we click on it to go directly to reading messages. While reading under the “read“ heading we eventually come to a list of functions. One of these states the following: “If you want to wait until a message arrives (or a timeout occurs) and then read it, call read with a timeout”. This sounds like what we are looking for. To read more about the function we can go directly to the “read” function by clicking the link labeled “read”. We can now see that “read” has a parameter called “timeout” which is an integer. This integer dictates how many milliseconds the program will wait for the message to be delivered before returning a timeout error. We have now found what we were looking for and can enter this into our code as channel.read(timeout = 500) for the program to wait 500 milliseconds.
If you have taken a break or just forgotten the used commands/procedures, please use this little list of powerful commands and instructions.
