Using the Californium (Cf) CoAP Framework

Table of Contents

• Prerequisites
• Preparing the workspace
  • Add supplied files to the local repositories
  • Import projects
  • Change settings
• 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 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>/Nordic/nrf51/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>/Nordic/nrf51/examples/iot/dtls/coap_client/pc_server
   into
   <Local Repositories>/californium/cf-secure/src/main/java/org/eclipse/californium/examples
3. Copy the whole certs directory from
   <Local Repositories>/californium/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 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/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

Running a secure CoAP server

1. Open the secure CoAP server implementation:
   <Local Repositories>/californium/cf-secure/src/main/java/org/eclipse/californium/examples/Nrf51SecureServer.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

Note

When sending the first request from the nRF51 DK, the DTLS handshake phase might take up to 3 minutes to complete.

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/Nrf51ConsoleClient.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 Nrf51ConsoleClient.java with the correct command line arguments. Use coaps as URI scheme for secure requests.
   

   Run configuration for Nrf51ConsoleClient.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>

Note

When sending the first request to the nRF51 DK, the DTLS handshake phase might take up to 3 minutes to complete.