Installing aiocoap

Note

The commands here will install aiocoap in your current environment. By default, that is your platform’s user install directory.

To keep that clean, or to use different sets or versions of libraries for different purposes, you may want to look into the venv documentation, which explains both the concept of virtual environments and how they are used on different platforms.

In most situations, it is recommended to install the latest released version of aiocoap. This is done using a simple:

$ pip3 install --upgrade "aiocoap[all]"

(In some cases, the program is called pip only).

Development version

If you want to play with aiocoap’s internals or consider contributing to the project, the suggested way of operation is getting a Git checkout of the project:

$ git clone https://github.com/chrysn/aiocoap
$ cd aiocoap

You can then use the project from that location, or install it with

$ pip3 install --upgrade ".[all,docs]"

If you need to install the latest development version of aiocoap but do not plan on editing (eg. because you were asked in the course of a bug report to test something against the latest aiocoap version), you can install it directly from the web:

$ pip3 install --upgrade "git+https://github.com/chrysn/aiocoap#egg=aiocoap[all]"

With the -e option, that is also a viable option if you want to modify aiocoap and pip’s choice of checkout directories is suitable for you.

Common errors

When upstream libraries change, or when dependencies of used libraries are not there (eg. no C compiler, C libraries missing), the installation process can fail.

On Debian based systems, it helps to install the packages python3-dev, build-essential, autoconf and automake; generally, the error output will contain some hints as to what is missing.

As a workaround, it can be helpful to not install with all extras, but replace the all with the extras you actually want from the list below. For example, if you see errors from DTLSSocket, rather than installing with [all,docs], you can leave out the tinydtls extra and install with [oscore,prettyprint,docs].

Slimmer installations

As aiocoap does not strictly depend on many of the libraries that are installed when following the above recommendations, a setup can be stripped down by entering any combination of the below “extras” in the place of the all in the above lines, or leaving out the [all] expression for a minimal installation.

The extras currently supported are:

  • oscore: Required for the aiocoap.transports.oscore transport, as well as for using EDHOC.

  • tinydtls: Required for using CoAP over DTLS.

  • ws: Required for using CoAP over WebSockets.

  • prettyprint: Allows using the --color and --pretty-print options of aiocoap-client or fancy HTML output.

  • docs: Installs tools needed to build the documentation (not part of all).

  • linkheader: Originally needed for generating and parsing files in RFC6690 link format, eg. .well-known/core files. This extra does not contain any external dependencies, but was left in place for compatibility.

Which libraries and versions are pulled in by this exactly is documented in the pyproject.toml file.

On pyodide

aiocoap can be run in a Python interpreter that is running in the browser called pyodide.

When using pyodide (either directly or through a Jupyter notebook), pip is unavailable, but there is micropip to replace it. Installation is then done directly in the Python environment using:

>>> import micropip
>>> await micropip.install("aiocoap[all]")

See the pyodide and Jupyter section of the documentation on how aiocoap can be used there.

Using unreleased versions on pyodide

The latest main version is made available through aiocoap’s CI runs, and can be used like this:

>>> import micropip
>>> await micropip.install(
...     "aiocoap[all]",
...     index_urls=["https://coap.amsuess.com", "PYPI"]
... )

That index not only contains the latest aiocoap versions, but also a suitable version of the lakers-python dependency. (Generally, that is package is regularly updated in pyodide, but the notebook may not be using the latest pyodide yet).

To test a local build with pyodide, get a Git checkout as described for development above, and run:

python3 -m build

Then, copy the newly created file dist/aiocoap-${VERSION}-py3-none-any.whl to a file server on the public web. Do not rename the file, as it is parsed by micropip. Note that the server may need some CORS setup to allow loading of the file from foreign web sites. For that reason, running the http.server module as a web server on localhost creates an insufficient server (unless pyodide is also served from the same host).