Socketcan level II driver
- Available for: Linux
- Driver Linux: libvscpl2_socketcandrv.so
- Socketcan is not available on Windows
This driver interface SocketCAN, the official CAN API of the Linux kernel, has been included in the kernel for a long time now. Meanwhile, the official Linux repository has device drivers for all major CAN chipsets used in various architectures and bus types. SocketCAN offers the user a multiuser capable as well as hardware independent socket-based API for CAN based communication and configuration. Socketcan nowadays give access to the major CAN adapters that is available on the market. Note that as CAN only can handle Level I events only events up to class < 1024 can be sent to this device. Other events will be filtered out.
Supports CAN FD.
You can find binary installation files here
You install the driver using the debian package with
sudo apt install ./vscpl2drv-socketcan_15.0.0.deb
the driver will be installed to the folder /var/lib/vscp/drivers/level2/.
After installing the driver you need to add configuration information for it to the vscpd.conf file (/etc/vscp/vscpd.json). Se the configuration section below.
You also need to set up the configuration file for the driver. If you don't need to dynamically edit the content of this file a good and safe location for it is in the /etc/vscp/ folder alongside the VSCP daemon configuration file.
If you need to do dynamic configuration (write enabled) we recommend that you create the file in the /var/lib/vscp/ folder or any location you find to be convenient.
A sample configuration file is available in /usr/share/vscpl2drv-socketcan folder after installation. The sample configuration file is named socketcan.json.
You need build-essentials and git installed on your system
sudo apt update && sudo apt -y upgrade
sudo apt install build-essential gitTo build this driver you to clone the driver source
git clone --recurse-submodules -j8 https://github.com/grodansparadis/vscpl2drv-socketcan.gitYou also need to have the vscp main repository checkout at the same location as you checkout the driver. Do this with
git clone --recurse-submodules -j8 https://github.com/grodansparadis/vscp.gitThe build used pandoc for man-page generation so you want the man pages you should install it first with
sudo apt install pandoc
If you skip it the build will give you some errors (which you can ignore if you don't care about the man page)
Now go into the repository and build the driver
cd vscpl2drv-socketcan
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/
make
sudo make install
Skip "-DCMAKE_INSTALL_PREFIX=/" if you want the "local" prefix to all install paths except for the driver.
If you want to generate binary packages issue
sudo cpackDefault install folder when you build from source is /var/lib/vscp/drivers/level2. You can change this with the --prefix option in the make install step. For example
make DESTDIR==/usr/local install
to install to /usr/local/var/lib/vscp/drivers/level2.
The VSCP daemon configuration file is (normally) located at /etc/vscp/vscpd.json (For the curious: VSCP daemon full sample config file for Linux). To use the vscpl2drv-socketcan.so driver there must be an entry in the drivers level2 section
"drivers" : {
"level2" : [with the following format
{
"enable" : true,
"name" : "socketcan",
"path-driver" : "/var/lib/vscp/drivers/level2/libvscpl2drv-socketcan.so",
"path-config" : "/etc/vscp/socketcan.json",
"guid" : "FF:FF:FF:FF:FF:FF:FF:F5:33:33:00:00:00:00:00:00",
"mqtt": {
"bind": "",
"host": "test.mosquitto.org",
"port": 1883,
"mqtt-options": {
"tcp-nodelay": true,
"protocol-version": 311,
"receive-maximum": 20,
"send-maximum": 20,
"ssl-ctx-with-defaults": 0,
"tls-ocsp-required": 0,
"tls-use-os-certs": 0
},
"user": "vscp",
"password": "secret",
"clientid": "the-vscp-daemon",
"publish-format": "json",
"subscribe-format": "auto",
"qos": 1,
"bcleansession": false,
"bretain": false,
"keepalive": 60,
"bjsonmeasurementblock": true,
"topic-daemon-base": "vscp-daemon/{{guid}}/",
"topic-drivers": "drivers",
"topic-discovery": "discovery",
"reconnect": {
"delay": 2,
"delay-max": 10,
"exponential-backoff": false
},
"tls": {
"cafile": "",
"capath": "",
"certfile": "",
"keyfile": "",
"pwkeyfile": "",
"no-hostname-checking": true,
"cert-reqs": 0,
"version": "",
"ciphers": "",
"psk": "",
"psk-identity": ""
},
"will": {
"topic": "vscp-daemon/{{srvguid}}/will",
"qos": 1,
"retain": true,
"payload": "VSCP Daemon is down"
},
"subscribe" : [
{
"topic": "remote-vscp/{{guid}}/#",
"qos": 0,
"v5-options": 0,
"format": "auto"
}
],
"publish" : [
{
"topic": "vscp/{{guid}}/{{class}}/{{type}}/{{nodeid}}",
"qos": 1,
"retain": false,
"format": "json"
}
]
}
}Set enable to "true" if the driver should be loaded by the VSCP daemon.
This is the name of the driver. Used when referring to it in different interfaces.
This is the path to the driver. If you install from a Debian package this will be /var/lib/vscp/drivers/level2/libvscpl2drv-socketcan.so.
This is the path to the driver configuration file (see below). This file determines the functionality of the driver. A good place for this file is in /etc/vscp/socketcan.json It should be readable only by the user the VSCP daemon is run under (normally vscp) as it holds credentials to log in to a remote VSCP tcp/ip link interface. Never make it writable at this location.
All level II drivers must have a unique GUID. There is many ways to obtain this GUID, Read more here. The tool vscp_eth_to_guid is a useful tool that is shipped with the VSCP daemon that will get you a unique GUID if you are working on a machine with an Ethernet interface.
See the VSCP configuration documentation for info about this section. It is common for all drivers.
On start up the configuration is read from the path set in the driver configuration of the VSCP daemon, usually /etc/vscp/conf-file-name and values are set from this location. If the write parameter is set to "true" the above location is a bad choice as the VSCP daemon will not be able to write to it. A better location is /var/lib/vscp/drivername/configure-name.json or some other writable location.
The configuration file have the following format
{
"debug" : true,
"write" : false,
"interface": "vcan0",
"flags": 0,
"key-file": "/var/vscp/vscp.key",
"encryption" : "none|aes128|aes192|aes256",
"logging": {
"console-enable": true,
"console-level": "trace",
"console-pattern": "[vcpl2drv-socketcan %c] [%^%l%$] %v",
"file-enable": true,
"file-log-level": "debug",
"file-log-path" : "/var/log/vscp/vscpl1drv-socketcan.log",
"file-log-pattern": "[vcpl2drv-socketcan %c] [%^%l%$] %v",
"file-log-max-size": 50000,
"file-log-max-files": 7
},
"filter" : {
"in-filter" : "incoming filter on string form",
"in-mask" : "incoming mask on string form",
"out-filter" : "outgoing filter on string form",
"out-mask" : "outgoing mask on string form"
}
}Set debug to true to get debug information written to the log file. This can be a valuable help if things does not behave as expected.
If write is true dynamic changes to the configuration file will be possible to save dynamically to disk. That is, settings you do at runtime can be saved and be persistent. The safest place for a configuration file is in the VSCP configuration folder /etc/vscp/ but for dynamic saves are not allowed if you don't run the VSCP daemon as root (which you should not). Next best place is to use the folder /var/lib/vscp/drivers/level2/configure.json. A default configuration file is written to /usr/share/vscp/drivers/level2/vscpl2drv-socketcan when the driver is installed.
If you never intend to change driver parameters during runtime consider moving the configuration file to the VSCP daemon configuration folder is a good choice.
All level II drivers must have a unique GUID. There is many ways to obtain this GUID, Read more here.
interface (For example can0/can1/can2...)
The parameter interface is the socketcan interface to use. Typically this is can0, can0, can1... Defaults is vcan0 the first virtual interface. If the variable prefix_interface is available it will be used instead of the configuration value.
This is configuration flags for the socketcan interface. Currently not used.
Path to file with encryption key. Currently not used.
Encryption used. Currently not used.
Options for driver logging is set here.
Set to true to log to the console.
Logging level for console log. Set to one of "off | critical | error | warn | info | debug | trace".
The logging pattern for the console. The default is
"[vcpl2drv-socketcan] [%^%l%$] %v"
Patterns are described here.
Set to true to log to the console.
Set to one of "off | critical | error | warn | info | debug | trace" to set log level.
This is a writable path to a file that will get log information written to it. This can be a valuable to have if things does not behave as expected.
The logging pattern for the console. The default is
"[vcpl2drv-socketcan] [%^%l%$] %v"
Patterns are described here.
Max size for log file before it will rotate and a new file is created. Default is 5 Mb.
Max number of log files to keep. Default is 7
Main filter for incoming and outgoing events. Default is to send and receive all events. The truth table for VSCP filter/masks is described here.
Filter and mask is a way to select which events is received by the driver. A filter have the following format
priority,vscpclass,vscptype,guid
All values can be give in decimal or hexadecimal (preceded number with '0x'). GUID is always given i hexadecimal (without preceded '0x').
Default: setting is
0,0,0,00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Read the vscpd manual for more information about how filter/masks work.
The default filter/mask pair means that all events are received by the driver.
Filter and mask is a way to select which events is received by the driver. A mask have the following format
priority,vscpclass,vscptype,guid
All values can be give in decimal or hexadecimal (preceded number with '0x'). GUID is always given i hexadecimal (without preceded '0x').
The mask have a binary one ('1') in the but position of the filter that should have a specific value and zero ('0') for a don't care bit.
Default setting is
0,0,0,00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Read the vscpd manual for more information about how filter/masks work.
The default filter/mask pair means that all events are received by the driver.
Incoming filter on string form. The string filter has the form "filter-priority, filter-class, filter-type, filter-GUID"
Incoming mask on string form. The string mask has the form "mask-priority, mask-class, mask-type, mask-GUID”.
Outgoing filter on string form. The string filter has the form "filter-priority, filter-class, filter-type, filter-GUID"
Outgoing mask on string form. The string mask has the form "mask-priority, mask-class, mask-type, mask-GUID”.
The easiest way to test the vscpl2drv-socketcan driver is to create a virtual CAN interface. You should first of all make sure that the necissary modules are loaded on your system. You do this with
modprobe can
modprobe can_raw
modprobe can-bcm
modprobe can-dev
modprobe can-gw
modprobe vcanThen you should create the virtual CAN interface. You can do this with
sudo ip link add dev vcan0 type vcanor if you want a CAN FD interface
ip link add dev vcan0 type vcan
ip link set vcan0 mtu 72Then you have to bring up the virtual interface
sudo ip link set up vcan0
You can use
ip link showto display information about your interfaces.
With
candump vcan0
you can check CAN frames sent on this interface.
You can use cansend to send frames to the interface
cansend vcan0 0000eb00#0011
or send random data with
cangen -e -f vcan0 -v vcan0
Remember that VSCP only use extended CAN frames (the -e switch). Here we also use the -f switch to enable CAN FD frames.
You have a good tutorial here describing the use of the virtual CAN interface.
To connect to a real CAN bus you need a CAN adapter like TouCAN. There are other adapters to of course but I list (and recommend) TouCAN here because Gediminas Simanskis the guy who has made it, has been around VSCP for many, many years now and on top of this is one of the best hardware engineers I know in the world.
This is a link to some info about setting up a real world CAN interface. But search on socketcan and you will find plenty of information.
- The VSCP site - https://www.vscp.org
- The VSCP document site - https://docs.vscp.org/
- VSCP discussions - https://github.com/grodansparadis/vscp/discussions
Copyright (C) 2000-2021 Åke Hedman, The VSCP Project - MIT license.