CoAP Class

Properties   Methods   Events   Configuration Settings   Errors  

An easy-to-use CoAP client and server implementation.

Syntax

class ipworksiot.CoAP

Remarks

The CoAP class provides a lightweight, fully-featured CoAP client and server implementation.

Using the Class in Client Mode

While in client mode (i.e., the listening property is disabled; its default setting), the class can be used to send requests to a CoAP server. It can also be used to register as an observer for various server-side resources, causing the server to send notifications anytime said resources change.

To send a request, populate the request_data, request_content_format, request_e_tag, and RequestOption* properties (if necessary, and as applicable), then call one of the following methods:

• get
• post
• put
• delete
• send_custom_request

The methods above require a URI as a parameter. The format of the URI parameter is coap://hostname:port/resource. The port is optional, and if not specified will default to 5683. For instance coap://myserver/test and coap://myserver:5683/test are equivalent.

Once a response is received, the response_code, response_data, response_content_format, response_e_tag, and ResponseOption* properties will be populated, and the on_request_complete event will fire. (If the request times out, the properties are not populated, but the event still fires.)

coap.OnRequestComplete += (s, e) => {
  Console.WriteLine("Request complete!");
  Console.WriteLine(coap.ResponseCode);
};

// Make a GET request to download a picture.
coap.Get("coap://mycoapserver/pictures/animals/cats4.dat?format=png");
// Imaginary function which accepts PNG image data and displays the picture to the user.
showPicture(coap.ResponseDataB);

To observe a resource, call the start_observing method. Assuming the server accepts the observer registration request, it will begin sending notifications for the resource anytime it changes. Each change notification will cause the response_code, response_data, response_content_format, response_e_tag, and ResponseOption* properties to be populated, and the on_notification event to fire.

To stop observing a resource, either call stop_observing with the same URI value used to call start_observing, or set the on_notification event's StopObserving parameter to True.

coap.OnNotification += (s, e) => {
  // Notifications can arrive out of order; only print to the log if this is the latest one we've received.
  if (e.IsLatest) {
    Console.WriteLine("Received notification for the resource at: " + e.URI);
    Console.WriteLine("New Value: " + coap.ResponseData);
  }
}

// Start observing a temperature sensor's data. Assume temperature values are sent back in text format.
coap.StartObserving("coap://mycoapserver/home/living_room/sensors/temperature?unit=fahrenheit");

// Assume the server accepts the request and starts sending notifications every so often.
// ...
// Later, stop observing the resource.
coap.StopObserving("coap://mycoapserver/home/living_room/sensors/temperature?unit=fahrenheit");

Using the Class in Server Mode

To operate in server mode, set the local_port to the port the class should listen on (typically 5683, the standard CoAP port), then enable the listening property. Each time a request arrives, the request_data, request_content_format, request_e_tag, and RequestOption* properties will be populated, and the on_request event will fire.

A response can be sent by populating the response_code, response_data, response_content_format, response_e_tag, and ResponseOption* properties as desired before the event finishes. Alternatively, the on_request event's SendResponse parameter can be set to False in order to send a response back later. In this case, the RequestId value from the event should be used to call the send_response method later.

coap.OnRequest += (s, e) => {
  // For the purpose of this snippet, assume we only service GET requests, which have a method code of 1.
  if (e.Method == 1) {
    Console.WriteLine("GET request received for URI path: " + e.URIPath + " and URI query params: " + e.URIQuery);
    coap.ResponseCode = "2.05"; // "Content".
    // Imaginary methods that look up the data and content format of the resource based on the URI path and URI query parameters.
    coap.ResponseData = lookupResourceData(e.URIPath, e.URIQuery);
    coap.ResponseContentFormat = lookupResourceContentFormat(e.URIPath, e.URIQuery);
  } else {
    coap.ResponseCode = "4.05"; // "Method Not Allowed".
    coap.ResponseData = "Only GET requests are allowed."; // Include a diagnostic payload.
    coap.ResponseContentFormat = "";
  }
  // Alternatively, this event could simply save the e.RequestId value somewhere, then some other code could fill in the Response*
  // properties and call the SendResponse() method later.
};

coap.OnResponseComplete += (s, e) => {
  Console.WriteLine("Response sent for request with Id " + e.RequestId);
};

In server mode, the class can also support resource observation. When a client attempts to register itself as an observer of a resource, the on_register event will fire; setting this event's Accept parameter to True will cause the class to accept the registration.

To notify clients that a resource has changed, populate the response_code, response_data, response_content_format, response_e_tag, and ResponseOption* properties as desired, and then call the send_notification method, passing it the URI of a resource that has registered observers.

When a client has unregistered from further change notifications, the on_unregistered event will fire.

coap.OnRegister += (s, e) => {
  Console.WriteLine("Client " + e.RemoteHost + ":" + e.RemotePort + " has registered for notifications for the URI " + e.URI);
  // Imaginary method that helps ensure the application keeps track of observed URIs. The class itself maintains the
  // list of observers for each URI, so the application just needs to know that there are observers in the first place.
  observerRegisteredForURI(e.URI);
  e.Accept = true;
};
coap.OnUnregistered += (s, e) => {
  Console.WriteLine("Client " + e.RemoteHost + ":" + e.RemotePort + " has unregistered from notifications for the URI " + e.URI);
  // As above, imaginary method that helps ensure the application keeps track of observed URIs.
  observerUnregisteredForURI(e.URI);
};

// Somewhere else in the application, this sort of code might get called after a resource changes to inform any observers of
// the change. We use another imaginary method here to check if the changed resource is observed, and to get its information.
if (isResourceObserved()) {
  coap.ResponseCode = "2.05"; // "Content".
  coap.ResponseDataB = getResourceContent();
  coap.ResponseContentFormat = getResourceContentFormat();
  coap.SendNotification(getResourceURI());
}