Leshan is an open source OMA Lightweight Machine to Machine (LWM2M) java client and server implementation. The project contains both client and server libraries that can be used to develop a LWM2M client and server using the Java programming language. The project contains both an example of a bootstrap server and LWM2M standalone server. To view Leshan's official repository, visit their Git Hub page.

How to set up Leshan on Ubuntu

In order to use the Leshan boostrap and LWM2M standalone server, it has to be compiled from source code. The description below is for a computer running Ubuntu.

First install maven and java using apt-get.
sudo apt-get install openjdk-7-jdk maven git-core
Clone the github repository of Leshan.
git clone https://github.com/eclipse/leshan.git
Step into the Leshan folder and run "mvn install".
cd leshan

mvn install

The libraries and example servers should now be compiled and ready to use. To test that the example server is working, run the following commands.

java -jar leshan-standalone/target/leshan-standalone-*-SNAPSHOT-jar-with-dependencies.jar

The server will bind to any network interface on the system listening on the default ports for CoAP, port 5683, and 5684 respectivly. Next, open localhost:8080 in a browser. You should see a page similar to the one in the figure below.

Figure 1. Leshan server user interface in browser showing the URI http://localhost:8080.

Multiplexing ports

As the Leshan bootstrap server and LWM2M server both are running on the same machine in this setup, we can multiplex the port numbers in order to allow client applications to make use of CoAP default ports. If both servers are running on the same port they will mutually exlude eachother in port occupation. You can configure one dedicated IPv6 address for each server, allowing each server to bind to a local port of its own.

The example below shows how to add multiple addresses to an interface after you have set up a Bluetooth 6LoWPAN connection with the example provided in the SDK and using the description provided in Connecting devices to the router. The commands assume that the bt0 interface is already up running.

ifconfig bt0 add 2001:db8::1/64

ifconfig bt0 add 2001:db8::2/64

The interface is now ready to have one server bound to each of the IPv6 addresses separately while using the same port numbers for both. In order to start up the bootstrap server and bind it to a specific IPv6 address, you can use a command like the following.

PORT=8888 COAPIFACE=2001:db8::1:5683 COAPSIFACE=2001:db8::1:5684 java -jar leshan-bs-server/target/leshan-bs-server-*-jar-with-dependencies.jar

The LWM2M standalone server could be bound to a different IPv6 address than the one used for the bootstrap server with a command as shown below.

COAPIFACE=2001:db8::2:5683 COAPSIFACE=2001:db8::2:5684 java -jar leshan-standalone/target/leshan-standalone-*-SNAPSHOT-jar-with-dependencies.jar

Bootstrap server configuration

Before any client connects to the bootstrap server it has to be configured with details about what to send to the client during bootstrap. This can be configured using a configuration file written in JSON format and performing a HTTP POST to the bootstrap server. The port used to POST the data is configured as the PORT in the command used when starting the bootstrap server.

Boostrap data for non secure example

This is an example of how a configuration file would look if no security is used.

{
 "servers": {
 "1": {
 "shortId": "1"
 }
 },
 "security": {
 "1": {
 "uri": "coap://[2001:db8::2]:5683/",
 "securityMode": "NO_SEC", 
 "serverId": "1"
 }
 }
}

Boostrap data for secure example using DTLS

This is an example of how a configuration file would look if security is used (DTLS-Secured CoAP).

{
 "servers": {
 "1": {
 "shortId": "1"
 }
 },
 "security": {
 "0": {
 "uri": "coaps://[2001:db8::1]:5684/",
 "bootstrapServer": true,
 "securityMode": "PSK",
 "serverPublicKeyOrId": [105, 100, 101, 110, 116, 105, 116, 121, 48],
 "publicKeyOrId": [105, 100, 101, 110, 116, 105, 116, 121, 48],
 "secretKey": [116, 111, 112, 115, 101, 99, 114, 101, 116, 48],
 "serverId": "0"
 },
 "1": {
 "uri": "coaps://[2001:db8::2]:5684/",
 "securityMode": "PSK", 
 "serverPublicKeyOrId": [105, 100, 101, 110, 116, 105, 116, 121],
 "publicKeyOrId": [105, 100, 101, 110, 116, 105, 116, 121],
 "secretKey": [116, 111, 112, 115, 101, 99, 114, 101, 116],
 "serverId": "1"
 }
 }
}

