Tutorial: Add CoAP to your application

Alt text

Summary. This tutorial explains how to add CoAP interface to your already existing application to be able to view and/or control the application from the outside.

Background: Constrained Application Protocol (CoAP) is a software protocol intended to be used in very simple electronics devices that allows them to communicate interactively over the Internet. It is particularly targeted for small low power sensors, switches, valves and similar components that need to be controlled or supervised remotely, through standard Internet network. You can read more from the Wikipedia article here.


Prerequisites:

  • Some familiarity with Reactive Blocks is necessary to get the most out of this tutorial.
  • Install Mozilla Firefox and enable/download Copper (Cu) add-on. To test it enter coap://localhost:5683/ in the address field and you should see something like this:

Alt text


Get your application.

We will use the following example application to show you how to add CoAP:

Alt text

It is a very trivial system, but good for demonstrating CoAP. Once a second a number is calcuated based on step and direction variables. The numbers are accumulated in a third variable (value).

This is how to get it:

  • Start Eclipse and open Reactive Blocks perspective.
  • Import (Level 3) CoAP tutorial project. (Read here about import.)
  • Open the Sample application block.

Now you are ready to make the application speak CoAP.


Step 1: Expose Your variables.

In this step we will explain how you can make some of the variables in your application visible in the browser. We also show how you can modify them from the browser.

First, locate the Set and Get Data via CoAP library (in the libraries tab).

Alt text

If you cannot find the library, you must import it first. Read more about that here.


Do the following modifications to your system:

  • Drag the String Resource block into your system/block
  • Initialize the block with a variable name, hint: Use a method with input to init pin
  • Between get and val pins of the String Resource block add a method that formats a variable into a string.
  • Connect a method to set pin of the String Resource block to be able to set the variable directly
  • (Optional) Repeat this sequence for the other variables in your system.

There are many ways to do it, one implementation may look like this.

Alt text

The getValueName method initializes the block with variable name and the makeString method formats variable into string and last but not least the makeInt makes it possible to set the variable from the browser.

We used the following Java code:

Alt text


Build the application and launch it. You may need to allow Eclipse to open the 5683 port in the firewall.

Now, open Mozilla Firefox browser (still with Copper (Cu) extension enabled) and enter coap://localhost:5683/ in the address field.

Then click the “Discover” button and you will see magic happens.

Alt text

Now you should see your variable name in the tree to the left.


Click the variable name (value), then click Get button several times and you should see the variable counting up. It may look like this:

Alt text


Click the Outgoing tab, enter “0” (or any other number) and click the Put button. The variable should be changed now.

Alt text


You can find a completed system in Sample application with exposed variables in tutorial project ((Level 3) CoAP).


Step 2: Command and control.

Now we have learnt to expose variables.

In this next step we will show a pattern to enter commands and to control your application. In your application, do the following:

  • Drag another instance of String Resource block into your system/block
  • Initialize the block instance with variable name command
  • Connect a decision to the output from the set pin
  • Add your commands to the different branches in the decision
    • Add these commands: start, stop, restart, kill (= stop application)
    • Add helpers for else branch and optionally a help command
    • In the example system the only thing the commands need to do is to start and/or stop the Periodic Timer, if your system looks different you may need to choose other commands.
  • (Optional) Connect a method between get and val pins of the String Resource block to be able to return command status (or invalid command message)

There are many ways to do it, one implementation may look like this.

Alt text

In the figure above, nodes labelled with toStart, toStop, collectResponse are connector merges. Those are merge nodes with labels of your own choice. You can add a connector merge like any other nodes, right-click and choose Add… → Connector Merge.

Alt text


Build the application and launch it. Again you may need to allow Eclipse to open the 5683 port in the firewall.

Now, open Mozilla Firefox browser (and the Copper (Cu) extension is still enabled) and enter coap://localhost:5683/ in the address field, press Discover to get all items.

You should see a variable named command, do the following steps to execute a command with it:

  • Click the command variable
  • Select the Outgoing tab
  • Enter restart in text field
  • Click Put

Alt text


  • (Optional) Then click the Get button and observe the output

Alt text

Now you can try the other commands and check if they behave as expected.


You can find a completed system in Sample application with command interface in tutorial project ((Level 3) CoAP).

If you want to challenge yourself you can make a turbo command to speed up the timer. The new timer parameter should of course be part of the command message.


Step 3: Prepare your own client.

So far we have been using Mozilla with an extension to monitor your application. For testing and debugging that is very fine, but for a production system you may want to make your own client.

For this step we will make a small Java application to control the backend application we already made in step 2. Fire up your backend system and keep it running. You may want to build without debug information, so it does not “reclaim” the console window all the time.

Now that you have the backend application running we will make the frontend application to control it.

For the client we will use the two blocks String Get Request and String Set Request from the same library as we used in the previous steps.

To get one value from the backend system, we use String Get Request* block like this:

Alt text

You may need to add additional blocks to poll the other variables or you may become creative and use a list of variables with an Iterator. You may also query variables in parallel instead of in sequence as the example does.


The getValueName method defines the parameters necessary to get the variable. In this example it would be the machine name, port number and name of variable. We use default port and localhost to indicate our own machine, but we could have used it to poll systems on other machines.

Alt text


To change a value or to issue a command you will use the String Set Request as demonstrated below. We need to buffer the commands, because each block is only capable of handling one request at a time.

Alt text

Each call to String Get Request* has attached an object that contains machine name, variable name and new value. See attached code for details, a constructor with port number is also also available.

Alt text


A complete system to control all values and use all command is published as Sample client in the tutorial project. It uses java.swing forms to enter commands and display values. Here is what it looks like.

Alt text


It will open this java.swing window where you can control the application. Below is a screenshot of the application.

Alt text


Note: The experienced user will notice that we use String Set Request also to modify the boolean variable direction. This is possible, since everything is transferred as strings and we chose to do it this way to make the system less complicated.