CoAP Shell

CoAP is a RESTful web transfer protocol specialized for use with constrained nodes and constrained networks in the Internet of Things (IoT).

The CoAP Shell provides an interactive, command line interface for interacting with CoAP enabled servers. It supports the coap: and coaps: schemas (e.g. UDP and DTLS). It also can manage your IKEA TRÅDFRI smart lights set ;)

The CoAP Shell is build on top of the Spring Shell, Californium (Cf) and Scandium (Sc) projects. It is a SpringBoot application, that builds into a single, self-executable jar and runs on any Java8+ environment.

Features

• Plain coap: and secured coaps: endpoints (e.g. UDP and DTLS transports).

• CoAP GET, PUT, POST and DELETE methods.

• CoAP Resource Observing.

• CoAP Resource Discovery. Filters by href, ct, rt, obs …​

• Synchronous and Asynchronous (--async argument) message exchanges.

• Confirmable and Non-Confirmable message exchange.

• TAB auto-completion for commands and arguments.

• Extensive commands help (type help).

• Plugable key/trust stores and credentials.

• SpringBoot, self-executable jar, running in any Java 8+ environment.

• Basic support for IKEA Tradfri Gateway.

The CoAP Shell Video highlights some of the features:

Quick Start

• Get a pre-build coap-shell.jar or build one yourself following the instructions further down.

• Then start the shell:

java -jar ./coap-shell-1.1.1.jar

  _____     ___   ___     ______       ____
 / ___/__  / _ | / _ \   / __/ /  ___ / / /
/ /__/ _ \/ __ |/ ___/  _\ \/ _ \/ -_) / /
\___/\___/_/ |_/_/     /___/_//_/\__/_/_/
CoAP Shell (v1.1.1)
For assistance hit TAB or type "help".

server-unknown:>

Caution

If you see an exception like: Caused by: java.lang.NumberFormatException: For input string: then you have to remove the existing spring-shell.log file in the same directory.

