Merge pull request #193 from husigeza/Coap_doc_fix

CoAp: Addressing review findings

Author: geza-pycom

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, it operates as both at the same time.
+This module implements a CoAp Server and Client, operating as both at the same time.
 
 ## Usage Example
 
@@ -16,7 +16,7 @@ from network import Coap
 import uselect
 import _thread
 
-# Callback handling the responses to the requests sent to a Coap Server
+# The callback that handles the responses generated from 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
@@ -34,20 +34,20 @@ def socket_thread(p, coap_socket):
             sock = s[0]
             event = s[1]
             if(event & uselect.POLLIN):
-                # Check if the socket belongs to Coap module
+                # Check if the socket belongs to the CoAp module
                 if(sock == coap_socket):
-                    # Call Coap.read() which parses the incoming Coap message
+                    # 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
+# Initialise the CoAp module
 Coap.init(str(wlan.ifconfig()[0]), service_discovery=True)
 
-# Add a resource with default value and plain text content format
+# Add a resource with a default value and a 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")
@@ -61,21 +61,21 @@ 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)
 
-# Register the response handler for the requests the module initiates as a Coap Client
+# Register the response handler for the requests that the module initiates as a CoAp Client
 Coap.register_response_handler(response_callback)
 
-# Get the UDP socket created for the Coap module
+# Get the UDP socket created for the CoAp module
 coap_server_socket = Coap.socket()
 
 # Create a new poll object
 p = uselect.poll()
-# Register the Coap Module's socket to the poll
+# Register the CoAp module'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))
 
-# Send a request to a Coap server
+# Send a request to a CoAp server
 id = Coap.send_request("192.168.0.234", Coap.REQUEST_GET, uri_port=5683, uri_path=".well-known/core", payload="payload", token="token1", include_options=True)
 print(id)
 
@@ -85,43 +85,43 @@ print(id)
 
 #### Coap.init(address, *, port=5683, service_discovery=False)
 
-Initialize the Coap module.
+Initialize the CoAp module.
 
-Arguments are:
+The arguments are:
 
-* `address` is the address where Coap Module will handle the communication .
-* `port` is the port where Coap Module 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 Module will listen on the Coap Multicast address too: 224.0.1.187. By default it is disabled.
+* `address` is the address where the CoAp module handles communication.
+* `port` is the port where the CoAp module listens. If not set, the default CoAp UDP port is 5683.
+* `service_discovery` is a Boolean argument that enables/disables service discovery. If enabled, the CoAp module will listen on the CoAp multicast address: 224.0.1.187. This is disabled by default.
 
-## Module's methods
+## Methods:
 
 #### Coap.socket()
 
-Returns with the socket assigned to the given `address` and `port` during `Coap.init()` (= assigned to the Coap Module).
+Returns with the socket assigned to the given address and port during Coap.init() (= assigned to the CoAp module).
 
 #### Coap.add_resource(uri, *, media_type=-1, max_age=-1, value=0, etag=False)
 
-Creates a resource object and adds it to the Coap Module to operate as a server.
+Creates a resource object and adds it to the CoAp module to operate as a server.
 
 * `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.
+* `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 that 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 initialised to decimal 0.
+* `etag` is a Boolean argument that enables/disables 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.
+Media-type argument is one of the standard defined values that is available via CoAp module's constants.
 {{% /hint %}}
 
 {{% 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.
+Entity tag calculation is a simple counter increment between value 1-65535 with overflow, it doesn't include the value 0. It is incremented each time and the value of the resource is changed.
 {{% /hint %}}
 
 
 #### Coap.remove_resource(uri)
 
-Removes the resource defined by `uri` argument.
+Removes the resource defined by the `uri` argument.
 
 * `uri` is the full path of the resource to be removed.
 
@@ -133,11 +133,11 @@ Returns with the resource defined by `uri` argument.
 
 #### Coap.read()
 
-Must be called when a packet is received on the socket assigned to the Coap Module. This function parses the incoming request, composes and sends out the response if needed.
+Must be called when a packet is received on the socket assigned to the CoAp module. This function passes on the incoming request, whilst also composing and sending out the response if needed.
 
 #### Coap.register_response_handler(callback)
 
-Registers a callback function which will be called when a remote Coap Server responses to our request.
+Registers a callback function which will be called when a remote CoAp Server responses to the local CoAp client's request.
 
 * `callback` is the callback to be registered. It must have the following arguments:
 * `code` is the response code from the received message
@@ -148,20 +148,20 @@ Registers a callback function which will be called when a remote Coap Server res
 
 #### Coap.send_request(uri_host, method, *, uri_port=5683, uri_path, content_format, payload, token, include_options=true)
 
-Creates and sends a request to a Coap server.
+Creates and sends a request to a CoAp server.
 
 * `uri_host` is the IP address of the server, included in the message as an "URI-HOST" option
 * `method` is the method to be sent to the server, can be: `Coap.REQUEST_GET`, `Coap.REQUEST_PUT`, `Coap.REQUEST_POST`, `Coap.REQUEST_DELETE`
-* `uri_port` is the port of the server, included in the message as an "URI-PORT" option, by default it is 5683
+* `uri_port` is the port of the server, included in the message as an "URI-PORT" option. By default it is 5683
 * `uri_path` is the full path of the resource in the server, included in the message as an "URI-PATH" option. If nothing is given the request will not have URI-PATH option.
 * `content_format` is the Content-Format option of the request, can be: `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`. If nothing is given the request will not have Content-Format option.
 * `payload` is the payload of the request. If nothing is given the request will not have payload.
 * `token` is the token field of the request. If nothing is given the request will not have token field.
-* `include_options` decides whether put any options (including the ones above) into the message or not. It can be used to send special requests to servers accepting Coap formed requests without options, e.g. to a Dish Telemetry server. By default the options are included.
+* `include_options` decides whether put any options (including the ones above) into the message or not. It can be used to send special requests to servers accepting CoAp formed requests without options, e.g. to a Dish Telemetry server. By default, the options are included.
 
 ## Class resource
 
-The resource class represents a resource in the scope of the Coap Module when acting as a server. A new resource can be only created with the `Coap.add_resource` function.
+The resource class represents a resource in the scope of the CoAp module when acting as a server. A new resource can only be created with the `Coap.add_resource` function.
 
 #### Class methods
 
@@ -175,7 +175,7 @@ Adds a new attribute to the resource. Attributes are used to explain the resourc
 * `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.
+During service discovery, GET request to ".well-know/core", the attributes are returned with the relevant 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
@@ -188,22 +188,22 @@ coap-client -m get coap://<Coap-Server's address>/.well-known/core
 
 Updates or fetches 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.
+* `value` is the new value to update the current value with.
+If the method is called without a 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`
+* `enable` is Boolean parameter that enables/disables 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).
+During a GET request, only the first occurrence of an ETAG or Accept option is passed on and interpreted; others of the same type are dropped (if any).
 {{% /hint %}}
 
 {{% 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).
+During a PUT request, only the first occurrence of an If-Match option is passed on and interpreted; others of the same type are dropped (if any).
 {{% /hint %}}
 
 {{% hint style="danger" %}}