|
|
# 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 |