• Connect to a CoAP server (such as coap://californium.eclipseprojects.io:5683/ or coap://coap.me)

server-unknown:>connect coap://californium.eclipseprojects.io:5683/
available
coap://californium.eclipseprojects.io:5683/:>

• Discover the available CoAP resources:

coap://californium.eclipseprojects.io:5683/:>discover --query href=/*

┌─────────────────┬──────────────────┬────────────────────────────────────┬──────────────┬─────────┬────────────────┐
│Path [href]      │Resource Type [rt]│Content Type [ct]                   │Interface [if]│Size [sz]│Observable [obs]│
├─────────────────┼──────────────────┼────────────────────────────────────┼──────────────┼─────────┼────────────────┤
│/.well-known/core│                  │                                    │              │         │                │
│/large           │block             │                                    │              │1280     │                │
│/link1           │Type1, Type2      │                                    │If1           │         │                │
│/multi-format    │                  │text/plain (0), application/xml (41)│              │         │                │
│/obs             │observe           │text/plain (0)                      │              │         │observable      │
                                                        .....

• Get resource data

coap://californium.eclipseprojects.io:5683/:>get /multi-format --accept application/xml

----------------------------------- Response -----------------------------------
GET coap://californium.eclipse.org/multi-format
MID: 31291, Type: ACK, Token: [0a10eaafaf3d024f], RTT: 123ms
Options: {"Content-Format":"application/xml"}
Status : 205-Reset Content, Payload: 63B
----------------------------------- Payload ------------------------------------
<msg type="CON" code="GET" mid=31291 accept="application/xml"/>
--------------------------------------------------------------------------------

• Use help to the available commands and how are they used.

• Use TAB for command and argument auto-completion.

Caution

If you see org.eclipse.californium.elements.EndpointMismatchException error message then your DTLS session has expired. You will have to re-connect again.

IKEA TRÅDFRI Gateway Support

Ikea Tradfri CoAP Docs

• Generate Gateway pre-share key Use the ikea gateway key to register a new account (e.g. identity + secret) to your IKEA Gateway:

server-unknown:>ikea gateway key --ip 192.168.178.150 --identity myIkeaGatewayIdentity --security-code <Gateway Code Label>

-------------------------------- CoAP Response ---------------------------------
 MID    : 58318
 Token  : [60d1dcf80d8eb84f]
 Type   : ACK
 Status : 201-Created
 Options: {}
 RTT    : 371 ms
 Payload: 45 Bytes
............................... Body Payload ...................................
{"9091":"X5xyYM41qFS7vNa9","9029":"1.3.0014"}
--------------------------------------------------------------------------------
IDENTITY: myIkeaGatewayIdentity , PRE_SHARED_KEY: X5xyYM41qFS7vN10

• You can find the security-code value at the back of your Gateway box.

• The 192.168.178.150 is the IP address of the gateway in your network. You should find the IP of your IKEA gateway box and use it instead!

• The myIkeaGatewayIdentity is the new identity to be registered with the gateway. the <Gateway Code Label> is printed on the back side of the Gateway box.

The response IDENTITY: myIkeaGatewayIdentity , PRE_SHARED_KEY: X5xyYM41qFS7vNa9 contains the new credential created for you. Store the generated identity and secret so you can use them to interact with your IKEA gateway.

• Use the generated credentials to connect to the gateway

server-unknown:>connect coaps://192.168.178.150:5684 --identity myIkeaGatewayIdentity --secret X5xyYM41qFS7vN10
available
coaps://192.168.178.150:5684:>

(Again substitute with the IP of your gateway. Use the identity and secret created in the previous step)

• List all devices registered with the gateway

coaps://192.168.178.150:5684:>ikea device list

┌────────┬─────────┬──────┬───────────────────────────────┬────────┬───────────┬──────┐
│Instance│Name     │Type  │Model                          │Firmware│Battery [%]│ON/OFF│
├────────┼─────────┼──────┼───────────────────────────────┼────────┼───────────┼──────┤
│65537   │E27 LR4  │LIGHT │TRADFRI bulb E27 CWS opal 600lm│1.3.002 │-          │OFF   │
│65539   │GU10 WC  │LIGHT │TRADFRI bulb GU10 W 400lm      │1.2.214 │-          │OFF   │
│65536   │Remote LR│SWITCH│TRADFRI remote control         │1.2.214 │87         │-     │
│65542   │GU10 LR3 │LIGHT │TRADFRI bulb GU10 WS 400lm     │1.2.217 │-          │ON    │
│65540   │GU10 LR1 │LIGHT │TRADFRI bulb GU10 WS 400lm     │1.2.217 │-          │ON    │
│65541   │GU10 LR2 │LIGHT │TRADFRI bulb GU10 WS 400lm     │1.2.217 │-          │ON    │
│65538   │Sensor WC│SENSOR│TRADFRI motion sensor          │1.2.214 │100        │-     │
└────────┴─────────┴──────┴───────────────────────────────┴────────┴───────────┴──────┘

• Turn a lamp on/off

coaps://192.168.178.150:5684:>ikea turn on --instance 65539
OK

coaps://192.168.178.150:5684:>ikea device list
┌────────┬─────────┬──────┬───────────────────────────────┬────────┬───────────┬──────┐
│Instance│Name     │Type  │Model                          │Firmware│Battery [%]│ON/OFF│
├────────┼─────────┼──────┼───────────────────────────────┼────────┼───────────┼──────┤
│65539   │GU10 WC  │LIGHT │TRADFRI bulb GU10 W 400lm      │1.2.214 │-          │ON    │


coaps://192.168.178.150:5684:>ikea turn off --instance 65539
OK

coaps://192.168.178.150:5684:>ikea device list
┌────────┬─────────┬──────┬───────────────────────────────┬────────┬───────────┬──────┐
│Instance│Name     │Type  │Model                          │Firmware│Battery [%]│ON/OFF│
├────────┼─────────┼──────┼───────────────────────────────┼────────┼───────────┼──────┤
│65539   │GU10 WC  │LIGHT │TRADFRI bulb GU10 W 400lm      │1.2.214 │-          │OFF   │

• Use the CoAP’s GET check the raw message response

coaps://192.168.178.150:5684:>get //15001/65539

----------------------------------- Response -----------------------------------
GET coaps://192.168.178.150:5684//15001/65539
MID: 30881, Type: ACK, Token: [260128b68be34371], RTT: 5ms
Options: {"Content-Format":"application/json", "Max-Age":604800}
Status : 205-Reset Content, Payload: 220B
----------------------------------- Payload ------------------------------------
{
  "3311" : [ {
    "5850" : 0,
    "5851" : 203,
    "9003" : 0
  } ],
  "9001" : "GU10 WC",
  "9002" : 1528124737,
  "9020" : 1528447038,
  "9003" : 65539,
  "9054" : 0,
  "5750" : 2,
  "9019" : 0,
  "3" : {
    "0" : "IKEA of Sweden",
    "1" : "TRADFRI bulb GU10 W 400lm",
    "2" : "",
    "3" : "1.2.214",
    "6" : 1
  }
}
--------------------------------------------------------------------------------

Note

The CoAP Gateway follows (partially!) some of the OpenMobileAlliance (formerly IPSO) Smart Object specs. For example "3311" block corresponds to the Light Control object and the 5850 is an mandatory On/Off attribute within this object. Similarly the LWM2M_Device section provides a Device manufacturer object spec. The gateway is not OpenMobileAlliance/IPSO compliant though as some compulsory attributes are missing. The range of 9xxx codes are proprietary. Some description of those codes can be found here.

• Next you can use CoAP’s PUT method with JSON payload to turn a light On or Off.

Set 5850 to 1 for turning the lamp ON:

coaps://192.168.178.150:5684:>put //15001/65539 --payload '{"3311":[{"5850":1}]}'

or 0 for turning it OFF:

coaps://192.168.178.150:5684:>put //15001/65539 --payload '{"3311":[{"5850":0}]}'

Use the //15001/<DEVICE ID> template to address the device you want.

Caution

If you see org.eclipse.californium.elements.EndpointMismatchException message that means that your DTLS session has expired due to IDLE timeout. You have to re-connect again.

How to Build

Clone the project from GitHub and build with Maven.

git clone https://github.com/tzolov/coap-shell.git
cd ./coap-shell
./mvnw clean install

Then run the self-executable jar in the target folder.

Debugging

Start the shell with --logging.level=DEBUG to enable debug log level for the entire applicationor --logging.level.org.eclipse.californium=DEBUG to debug only californium and scandium. Later is useful to debug the CoAP request message and DTLS interactions.

For example:

java -jar ./target/coap-shell-1.1.1-SNAPSHOT.jar --logging.level.org.eclipse.californium=DEBUG