Notice that the configuration describes security instance "0", which is not really used by any example in the SDK. This is added in order to trigger a DTLS session on the bootstrap server. There is also a flag set in order to mark this instance as bootstrap server credentials, not expecting the server to expect a server instance. Therefore, the configuration "bootstrapServer" has been added and set to "true". Translated from HEX to text, the configuration for the bootstrap server DTLS session would be:

"serverPublicKeyOrId": "identity0"
"publicKeyOrId": "identity0"
"secretKey": "topsecret0"

The configuration for the server which is going to be posted to the client during bootstrap contains both a server instance description as well as a security instance. However, the security credentials defined here will be used by the LWM2M after the handshake, and a seperate step has to be taken to register the credentials for the client in the server user interface. This is described in Adding credentials for client application. Translated from HEX to text, the configuration for the LWM2M server would be:

"serverPublicKeyOrId": "identity"
"publicKeyOrId": "identity"
"secretKey": "topsecret"

The object configurations for the client endpoint can be saved into a file. In this document the data is expected to be saved into a file named data.json.

Posting configuration to the bootstrap server

To insert objects into the Bootstrap server you need to POST data on the HTTP interface of the bootstrap server. The command below demonstrates how to insert objects for a client with the endpoint name "0a18de70-0ce0-4570-bce9-7f5895db6c70". The endpoint name will be part of the URI which is posted. The port number used should also be matching the one configured when starting up the bootstrap server as described in Multiplexing ports. The object configuration is located in data.json.

curl -X POST -H "Accept: application/json" -d @data.json http://localhost:8888/api/bootstrap/0a18de70-0ce0-4570-bce9-7f5895db6c70

Adding credentials for client application

In order to successfully connect to the LWM2M standalone server with a secure connection for a client application, credentials for the specific client endpoint have to be added. The Leshan user interface in the browser can be used to add such credentials. The image below shows a typical configuration for the examples provided in the SDK.

Figure 2. Example of a server security configuration for the client endpoint.

Setting up some helper scripts

In the following section there are two scripts that can help automate the process of starting the bootstrap server and the LWM2M standalone server. The scripts assume that there is an object configuration file (data.json) for the bootstrap server located in the root of the leshan Git clone. There is an assumption in the scripts that they are initiated from the same root folder.

Bootstrap server startup script

The script below will start up the bootstrap server, binding the HTTP interface to port 8888. It will also bind the server CoAP interface to port 5683 and 5684 on the IPv6 address 2001:db8::1

#!/usr/bin/env bash
# echo commands as they are executed
set -x
# Port configurations
export PORT=8888 
export COAPIFACE=2001:db8::1:5683 
export COAPSIFACE=2001:db8::1:5684
# Start the bootstrap server
java -jar leshan-bs-server/target/leshan-bs-server-*-jar-with-dependencies.jar &
# Copy the pid of previous backgroud process
pid=$!
# Relay traps to kill the background process and exit this process
trap "kill $pid; exit" SIGHUP SIGTERM SIGINT
# Wait 5 seconds in order to let the the Bootstrap server start
sleep 5
# Configure the Bootstrap server with objects for the client endpoint
echo "Inserting objects into the Bootstrap Server"
curl -X POST -H "Accept: application/json" -d @data.json http://localhost:8888/api/bootstrap/0a18de70-0ce0-4570-bce9-7f5895db6c70
# Wait for a trap
wait

LWM2m server startup script

The script below will start up the LWM2M standalone server. It will bind the server to the server CoAP interface to port 5683 and 5684 on the IPv6 address 2001:db8::2.

#!/usr/bin/env bash
set -x
# Port configurations
export COAPIFACE=2001:db8::2:5683 
export COAPSIFACE=2001:db8::2:5684 
# Start the standalone server
java -jar leshan-standalone/target/leshan-standalone-*-SNAPSHOT-jar-with-dependencies.jar

Table of Contents