Skip to content

Home

Jump to bottom
Nikolaos Ftylitakis edited this page Jan 2, 2020 · 5 revisions

Welcome to the microCoAPy wiki!

Follows a more detailed documentation of the library's API.

MicroCoAPy

CoapPacket

CoapPacket class contains all the data needed for a CoAP request or a response. Contents:

  • type: message type (CON, NONCON, ACK, RESET) . [CoAP message types]
  • code: method code (GET, POST, PUT, DELETE) [RFC7252 Section 5.8]
  • token: random number used to match request/response pairs [RFC7252 Section 5.3.1]
  • payload: The actual payload that will be transmitted. Its format depends on the content_format.
  • messageid: Used to detect message duplication and to match messages of type Acknowledgement/Reset to messages of type Confirmable/Non-confirmable [RFC7252 Section 3]
  • content_format: indicates the representation format of the message payload [RFC7252 Section 5.10.3]
  • query: URI query for extra parameter passing [RFC7252 Section 5.10.1]
  • options: internal structure used for CoAP message formatting. [RFC7252 Section 5.4]

Coap

start(port)

Initialize a UDP socket at the given port. Used for both client and server.

  • [arguments]
    • (optional) port: the port of the UDP socket. default value: 5683

stop

Stop the initialized UDP socket. Used only when start has been previously called.

resposeCallback(packet, remoteAddress) instance member

When running as a client, it will be called upon receiving a response to an already sent response.

  • [arguments]
    • packet: the instance of the received CoapPacket.
    • remoteAddress: the address of the remote end that responded with the packet
  • [example]
def receivedMessageCallback(packet, sender):
     print('Message received:', packet, ', from: ', sender)

client = microcoapy.Coap()
client.resposeCallback = receivedMessageCallback

setCustomSocket(custom_socket)

Set a custom instance of a UDP socket Is used instead of calling start/stop functions. This overrides the automatic socket that has been created by the 'start' function.

  • [arguments]
    • custom_socket: the custom socket instance

The custom socket MUST support functions:

  • socket.sendto(bytes, address)
  • socket.recvfrom(bufsize)
  • socket.setblocking(flag)

addIncomingRequestCallback(requestUrl, callback)

When running as server, add callbacks for specific URLs. For a specific URL, only the last declared callback will be used. To deactivate call the function with an undefiend callback.

  • [arguments]
    • requestUrl: the URL that will be handled
    • callback: the callback that will be called if the requestUrl is requested.

send(self, ip, port, url, type, method, token, payload, content_format, queryOption)

the generic function that creates and send a CoAP packet. It can be used directly, or it can be used indirectly through helper functions get, put, post.

  • [arguments]
    • ip: The IP of the packet receiver
    • port: The IP of the port receiver
    • url: The request URL (ex. "led/turnOn")
    • type: The message type. Helper macro: coap_macros.COAP_TYPE. Refer to CoapPacket definition.
    • method: The method code. Helper macro: coap_macros.COAP_METHOD. Refer to CoapPacket definition.
    • token: (optional) token code that will be used for response/request matching. 0-8 bytes.
    • payload: The payload of the request. In case of a GET request, the payload is empty.
    • content_format: The format of the message payload. Refer to CoapPacket definition.
    • queryOption: URI query for extra parameter passing. Refer to CoapPacket definition.
  • [returns]
    • message id (int): If the message is sent successfully the function returns the messageid. If it fails, it returns 0.

sendResponse(ip, port, messageid, payload, code, content_format, token)

When running as server, after receiving a packet through a registered callback (addIncomingRequestCallback), use this function to respond back.

Important: the token MUST match in both request and response.

  • [arguments]
    • ip: The IP of the packet receiver
    • port: The IP of the port receiver
    • messageid: The message ID used for dublicate detection.
    • payload: The payload of the request. In case of a GET request, the payload is empty.
    • code: method code (GET, POST, PUT, DELETE)
    • content_format: The format of the message payload. Refer to CoapPacket definition.
    • token: (optional) token code that will be used for response/request matching. 0-8 bytes.
  • [returns]
    • message id (int): If the message is sent successfully the function returns the messageid. If it fails, it returns 0.

get(ip, port, url, token)

Wrapper of send for sending a GET request.

  • [arguments]
    • ip: The IP of the packet receiver
    • port: The IP of the port receiver
    • url: The request URL (ex. "led/turnOn")
    • token: (bytearray) The requestID byte array. The array length >= 0 and <=8. Default value: empty bytearray.
  • [returns]
    • message id (int): If the message is sent successfully the function returns the messageid. If it fails, it returns 0.

put(ip, port, url, payloa, queryOption, content_format, token)

Wrapper of send for sending a PUT request.

  • [arguments]
    • ip: The IP of the packet receiver
    • port: The IP of the port receiver
    • url: The request URL (ex. "led/turnOn")
    • payload: The payload of the request. In case of a GET request, the payload is empty. Default: empty array.
    • queryOption: URI query for extra parameter passing. Refer to CoapPacket definition. Default: None.
    • content_format: The format of the message payload. Refer to CoapPacket definition. Default: COAP_CONTENT_FORMAT.COAP_NONE
    • token: (bytearray) The requestID byte array. The array length >= 0 and <=8. Default value: empty bytearray.
  • [returns]
    • message id (int): If the message is sent successfully the function returns the messageid. If it fails, it returns 0.

post(ip, port, url, payload, queryOption, content_format, token)

Wrapper of send for sending a POST request.

  • [arguments]
    • ip: The IP of the packet receiver
    • port: The IP of the port receiver
    • url: The request URL (ex. "led/turnOn")
    • payload: The payload of the request. In case of a GET request, the payload is empty. Default: empty array.
    • queryOption: URI query for extra parameter passing. Refer to CoapPacket definition. Default: None.
    • content_format: The format of the message payload. Refer to CoapPacket definition. Default: COAP_CONTENT_FORMAT.COAP_NONE
    • token: (bytearray) The requestID byte array. The array length >= 0 and <=8. Default value: empty bytearray.
  • [returns]
    • message id (int): If the message is sent successfully the function returns the messageid. If it fails, it returns 0.

loop(blocking)

Check once for incoming messages. If set blocking == true, it will block till a message arrives. If blocking is set to false, if no messages is in the queue it will return immediatelly.

  • [arguments]
    • blocking: Enable/disable the blocking behaviour when checking for new incoming messages. Default: true.
  • [returns]
    • status (boolean): Boolean status whether a message has been received or not.

poll(timeoutMs, pollPeriodMs)

Check for incoming message for timeoutMs duration with period pollPeriodMs. If no message arrives after the timeout period the function returns. If timeoutMs is set to -1, this function will run infinently till a message arrives.

  • [arguments]
    • timeoutMs: The IP of the packet receiver. Default: -1
    • pollPeriodMs: The IP of the port receiver. Default: 500ms
  • [returns]
    • status (boolean): Boolean status whether a message has been received or not.
Clone this wiki locally