Customize limits and capabilities of unicoap. More...

Detailed Description

Customize limits and capabilities of unicoap.

Topics
	CoAP over DTLS Driver
	Use CoAP over DTLS, with optional reliability.

Files
file	config.h
	Compile-time configuration parameters.

Macros
#define	CONFIG_UNICOAP_BLOCK_SIZE (32)
	Block size unicoap will suggest for Block1 and Block2 transfers.

Essentials
#define	CONFIG_UNICOAP_CREATE_THREAD 1
	A configuration option determining whether a dedicated thread is created for `unicoap` on initialization.

#define	CONFIG_UNICOAP_DEBUG_LOGGING 0
	Enables debug logging in all `unicoap` source files, except where locally overwritten.

#define	CONFIG_UNICOAP_ASSIST CONFIG_UNICOAP_DEBUG_LOGGING
	Catches and prints API misuse.

Ports
#define	UNICOAP_DEFAULT_COAP_PORT (5683)
	Default CoAP port.

#define	UNICOAP_DEFAULT_COAPS_PORT (5684)
	Default CoAP secure port.

#define	CONFIG_UNICOAP_SOCK_ZERO_COPY_GUARANTEES IS_USED(MODULE_GNRC_SOCK_UDP)
	If enabled, guarantees sock_udp_recv_buf never returns fragmented data, i.e., the entire datagram is always fully retrieved after the first call to sock_udp_recv_buf.

#define	CONFIG_UNICOAP_GET_LOCAL_ENDPOINTS 1
	Instructs the transport drivers to retrieve the local endpoint a PDU arrives at.

#define	CONFIG_UNICOAP_UDP_PORT UNICOAP_DEFAULT_COAP_PORT
	UDP port.

#define	CONFIG_UNICOAP_DTLS_PORT UNICOAP_DEFAULT_COAPS_PORT
	DTLS port.

Limits
#define	CONFIG_UNICOAP_OPTIONS_MAX (16)
	Maximum number of options that can be present in a request or response.

#define	CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY (32)
	Default buffer capacity unicoap chooses when you invoke UNICOAP_OPTIONS_ALLOC_DEFAULT.

#define	UNICOAP_HEADER_SIZE_MAX (15)
	Size of buffer unicoap allocates for a CoAP message header, including token length.

#define	CONFIG_UNICOAP_EXTERNAL_TOKEN_LENGTH_MAX (8)
	Maximum length of a token received from a client.

#define	CONFIG_UNICOAP_GENERATED_TOKEN_LENGTH (2)
	Length of tokens generated by the unicoap client API.

#define	UNICOAP_ETAG_LENGTH_FIXED_WIDTH 4
	Numbers of bits needed to represent a given ETag's length.

#define	CONFIG_UNICOAP_PDU_SIZE_MAX (128)
	Capacity of internal buffers.

#define	CONFIG_UNICOAP_WELL_KNOWN_CORE_SIZE_MAX (120)
	Maximum size of `/.well-known/core` payload.

