This README is for the latest, possibly unreleased, version. For the documentation on the 2.x releases, check the releases/2.x
branch.
Bindings for SocketCAN's CAN_RAW, CAN_BCM and CAN_ISOTP sockets with full support for blocking and non-blocking IO. Non-blocking IO is possible using the epoll module, that provides an API very similar to Java's Selector API.
Implementing Java's SelectableChannel API is not possible with EPoll and SocketCAN due to various hardcoded assumptions in the JDK.
- Creating and binding CAN_RAW, CAN_BCM and CAN_ISOTP sockets
- Sending and receiving standard CAN and CAN-FD frames with and without EFF
- Getting and setting all supported socket options
- Event-driven networking using an IOSelector
- Fairly robust test coverage
- Support for other CAN protocols (e.g. CAN_MCNET)
- CAN XL
- A netty integration (see #20)
- BSD Support
- io_uring Support
Pull requests are welcome!
- obd4s: A Scala library for OBD-II communication with vehicles.
- VirtualECU: An ECU simulator to test OBD-II clients against.
- Apache PLC4X: Apache PLC4X brings support for various PLC systems. JavaCAN serves as the transport layer for CANopen and other CAN related protocols.
This project is a wrapper around SocketCAN, which is a Linux kernel module that implements CAN communication. As such, only Linux can be supported. For this reason, the custom Selector will also only use epoll (Linux API for event-driven IO), as support for other OS' is not possible anyway.
The project uses dockcross to cross-compile its native components for various Linux supported platforms.
Currently, the full build process includes the following architectures:
- x86_32
- x86_64
- armv6
- armv7
- armv7a
- armv7l (musl libc, linked statically)
- aarch64
- riscv32
- riscv64
The implementation can handle word sizes up to 64 bit and is byte order aware. If you need another architecture, feel free to ask for it! Alternatively read how to build another architecture down below.
- Compile yourself or get a compiled release from Maven Central
- Install the native components into your
LD_LIBRARY_PATH
or configure the appropriate Java properties (See next section) - Create a channel by calling one of the
CanChannels.new...Channel()
methods - Create a
NetworkDevice
using its staticlookup(String)
method - Bind the channel to an interface using the
bind(CanDevice)
method
Usage example can be found in the unit tests or in the related projects mentioned above.
Remember: JavaCAN is a fairly thin wrapper around Linux syscalls. Even though some aspects of the low-level C API are hidden, most Java APIs in this library will at some point call into a
(usually similarly named) C API and as such inherits all of its properties. For example RawCanChannel.close()
translates to a call to close()
on the underlying file descriptor, so their behaviour
should be identical. So if the behaviour of a certain API is unclear, a look into the man pages of related Linux syscalls might help. Feel free to still request additional documentation in the issues
on GitHub!
The library relies on several native (JNI) components. By default, these components are either loaded from the standard library path (LD_LIBRARY_PATH
/ java.library.path
) or are extracted from
the classpath into a temporary folder.
While JavaCAN 2.x bundled the native components, starting with the 3.x release series no native components are bundles with the core libraries. Dedicated jar files are generated for each native component (classified by their architecture). JavaCAN will not attempt to discover the location of a library version appropriate for the correct architecture. This is instead left to the downstream application developer.
There are a few approaches to get the correct native libraries loaded:
- Installing the libraries into the library path (the
LD_LIBRARY_PATH
environment variable or thejava.library.path
property) - Configuring the
javacan.native.javacan-<module>.path
property to tell JavaCAN the exact file system path where the native component is located - Configuring the
javacan.native.javacan-<module>.classpath
property to tell JavaCAN the exact location on the classpath where the native component is located - Adding one of the architecture-specific jar files into the classpath (either add compile time or runtime)
Application that are intended to run on a single architecture or that build architecture-specific version already, the simplest solution is to bundle the provided architecture-specific jar files matching the build architecture.
For applications supporting multiple architectures at once I'd recommend dynamically adding the architecture-specific jar file at runtime or to repackage the available native libraries and
dynamically configuring the javacan.native.javacan-<module>.path
properties in the CLI or before any JavaCAN classes are loaded.
The value for the <module>
placeholder used throughout this section is core
and if the EPoll support is used, an additional option with epoll
for <module>
is necessary.
In case you have issues, have a look at the troubleshooting document.
For compilation:
- Maven 3 or newer
- A locally running docker daemon and permissions to run containers
- Java 8 (Maven will enforce this)
- Bash
For tests:
- A fairly recent Linux kernel with CAN support
- The can-isotp kernel module loaded (Kernel 5.10 with
CONFIG_CAN_ISOTP
enabled or the out-of-tree module) - can-utils installed in the
PATH
- A CAN interface named "vcan0"
- Java 8 or newer installed
- a libc (unless compiled statically)
For usage:
- A fairly recent Linux kernel with CAN support
- For ISOTP channels, the can-isotp kernel module loaded (Kernel 5.10 with
CONFIG_CAN_ISOTP
enabled or the out-of-tree module) - Java 8 or newer installed
- A few kilobytes of disk space to extract the native components
- a libc (unless compiled statically)
By default, the project only builds the x86_64 native components (single-architecture
maven profile):
mvn clean package
The single-architecture
profile can build different architectures by specifying the properties javacan.architecture
and dockcross.image
. This can be used to build architectures
that are not currently included in JavaCAN releases. Unit tests will be executed with the architecture being built. Overriding the test architecture is not possible, since other architectures are
not being built. By default, the libraries are linked dynamically, by setting the dockcross.link-mode
property to static
it can be switched to static linking, however not every dockcross image
supports static linking (musl libc based images usually do).
In order to build all architectures that are currently part of releases, the all-architectures
maven profile must be activated:
mvn clean package -Pall-architectures
The all-architectures
profile will execute the tests using the x86_64
libraries by default. To override this the property javacan.test.architecture
can be set to any other architecture that
is part of the build.
If the architecture you are building on is not part of the build, then tests will always fail. To prevent this you have to disable the test
maven profile:
mvn clean package -P!test
Each architecture in the all-architectures
profile can have its dockcross image and linking mode overridden by setting the dockcross.image.<arch>
and/or dockcross.link-mode.<arch>
properties.