home.markdown

@@ -11,17 +11,20 @@ The following points will be covered by this tutorial:
 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:
+## 1. Requirements for this tutorial
 * JAVA SE JDK 1.6+
 * Eclipse IDE for JAVA development
 * Prepared JAVA project files for Hands-on
 
-## 1. Installation of Copper Plugin for Mozilla Firefox
+## 2. 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
+After the installation you can enter coap://host:port/resourcePath/?query=filter.
+Copper will allow you to make any CoAP interaction interactively.
+
+## 3. Introduction of jCoAP
 - WS4D-jCoAP: Java implementation of CoAP
  - http://ws4d.org/
  - https://gitlab.amd.e-technik.uni-rostock.de/ws4d/jcoap
@@ -32,28 +35,16 @@ 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
+**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
@@ -62,6 +53,7 @@ Client Side
  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
@@ -69,7 +61,10 @@ Client Side
  4. Wait for CoapResponse
  5. Print the CoapResponse on the console
 
-## 3. Import of prepared project into Eclipse
+## 4. Import of prepared project into Eclipse
+
+You can find the required files in our repository at [file](ws4d/jcoap/tree/master/ws4d-jcoap-handsOn)
+
 1. File > Import
 2. General > Existing Projects ...
 3. Click ‚Next‘
@@ -87,7 +82,9 @@ Client Side
  * Type „task“
  * Select „General > Task“ view
 
-## 4. Task 1: Implementation of client/server and enable simple message exchange
+## 5. Task 1: Implementation of client/server and enable simple message exchange
+
+### Server
 
 1. Create a new resource class TemperatureResource (already done in our example Server)
 2. Instantiate a new ResourceServer
@@ -95,8 +92,8 @@ Client Side
 4. Add the TemperatureResource to the ResourceServer
 5. Run the ResourceServer
 
-1. Create a new resource class TemperatureResource (TemperatureResource.java):
 
+#### 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
@@ -107,81 +104,85 @@ Client Side
 * 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
+ * A constructor to initialize the resource and disallow POST, PUT and DELETE requests
+ * Two 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):
+#### 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):
+#### 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):
+#### 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):
+#### 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“
+ * Create another resource type e.g.: humidity or current Time
+ * Tip: make a copy of „TemperatureResource.java“
+
+### Client
 
-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):
+#### 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 {`
+    `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):
+
+#### 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):
+
+#### 3. Send the CoapRequest (Client.java, FIXME 6-8):  
     `clientChannel.sendMessage(request);`
-4. Wait for CoapResponse & Print the CoapResponse on the console
+
+#### 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
+ * 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
+## 6. 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”
 
+
 1. Use the eventing mechanism CoAP-Observe (Server.java, TODO 10):
- * Mark the TemperatureResource as observable `resource.setObservable(true);`
+ * 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) {`  
@@ -197,7 +198,7 @@ Client
 `CoapRequest request = clientChannel.createRequest(true, CoapRequestCode.PUT);`  
 `request.setUriPath(“/ACControl”);`  
 `request.setContentType(CoapMediaType.text_plain);`  
-Depending on the received temperature, set the payload to high, medium, low, off
+Depending on the received temperature, set the payload to high, medium, low or off  
 28 <= Temperature -> high  
 25 <= Temperature < 28 -> medium  
 21 <= Temperature < 25 -> low