aiocoap – The Python CoAP library¶
The aiocoap package is an implementation of CoAP, the Constrained Application Protocol.
It is written in Python 3 using its native asyncio methods to facilitate concurrent operations while maintaining an easy to use interface.
aiocoap is originally based on txThings. If you want to use CoAP in your existing Twisted application, or can not migrate to Python 3 yet, that is probably more useful to you than aiocoap.
A full reference is available in the API documentation.
All examples can be run directly from a source code copy. If you prefer to install it, the usual Python mechanisms apply (see Installing aiocoap).
Features / Standards¶
This library supports the following standards in full or partially:
- RFC7252 (CoAP): missing are a caching and cross proxy implementation, proper multicast (support is incomplete); DTLS support is client-side only so far, and lacking some security properties.
- RFC7641 (Observe): Reordering, re-registration, and active cancellation are missing.
- RFC7959 (Blockwise): Multicast exceptions missing.
- RFC8323 (TCP): Supports CoAP over TCP and TLS (certificate only, no preshared or raw public keys) but not CoAP over WebSockets.
- RFC7967 (No-Response): Supported.
- RFC8132 (PATCH/FETCH): Types and codes known, FETCH observation supported
- draft-ietf-core-resource-directory: A standalone resource directory server is provided along with a library function to register at one. They lack support for groups and security considerations, and are generally rather simplistic.
- RFC8613 (OSCORE): Full support client-side; protected servers can be implemented based on it but are not automatic yet.
If something described by one of the standards but not implemented, it is considered a bug; please file at the github issue tracker. (If it’s not on the list or in the excluded items, file a wishlist item at the same location).
Basic aiocoap works out of the box on Python 3.5.2 or newer (also works on PyPy3). For full support (DTLS, OSCORE and link-format handling) follow the Installing aiocoap instructions as these require additional libraries.
aiocoap provides different network backends for different platforms. The udp6 module is most full-featured, but ties into the default asyncio loop and requires full POSIX network interfaces only available on Linux and possibly some BSDs. On Windows and macOS, more constrained server and client transports with some caveats of their own are used; for more details, see the currently open platform issues. Alternative main loops like uvloop or gbulb can be used without restriction.
If your library depends on aiocoap, it should pick the required extras (as per
Installing aiocoap) and declare a dependency like
aiocoap[linkheader,oscore] >= 0.4b2.
aiocoap tries to stay close to PEP8 recommendations and general best practice, and should thus be easy to contribute to.
Bugs (ranging from “design goal” and “wishlist” to typos) are currently tracked in the github issue tracker. Pull requests are welcome there; if you start working on larger changes, please coordinate on the issue tracker.
Documentation is built using sphinx with
./setup.py build_sphinx; hacks
used there are described in
Unit tests are implemented in the
./tests/ directory and easiest run using
tox (though still available through
./setup.py test for the time being);
complete test coverage is aimed for, but not yet complete (and might never be,
as the error handling for pathological network partners is hard to trigger with
a library designed not to misbehave). The tests are regularly run at the CI
suite at gitlab, from where coverage reports are available.
This is where the latest source code can be found, and bugs can be reported. Generally, this serves as the project web site.
Online documentation built from the sources.
Further general information on CoAP, the standard documents involved, and other implementations and tools available.
aiocoap is published under the MIT License, see LICENSE for details.
When using aiocoap for a publication, please cite it according to the output of
./setup.py cite [--bibtex].