pycom-documentation/firmwareapi/pycom/network/coap.md

COAP

This module implements a CoAp Server.

Usage Example

from network import WLAN
from network import Coap
import uselect
import _thread

# Thread handling the sockets
def socket_thread(p, coap_socket):
    while True:
        # Wait for any socket to become available
        sockets = p.poll()
        for s in sockets:
            sock = s[0]
            event = s[1]
            if(event & uselect.POLLIN):
                # Check if the socket belongs to COAP
                if(sock == coap_socket):
                    # Call Coap.read() which parses the incoming Coap message
                    Coap.read()


# Connect to the network
wlan = WLAN(mode=WLAN.STA)
wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key'))


# Initialize Coap module
Coap.init(str(wlan.ifconfig()[0]), service_discovery=True)

# Add a resource with default value and plain text content format
r = Coap.add_resource("resource1", media_type=Coap.MEDIATYPE_TEXT_PLAIN, value="default_value")
# Add an attribute to the resource
r.add_attribute("title", "resource1")
# Add an attribute to the resource
r.add_attribute("ct", str(Coap.MEDIATYPE_TEXT_PLAIN))
# Configure the possible operations on the resource
r.callback(Coap.REQUEST_GET | Coap.REQUEST_POST | Coap.REQUEST_PUT, True)

# Add a resource without default value, XML content format and E-Tag enabled
r = Coap.add_resource("resource2", media_type=Coap.MEDIATYPE_APP_XML, etag=True)
# Configure the possible operations on the resource
r.callback(Coap.REQUEST_GET | Coap.REQUEST_POST | Coap.REQUEST_PUT | Coap.REQUEST_DELETE, True)

# Get the UDP socket created for the Coap Server
coap_server_socket = Coap.socket()

# Create a new poll object
p = uselect.poll()
# Register the Coap Server's socket to the poll
p.register(coap_server_socket, uselect.POLLIN | uselect.POLLHUP | uselect.POLLERR)

# Start a new thread which will handle the sockets of "p" poll
_thread.start_new_thread(socket_thread, (p, coap_server_socket))

Initialization

Coap.init(address, *, port=5683, service_discovery=False)

Initialize the Coap Server module.

Arguments are:

• address is the address where Coap Server will listen.
• port is the port where Coap Server will listen, if not given it is the default Coap UDP port: 5683.
• service_discovery is a boolean argument to enable/disable service discovery. If enabled, the Coap Server will listen on the Coap Multicast address too: 224.0.1.187. By default it is disabled.

Module's methods

Coap.socket()

Returns with the socket assigned to the given address and port during Coap.init() (= assigned to the Coap Server).

Coap.add_resource(uri, *, media_type=-1, max_age=-1, value=0, etag=False)

Create a resource object and add it to the Coap Sever.

• uri is the full path of the resource.
• media_type is the media type (Coap option: Content-Format) of the resource. If not given, no defined media type is associated with the resource.
• max_age is the maximum time in seconds when the value of the resource is considered fresh (Coap option: Max-Age). If not given, no fresh time is associated with the resource.
• value is the default value of the resource. If not given it is initialized to decimal 0.
• etag is a boolean argument to enable/disable entity tag calculation (Coap option: ETag). By default it is turned off.

{% hint style="info" %} Media type argument should be one of the standard defined value which are available via Coap module's constants. {% endhint %}

{% hint style="info" %} Entity tag calculation is a simple counter increment between value 1-65535 with overflow but without value 0. Incremented each time the value of the resource is changed. {% endhint %}

Coap.remove_resource(uri)

Remove the resource defined by uri argument.

• uri is the full path of the resource to be removed.

Coap.get_resource(uri)

Returns with the resource defined by uri argument.

• uri is the full path of the resource to be returned.

Coap.read()

Must be called when a packet is received on the socket assigned to the Coap Server. This function parses the incoming request, composes and sends out the response.

Class resource

The resource class represents a resource in the scope of the Coap Server. A new resource can be only created with the Coap.add_resource function.

Class methods

The following methods are defined in the scope of the resource class.

resource.add_attribute(name, value)

Add a new attribute to the resource. Attributes are used to explain the resource during service discovery.

• name is the name of the resource.
• value is the value of the resource.

{% hint style="info" %} During service discovery, GET request to ".well-know/core", the attributes are returned with the belonging values. E.g. using the "libcoap's" command line coap-client to fetch the resource from our server:

coap-client -m get coap://<Coap-Server's address>/.well-known/core ,;ct=0;title=resource1

{% endhint %}

resource.value(value)

Update or fetch the value of the resource.

• value is the value to update the current value with. If the method is called without parameter the current value is returned.

resource.callback(operation, enable)

To enable or disable a specific operation (GET, PUT, POST, DELETE) on the resource.

• operation is the operation to enable/disable, can be ORED of the followings: Coap.REQUEST_GET, Coap.REQUEST_PUT, Coap.REQUEST_POST, Coap.REQUEST_DELETE
• enable is boolean parameter to enable/disable the operations specified by operation

{% hint style="info" %} During a GET request, only the first occurance of an ETAG or Accept option is parsed and interpreted, the others of the same type are dropped (if any). {% endhint %}

{% hint style="info" %} During a PUT request, only the first occurance of an If-Match option is parsed and interpreted, the others of the same type are dropped (if any). {% endhint %}

{% hint style="danger" %} Due to limitations of the underlying ESP-IDF/libcoap library, new resources cannot be added via PUT or POST requests. {% endhint %}

Constants

• Define the media type: Coap.MEDIATYPE_TEXT_PLAIN, Coap.MEDIATYPE_APP_LINK_FORMAT, Coap.MEDIATYPE_APP_XML, Coap.MEDIATYPE_APP_OCTET_STREAM, Coap.MEDIATYPE_APP_RDF_XML, Coap.MEDIATYPE_APP_EXI, Coap.MEDIATYPE_APP_JSON, Coap.MEDIATYPE_APP_CBOR
• Define the operation: Coap.REQUEST_GET, Coap.REQUEST_PUT, Coap.REQUEST_POST, Coap.REQUEST_DELETE