Update Coap documentation as per review findings

Author: geza-pycom

config.toml

@@ -513,6 +513,13 @@ theme = "doc-theme"
     parent = "tutorials@all"
     weight = 190
 
+[[menu.main]]
+    name = "CoAp"
+    url = "/tutorials/all/coap/"
+    identifier = "tutorials@all@coap"
+    parent = "tutorials@all"
+    weight = 200
+
 [[menu.main]]
     name = "LoRa Examples"
     url = "/tutorials/lora/"

content/firmwareapi/pycom/network/coap.md

@@ -5,7 +5,7 @@ aliases:
     - firmwareapi/pycom/network/coap.md
     - chapter/firmwareapi/pycom/network/coap
 ---
-This module implements a CoAp Server and Client, operating as both at the same time.
+This module implements a CoAp Server and Client.
 
 ## Usage Example of CoAp Server
 
@@ -15,26 +15,11 @@ from network import WLAN
 from network import Coap
 import _thread
 
-# Callback to be called when a new resource has been added via PUT
-def new_resource_callback(new_resource):
-    details = new_resource.get_details()
-    print("New resource has been created!")
-    print("URI: {}".format(details[0]))
-    print("Mediatype: {}".format(details[1]))
-    print("Max Age: {}".format(details[2]))
-    print("ETAG: {}".format(details[3]))
-    print("ETAG value: {}".format(details[4]))
-    print("Value: {}".format(new_resource.value()))
-    # Configure the properties of the new resource
-    new_resource.set_details(mediatype=Coap.MEDIATYPE_TEXT_PLAIN, max_age=132, etag=True)
-
 # Thread handling the CoAp Server
 def coap_thread():
     while True:
-        # Call Coap.read() without specyfing timeout value, in this way it handles all requests sent to the CoAp Server silently
         Coap.read()
 
-
 # Connect to the network
 wlan = WLAN(mode=WLAN.STA)
 wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key'))
@@ -44,26 +29,17 @@ Coap.init(str(wlan.ifconfig()[0]), service_discovery=True, dynamic_resources=Tru
 # Register callback which will be called when new resource is added via PUT
 Coap.register_new_resource_handler(new_resource_callback)
 
-# Add a resource with default value and plain text content format
+# Add an example resource with URI "resource1" and value "default_value" and content format "plain text" 
 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)
-
 # Start a new thread which handles the CoAp Server
 _thread.start_new_thread(coap_thread, ())
 
 ```
 
-## Usage Example of CoAp Client in blocking mode
+## Usage Example of CoAp Client
 
 ```python
 
@@ -83,110 +59,29 @@ def response_callback(code, id_param, type_param, token, payload):
 # Thread handling the sockets
 def coap_thread():
     while True:
-        # Using Coap.read() without timeout value means that if no new packet arrives to any of the client sessions registered before this is called, then this function will never return
         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)
+Coap.init(str(wlan.ifconfig()[0]))
 
 # Register the response handler for the requests the module initiates as a Coap Client
 Coap.register_response_handler(response_callback)
+# Create a new Client Session to use to communicate with the CoAp Server
+session = Coap.new_client_session("server-ip-address")
 
-# As the Coap.read() will be called in a form that it blocks until no new data arrives to the socket, it is only safe
-# to create new client sessions before Coap.read() is called
-session = Coap.new_client_session("192.168.0.234", 5683)
-
-# Start a new thread which calls Coap.read() which will block until no new packet arrives to the socket
+# Start a new thread which calls Coap.read() to handle incoming requests
 _thread.start_new_thread(coap_thread, ())
 
-# After this point it is not safe to create new Coap Client Session as they might not be handled by Coap.read()
-
-# Request to a normal CoAp Server
-id = session.send_request(Coap.REQUEST_GET, uri_path=".well-known/core", payload="payload", token="token1", include_options=True)
-print(id)
-# Request to a normal CoAp Server
-id = session.send_request(Coap.REQUEST_GET, uri_path="time", payload="payload", token="token2", include_options=True)
-print(id)
-# Request to a normal CoAp Server
-id = session.send_request(Coap.REQUEST_PUT, uri_path="time",content_format=Coap.MEDIATYPE_TEXT_PLAIN, payload="ABCD", token="token3", include_options=True)
-print(id)
-# Request to a Dish Telemetry server, payload is the AMQP message, token is maximum 8 bytes containing the IMEI or IMSI id, no options should be present
-imei = int('359738090028145').to_bytes(8, 'big')
-id = session.send_request(Coap.REQUEST_GET, payload="amqp://artemis:5672/dish.app1.FjhBV78.telemetry", token=imei, include_options=False)
+# Send a GET Request to the CoAp Server asking for all resources via URI ".well-known/core"
+id = session.send_request(Coap.REQUEST_GET, uri_path=".well-known/core")
 print(id)
 
 ```
 
-## Usage Example of CoAp Client in non-blocking mode
-
-```python
-
-from network import WLAN
-from network import Coap
-import _thread
-
-# Callback handling the responses to the requests sent to a Coap Server
-def response_callback(code, id_param, type_param, token, payload):
-    print("Code: {}".format(code))
-    # The ID can be used to pair the requests with the responses
-    print("ID: {}".format(id_param))
-    print("Type: {}".format(type_param))
-    print("Token: {}".format(token))
-    print("Payload: {}".format(payload))
-
-# Thread handling the sockets
-def coap_thread():
-    while True:
-        # Wait only 3 seconds for new packets then return back
-        # In the next call it will also handle any new CoAp Client Sessions created during the previous call
-        Coap.read(3000)
-
-
-# Connect to the network
-wlan = WLAN(mode=WLAN.STA)
-wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key'))
-
-# Initialize Coap module, to be used only as a CoAp Client
-Coap.init()
-
-# Start a new thread which handles the CoAp, it is safe to start as soon as possible as the Coap.read() has timeout specified
-# After this point it is safe to create new CoAp Client Sessions, it will be processed by the coap_thread correctly as Coap.read() is used with timeout value
-_thread.start_new_thread(coap_thread, ())
-
-# Register the response handler for the requests the module initiates as a Coap Client
-Coap.register_response_handler(response_callback)
-
-# Create a new client session on demand
-session1 = Coap.new_client_session("192.168.0.234", 5683)
-
-# Request to a normal CoAp Server via CoAp Client Session: session1
-id = session1.send_request(Coap.REQUEST_GET, uri_path=".well-known/core", token="session1")
-print(id)
-# Request to a normal CoAp Server via CoAp Client Session: session1
-id = session1.send_request(Coap.REQUEST_GET, uri_path="time", token="session1")
-print(id)
-
-# Create again a new CoAp Client Session on demand, without restriction
-session2 = Coap.new_client_session("192.168.0.236", 5683)
-
-# Request to a normal CoAp server via CoAp Client Session: session2
-id = session2.send_request(Coap.REQUEST_GET, uri_path=".well-known/core")
-print(id)
-# Request to a normal CoAp server via CoAp Client Session: session2
-id = session2.send_request(Coap.REQUEST_GET, uri_path="resource1")
-print(id)
-# Request to a normal CoAp server via CoAp Client Session: session2
-id = session2.send_request(Coap.REQUEST_POST, uri_path="resource1", payload="new_value")
-print(id)
-
-```
-
-
 ## Initialization
 
 #### Coap.init(address, *, port=5683, service_discovery=False, dynamic_resources=False)