aiocoap.config module

Configurable behavior of aiocoap.

Classes of this module can be used to customize aspects of aiocoap operation that are generally not part of a written application, such as which addresses to bind to or which CoAP transports to make available.

The two main places to enter them are:

There are two main ways to create them:

  • Programmatically by constructing the classes.

    All these classes are standard Python dataclasses, and can be populated in a constructor or be built up after constructing them with default values.

    This is practical when the application has its own configuration format that is exposed to the user, or when in ad-hoc scripts where the configuration is hard-coded.

  • Loading from JSON, TOML, or (provided dependencies are present) YAML, CBOR or CBOR Diagnostic Notation (EDN) files.

    All types in here are instances of LoadStoreClass, and thus have a .load_from_file() method by which they can be loaded.

    For most data types, the common information model has a trivial representation – for example, a full config that contains a transport details for UDP can be:

    [transport.udp6]
bind = ["[::]:5683", "[::]:61616"]

    Some types in the items receive special handling to make them easier to use: For example, any Path items are, when relative, resolved based on the loaded file’s location.

  • There exists the hybrid option of creating the deserialized version of such a configuration file in Python, and passing it to .load():

    >>> config = Config.load({"transport": {"udp6": {"bind": ["[::]:5683", "[::]:61616"]}}})
>>> config.transport.udp6
Udp6Parameters(bind=['[::]:5683', '[::]:61616'], ...)

Stability

This module is regarded as stable; breaking changes will be pointed out through semver releases.

Main classes

class aiocoap.config.Config(transport: TransportParameters = <factory>)

Configuration for aiocoap

An instance of this type covers aspects of aiocoap’s behavior that are orthogonal to typical CoAP server or client applications, or for which an application would typically only forward configuration settings to.

transport: TransportParameters

Configuration for which transport protocols of CoAP are to be enabled, and how they are to be set up.

class aiocoap.config.TransportParameters(is_server: bool | None = None, default_transports: bool = False, udp6: Udp6Parameters | None = None, simple6: Simple6Parameters | None = None, simplesocketserver: SimpleSocketServerParameters | None = None, tinydtls: TinyDTLSParameters | None = None, tinydtls_server: TinyDTLSServerParameters | None = None, tcpclient: TcpClientParameters | None = None, tcpserver: TcpServerParameters | None = None, tlsclient: TlsClientParameters | None = None, tlsserver: TlsServerParameters | None = None, ws: WsParameters | None = None, oscore: OscoreParameters | None = None, slipmux: SlipmuxParameters | None = None)

Parameters that guide which transports are selected and how they are configured.

is_server: bool | None = None

If True, in any place it applies, parameters for server operation are set. (For example, the UDP and TCP ports bind to the default port rather than an ephemeral port, and the default transports selection may be different).

Leaving this unset allows the parameters to be set when creating the context.

default_transports: bool = False

If True, all transports that are on by default (or selected by the environment) are enabled.

Note that this is False by default: If TransportParameters are given explicitly (by construction or by loading from JSON/CBOR/TOML style files), all transports are opt-in, and only when not specifying anything (or a legacy format) to the Context constructor, this gets set.

Transport specifics

class aiocoap.config.Udp6Parameters(bind: list[str] | None = None, reuse_port: bool | None = None)

Bases: LoadStoreClass

Parameters for setting up a udp6 transport.

bind: list[str] | None = None

Address and port to bind to.

Addresses without a port are bound to the default port (5683). Binding to an address at the unspecified port is possible by explicitly giving the port as :0; the choice of a port of an ephemeral port will be left to the operating system.

The default value when nothing is given explicitly depends on whether a server is run (then it’s ["[::]"] implying port 5683) or not (then it’s effectively ["[::]:0"], although the bind syscall may be elided in that case). The default is altered when the to-be-deprecated bind argument is passed at server creation.

Multiple explicit ports can be bound to, both by listing them explicitly, and by giving names that are resolved (at startup) to multiple addresses.

Currently, only the first address (first resolved value of the first address) is used for outgoing requests (more precisley, for outgoing requests with an UnspecifiedRemote remote; outgoing requests from role reversal always stick with their addresses). That means that unless the first item is a [::] unspecified address, only that addresse’s IP version will work for outgoing requests. A convenient workaround is to bind to [::]:0 first, which sends all such outgoing requests through a random port chosen by the OS at startup, and then list the concrete addresses to bind to.

reuse_port: bool | None = None

Use the SO_REUSEPORT option.

It has the effect that multiple Python processes can be bound to the same port to get some implicit load balancing.

The default is currently True if available on the platform, and also influenced by the (hereby deprecated) AIOCOAP_REUSE_PORT environment variable.

class aiocoap.config.Simple6Parameters

Bases: LoadStoreClass

Parameters for setting up a simple6 transport.

class aiocoap.config.SimpleSocketServerParameters

Bases: LoadStoreClass

Parameters for setting up a simplesocketserver transport.

class aiocoap.config.TinyDTLSParameters

Bases: LoadStoreClass

Parameters for setting up a tinydtls transport.

class aiocoap.config.TinyDTLSServerParameters

Bases: LoadStoreClass

Parameters for setting up a tinydtls_server transport.

class aiocoap.config.TcpClientParameters

Bases: LoadStoreClass

Parameters for setting up a tcpclient transport.

class aiocoap.config.TcpServerParameters

Bases: LoadStoreClass

Parameters for setting up a tcpserver transport.

class aiocoap.config.TlsClientParameters

Bases: LoadStoreClass

Parameters for setting up a tlsclient transport.

class aiocoap.config.TlsServerParameters

Bases: LoadStoreClass

Parameters for setting up a tlsserver transport.

class aiocoap.config.WsParameters

Bases: LoadStoreClass

Parameters for setting up a ws transport.

class aiocoap.config.OscoreParameters

Bases: LoadStoreClass

Parameters for setting up an oscore transport.

class aiocoap.config.SlipmuxDevice(device: Path | None = None, unix_connect: Path | None = None, unix_listen: Path | None = None)

Bases: LoadStoreClass

Parameters for a single slipmux device.

By default, establishes a connection by looking up the name case-insensitively in /dev/ (which works for UNIXes), falling back to opening the device by its name (which probably works on Windows)

device: Path | None = None

Overrides the path at which the device file is expected.

This can be useful when catering for device path renames, or when devices contain characters that are not trivially encoded in the Hostname component of a URI.

unix_connect: Path | None = None

If set, connection is not made through a serial port but rather by connecting to a UNIX socket at that file name.

unix_listen: Path | None = None

If set, connection is not made through a serial port but rather by creating and listening at a UNIX socket at that file name.

class aiocoap.config.SlipmuxParameters(devices: dict[str, ~aiocoap.config.SlipmuxDevice]=<factory>)

Bases: LoadStoreClass

Parameters for setting up a slipmux transport.

devices: dict[str, SlipmuxDevice]

Details of known slipmux devices.

The keys are the “devname” part of the coap://devname.dev.alt origins used with slimux.

Setting an item is done for two practical effects:

  • It allows overriding properties (see SlipmuxParameters).

  • When configured as a server, these are the ports that get connected at startup.