{"id":13705021,"url":"https://github.com/tzolov/coap-shell","last_synced_at":"2025-04-21T22:30:34.477Z","repository":{"id":48796344,"uuid":"136387160","full_name":"tzolov/coap-shell","owner":"tzolov","description":"Constrained Application Protocol (CoAP) Interactive Shell","archived":false,"fork":false,"pushed_at":"2022-11-16T01:40:10.000Z","size":6193,"stargazers_count":50,"open_issues_count":6,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-03T22:14:16.572Z","etag":null,"topics":["coap","iot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tzolov.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-06T21:18:43.000Z","updated_at":"2024-06-27T03:11:08.000Z","dependencies_parsed_at":"2023-01-23T08:01:08.545Z","dependency_job_id":null,"html_url":"https://github.com/tzolov/coap-shell","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzolov%2Fcoap-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzolov%2Fcoap-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzolov%2Fcoap-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzolov%2Fcoap-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tzolov","download_url":"https://codeload.github.com/tzolov/coap-shell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223881081,"owners_count":17219248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coap","iot"],"created_at":"2024-08-02T22:00:30.029Z","updated_at":"2024-11-09T20:33:49.987Z","avatar_url":"https://github.com/tzolov.png","language":"Java","funding_links":[],"categories":["Tools"],"sub_categories":["Interaction"],"readme":"= CoAP Shell\n\nhttps://bintray.com/big-data/maven/coap-shell/_latestVersion[ image:https://api.bintray.com/packages/big-data/maven/coap-shell/images/download.svg[Download] ]\n\nhttps://en.wikipedia.org/wiki/Constrained_Application_Protocol[CoAP] is a RESTful web transfer protocol specialized for use with constrained nodes and constrained networks in the Internet of Things (IoT).\n\nThe https://github.com/tzolov/coap-shell[CoAP Shell] provides an interactive, command line interface for interacting with CoAP enabled servers.\nIt supports the `coap:` and `coaps:` schemas (e.g. UDP and https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security[DTLS]).\nIt also can manage your `IKEA TRÅDFRI` smart lights set ;)\n\nThe CoAP Shell is build on top of the https://projects.spring.io/spring-shell/[Spring Shell], https://www.eclipse.org/californium/[Californium (Cf)] and https://www.eclipse.org/californium/[Scandium (Sc)]\nprojects. It is a https://spring.io/projects/spring-boot[SpringBoot] application, that builds into a single, self-executable jar and runs on any Java8+ environment.\n\nimage:https://raw.githubusercontent.com/tzolov/coap-shell/master/src/test/resources/coap-shell-demo2.gif[CoAP Shell Demo]\n\n=== Features\n- Plain https://tools.ietf.org/html/rfc7252#section-6.1[coap:] and secured https://tools.ietf.org/html/rfc7252#section-6.2[coaps:] endpoints (e.g. `UDP` and `DTLS` transports).\n- CoAP `GET`, `PUT`, `POST` and `DELETE` methods.\n- CoAP Resource https://tools.ietf.org/html/rfc7641[Observing].\n- CoAP Resource https://tools.ietf.org/html/rfc7252#section-7.2[Discovery]. Filters by `href`, `ct`, `rt`, `obs` ...\n- `Synchronous` and `Asynchronous` (`--async` argument) message exchanges.\n- https://tools.ietf.org/html/draft-ietf-core-observe-08#section-3.5[Confirmable] and `Non-Confirmable` message exchange.\n- `TAB` auto-completion for `commands` and `arguments`.\n- Extensive `commands` help (type `help`).\n- Plugable key/trust stores and credentials.\n- https://spring.io/projects/spring-boot[SpringBoot], self-executable jar, running in any Java 8+ environment.\n- Basic support for `IKEA Tradfri Gateway`.\n\nThe https://youtu.be/zhEGFfCJwTg[CoAP Shell Video] highlights some of the features:\n\nhttps://youtu.be/zhEGFfCJwTg[image:https://raw.githubusercontent.com/tzolov/coap-shell/master/src/test/resources/coap-shell-video-log.png[CoAP Shell video,157,54]]\n\n\n=== Quick Start\n\n* Get a pre-build https://bintray.com/big-data/maven/download_file?file_path=io%2Fdatalake%2Fcoap%2Fcoap-shell%2F1.1.1%2Fcoap-shell-1.1.1.jar[coap-shell.jar] or build one yourself following the instructions further down.\n* Then start the shell:\n[source,bash]\n----\njava -jar ./coap-shell-1.1.1.jar\n----\n\n[source,bash]\n----\n  _____     ___   ___     ______       ____\n / ___/__  / _ | / _ \\   / __/ /  ___ / / /\n/ /__/ _ \\/ __ |/ ___/  _\\ \\/ _ \\/ -_) / /\n\\___/\\___/_/ |_/_/     /___/_//_/\\__/_/_/\nCoAP Shell (v1.1.1)\nFor assistance hit TAB or type \"help\".\n\nserver-unknown:\u003e\n----\n\nCAUTION: 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.\n\n* Connect to a CoAP server (such as `coap://californium.eclipseprojects.io:5683/` or `coap://coap.me`)\n[source,bash]\n----\nserver-unknown:\u003econnect coap://californium.eclipseprojects.io:5683/\navailable\ncoap://californium.eclipseprojects.io:5683/:\u003e\n----\n\n* Discover the available CoAP resources:\n[source,bash]\n----\ncoap://californium.eclipseprojects.io:5683/:\u003ediscover --query href=/*\n\n┌─────────────────┬──────────────────┬────────────────────────────────────┬──────────────┬─────────┬────────────────┐\n│Path [href]      │Resource Type [rt]│Content Type [ct]                   │Interface [if]│Size [sz]│Observable [obs]│\n├─────────────────┼──────────────────┼────────────────────────────────────┼──────────────┼─────────┼────────────────┤\n│/.well-known/core│                  │                                    │              │         │                │\n│/large           │block             │                                    │              │1280     │                │\n│/link1           │Type1, Type2      │                                    │If1           │         │                │\n│/multi-format    │                  │text/plain (0), application/xml (41)│              │         │                │\n│/obs             │observe           │text/plain (0)                      │              │         │observable      │\n                                                        .....\n----\n\n* Get resource data\n[source,bash]\n----\ncoap://californium.eclipseprojects.io:5683/:\u003eget /multi-format --accept application/xml\n\n----------------------------------- Response -----------------------------------\nGET coap://californium.eclipse.org/multi-format\nMID: 31291, Type: ACK, Token: [0a10eaafaf3d024f], RTT: 123ms\nOptions: {\"Content-Format\":\"application/xml\"}\nStatus : 205-Reset Content, Payload: 63B\n----------------------------------- Payload ------------------------------------\n\u003cmsg type=\"CON\" code=\"GET\" mid=31291 accept=\"application/xml\"/\u003e\n--------------------------------------------------------------------------------\n\n----\n\n* Use `help` to the available commands and how are they used.\n* Use `TAB` for command and argument auto-completion.\n\nCAUTION: If you see `org.eclipse.californium.elements.EndpointMismatchException` error message then your DTLS session\nhas expired. You will have to re-connect again.\n\n=== IKEA TRÅDFRI Gateway Support\n\nhttps://github.com/glenndehaan/ikea-tradfri-coap-docs[Ikea Tradfri CoAP Docs]\n\n* Generate Gateway pre-share key\nUse the `ikea gateway key` to register a new account (e.g. identity + secret) to your IKEA Gateway:\n\n[source,bash]\n----\nserver-unknown:\u003eikea gateway key --ip 192.168.178.150 --identity myIkeaGatewayIdentity --security-code \u003cGateway Code Label\u003e\n\n-------------------------------- CoAP Response ---------------------------------\n MID    : 58318\n Token  : [60d1dcf80d8eb84f]\n Type   : ACK\n Status : 201-Created\n Options: {}\n RTT    : 371 ms\n Payload: 45 Bytes\n............................... Body Payload ...................................\n{\"9091\":\"X5xyYM41qFS7vNa9\",\"9029\":\"1.3.0014\"}\n--------------------------------------------------------------------------------\nIDENTITY: myIkeaGatewayIdentity , PRE_SHARED_KEY: X5xyYM41qFS7vN10\n----\n\n- You can find the `security-code` value at the back of your Gateway box.\n- 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!\n- The `myIkeaGatewayIdentity` is the new identity to be registered with the gateway. the `\u003cGateway Code Label\u003e` is printed on the back side of the Gateway box.\n\nThe response `IDENTITY: myIkeaGatewayIdentity , PRE_SHARED_KEY: X5xyYM41qFS7vNa9` contains the new credential created for you.\nStore the generated identity and secret so you can use them to interact with your IKEA gateway.\n\n* Use the generated credentials to connect to the gateway\n\n[source,bash]\n----\nserver-unknown:\u003econnect coaps://192.168.178.150:5684 --identity myIkeaGatewayIdentity --secret X5xyYM41qFS7vN10\navailable\ncoaps://192.168.178.150:5684:\u003e\n----\n(Again substitute with the IP of your gateway. Use the identity and secret created in the previous step)\n\n* List all devices registered with the gateway\n\n[source,bash]\n----\ncoaps://192.168.178.150:5684:\u003eikea device list\n\n┌────────┬─────────┬──────┬───────────────────────────────┬────────┬───────────┬──────┐\n│Instance│Name     │Type  │Model                          │Firmware│Battery [%]│ON/OFF│\n├────────┼─────────┼──────┼───────────────────────────────┼────────┼───────────┼──────┤\n│65537   │E27 LR4  │LIGHT │TRADFRI bulb E27 CWS opal 600lm│1.3.002 │-          │OFF   │\n│65539   │GU10 WC  │LIGHT │TRADFRI bulb GU10 W 400lm      │1.2.214 │-          │OFF   │\n│65536   │Remote LR│SWITCH│TRADFRI remote control         │1.2.214 │87         │-     │\n│65542   │GU10 LR3 │LIGHT │TRADFRI bulb GU10 WS 400lm     │1.2.217 │-          │ON    │\n│65540   │GU10 LR1 │LIGHT │TRADFRI bulb GU10 WS 400lm     │1.2.217 │-          │ON    │\n│65541   │GU10 LR2 │LIGHT │TRADFRI bulb GU10 WS 400lm     │1.2.217 │-          │ON    │\n│65538   │Sensor WC│SENSOR│TRADFRI motion sensor          │1.2.214 │100        │-     │\n└────────┴─────────┴──────┴───────────────────────────────┴────────┴───────────┴──────┘\n----\n\n* Turn a lamp on/off\n\n[source,bash]\n----\ncoaps://192.168.178.150:5684:\u003eikea turn on --instance 65539\nOK\n\ncoaps://192.168.178.150:5684:\u003eikea device list\n┌────────┬─────────┬──────┬───────────────────────────────┬────────┬───────────┬──────┐\n│Instance│Name     │Type  │Model                          │Firmware│Battery [%]│ON/OFF│\n├────────┼─────────┼──────┼───────────────────────────────┼────────┼───────────┼──────┤\n│65539   │GU10 WC  │LIGHT │TRADFRI bulb GU10 W 400lm      │1.2.214 │-          │ON    │\n\n\ncoaps://192.168.178.150:5684:\u003eikea turn off --instance 65539\nOK\n\ncoaps://192.168.178.150:5684:\u003eikea device list\n┌────────┬─────────┬──────┬───────────────────────────────┬────────┬───────────┬──────┐\n│Instance│Name     │Type  │Model                          │Firmware│Battery [%]│ON/OFF│\n├────────┼─────────┼──────┼───────────────────────────────┼────────┼───────────┼──────┤\n│65539   │GU10 WC  │LIGHT │TRADFRI bulb GU10 W 400lm      │1.2.214 │-          │OFF   │\n\n----\n\n* Use the CoAP's `GET` check the raw message response\n\n[source,bash]\n----\ncoaps://192.168.178.150:5684:\u003eget //15001/65539\n\n----------------------------------- Response -----------------------------------\nGET coaps://192.168.178.150:5684//15001/65539\nMID: 30881, Type: ACK, Token: [260128b68be34371], RTT: 5ms\nOptions: {\"Content-Format\":\"application/json\", \"Max-Age\":604800}\nStatus : 205-Reset Content, Payload: 220B\n----------------------------------- Payload ------------------------------------\n{\n  \"3311\" : [ {\n    \"5850\" : 0,\n    \"5851\" : 203,\n    \"9003\" : 0\n  } ],\n  \"9001\" : \"GU10 WC\",\n  \"9002\" : 1528124737,\n  \"9020\" : 1528447038,\n  \"9003\" : 65539,\n  \"9054\" : 0,\n  \"5750\" : 2,\n  \"9019\" : 0,\n  \"3\" : {\n    \"0\" : \"IKEA of Sweden\",\n    \"1\" : \"TRADFRI bulb GU10 W 400lm\",\n    \"2\" : \"\",\n    \"3\" : \"1.2.214\",\n    \"6\" : 1\n  }\n}\n--------------------------------------------------------------------------------\n----\n\nNOTE: The CoAP Gateway follows (*partially!*) some of the https://github.com/OpenMobileAlliance/lwm2m-registry[OpenMobileAlliance] (formerly IPSO) Smart Object specs.\nFor example https://github.com/OpenMobileAlliance/lwm2m-registry/blob/test/3311.xml[\"3311\"] block corresponds to the `Light Control` object and the `5850` is an mandatory `On/Off` attribute within this object.\nSimilarly the https://github.com/OpenMobileAlliance/lwm2m-registry/blob/test/LWM2M_Device-v1_1.xml[LWM2M_Device] section provides a `Device` manufacturer object spec.\nThe 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\nhttps://github.com/eclipse/smarthome/blob/master/extensions/binding/org.eclipse.smarthome.binding.tradfri/src/main/java/org/eclipse/smarthome/binding/tradfri/TradfriBindingConstants.java[here].\n\n* Next you can use CoAP's `PUT` method with JSON payload to turn a light On or Off.\n\nSet `5850` to `1` for turning the lamp ON:\n\n[source,bash]\n----\ncoaps://192.168.178.150:5684:\u003eput //15001/65539 --payload '{\"3311\":[{\"5850\":1}]}'\n----\n\nor `0` for turning it OFF:\n\n[source,bash]\n----\ncoaps://192.168.178.150:5684:\u003eput //15001/65539 --payload '{\"3311\":[{\"5850\":0}]}'\n----\n\nUse the `//15001/\u003cDEVICE ID\u003e` template to address the device you want.\n\nCAUTION: If you see `org.eclipse.californium.elements.EndpointMismatchException` message that means that your DTLS session has expired\ndue to IDLE timeout. You have to re-connect again.\n\n=== How to Build\n\nClone the project from GitHub and build with Maven.\n\n[source,bash]\n----\ngit clone https://github.com/tzolov/coap-shell.git\ncd ./coap-shell\n./mvnw clean install\n----\n\nThen run the self-executable jar in the `target` folder.\n\n=== Debugging\n\nStart the shell with `--logging.level=DEBUG` to enable debug log level for the entire applicationor `--logging.level.org.eclipse.californium=DEBUG`\nto debug only californium and scandium. Later is useful to debug the CoAP request message and DTLS interactions.\n\nFor example:\n[source,bash]\n----\njava -jar ./target/coap-shell-1.1.1-SNAPSHOT.jar --logging.level.org.eclipse.californium=DEBUG\n----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftzolov%2Fcoap-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftzolov%2Fcoap-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftzolov%2Fcoap-shell/lists"}