diff --git a/firmwareapi/pycom/network/coap.md b/firmwareapi/pycom/network/coap.md new file mode 100644 index 0000000..57c2c71 --- /dev/null +++ b/firmwareapi/pycom/network/coap.md @@ -0,0 +1,165 @@ +# COAP + +This module implements a CoAp Server. + +## Usage Example + +```python + +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:///.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`