IPWorks IoT 2020 Delphi Edition

Questions / Feedback?

CoAP Component

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

TiotCoAP

Remarks

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

Using the Component in Client Mode

While in client mode (i.e., the Listening property is disabled; its default setting), the component 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 RequestData, RequestContentFormat, RequestETag, and RequestOption* properties (if necessary, and as applicable), then call one of the following methods:

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 ResponseCode, ResponseData, ResponseContentFormat, ResponseETag, and ResponseOption* properties will be populated, and the RequestComplete 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 StartObserving 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 ResponseCode, ResponseData, ResponseContentFormat, ResponseETag, and ResponseOption* properties to be populated, and the Notification event to fire.

To stop observing a resource, either call StopObserving with the same URI value used to call StartObserving, or set the 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 Component in Server Mode

To operate in server mode, set the LocalPort to the port the component should listen on (typically 5683, the standard CoAP port), then enable the Listening property. Each time a request arrives, the RequestData, RequestContentFormat, RequestETag, and RequestOption* properties will be populated, and the Request event will fire.

A response can be sent by populating the ResponseCode, ResponseData, ResponseContentFormat, ResponseETag, and ResponseOption* properties as desired before the event finishes. Alternatively, the 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 SendResponse 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 component can also support resource observation. When a client attempts to register itself as an observer of a resource, the Register event will fire; setting this event's Accept parameter to True will cause the component to accept the registration.

To notify clients that a resource has changed, populate the ResponseCode, ResponseData, ResponseContentFormat, ResponseETag, and ResponseOption* properties as desired, and then call the SendNotification method, passing it the URI of a resource that has registered observers.

When a client has unregistered from further change notifications, the 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 component 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());
}

Property List


The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

ListeningWhether the component should operate in server mode by listening for incoming requests.
LocalHostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPortThe UDP port in the local host where UDPPort binds.
PendingRequestsCollection of pending requests.
RequestContentFormatThe request content format.
RequestDataThe request data.
RequestETagThe request ETag.
RequestOptionsCollection of request options.
ResponseCodeThe response code.
ResponseContentFormatThe response content format.
ResponseDataThe response data.
ResponseETagThe response ETag.
ResponseOptionsCollection of response options.
TimeoutA timeout for the component.
UseConfirmableMessagesWhether to use confirmable message.

Method List


The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

CancelRequestCancels a pending request.
ConfigSets or retrieves a configuration setting.
DeleteSends a DELETE request to the server.
DoEventsProcesses events from the internal message queue.
GetSends a GET request to the server.
PostSends a POST request to the server.
PutSends a PUT request to the server.
ResetReset the component.
SendCustomRequestSends a custom request to the server.
SendNotificationSends a notification to all clients observing a given resource.
SendResponseSends a response for a given pending request to the corresponding client.
StartObservingRegisters the component as an observer for a given resource.
StopObservingUnregisters the component as an observer for a given resource.

Event List


The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

ErrorInformation about errors during data delivery.
LogFires once for each log message.
NotificationFires when a notification is received from the server.
RegisterFires when a client wishes to register for notifications.
RequestFires when a request is received from a client.
RequestCompleteFires when a request completes.
ResponseCompleteFires when a response has been sent to a client.
UnregisteredFires when a client has unregistered from notifications.

Configuration Settings


The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.

CaptureIPPacketInfoUsed to capture the packet information.
DestinationAddressUsed to get the destination address from the packet information.
DontFragmentUsed to set the Don't Fragment flag of outgoing packets.
LocalHostThe name of the local host through which connections are initiated or accepted.
LocalPortThe port in the local host where the component binds.
MaxPacketSizeThe maximum length of the packets that can be received.
QOSDSCPValueUsed to specify an arbitrary QOS/DSCP setting (optional).
QOSTrafficTypeUsed to specify QOS/DSCP settings (optional).
ShareLocalPortIf set to True, allows more than one instance of the component to be active on the same local port.
UseConnectionDetermines whether to use a connected socket.
UseIPv6Whether or not to use IPv6.
AbsoluteTimeoutDetermines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallDataUsed to send extra data to the firewall.
InBufferSizeThe size in bytes of the incoming queue of the socket.
OutBufferSizeThe size in bytes of the outgoing queue of the socket.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks IoT 2020 Delphi Edition - Version 20.0 [Build 8265]