Timing
These parameters are defined as being configurable in [RFC 7252, section 4.8.1] (https://tools.ietf.org/html/rfc7252#section-4.8.1).
#define	UNICOAP_NSTART (1)
	`NSTART` constant for multicast delay calculation

#define	UNICOAP_DEFAULT_LEISURE (5)
	`DEFAULT_LEISURE` constant for multicast delay calculation

Resource observation
#define	CONFIG_UNICOAP_OBSERVE_VALUE_WIDTH (3)
	Width in bytes of the Observe option value for a notification.

Server
See CONFIG_UNICOAP_OBSERVE_VALUE_WIDTH
#define	CONFIG_UNICOAP_PREVENT_OPTIONAL_RESPONSES 0
	Prevents unicoap from sending a response if optional, as indicated by the `No-Response` option.

#define	CONFIG_UNICOAP_WELL_KNOWN_CORE (1)
	Determines whether `unicoap` registers a default `/.well-known/core` resource.

RFC 7252 messaging
#define	CONFIG_UNICOAP_RANDOM_FACTOR_1000 (1500)
	Used to calculate upper bound for timeout.

#define	UNICOAP_TIMEOUT_ACK_RANGE_UPPER ((uint32_t)CONFIG_UNICOAP_TIMEOUT_ACK_MS * CONFIG_UNICOAP_RANDOM_FACTOR_1000 / 1000)
	Upper bound of range ACK timeouts are selected from.

#define	CONFIG_UNICOAP_TIMEOUT_ACK_MS (2000)
	Initial ACK timeout after which a given message will be retransmitted.

#define	CONFIG_UNICOAP_RETRANSMISSIONS_MAX (4)
	Maximum number of retransmissions of a confirmable message.

#define	CONFIG_UNICOAP_RFC7252_TRANSMISSIONS_MAX 2
	Maximum number of parallel message IDs that are sent and watched for reset and acknowledgment messages.

#define	CONFIG_UNICOAP_CARBON_COPIES_MAX (2)
	Maximum number of internal buffers unicoap reserves.

Stack sizes
#define	UNICOAP_DTLS_EXTRA_STACKSIZE (0)
	Stack size for module thread.

#define	UNICOAP_STACK_SIZE
	Stack memory used by `unicoap` thread.

Macro Definition Documentation

◆ CONFIG_UNICOAP_ASSIST

#define CONFIG_UNICOAP_ASSIST CONFIG_UNICOAP_DEBUG_LOGGING

Catches and prints API misuse.

This is a lighter version of debug logging, where no trace information and artifacts are logged, but only warnings for missing modules, API misuse, and tips for fixing these.

Default: enabled if CONFIG_UNICOAP_DEBUG_LOGGING is enabled.

Warning: unicoap will not honour safety fences, hence you may run into faulty memory behavior if your API usage deviates from the documented one.

Definition at line 69 of file config.h.

◆ CONFIG_UNICOAP_BLOCK_SIZE

#define CONFIG_UNICOAP_BLOCK_SIZE (32)

Block size unicoap will suggest for Block1 and Block2 transfers.

Default: 32 bytes

Definition at line 455 of file config.h.

◆ CONFIG_UNICOAP_CARBON_COPIES_MAX

#define CONFIG_UNICOAP_CARBON_COPIES_MAX (2)

Maximum number of internal buffers unicoap reserves.

Used for retransmitting CON messages, and storing ACK messages when deduplicating. Default: 2

Guidance on common scenarios

Developers of apps that serve responses reliably should consider how many clients will request the same resource at a time. CON responses will need to cached, i.e., a carbon copy will be created. If the client acknowledges the response directly and no retransmission is needed, the copy will be deleted. Otherwise, the copy is kept until an ACK arrives or the retransmission counter exceeds CONFIG_UNICOAP_RFC7252_TRANSMISSIONS_MAX.

Definition at line 372 of file config.h.

◆ CONFIG_UNICOAP_CREATE_THREAD

#define CONFIG_UNICOAP_CREATE_THREAD 1

A configuration option determining whether a dedicated thread is created for unicoap on initialization.

When this option is turned on, unicoap_init will call thread_create. The unicoap thread will execute unicoap_loop_run on initialisation. If you want to run unicoap on another thread (e.g., the main thread), disable this option and call unicoap_loop_run yourself.

Default: enabled

Definition at line 43 of file config.h.

◆ CONFIG_UNICOAP_DEBUG_LOGGING

#define CONFIG_UNICOAP_DEBUG_LOGGING 0

Enables debug logging in all unicoap source files, except where locally overwritten.

Default: disabled

Debug logging includes assistance diagnostics, such as for API misuse.

Definition at line 54 of file config.h.

◆ CONFIG_UNICOAP_DTLS_PORT

#define CONFIG_UNICOAP_DTLS_PORT UNICOAP_DEFAULT_COAPS_PORT

DTLS port.

Definition at line 105 of file config.h.

◆ CONFIG_UNICOAP_EXTERNAL_TOKEN_LENGTH_MAX

#define CONFIG_UNICOAP_EXTERNAL_TOKEN_LENGTH_MAX (8)

Maximum length of a token received from a client.

Default: 8 bytes

Definition at line 169 of file config.h.

◆ CONFIG_UNICOAP_GENERATED_TOKEN_LENGTH

#define CONFIG_UNICOAP_GENERATED_TOKEN_LENGTH (2)

Length of tokens generated by the unicoap client API.

Default: 2 bytes

Definition at line 181 of file config.h.

◆ CONFIG_UNICOAP_GET_LOCAL_ENDPOINTS

#define CONFIG_UNICOAP_GET_LOCAL_ENDPOINTS 1

Instructs the transport drivers to retrieve the local endpoint a PDU arrives at.

Default: Enabled

Definition at line 124 of file config.h.

◆ CONFIG_UNICOAP_OBSERVE_VALUE_WIDTH

#define CONFIG_UNICOAP_OBSERVE_VALUE_WIDTH (3)

Width in bytes of the Observe option value for a notification.

Maximum allowed value: 3 bytes

Definition at line 248 of file config.h.

◆ CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY

#define CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY (32)

Default buffer capacity unicoap chooses when you invoke UNICOAP_OPTIONS_ALLOC_DEFAULT.

Options are stored in a contiguous memory region according to the format specified in RFC 7252, Section 3.1. This parameter does not affect UNICOAP_OPTIONS_ALLOC.

Default: 32 bytes

Definition at line 152 of file config.h.

◆ CONFIG_UNICOAP_OPTIONS_MAX

#define CONFIG_UNICOAP_OPTIONS_MAX (16)

Maximum number of options that can be present in a request or response.

Default: 16 options

Definition at line 139 of file config.h.

◆ CONFIG_UNICOAP_PDU_SIZE_MAX

#define CONFIG_UNICOAP_PDU_SIZE_MAX (128)

Capacity of internal buffers.

Set to maximum PDU size.

Default: 128

Note: In certain situations, such as when sending a request unreliably, this limit has no effect. Internally, it is used for, but is, in the future, not limited to, retransmission copies.

Definition at line 202 of file config.h.

◆ CONFIG_UNICOAP_PREVENT_OPTIONAL_RESPONSES

#define CONFIG_UNICOAP_PREVENT_OPTIONAL_RESPONSES 0

Prevents unicoap from sending a response if optional, as indicated by the No-Response option.

If enabled, responses prepared by the application will be disregarded and not sent.

Default: off

Definition at line 279 of file config.h.

◆ CONFIG_UNICOAP_RANDOM_FACTOR_1000

#define CONFIG_UNICOAP_RANDOM_FACTOR_1000 (1500)

Used to calculate upper bound for timeout.

Default: 1500

This represents the ACK_RANDOM_FACTOR (RFC 7252, section 4.2) multiplied by 1000, to avoid floating point arithmetic.

See also: CONFIG_UNICOAP_TIMEOUT_ACK_MS

Definition at line 310 of file config.h.

◆ CONFIG_UNICOAP_RETRANSMISSIONS_MAX

#define CONFIG_UNICOAP_RETRANSMISSIONS_MAX (4)

Maximum number of retransmissions of a confirmable message.

Default: 4

Definition at line 339 of file config.h.

◆ CONFIG_UNICOAP_RFC7252_TRANSMISSIONS_MAX

#define CONFIG_UNICOAP_RFC7252_TRANSMISSIONS_MAX 2

Maximum number of parallel message IDs that are sent and watched for reset and acknowledgment messages.

Default: 2 transmissions

Definition at line 352 of file config.h.

◆ CONFIG_UNICOAP_SOCK_ZERO_COPY_GUARANTEES

#define CONFIG_UNICOAP_SOCK_ZERO_COPY_GUARANTEES IS_USED(MODULE_GNRC_SOCK_UDP)

If enabled, guarantees sock_udp_recv_buf never returns fragmented data, i.e., the entire datagram is always fully retrieved after the first call to sock_udp_recv_buf.

Default: Set if gnrc_sock_udp module is used (automatically used when UDP driver imported)

Definition at line 115 of file config.h.

◆ CONFIG_UNICOAP_TIMEOUT_ACK_MS

#define CONFIG_UNICOAP_TIMEOUT_ACK_MS (2000)

Initial ACK timeout after which a given message will be retransmitted.

Unit: milliseconds Default: 2000

Note: The timeout doubles for subsequent retries. To avoid synchronization of retransmissions across hosts, the actual timeout is chosen randomly between the ACK timeout and (ACK timeout * random factor / 1000).

Definition at line 330 of file config.h.

◆ CONFIG_UNICOAP_UDP_PORT

#define CONFIG_UNICOAP_UDP_PORT UNICOAP_DEFAULT_COAP_PORT

UDP port.

Definition at line 97 of file config.h.

◆ CONFIG_UNICOAP_WELL_KNOWN_CORE

#define CONFIG_UNICOAP_WELL_KNOWN_CORE (1)

Determines whether unicoap registers a default /.well-known/core resource.

See also: CoAP Server

Default: enabled (1)

Definition at line 288 of file config.h.

◆ CONFIG_UNICOAP_WELL_KNOWN_CORE_SIZE_MAX

#define CONFIG_UNICOAP_WELL_KNOWN_CORE_SIZE_MAX (120)

Maximum size of /.well-known/core payload.

Default: 120 bytes

Allowed to exceed the maximum PDU size

Definition at line 213 of file config.h.

◆ UNICOAP_DEFAULT_COAP_PORT

#define UNICOAP_DEFAULT_COAP_PORT (5683)

Default CoAP port.

Definition at line 85 of file config.h.

◆ UNICOAP_DEFAULT_COAPS_PORT

#define UNICOAP_DEFAULT_COAPS_PORT (5684)

Default CoAP secure port.

Definition at line 90 of file config.h.

◆ UNICOAP_DEFAULT_LEISURE

#define UNICOAP_DEFAULT_LEISURE (5)

DEFAULT_LEISURE constant for multicast delay calculation

Definition at line 234 of file config.h.

◆ UNICOAP_DTLS_EXTRA_STACKSIZE

#define UNICOAP_DTLS_EXTRA_STACKSIZE (0)

Stack size for module thread.

Extra stack memory to be used when CoAP over DTLS driver is used

Definition at line 434 of file config.h.

◆ UNICOAP_ETAG_LENGTH_FIXED_WIDTH

#define UNICOAP_ETAG_LENGTH_FIXED_WIDTH 4

Numbers of bits needed to represent a given ETag's length.

Definition at line 190 of file config.h.

◆ UNICOAP_HEADER_SIZE_MAX

#define UNICOAP_HEADER_SIZE_MAX (15)

Size of buffer unicoap allocates for a CoAP message header, including token length.

Definition at line 159 of file config.h.

◆ UNICOAP_NSTART

#define UNICOAP_NSTART (1)

NSTART constant for multicast delay calculation

Definition at line 229 of file config.h.

◆ UNICOAP_STACK_SIZE

#define UNICOAP_STACK_SIZE

Value:

(THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE + \

CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY + UNICOAP_DTLS_EXTRA_STACKSIZE)

DEBUG_EXTRA_STACKSIZE

#define DEBUG_EXTRA_STACKSIZE

Extra stacksize needed when ENABLE_DEBUG==1.

Definition debug.h:138

CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY

#define CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY

Default buffer capacity unicoap chooses when you invoke UNICOAP_OPTIONS_ALLOC_DEFAULT.

Definition config.h:152

UNICOAP_DTLS_EXTRA_STACKSIZE

#define UNICOAP_DTLS_EXTRA_STACKSIZE

Stack size for module thread.

Definition config.h:434

THREAD_STACKSIZE_DEFAULT

#define THREAD_STACKSIZE_DEFAULT

A reasonable default stack size that will suffice most smaller tasks.

Definition thread_config.h:39

Stack memory used by unicoap thread.

This parameter is relevant if you disable CONFIG_UNICOAP_CREATE_THREAD

Definition at line 442 of file config.h.

◆ UNICOAP_TIMEOUT_ACK_RANGE_UPPER

#define UNICOAP_TIMEOUT_ACK_RANGE_UPPER ((uint32_t)CONFIG_UNICOAP_TIMEOUT_ACK_MS * CONFIG_UNICOAP_RANDOM_FACTOR_1000 / 1000)

Upper bound of range ACK timeouts are selected from.

Definition at line 314 of file config.h.