Constrained Application Protocol (CoAP) Interactive Shell
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.mvn/wrapper Initial project commit Jun 6, 2018
src Disable Ping on server connection Jun 26, 2018
.gitignore Add demo gif Jun 7, 2018
LICENSE Add Apache-2.0 license file Jun 15, 2018
README.adoc Disable Ping on server connection Jun 26, 2018
mvnw Initial project commit Jun 6, 2018
mvnw.cmd Initial project commit Jun 6, 2018
pom.xml [maven-release-plugin] prepare for next development iteration Jun 26, 2018

README.adoc

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.

CoAP Shell Demo

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:

CoAP Shell video

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.0.7.jar
  _____     ___   ___     ______       ____
 / ___/__  / _ | / _ \   / __/ /  ___ / / /
/ /__/ _ \/ __ |/ ___/  _\ \/ _ \/ -_) / /
\___/\___/_/ |_/_/     /___/_//_/\__/_/_/
CoAP Shell (v1.0.7)
For assistance hit TAB or type "help".

server-unknown:>
  • Connect to a CoAP server (such as coaps://californium.eclipse.org:5684 or coap://coap.me)

server-unknown:>connect coaps://californium.eclipse.org:5684
available
coaps://californium.eclipse.org:5684:>
  • Discover the available CoAP resources:

coaps://californium.eclipse.org:5684:>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

coaps://californium.eclipse.org:5684:>get /multi-format --accept application/xml

----------------------------------- Response -----------------------------------
GET coaps://californium.eclipse.org:5684/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 that means that your DTLS session has expired and you have to re-connect again.

IKEA TRÅDFRI Gateway Support

  • 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.151 --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

The 192.168.178.151 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.151:5684 --identity myIkeaGatewayIdentity --secret X5xyYM41qFS7vN10
available
coaps://192.168.178.151: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.151: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.151:5684:>ikea turn on --instance 65539
OK

coaps://192.168.178.151: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.151:5684:>ikea turn off --instance 65539
OK

coaps://192.168.178.151: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.151:5684:>get //15001/65539

----------------------------------- Response -----------------------------------
GET coaps://192.168.178.151: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 IPSO Smart Object specs. For example the "3311" block corresponds to the Light Control object and the 5850 is an mandatory On/Off attribute within this object. Similarly the "3" section corresponds to the Device manufacturer object spec. The gateway is not 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.151:5684:>put //15001/65539 --payload '{"3311":[{"5850":1}]}'

or 0 for turning it OFF:

coaps://192.168.178.151: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.0.8-SNAPSHOT.jar --logging.level.org.eclipse.californium=DEBUG