aiocoap.message module

class aiocoap.message.Message(*, mtype=None, mid=None, code=None, payload=b'', token=b'', uri=None, transport_tuning=None, **kwargs)

Bases: object

CoAP Message with some handling metadata

This object’s attributes provide access to the fields in a CoAP message and can be directly manipulated.

  • Some attributes are additional data that do not round-trip through serialization and deserialization. They are marked as “non-roundtrippable”.

  • Some attributes that need to be filled for submission of the message can be left empty by most applications, and will be taken care of by the library. Those are marked as “managed”.

The attributes are:

  • payload: The payload (body) of the message as bytes.

  • mtype: Message type (CON, ACK etc, see numbers.types). Managed unless set by the application.

  • code: The code (either request or response code), see

  • opt: A container for the options, see options.Options.

  • mid: The message ID. Managed by the Context.

  • token: The message’s token as bytes. Managed by the Context.

  • remote: The socket address of the other side, managed by the protocol.Request by resolving the .opt.uri_host or unresolved_remote, or the Responder by echoing the incoming request’s. Follows the interfaces.EndpointAddress interface. Non-roundtrippable.

    While a message has not been transmitted, the property is managed by the Message itself using the set_request_uri() or the constructor uri argument.

  • transport_tuning: Parameters used by one or more transports to guide transmission. These are purely advisory hints; unknown properties of that object are ignored, and transports consider them over built-in constants on a best-effort basis.

    Note that many attributes are mandatory if this is not None; it is recommended that any objects passed in here are based on the aiocoap.numbers.constants.TransportTuning class.

  • request: The request to which an incoming response message belongs; only available at the client. Managed by the interfaces.RequestProvider (typically a Context).

These properties are still available but deprecated:

  • requested_*: Managed by the protocol.Request a response results from, and filled with the request’s URL data. Non-roundtrippable.

  • unresolved_remote: host[:port] (strictly speaking; hostinfo as in a URI) formatted string. If this attribute is set, it overrides .RequestManageropt.uri_host (and -_port) when it comes to filling the remote in an outgoing request.

    Use this when you want to send a request with a host name that would not normally resolve to the destination address. (Typically, this is used for proxying.)

Options can be given as further keyword arguments at message construction time. This feature is experimental, as future message parameters could collide with options.

The four messages involved in an exchange

Requester                                  Responder

+-------------+                          +-------------+
| request msg |  ---- send request --->  | request msg |
+-------------+                          +-------------+
                                          processed into
+-------------+                          +-------------+
| response m. |  <--- send response ---  | response m. |
+-------------+                          +-------------+

The above shows the four message instances involved in communication between an aiocoap client and server process. Boxes represent instances of Message, and the messages on the same line represent a single CoAP as passed around on the network. Still, they differ in some aspects:

  • The requested URI will look different between requester and responder if the requester uses a host name and does not send it in the message.

  • If the request was sent via multicast, the response’s requested URI differs from the request URI because it has the responder’s address filled in. That address is not known at the responder’s side yet, as it is typically filled out by the network stack.

  • It is yet unclear whether the response’s URI should contain an IP literal or a host name in the unicast case if the Uri-Host option was not sent.

  • Properties like Message ID and token will differ if a proxy was involved.

  • Some options or even the payload may differ if a proxy was involved.


Create a copy of the Message. kwargs are treated like the named arguments in the constructor, and update the copy.

classmethod decode(rawdata, remote=None)

Create Message object from binary representation of message.


Create binary representation of message from Message object.


Generate a hashable and comparable object (currently a tuple) from the message’s code and all option values that are part of the cache key and not in the optional list of ignore_options (which is the list of option numbers that are not technically NoCacheKey but handled by the application using this method).

>>> from aiocoap.numbers import GET
>>> m1 = Message(code=GET)
>>> m2 = Message(code=GET)
>>> m1.opt.uri_path = ('s', '1')
>>> m2.opt.uri_path = ('s', '1')
>>> m1.opt.size1 = 10 # the only no-cache-key option in the base spec
>>> m2.opt.size1 = 20
>>> m1.get_cache_key() == m2.get_cache_key()
>>> m2.opt.etag = b'000'
>>> m1.get_cache_key() == m2.get_cache_key()
>>> from aiocoap.numbers.optionnumbers import OptionNumber
>>> ignore = [OptionNumber.ETAG]
>>> m1.get_cache_key(ignore) == m2.get_cache_key(ignore)
get_request_uri(*, local_is_server=False)

The absolute URI this message belongs to.

For requests, this is composed from the options (falling back to the remote). For responses, this is largely taken from the original request message (so far, that could have been trackecd by the requesting application as well), but – in case of a multicast request – with the host replaced by the responder’s endpoint details.

This implements Section 6.5 of RFC7252.

By default, these values are only valid on the client. To determine a message’s request URI on the server, set the local_is_server argument to True. Note that determining the request URI on the server is brittle when behind a reverse proxy, may not be possible on all platforms, and can only be applied to a request message in a renderer (for the response message created by the renderer will only be populated when it gets transmitted; simple manual copying of the request’s remote to the response will not magically make this work, for in the very case where the request and response’s URIs differ, that would not catch the difference and still report the multicast address, while the actual sending address will only be populated by the operating system later).

set_request_uri(uri, *, set_uri_host=True)

Parse a given URI into the uri_* fields of the options.

The remote does not get set automatically; instead, the remote data is stored in the uri_host and uri_port options. That is because name resolution is coupled with network specifics the protocol will know better by the time the message is sent. Whatever sends the message, be it the protocol itself, a proxy wrapper or an alternative transport, will know how to handle the information correctly.

When set_uri_host=False is passed, the host/port is stored in the unresolved_remote message property instead of the uri_host option; as a result, the unresolved host name is not sent on the wire, which breaks virtual hosts but makes message sizes smaller.

This implements Section 6.4 of RFC7252.

property unresolved_remote
property requested_scheme
property requested_proxy_uri
property requested_hostinfo
property requested_path
property requested_query
aiocoap.message.NoResponse = <NoResponse>

Result that can be returned from a render method instead of a Message when due to defaults (eg. multicast link-format queries) or explicit configuration (eg. the No-Response option), no response should be sent at all. Note that per RFC7967 section 2, an ACK is still sent to a CON request.

Depercated; set the no_response option on a regular response instead (see interfaces.Resource.render() for details).