Using the Californium (Cf) CoAP Framework

Table of Contents

• Prerequisites
• Preparing the workspace
  • Add supplied files to the local repositories
  • Import projects
  • Change settings
• Known limitations
• Running a secure CoAP server
• Running a secure CoAP client

Here, we provide a short description of how Californium and Scandium on the PC can be used to evaluate the DTLS CoAP examples that use Nordic's smartCoAP library over DTLS".

Californium (Cf) is an open source implementation of the Constrained Application Protocol (CoAP) that is written in Java and targets unconstrained environments. Please visit the project's website to learn about what licensing applies when using Californium. Californium is divided into multiple sub-projects, the Scandium (Sc) sub-project provides security for Californium.

The Californium project is hosted by the Eclipse Foundation, which is a not-for-profit, member supported corporation that helps cultivate both an open source community and an ecosystem of complementary products and services.

Prerequisites

• Java Development Kit (make sure that your Path environment variable points to the JDK and not to a JRE).
• Eclipse integrated development environment with the EGit and M2Eclipse plugins (Eclipse Luna for Java Developers is highly recommended, because it contains the listed plugins by default).
• Git client.
• Californium Core source code. Use git to clone to a local directory. This guide is based on revision number 7f999295c7d5e4aa5791b40d3a0913078454b7cb.
• Scandium source code. Use git to clone to a local directory. This guide is based on revision number 34ff497e5e90fdb69f46559d2f42caef3a018a9a.
• Californium Tools source code. Use git to clone to a local directory. This guide is based on revision number c8c6e147bdfabb4466afd5e62b711e4ef6b33d9b.

Preparing the workspace

Add supplied files to the local repositories

1. Copy the secure CoAP client application (1 Java source file, don't copy the directory) from
   <InstallFolder>/examples/iot/dtls/coap_server/pc_client
   into
   <Local Repositories>/californium.tools/cf-client/src/main/java/org/eclipse/californium/tools
2. Copy the secure CoAP server application (2 Java source files, don't copy the directory) from
   <InstallFolder>/examples/iot/dtls/coap_client/pc_server
   into
   <Local Repositories>/californium.core/cf-secure/src/main/java/org/eclipse/californium/examples
3. Copy the whole certs directory from
   <Local Repositories>/californium.core/cf-secure/certs
   to
   <Local Repositories>/californium.tools/cf-client/certs

Import projects

1. Open a blank workspace in Eclipse.
2. Chose File menu > Import... and select Maven > Existing Maven Projects.
   

   Importing existing maven projects
   
   
3. Select the directory where you cloned the Californium Core repository and click Finish.
   

   Select your local repository
   
   
4. Repeat steps 2 and 3 with the Scandium project.
5. Repeat steps 2 and 3 with the Californium Tools project.

Change settings

1. Remove Californium.properties files, if any, from all local repositories.
2. Open the following file:
   <Local Repositories>/californium.scandium/src/main/java/org/eclipse/californium/scandium/config/DtlsConnectorConfig.java
3. On line 54 set retransmissionTimeout to 20000:
   

   private int retransmissionTimeout = 20000; 

4. Save and close DtlsConnectorConfig.java
5. Open the following file:
   <Local Repositories>/californium.core/californium-core/src/main/java/org/eclipse/californium/core/network/config/NetworkConfigDefaults.java
6. On line 43 set the default value for ACK_TIMEOUT to 200000:
   

   config.setInt(NetworkConfig.Keys.ACK_TIMEOUT, 200000); 

7. Save and close NetworkConfigDefaults.java

Known limitations

When trying the examples, there are some limitations and behavior that should be taken into account:

1. When sending the first request from the nRF5x DK, the DTLS handshake phase might take up to 3 minutes to complete.
2. Since the example has no way of knowing if a DTLS session is closed, it cannot free its resources until it is reset. If you invoke the client multiple times, the dev kit will not be able to establish a new session. From the client side, you will appear to get a timeout.
3. If you modify the client to use an unsupported cipher suite, you will get a timeout when trying to connect.

Running a secure CoAP server

1. Open the secure CoAP server implementation:
   <Local Repositories>/californium.core/cf-secure/src/main/java/org/eclipse/californium/examples/Nrf5xSecureServer.java
2. On line 99 set the IPv6 address of the local interface that is to be used:
   

   InetAddress myIPv6Addr = Inet6Address.getByName("2001:0DB8:AC10:FE01:0000:0000:0000:0001");

3. The secure server is ready to be started by pressing Ctrl+F11.

The expected output of the server is as follows:

(...)
Secure CoAP server powered by Scandium (Sc) is listening on port 5684

Running a secure CoAP client

1. Open the secure CoAP client implementation:
   <Local Repositories>/californium.tools/cf-client/src/main/java/org/eclipse/californium/tools/Nrf5xConsoleClient.java
2. On line 225 set the IPv6 address of the local interface that is to be used as the source of the CoAP requests:
   

   InetAddress myIPv6Addr = Inet6Address.getByName("2001:0DB8:AC10:FE01:0000:0000:0000:0001");

3. To view the documentation of the application run it without command line arguments.
4. In Eclipse, chose the Run menu > Run Configurations... item to create a run configuration for Nrf5xConsoleClient.java with the correct command line arguments. Use coaps as URI scheme for secure requests.
   

   Run configuration for Nrf5xConsoleClient.java. Replace REMOTE_SERVER_IPv6_ADDRESS with actual IPv6 address of the server.
   
   

If the DTLS handshake is successful, the server will print the following lines to the console (these lines will be interleaved with other messages that pertain to the DTLS handshake):

(...)

16 INFO [MessageTracer]: /2001:0DB8:AC10:FE01:0:0:0:1:5694 ==> req CON-GET    MID=14675, Token=0e6e0e5d, OptionSet={"Uri-Path":[".well-known","core"], "Content-Format":"text/plain"}, "" - (org.eclipse.californium.core.network.interceptors.MessageTracer.java:54) receiveRequest() in thread pool-1-thread-2 at (2015-05-26 13:41:23)
16 INFO [MessageTracer]: /2001:0DB8:AC10:FE01:0:0:0:1:5694 <== res ACK-2.05   MID=14675, Token=0e6e0e5d, OptionSet={"Content-Format":"application/link-format"}, "</lights>,</lights/l".. 22 bytes - (org.eclipse.californium.core.network.interceptors.MessageTracer.java:44) sendResponse() in thread pool-1-thread-2 at (2015-05-26 13:41:23)

(...)

The expected output of the client is as follows (these lines will be interleaved with other messages that pertain to the DTLS handshake):

(...)

==[ CoAP Response ]============================================
MID    : 14675
Token  : 0e6e0e5d
Type   : ACK
Status : 2.05
Options: {"Content-Format":"application/link-format"}
Payload: 107 Bytes
---------------------------------------------------------------
</lights>,</lights/led3>;title="nRF DK Resource",</lights/led4>;title="nRF DK Resource",</.well-known/core>
===============================================================
Time elapsed (ms): 1100

Discovered resources:
</lights>,</lights/led3>;title="nRF DK Resource",</lights/led4>;title="nRF DK Resource",</.well-known/core>