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.
+
+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
+
+## 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)
+
+## 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
+
+- Server:
+ - individual implementation of a server application, creates CoapResourceServer and resources
+- TemperatureResource:
+ - individual resource, inherits from BasicCoapResource
+- BasicCoapResource:
+ - already implemented resource with basic functionality, implements CoapResource (interface)
+- CoapResource (interface):
+ - describes interfaces that must be supported by each resource.
+- CoapResourceServer:
+ - manages a list of resources, enables access of these resources from outside, implements
+- CoapServer (interface):
+ - uses ChannelManager for connection management.
+- CoapServer (interface):
+ - describes interfaces that must be supported by a resource server
+- ChannelManager:
+ - manages channels
+- Channel:
+ - one channel represents a connection to one client
+- Client:
+ - individual implementation of a client application, implements CoapClient (interface)
+- CoapClient (interface):
+ - describes interfaces that must be supported by a client
+
+* ToDo on server side:
+ 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
+
+
+* ToDo on client side:
+ 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
+
+## 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’
+
+* the resulting GUI should look like this:
+
+* We have prepared some FIXME and TODO annotations:
+ * Just open the „Task“ view
+ * FIXMEs are for the first task (message exchange)
+ * TODOs are for the second task (observe and AC control)
+* If you do not have a „Task“ view:
+ * Window > Show View > Other
+ * Type „task“
+ * Select „General > Task“ view
+
+## 4. Task 1: Implementation of client/server and enable simple message exchange
+
+1. Create a new resource class TemperatureResource (already done in our example Server)
+2. Instantiate a new ResourceServer
+3. Instantiate a new TemperatureResource
+4. Add the TemperatureResource to the ResourceServer
+5. Run the ResourceServer
+
+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();`
+
+* 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“
+
+Client
+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)
+
+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);`
+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