Skip to main content

Gets started with CoAP

Support
  • Updated

This tutorial will show you how to quickly test the connection of your devices to Servitly using the CoAP standard protocol.

To publish data through the CoAP protocol, you can download the Eclipse CoAP library for Java from Eclipse CoAP official site.

CoAP is available in several programming languages, check out the download page for more details.

Before starting publishing data you need a Servitly account where to connect, if you don’t already have an account you can use the Servitly sandbox environment to create a new one, and make your tests, instead, jump to the Publishing Data section directly.

 

Account Creation

  1. Create a new account on Servitly Lab, from the home page click the Create new account link and follow the instructions. Once the activation email has been received, click the registration link within the mail, and complete all the required fields. This step will create a new Customer and User under the Servitly Lab tenant.

Create account

  1. When the account registration is completed, it will be possible to authenticate on the platform by using the credentials just provided.

Account creation

  1. Within the Locations page, click on the Add Location button (top right) to create a new Location, which is the physical place where the equipment is located (e.g., a shop, a home, a production plant).

Edit location

  1. Press the upper chevron (top right) to access the created Location

  2. Within the Equipment list press the Add Equipment button to create a new one, and provide the following information:

Edit equipment

  • Name: as desired, it’s the mnemonic name of the equipment.

  • Serial Number: as desired, it’s the equipment’s unique serial number.

  • Thing Definition: select Generic-Device, it’s the default equipment definition for testing that includes a predefined set of metrics, commands, configuration parameters, and alerts definitions.

  • GPS Position: optional, inherited from the location if specified.

  1. Once saved, go to the equipment Connection tab to configure how the Equipment will connect to the cloud. Provide the following information:

    • Type: Servitly CoAP Connector

    • CoAP Server URL: coap.servitly.com:5683

    • Username: as desired by you, it is the unique username identifying the CoAP connection. It’s the root part of the CoAP URL <USERNAME>/<ASSET_ID>/<METRIC_PATH>

    • Payload Format: JSON

    • Asset Id: the equipment identifier that will be used as the CoAP sub-path (usually it is equivalent to the Serial Number or the MAC address of the device)

Edit equipment mapping

  1. Press the upper chevron (top right) to go back to the Thing dashboard.

  2. Now we are ready to open a CoAP connection and start sending data to Servitly.

Publishing Data

To publish data through the CoAP channel, the following information is needed:

 

  • CoAP Server URL: the CoAP broker connection URL.

  • Username: the username used to open the CoAP connection.

  • Asset Id: the device identifier used within the publishing topic, and same as specified within the Thing mapping.

  • Metric Path: the path mapping of the metrics you want to publish.


For more details about how to configure the connection properties, enter the device dashboard page and click on the Edit button (top right), and then enter the Connection tab.

Please note that the publishing URL must have this structure <USERNAME>/<ASSET_ID>/<METRIC_PATH>, for this test you can use measures as the metric path.

The code below is a very basic sample that connects to the Servitly CoAP server and publishes a message by using Californium CoapClient. Remember to replace the variables (<***>) with your connection properties.

 

package com.servitly.test.coap;

import static org.junit.Assert.assertTrue;
import java.net.URI;
import org.eclipse.californium.core.CoapClient;
import org.eclipse.californium.core.CoapResponse;
import org.eclipse.californium.core.coap.MediaTypeRegistry;
import org.eclipse.californium.core.network.CoapEndpoint;
import org.eclipse.californium.core.network.config.NetworkConfig;
import org.eclipse.californium.elements.UDPConnector;
import com.fasterxml.jackson.databind.node.JsonNodeFactory;
import com.fasterxml.jackson.databind.node.ObjectNode;

public class TestCoAP {

    public static void main(String args[]) throws Exception {

        URI uri = new URI("coap://coap.servitly.com:5683/<USERNAME>/<ASSET_ID>/measures");

        ObjectNode payload = JsonNodeFactory.instance.objectNode();
        payload.set("ts", System.currentTimeMillis());
		ObjectNode data = JsonNodeFactory.instance.objectNode();
        data.put("measure1", 42);
        data.put("measure2", 42);
        payload.set("data", data);
        System.out.println(payload.toString());

        CoapClient client = new CoapClient(uri);
        client.setEndpoint(new CoapEndpoint(new UDPConnector(), NetworkConfig.getStandard()));
        CoapResponse response = client.post(payload.toString(), MediaTypeRegistry.APPLICATION_JSON);
        assertTrue(response.isSuccess());
        System.out.println(response.getResponseText());
        client.shutdown();

    }

}

 

Let’s see how it works.

 

CoAP Connection Setup

URI uri = new URI("coap://coap.servitly.com:5683/<USERNAME>/<ASSET_ID>/measures");

 

Here, we are defining the URI to use for opening the connection, all the parameters needed (username, asset-id) have been configured during the Thing registration within Servitly.

 

Create the CoAP message payload

ObjectNode payload = JsonNodeFactory.instance.objectNode();
payload.set("ts", System.currentTimeMillis());
ObjectNode data = JsonNodeFactory.instance.objectNode();
data.put("measure1", 42);
data.put("measure2", 42);
payload.set("data", data);

 

Here, we are preparing the CoAP payload that contains the measures being sent to Servitly. A generic payload has the following format:

 

{"ts": 1605179226000,
 "data":{
    "measure1": 42,
    "measure2": 24
 }
}

 

The ts field is optional, and if omitted, the server-side receive timestamp is used.

The Generic-Device-Coap thing-definition exposes two metrics:

 

METRIC

MAPPING PATH

MAPPING NAME

Measure 1

measures

measure1

Measure 2

measures

measure2

 

Publish the CoAP Message

CoapClient client = new CoapClient(uri);
client.setEndpoint(new CoapEndpoint(new UDPConnector(), NetworkConfig.getStandard()));
CoapResponse response = client.post(payload.toString(), MediaTypeRegistry.APPLICATION_JSON);
assertTrue(response.isSuccess());
System.out.println(response.getResponseText());
client.shutdown();

 

Here, we are creating the CoAP client that will connect to Servitly and will send the message that we have previously created.

If everything works correctly, the result will be the Connection Status changed to ONLINE, and then a new measure is received.

 

Dashboard

 

Technical Restrictions

  • The communication between the gateway and Servitly is UDP-based and not encrypted.

  • The CoAP server is exposed on 5683 port, to open the connection this information is mandatory:

    • username: credential defined within the Connection tab of the equipment registered within Servitly.

    • asset-id: id of the asset opening the connection, usually the serial number of the equipment or the MAC address is used.

  • The CoAP URI must always start with the <USERNAME>/<ASSET_ID>/ path.

  • The CoAP URI must always end with the metric mapping path.

  • The Servitly Lab tenant allows 200 measures per hour per equipment, the measures exceeding such a limit will be discarded until the end of the hour.

Related articles

Comments

0 comments

Please sign in to leave a comment.