milesstoetzner / stoetzms-can2x

can2x is a simple utility for connecting a CAN bus bidirectional with one or multiple CAN busses over the network using common web protocols, such as HTTP, MQTT, Socket.IO, and WebSockets.

can2x

This project is a research prototype. TRL is about 3 heading towards 4.

can2x is a simple utility for connecting a CAN bus bidirectional with one or multiple CAN busses over the network using common web protocols, such as HTTP, MQTT, Socket.IO, and WebSockets.

Table of Contents

• Overview
• Features
• Example
• Installation
• Requirements
• Commands
  • bridge start
  • bus start
  • vcan check
  • vcan start
  • vcan stop
• CAN Message
• Limitations
• Similar Projects
• Dependencies
• Notes
• Keywords
• Acknowledgements

Overview

can2x supports various sources and targets when bridging CAN messages. A source, such as a CAN bus in a first computing environment, forwards the CAN message to the target, such as a Socket.IO server running on a second computing environment. This target then acts as a source and forwards the CAN message to another target, such as a CAN bus connected to the second computing environment. It is also possible to have a arbitrary long chains of different of such bridges. Also, most bridges are bidirectional, thus, CAN message are also bridged backward. In addition, a can2x bus is able to connect multiple can2x bridges.

Features

can2x provides the following features.

• connect CAN busses over the network, e.g., public internet
• bidirectional bridges
• unidirectional bridges
• multi-client bidirectional busses
• protocols/ sources/ targets
  • CAN
  • Console/ stdout
  • File
  • HTTP
  • MQTT
  • Socket.IO
  • Websocket (WS)
• open source

Example

In the following example, we connect a vCAN on the source host to a vCAN on the target host using Socket.IO.

On the target host, start the vCAN and the Socket.IO server.

sudo can2x vcan start
can2x bridge start --source socketio --source-host 0.0.0.0 --target can

Then, on the target host, listen to the vCAN.

sudo apt-get update -y
sudo apt-get install can-utils -y
candump can2x

On the source host, start the vCAN and the Socket.IO client. You need to replace the <TARGET HOST IP> with the actual IP of your target host.

sudo can2x vcan start
can2x bridge start --source can --target socketio --target-endpoint http://<TARGET HOST IP>:3000

Then, on the source host, send a message to the vCAN.

sudo apt-get update -y
sudo apt-get install can-utils -y
cansend can2x 01a#11223344AABBCCDD

On the target host, we can observe the CAN message.

can2x  01A   [8]  11 22 33 44 AA BB CC DD

Installation

Install can2x system-wide using npm. Ensure, that npm bin -g is in your $PATH.

npm install --global can2x

Alternatively, install can2x system-wide using yarn (classic). Ensure, that yarn global bin is in your $PATH.

yarn global add can2x

Requirements

can2x has the following requirements.

• Linux
• SocketCAN, thus, Git Bash and WSL are not supported

Commands

can2x supports the following commands.

Command bridge start

The following command starts a can2x bridge.

can2x bridge start [options]

The following options are supported.

Option	Type	Default	Required	Description
--source	can, console, file, http, mqtt, socketio, ws	can	false
--source-port	number	3000	false
--source-host	string	localhost	false
--source-event	string	can2x	false
--source-topic	string	can2x	false
--source-name	string	can2x	false
--source-id	number	none	false
--source-data	number[]	none	false
--source-ext	boolean	none	false
--source-rtr	boolean	none	false
--source-file	string	none	false
--source-bidirectional	boolean	true	false
--target	can, console, file, http, mqtt, socketio, ws	console	false
--target-endpoint	string	none	false
--target-event	string	can2x	false
--target-topic	string	can2x	false
--target-name	string	can2x	false
--target-file	string	none	false
--target-bidirectional	boolean	true	false

Sources

can2x supports the following sources.

CAN Bus

can2x supports a can2x bridge, i.e., --source can. The following options are supported.

Option	Type	Default	Required	Description
--source-name	string	can2x	false
--source-bidirectional	boolean	true	false

Console

can2x supports a console2x bridge, i.e., --source console. The following options are supported.

Option	Type	Default	Required	Description
--source-id	number	none	true
--source-data	number[]	none	true

File

can2x supports a file2x bridge, i.e., --source file. The following options are supported.

Option	Type	Default	Required	Description
--source-file	string	none	true

HTTP

can2x supports a http2x bridge, i.e., --source http. The following options are supported.

Option	Type	Default	Required	Description
--source-port	number	3000	false
--source-host	string	localhost	false

MQTT

can2x supports a mqtt2x bridge, i.e., --source mqtt. The following options are supported.

Option	Type	Default	Required	Description
--source-port	number	3000	false
--source-host	string	localhost	false
--source-topic	string	can2x	false
--source-bidirectional	boolean	true	false

Socket.IO

can2x supports a socketio2x bridge, i.e., --source socketio. The following options are supported.

Option	Type	Default	Required	Description
--source-port	number	3000	false
--source-host	string	localhost	false
--source-event	string	can2x	false
--source-bidirectional	boolean	true	false

