pamoja.coap

Idiomatic CoAP facade.

CoAP is the transport for links where MQTT is more than the budget allows: it runs over UDP, its headers are a handful of bytes, and a node can fire a reading and forget it rather than holding a session open. A CoapClient is the node's end, and a CoapServer the gateway it reports to.

 1"""Idiomatic CoAP facade.
 2
 3CoAP is the transport for links where MQTT is more than the budget allows: it
 4runs over UDP, its headers are a handful of bytes, and a node can fire a reading
 5and forget it rather than holding a session open. A ``CoapClient`` is the node's
 6end, and a ``CoapServer`` the gateway it reports to.
 7"""
 8
 9from __future__ import annotations
10
11import enum
12
13from pamoja._native import CoapClient, CoapServer, Message
14
15__all__ = [
16    "CoapClient",
17    "CoapServer",
18    "Message",
19    "Reliability",
20]
21
22
23class Reliability(str, enum.Enum):
24    """Whether a request is acknowledged and retried."""
25
26    #: Fire and forget: the request is sent once and not acknowledged.
27    NON_CONFIRMABLE = "NonConfirmable"
28    #: The request is acknowledged, and retransmitted until an ACK arrives.
29    CONFIRMABLE = "Confirmable"
class CoapClient:

A CoAP endpoint.

def connect(self, /):

Binds the local socket so the endpoint can carry traffic.

def send(self, /, topic, payload):

Sends a payload to a resource path.

def subscribe(self, /, topic):

Observes a resource path, so messages published to it reach recv.

def recv(self, /):

Waits for the next message on an observed path, or None once closed.

def is_connected(self, /):

Whether the local socket is bound.

def disconnect(self, /):

Releases the socket the endpoint holds.

class CoapServer:

A CoAP server: the end that nodes send their readings to and observe their commands on.

A PUT or POST to a path matching one of its subscribe filters is answered 2.04 Changed and delivered to recv, and one to any other path 4.04 Not Found. send sets a resource's state, which a GET reads and every observer is notified of. send does not wait for a recv that is waiting, so a gateway sends commands while it listens for readings.

def connect(self, /):

Binds the socket and starts answering requests.

def subscribe(self, /, filter):

Takes the readings sent to the paths a filter matches, with + for one level and # for the rest.

def send(self, /, path, payload):

Sets a resource's state and notifies every observer of it.

def recv(self, /):

Waits for the next reading sent to a path the server takes.

def observers(self, /, path):

Counts the clients observing a resource.

def disconnect(self, /):

Closes the socket, keeping the resources and filters.

local_port

The port the server listens on, which names the one the system chose for port 0, or None while it is not connected.

is_connected

Whether the server holds a bound socket.

class Message:

A message that arrived on a subscribed topic.

CoAP and the loopback broker both hand back a topic and a payload, so one class serves them rather than a near-identical type per transport.

text

The payload as text: words, or a number written out.

Raises ValueError if the payload is not UTF-8 text.

topic

The topic it was published to.

payload

The raw payload bytes.

number

The payload as a number written out as text, such as 21.5.

Raises ValueError if the payload is not text or the text is not a number.

class Reliability(builtins.str, enum.Enum): 
24class Reliability(str, enum.Enum):
25    """Whether a request is acknowledged and retried."""
26
27    #: Fire and forget: the request is sent once and not acknowledged.
28    NON_CONFIRMABLE = "NonConfirmable"
29    #: The request is acknowledged, and retransmitted until an ACK arrives.
30    CONFIRMABLE = "Confirmable"

Whether a request is acknowledged and retried.

NON_CONFIRMABLE = <Reliability.NON_CONFIRMABLE: 'NonConfirmable'>
CONFIRMABLE = <Reliability.CONFIRMABLE: 'Confirmable'>