Skip to content

Commit e1c805a

Browse files
ftylitakftylitak
committed
Finalize first version of README file adding example for the server operation, Future work and contribution statements
1 parent a4e0ae7 commit e1c805a

File tree

1 file changed

+97
-7
lines changed

1 file changed

+97
-7
lines changed

‎README.md‎

Lines changed: 97 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ It is a port of an Arduino C++ library [CoAP-simple-library](https://github.com/
55

66
Its main difference compared to the established Python implementations [aiocoap](https://github.com/chrysn/aiocoap) and [CoAPthon](https://github.com/Tanganelli/CoAPthon) is its size and complexity since this library will be used on microcontrollers that support MicroPython such as: Pycom devices, ESP32, ESP8266.
77

8-
The first goal of this implementation is to provide basic functionality to send and receive data. DTLS and/or any special features of CoAP as defined in the RFC's, will be examined and implented in the future.
8+
The first goal of this implementation is to provide basic functionality to send and receive data. DTLS and/or any special features of CoAP as defined in the RFC's, will be examined and implemented in the future.
99

1010
# Supported operations
1111

@@ -14,9 +14,9 @@ The first goal of this implementation is to provide basic functionality to send
1414
* POST
1515
* GET
1616

17-
## Example of usage
17+
### Example of usage
18+
Here is an example using the CoAP client functionality to send requests and receive responses. (this example is part of [examples/pycom_wifi_coap_client.py](https://github.com/insighiot/microCoAPy/blob/master/examples/pycom_wifi_coap_client.py))
1819

19-
Here is an example using the CoAP client functionality to send requests and receive responses.
2020

2121
```python
2222
import microcoapy.microcoapy as microcoapy
@@ -40,6 +40,7 @@ client.poll(2000)
4040
client.stop()
4141
```
4242

43+
#### Code explained
4344
Lets examine the above code and explain its purpose.
4445

4546
```python
@@ -56,23 +57,112 @@ During this step, the CoAP object get initialized. A callback handler is also cr
5657
client.start()
5758
```
5859

59-
The call to the _start_ function is where the UDP socket gets created. By default it gets bind to the defalut CoAP port 5683. If a custom port is needed, pass it as argument to the _start_ function.
60+
The call to the _start_ function is where the UDP socket gets created. By default it gets bind to the default CoAP port 5683. If a custom port is required, pass it as argument to the _start_ function.
6061

6162
```python
6263
bytesTransferred = client.get(_SERVER_IP, _SERVER_PORT, "current/measure")
6364
print("[GET] Sent bytes: ", bytesTransferred)
6465
```
6566

66-
Having the socket ready, it is time to send our request. In this case we send a simple GET request to the specific address (ex. 192.168.1.2:5683). The _get_ function returns the number of bytes that has been able to send. So in case of error, 0 will be returned.
67+
Having the socket ready, it is time to send our request. In this case we send a simple GET request to the specific address (ex. 192.168.1.2:5683). The _get_ function returns the number of bytes that have been sent. So in case of error, 0 will be returned.
6768

6869
```python
6970
client.poll(2000)
7071
```
7172

7273
Since a GET request has been posted, most likely it would be nice to receive and process the server response. For this reason we call _poll_ function that will try to read incoming messages for 2000 milliseconds. Upon timeout the execution will continue to the next command.
7374

74-
If a packet gets received during that period of type that is an _ACK_ to our request or a report (ex. _404_), the callback that has been registered at the beginning will be called.
75+
If a packet gets received during that period of type that is an _ACK_ to our request or a report (ex. _404_), the callback that has been registered at the beginning will be called.
7576

77+
```python
78+
client.stop()
79+
```
80+
81+
Finally, stop is called to gracefully close the socket. It is preferable to have a corresponding call of _stop_ to each call of _start_ function because in special cases such as when using mobile modems, the modem might stuck when running out of available sockets.
82+
83+
To send POST or PUT message replace the call of _get_ function with:
84+
```python
85+
bytesTransferred = client.put(_SERVER_IP, _SERVER_PORT, "led/turnOn", "test",
86+
None, microcoapy.COAP_CONTENT_TYPE.COAP_TEXT_PLAIN)
87+
```
88+
or
89+
```python
90+
bytesTransferred = client.post(_SERVER_IP, _SERVER_PORT, "led/turnOn", "test",
91+
None, microcoapy.COAP_CONTENT_TYPE.COAP_TEXT_PLAIN)
92+
```
93+
94+
For details on the arguments please advice the __documentation__ (link to be soon provided).
7695

7796
## CoAP server
78-
* Starts a server and calls custom callbacks upon receiving an incoming request. The respose needs to be defined by the user of the library.
97+
Starts a server and calls custom callbacks upon receiving an incoming request. The response needs to be defined by the user of the library.
98+
99+
### Example of usage
100+
101+
Here is an example using the CoAP server functionality to receive requests and respond back. (this example is part of [examples/pycom_wifi_coap_server.py](https://github.com/insighiot/microCoAPy/blob/master/examples/pycom_wifi_coap_server.py))
102+
103+
```python
104+
import microcoapy.microcoapy as microcoapy
105+
# your code to connect to the network
106+
#...
107+
client = microcoapy.Coap()
108+
109+
def measureCurrent(packet, senderIp, senderPort):
110+
print('Measure-current request received:', packet, ', from: ', senderIp, ":", senderPort)
111+
client.sendResponse(senderIp, senderPort, packet.messageid,
112+
None, microcoapy.COAP_RESPONSE_CODE.COAP_CONTENT,
113+
microcoapy.COAP_CONTENT_TYPE.COAP_NONE, "222")
114+
115+
client.addIncomingRequestCallback('current/measure', measureCurrent)
116+
117+
client.start()
118+
119+
# wait for incoming request for 60 seconds
120+
timeoutMs = 60000
121+
start_time = time.ticks_ms()
122+
while time.ticks_diff(time.ticks_ms(), start_time) < timeoutMs:
123+
client.poll(60000)
124+
125+
client.stop()
126+
```
127+
128+
#### Code explained
129+
Lets examine the above code and explain its purpose. For details on _start_ and _stop_ functions advice the previous paragraph of the client example.
130+
131+
```python
132+
def measureCurrent(packet, senderIp, senderPort):
133+
print('Measure-current request received:', packet, ', from: ', senderIp, ":", senderPort)
134+
client.sendResponse(senderIp, senderPort, packet.messageid,
135+
None, microcoapy.COAP_RESPONSE_CODE.COAP_CONTENT,
136+
microcoapy.COAP_CONTENT_TYPE.COAP_NONE, "222")
137+
138+
client.addIncomingRequestCallback('current/measure', measureCurrent)
139+
```
140+
141+
This is the main step to prepare the CoAP instance to behave as a server: receive and handle requests. First we create a function _measureCurrent_ that takes as arguments the incoming packet, the sender IP and Port. This function will be used as a callback and will be triggered every time a specific URI path is provided in the incoming request.
142+
143+
This URL is defined upon registering the callback to the CoAP instance by calling _addIncomingRequestCallback_ function. After this call, if a CoAP GET/PUT/POST packet is received with URI path: coap://<IP>/current/measure , the callback will be triggered.
144+
145+
By default, the server does not send any response. This is a responsibility of the user to send (if needed) the appropriate response.
146+
147+
In this example, we reply with a response message packet (which has the same message id as the incoming request packet) whose payload is the actual value of the reading that has just been executed (in the example it is a hard-coded value of 222).
148+
149+
```python
150+
timeoutMs = 60000
151+
start_time = time.ticks_ms()
152+
while time.ticks_diff(time.ticks_ms(), start_time) < timeoutMs:
153+
client.poll(60000)
154+
```
155+
156+
Finally, since the functions _loop_ and _poll_ __can handle a since packet per run__, we wrap its call to a while loop and wait for incoming messages.
157+
158+
# Future work
159+
160+
* Since this library is quite fresh, the next period will be full of testing.
161+
* write documentation on GitHub
162+
* write documentation as docstring in the code at the declaration of each function
163+
* create more examples with new scenarios and more platforms (ex. ESP32, ESP8266, etc.)
164+
* enhancments on funtionality as needed
165+
166+
# Issues & contributions
167+
168+
It would be our pleasure to receive comments, bug reports and/or contributions. To do this use the Issues and Pull requests of GitHub.

0 commit comments

Comments
 (0)