home.markdown

+# Tutorial for jCoAP Hands-on
+
+In this tutorial we will describe how to develop a simple message exchange between devices using jCoAP.
+Furthermore, we will introduce the observe mechanism.
+
+## 0. The requirements for this tutorial:
+• JAVA SE JDK 1.6+
+• Eclipse IDE for JAVA development
+• Prepared JAVA project files for Hands-on
+• (Copper plugin for Mozilla Firefox)
+
+The following points will be covered by this tutorial:
+1. Installation of Copper Plugin for Mozilla Firefox
+2. Introduction of jCoAP (based on Task 1)
+3. Import of prepared project into Eclipse
+4. Task 1: Implementation of client/server and enable simple message exchange
+5. Task 2: Implementation of an airconditioner control by using the CoAP-observe mechanism
+
+## 1. Installation of Copper Plugin for Mozilla Firefox
+- https://addons.mozilla.org/de/firefox/addon/copper-270430/
+- Click on „add to Firefox“ & Confirm Installation
+- Restart Firefox
+
+## 2. Introduction of jCoAP
+- WS4D-jCoAP: Java implementation of CoAP
+-- http://ws4d.org/
+-- https://gitlab.amd.e-technik.uni-rostock.de/ws4d/jcoap
+
+• Task 1 – Sequence Diagram:
+Server Side Client Side
+Communication
+Server:
+TemperatureResource:
+BasicCoapResource:
+CoapResource (interface):
+CoapResourceServer:
+CoapServer (interface):
+ChannelManager:
+Channel:
+Client:
+CoapClient (interface):
+individual implementation of a server application, creates CoapResourceServer and resources
+individual resource, inherits from BasicCoapResource
+already implemented resource with basic functionality, implements CoapResource (interface)
+describes interfaces that must be supported by each resource
+manages a list of resources, enables access of these resources from outside, implements
+CoapServer (interface), uses ChannelManager for connection management
+describes interfaces that must be supported by a resource server
+manages channels
+one channel represents a connection to one client
+individual implementation of a client application, implements CoapClient (interface)
+describes interfaces that must be supported by a client
+
+
+• ToDo on server side:
+• ToDo on client side:
+
+
+## 3. Import of prepared project into Eclipse
+1. File > Import
+2. General > Existing Projects ...
+3. Click ‚Next‘
+4. Browse <Select Project Folder>
+5. Click ‚Finish’
+
+1. Create a new resource class TemperatureResource
+2. Instantiate a new ResourceServer
+3. Instantiate a new TemperatureResource
+4. Add the TemperatureResource to the ResourceServer
+5. Run the ResourceServer
+1. Establish a connection to the Server using the ChannelManager
+2. Create a CoapRequest & add some Options
+3. Send the CoapRequest
+4. Wait for CoapResponse
+5. Print the CoapResponse on the console
+
+• the resulting GUI should look like this:
+• We have prepared some FIXME and TODO annotations:
+o Just open the „Task“ view
+o FIXMEs are for the first task (message exchange)
+o TODOs are for the second task (observe and AC control)
+• If you do not have a „Task“ view:
+o Window > Show View > Other
+o Type „task“
+o Select „General > Task“ view
+
+
+## 4. Task 1: Implementation of client/server and enable simple message exchange
+
+1. Create a new resource class TemperatureResource (TemperatureResource.java):
+* We could have used the predefined BasicCoapResource
+* BasicCoapResource is a resource that just keeps a static `byte[ ]` that is:
+** returned on GET requests
+** replaced by the payload on PUT requests
+** appended with the payload on POST requests
+** deleted on DELETE requests
+** We do not want a static `byte[ ]`
+* Instead we want a random number to be returned on a GET
+* PUT, POST and DELETE are not used
+* ->So we implemented TemperatureResource wich extends BasicCoapResource with:
+** A constructor
+*** To initialize the resource
+*** Disallow POST, PUT and DELETE
+** 2 get() Methods
+*** Get a list of accepted media types [& query parameters]
+*** Returns a `byte[ ]` together with its media type
+** And the `getResourceType()` method
+*** Wich returns a description string of the resource
+2. Instantiate a new ResourceServer (Server.java, FIXME 1):
+* Need a CoapResourceServer to maintain resources
+`CoapResourceServer resourceServer = new CoapResourceServer();`
+3. Instantiate a new TemperatureResource (Server.java, FIXME 2):
+* Resources are created like normal objects and added to the server
+`CoapResource resource = new CoapResource();`
+1. Create a new resource class TemperatureResource
+2. Instantiate a new ResourceServer
+3. Instantiate a new TemperatureResource
+4. Add the TemperatureResource to the ResourceServer
+5. Run the ResourceServer
+already done in our example Server
+• Use the „Tasks“ view of Eclipse to find the right places
+• Solve only FIXME 1-3 as described by the following instructions - ignore other FIXMEs or TODOs
+
+4. Add the TemperatureResource to the ResourceServer (Server.java, FIXME 3):
+* Resources are created like normal objects and added to the server
+`resourceServer.createResource(resource);`
+5. Run the ResourceServer (Server.java):
+`resourceServer.start();`
+* Run Server: Click on Run -> Run in the Menu bar
+* To stop the server, press the red terminate button in the console/task area
+* Test it with Copper: coap://127.0.0.1
+* Stretch goal:
+** Create another resource type e.g.: humidity or current Time
+*** Tip: make a copy of „TemperatureResource.java“
+
+1. Establish a connection to the Server using the ChannelManager (Client.java, FIXME 4-5):
+* A client must implement CoapClient interface
+public class Client implements CoapClient {
+* A CoapChannelManager is used to manage different connections and to establish a connection to a server
+`channelManager = BasicCoapChannelManager.getInstance();`
+`clientChannel = channelManager.connect(CoapClient client,InetAddress serverIP, int serverPort);`
+Client
+* Use the „Tasks“ view of Eclipse to find the right places
+* Solve only FIXME 4-9 as described by the following instructions - ignore other FIXMEs or TODOs
+1. Establish a connection to the Server using the ChannelManager
+2. Create a CoapRequest & add some Options
+3. Send the CoapRequest
+4. Wait for CoapResponse
+5. Print the CoapResponse on the console
+already done in our example
+
+2. Create a CoapRequest & add some Options (Client.java, FIXME 6-8):
+* A channel represents a single connection and is used to create and send requests
+`Boolean reliable = false;`
+`CoapRequestCode reqCode = CoapRequestCode.GET;`
+`CoapRequest request = clientChannel.createRequest(reliable,reqCode);`
+`request.setUriPath("/temperature");`
+3. Send the CoapRequest (Client.java, FIXME 6-8):
+`clientChannel.sendMessage(request);`
+4. Wait for CoapResponse & Print the CoapResponse on the console
+• A client has some callbacks that are invoked, when the corresponding event occurs
+`public void onConnectionFailed(...)`
+`public void onResponse(...) // = Unicast`
+`public void onMCResponse(...) // MC = Multicast`
+* Run Server: select Server.java and click on Run -> Run in the Menu bar
+* Run Client: select Client.java and click on Run -> Run in the Menu bar
+* Stretch goal:
+** GET the “/.well-known/core” resource (it is generated automatically by the server)
+** If you have written your own resources before: GET them
+
+## 5 Task 2: Implementation of a AC control by using the CoAP-observe mechanism
+
+1. Use the eventing mechanism CoAP-Observe
+2. Let the server notify clients every 5 seconds about a changed TemperatureResource
+3. Implement an Air Conditioner Resource with the path “/ACControl”, that can be set to “high”,
+“medium”, “low” or “off”
+* 28 <= Temperature -> high
+* 25 <= Temperature < 28 -> medium
+* 21 <= Temperature < 25 -> low
+* Temperature < 21 -> off
+1. Use the eventing mechanism CoAP-Observe (Server.java, TODO 10):
+• Mark the TemperatureResource as observable
+`resource.setObservable(true);`
+2. Let server notify clients every 5 s about changed TemperatureResource (Server.java, TODO 11):
+* indicate a change for resource every 5 seconds
+`while (true) {
+try {Thread.sleep(5000);}
+catch (InterruptedException e) {/*do nothing*/}
+resource.changed();
+}`
+* Use the „Tasks“ view of Eclipse to find the right places
+* Solve only TODO 10-15 as described by the following instructions - ignore other TODOs or FIXMEs
+
+3. Implement an Air Conditioner Resource with the path “/ACControl”, that can be set to “high”,
+“medium”, “low” or “off” (Client.java & Server.java, TODO 12-15):
+* Change exitAfterResponse to false (Client.java, TODO 12)
+* Add the observe-option to your CoAP-GET request (Client.java, TODO 13)
+request.setObserveOption(0);
+* add a BasicCoapResource to the ResourceServer (Server.java, TODO 14)
+resourceServer.createResource( newBasicCoapResource(“/ACControl”,”off”,CoapMediaType.text_plain));
+* send PUT request (Client.java, TODO 15)
+`CoapRequest request = clientChannel.
+createRequest(true, CoapRequestCode.PUT);
+request.setUriPath(“/ACControl”);
+request.setContentType(CoapMediaType.text_plain);
+/*Depending on the received payload high, medium, low, off*/
+request.setPayload(“medium”.getBytes());
+clientChannel.sendMessage(request);`
+* 28 <= Temperature -> high
+* 25 <= Temperature < 28 -> medium
+* 21 <= Temperature < 25 -> low
+* Temperature < 21 -> off
\ No newline at end of file