mirror of
https://github.com/sascha-hemi/pycom-documentation.git
synced 2026-03-21 06:06:03 +01:00
Add documentation of Coap-server module
This commit is contained in:
Geza Husi
165
firmwareapi/pycom/network/coap.md
Normal file
165
firmwareapi/pycom/network/coap.md
Normal file
@@ -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://<Coap-Server's address>/.well-known/core
|
||||
</resource2>,</resource1>;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`
|
||||
Reference in New Issue
Block a user