WebSocket

can2x supports a ws2x bridge, i.e., --source ws. The following options are supported.

Option	Type	Default	Required	Description
--source-port	number	3000	false
--source-host	string	localhost	false
--source-bidirectional	boolean	true	false

Targets

can2x supports the following targets.

CAN Bus

can2x supports a x2can bridge, i.e., --target can. The following options are supported.

Option	Type	Default	Required	Description
--target-name	string	can2x	false
--target-bidirectional	boolean	true	false

Console

can2x supports a x2console bridge, i.e., --target console. No options are supported.

File

can2x supports a x2file bridge, i.e., --target file. The following options are supported.

Option	Type	Default	Required	Description
--target-file	string	none	true

HTTP

can2x supports a x2http bridge, i.e., --target http. The following options are supported.

Option	Type	Default	Required	Description
--target-endpoint	string	none	true

MQTT

can2x supports a x2mqtt bridge, i.e., --target mqtt. The following options are supported.

Option	Type	Default	Required	Description
--target-endpoint	string	none	true
--target-topic	string	can2x	false
--target-bidirectional	boolean	true	false

Socket.IO

can2x supports a x2socketio bridge, i.e., --target socketio. The following options are supported.

Option	Type	Default	Required	Description
--target-endpoint	string	none	true
--target-event	string	can2x	false
--target-bidirectional	boolean	true	false

Websocket

can2x supports a x2ws bridge, i.e., --target ws. The following options are supported.

Option	Type	Default	Required	Description
--target-endpoint	string	none	true
--target-bidirectional	boolean	true	false

Command bus start

The following command starts a can2x bus.

can2x bus start [options]

The following options are supported.

Option	Type	Default	Required	Description
--bus	can, mqtt, socketio, ws	socketio	false
--port	number	3000	false
--host	string	localhost	false
--event	string	can2x	false
--name	string	can2x	false

can2x supports the following busses.

CAN Bus

can2x supports a can bus, i.e., --bus can. The following options are supported.

Option	Type	Default	Required	Description
--name	string	can2x	false

MQTT

can2x supports a mqtt bus, i.e., --bus mqtt. The following options are supported.

Option	Type	Default	Required	Description
--port	number	3000	false
--host	string	localhost	false
--topic	string	can2x	false

Socket.IO

can2x supports a socketio bus, i.e., --bus socketio. The following options are supported.

Option	Type	Default	Required	Description
--port	number	3000	false
--host	string	localhost	false
--event	string	can2x	false

Websocket

can2x supports a ws bus, i.e., --bus ws. The following options are supported.

Option	Type	Default	Required	Description
--port	number	3000	false
--host	string	localhost	false

Command vcan check

The following command checks if required module exist.

can2x vcan check

No options are supported.

Command vcan start

The following command starts a vCAN using SocketCAN.

can2x vcan start [options]

The following options are supported.

Option	Type	Default	Required	Description
--name	string	can2x	false	The name of the vCAN.

Command vcan stop

The following command stops a vCAN using SocketCAN.

can2x vcan stop [options]

The following options are supported.

Option	Type	Default	Required	Description
--name	string	can2x	false	The name of the vCAN.

CAN Message

A CAN message is internally represented as follows.

Keyword	Type	Description
id	number	The decimal id of the CAN message.
data	number[]	The decimal payload of the CAN message.
ext	boolean
rtr	boolean
origin?	string	The origin of the message used, e.g., for MQTT to detect own published messages

Limitations

• security aspects, such as encryption, authentication, and authorization, are not supported
• there are no guarantees, e.g., the ordering of messages or even if a message is delivered at all

Similar Projects

It is worth to check out the following projects.

• can2udp
• can2mqtt
• cannelloni

Dependencies

The licenses of the dependencies that can2x uses in production are as follows.

license-checker --production --summary --onlyAllow "MIT;Apache-2.0;Python-2.0;BSD-2-Clause;BSD-3-Clause;ISC;CC-BY-3.0;CC0-1.0;PSF;0BSD;BlueOak-1.0.0"
├─ MIT: 193
├─ ISC: 58
├─ Apache-2.0: 3
├─ BSD-2-Clause: 2
├─ BSD-3-Clause: 2
├─ BlueOak-1.0.0: 2
└─ Python-2.0: 1

Notes

Some helpful notes.

Manually Starting a vCAN

The following commands start a vCAN.

sudo modprobe can
sudo modprobe can_raw
sudo modprobe vcan

ip link add vcan0 type vcan
ip link set vcan0 up

Manually Stopping a vCAN

The following commands stop a vCAN.

ip link set vcan0 down
ip link delete vcan0

Keywords

http, mqtt, can, bridge, ws, websocket, socketio, vcan, can2http, can2mqtt, can2socketio, can2x, can2ws, virtual

Acknowledgements

This project is s partially funded by the German Federal Ministry for Economic Affairs and Climate Action (BMWK) as part of the Software-Defined Car (SofDCar) project (19S21002).