CoAP/DTLS Java Implementation
Eclipse Californium is a Java implementation of RFC7252 - Constrained Application Protocol for IoT Cloud services. Thus, the focus is on scalability and usability instead of resource-efficiency like for embedded devices. Yet Californium is also suitable for embedded JVMs.
You need to have a working maven installation to build Californium. Then simply run the following from the project's root directory:
$ mvn clean install
Executable JARs of the examples with all dependencies can be found in the
The build-process in branch
masteris tested for jdk 7, jdk 8, jdk 11, jdk 15 and jdk 16. For jdk 7 the revapi maven-plugin is disabled, it requires at least java 8.
To generate the javadocs, add "-DcreateJavadoc=true" to the command line and set the
$ mvn clean install -DcreateJavadoc=true
The hostname "non-existing.host" is now existing and all builds of version and tags before that date will fail.
To (re-)build versions before that date the unit tests must therefore be skipped.
$ mvn clean install -DskipTests
Earlier versions (3.0.0-Mx, 2.6.5 and before) may also fail to build with newer JDKs, especially, if java 16 is used! That is cause by the unit test dependency to a deprecated version of "mockito". If such a (re-)build is required, the unit tests must be skipped (which is in the meantime anyway required caused by the "non-existing.host").
In combination with the "non-existing.host" now existing, the build with unit test only works for the current heads of the branches
Californium 2.x and newer can be used with java 7 or newer. If you want to build it with a jdk 7, but use also plugins which are only supported for newer jdks, the toolchain plugin could be used. That requires a toolchains configuration in "toolchains.xml" in your maven ".m2" folder
jdk 1.7 path..to..jdk7...home
To use the jdk7 toolchain, add "-DuseToolchain=true" to the command line.
$ mvn clean install -DuseToolchain=true
To use the jdk7 toolchain and create javadocs, add "-DuseToolchainJavadoc=true" to the command line (
JAVA_HOMEis not required).
$ mvn clean install -DuseToolchainJavadoc=true
To support EdDSA, either java 15, java 16, or java 11 with ed25519-java is required at runtime. Using java 15 to build Californium, leaves out
ed25519-java, using java 11 for building, includes
ed25519-javaby default. If
ed25519-javashould NOT be included into the californium's jars, add
-Dno.net.i2p.crypto.eddsa=trueto maven's arguments.
$ mvn clean install -Dno.net.i2p.crypto.eddsa=true
In that case, it's still possible to use
ed25519-java, if the eddsa-0.3.0.jar is provided to the classpath separately.
With 3.0 a first, experimental support for using Bouncy Castle (1.69, bcprov-jdk15on, bcpkix-jdk15on, and, for tls, bctls-jdk15on) is implemented.
To demonstrate the basic functions, run the unit-tests using the profile
$ mvn clean install -Pbc-tests
Supporting Bouncy Castle for the unit test uncovers a couple of differences, which required to adapt the implementation. It is assumed, that more will be found and more adaption will be required. If you find some, don't hesitate to report issues, perhaps research and analysis, and fixes. On the other hand, the project Californium will for now not be able to provide support for Bouncy Castle questions with or without relation to Californium. You may create issues, but it may be not possible for us to answer them.
On issue seems to be the
SecureRandomgenerator, which shows in some environments strange CPU/time consumption.
With that, it gets very time consuming to test all combinations. Therefore, if you need a specific one, please test it on your own. If you consider, that some adaption is required, let us know by creating an issue or PR.
We are publishing Californium's artifacts for milestones and releases to Maven Central. To use the latest released version as a library in your projects, add the following dependency to your
pom.xml(without the dots):
... org.eclipse.californium californium-core 3.0.0 ... ...
You can also be bold and try out the most recent build from
master. However, we are not publishing those to Maven Central but to Californium's project repository at Eclipse only. You will therefore need to add the Eclipse Repository to your
... repo.eclipse.org Californium Repository https://repo.eclipse.org/content/repositories/californium/ ...
You can then simply depend on
The project can be easily imported into a recent version of the Eclipse IDE. Make sure to have the following before importing the Californium (Cf) projects:
Then choose [Import... » Maven » Existing Maven Projects] to import
The project can also be imported to IntelliJ as follows:
In IntelliJ, choose [File.. » Open] then select the location of the cloned repository in your filesystem. IntelliJ will then automatically import all projects and resolve required Maven dependencies.
A test server is running at coap://californium.eclipseprojects.io:5683/
It is an instance of the cf-plugtest-server from the demo-apps. The root resource responds with its current version.
More information can be found at http://www.eclipse.org/californium and technical details at https://projects.eclipse.org/projects/iot.californium.
For some systems (particularly when multicasting), it may be necessary to specify/restrict californium to a particular network interface, or interfaces. This can be achieved by setting the
COAP_NETWORK_INTERFACESJVM parameter to a suitable regex, for example:
java -DCOAP_NETWORK_INTERFACES='.*wpan0' -jar target/cf-helloworld-server-3.0.0.jar MulticastTestServer
A bug, an idea, an issue? Join the Mailing list or create an issue here on GitHub.
Please check out our contribution guidelines