Advanced configuration options
This document describes the macros you can set at compile-time to configure various components of Device Management Client.
Device Management Client is composed of multiple libraries, each of which has its own configuration:
- Device Management Client library, that describes the application user-facing default behavior and configuration.
- Mbed Client library.
Device Management Client
To configure Device Management Client-specific behavior, use the application configuration file, mbed_cloud_client_user_config.h.
Pass parameters to Device Management Client by defining this MACRO:
MBED_CLOUD_CLIENT_USER_CONFIG_FILE="mbed_cloud_client_user_config.h"
Mandatory macros for compiling Device Management Client
Set these macros:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CLOUD_CLIENT_LIFETIME | Expected lifetime of the registration of the LwM2M client. | The minimum registration lifetime period is 60 seconds. |
| MBED_CLOUD_CLIENT_ENDPOINT_TYPE | String-type value for endpoint identification. For mesh network devices, set to borderrouter for border routers and routernode for nodes. |
default is default value. MBED_GW is a reserved value for Edge devices. |
| SN_COAP_MAX_BLOCKWISE_PAYLOAD_SIZE | The maximum size of single CoAP message. | Accepted values: 16, 32, 64, 128, 256, 512, or 1024 bytes. |
Transport modes
Select the transport mode:
| Mode | Configuration |
|---|---|
| MBED_CLOUD_CLIENT_TRANSPORT_MODE_TCP | Default. Device Management Client uses TCP. Typically for Ethernet and Wi-Fi devices. |
| MBED_CLOUD_CLIENT_TRANSPORT_MODE_UDP | Device Management Client uses UDP. Typically for Cellular and Mesh. UDP does not typically work unless your network connectivity stays open from the client to Device Management through all involved network elements. NATs and firewalls close UDP ports aggressively. Use either TCP or UDP_QUEUE. |
| MBED_CLOUD_CLIENT_TRANSPORT_MODE_UDP_QUEUE | Device Management Client uses UDP with queue mode. Use this for sleepy devices. Sleepy devices are not reachable from Device Management immediately. They are reachable when they have reconnected to Device Management. Device Management REST API operations, such as GET, PUT and POST, will be queued in Device Management until the device reconnects and the operations can be forwarded to it. |
Firmware-Over-The-Air (FOTA) feature
Set the update parameters:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CLOUD_CLIENT_SUPPORT_UPDATE | If defined, enables firmware update functionality. | |
| MBED_CLOUD_CLIENT_UPDATE_BUFFER | Total memory allocated for download buffers. | Default 1024 bytes. Must be at least 1024 bytes. |
| MBED_CLOUD_CLIENT_UPDATE_DOWNLOAD_PROTOCOL | The download protocol used for update. | For Mbed OS targets, the default download protocol is CoAP. For Linux targets, the default download protocol is HTTP. For Device Management Client Lite the default and only supported download protocol is CoAP. For Mbed OS to use HTTP download, modify mbed_app.json and add to target_overrides: "mbed-cloud-client.update-download-protocol": "MBED_CLOUD_CLIENT_UPDATE_DOWNLOAD_PROTOCOL_HTTP"For Linux builds to use CoAP download, modify define.txt (or define-rpi3-yocto.txt for Yocto) and add: add_definitions(-DMBED_CONF_MBED_CLOUD_CLIENT_UPDATE_DOWNLOAD_PROTOCOL=MBED_CLOUD_CLIENT_UPDATE_DOWNLOAD_PROTOCOL_COAP) Only one download protocol may be active at a time. |
Multicast update on a Wi-SUN mesh network
To multicast update on a Wi-SUN mesh network, define these macros:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CLOUD_CLIENT_SUPPORT_MULTICAST_UPDATE | Master switch to enable multicast update. | |
| MBED_CLOUD_CLIENT_MULTICAST_BORDER_ROUTER | Identifies the device as a border router. Set on border routers only. | |
| MBED_CLOUD_CLIENT_MULTICAST_INTERVAL | Defines how often the border router sends multicast messages (firmware fragments) to nodes. | Default is 60 seconds. |
For more information about multicast updates on a Wi-SUN mesh network, please see Update campaign types.
Secure Device Access (SDA) feature
Set this macro:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CLOUD_CLIENT_ENABLE_SDA | Enables SDA functionality. | Disabled by default. |
Mbed Client
This component is responsible for connectivity to Device Management.
Mbed Client behavior
Use these macros to control Mbed Client behavior:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CLIENT_MEMORY_OPTIMIZED_API | If enabled, reduces RAM and ROM consumption. Note: This disables usage of some APIs, and changes some API signatures. | Disabled. |
| MBED_CLIENT_EVENT_LOOP_SIZE | The size of memory allocated for event loop in timer and network event handling in Mbed Client. | 1024 bytes |
| MBED_CLIENT_RECONNECTION_COUNT | The number of CoAP packet resending attempts. | 3 |
| MBED_CLIENT_RECONNECTION_INTERVAL | The interval between reconnect attempts. | 5 |
| MBED_CLIENT_TCP_KEEPALIVE_INTERVAL | CoAP ping sending interval in TCP mode. | 540 seconds |
| MBED_CONF_MBED_CLIENT_DTLS_PEER_MAX_TIMEOUT | Timeout for DTLS negotiation. | 80 000ms |
Memory optimization
Use these macros to optimize the memory use:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CLIENT_DISABLE_BOOTSTRAP_FEATURE | Mandatory for Device Management Client; should not be enabled when using Device Management service. | Disabled. |
| MBED_CONF_MBED_CLIENT_COAP_DISABLE_OBS_FEATURE | Mandatory for Device Management Client; should not be enabled when using Device Management service. Disables CoAP obs sending feature as part of registration message. May be needed for some strict LwM2M server implementations. |
Not defined. |
| MBED_CONF_MBED_CLIENT_DISABLE_INTERFACE_DESCRIPTION | If enabled, textual interface information is not published to LwM2M server. This flag is optional and turning it on will save RAM and ROM. | Not defined. |
| MBED_CONF_MBED_CLIENT_DISABLE_RESOURCE_TYPE | If enabled, textual information of LwM2M resource is not published to LwM2M server. This flag is optional and turning it on will save RAM and ROM. | Not defined. |
| MBED_CONF_MBED_CLIENT_DISABLE_DELAYED_RESPONSE | If enabled, delayed response feature of CoAP is not used. This flag is optional and if you turn it on, you cannot handle POST requests asynchronously from an application. |
Not defined. |
| MBED_CONF_MBED_CLIENT_DISABLE_BLOCK_MESSAGE | If enabled, external blockwise feature is disabled. If you turn on this flag, your client cannot handle CoAP block messages from service. | Not defined. CoAP firmware download needs this feature. |
| MBED_CONF_MBED_CLIENT_ENABLE_OBSERVATION_PARAMETERS | Controls the use of LwM2M write attributes for LwM2M resources. Disabling this feature allows you to save RAM used by observation parameters for each resource. |
Enabled by default. |
CoAP configuration
Device Management Client uses CoAP as its download protocol. CoAP has multiple configurations that you can change based on application's requirements.
You can modify three categories of parameters:
- Retransmission.
- Blockwise payload.
- Message duplication.
Retransmission parameters
Use these macros to control retransmission:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| SN_COAP_DISABLE_RESENDINGS | Disables the resending feature. The feature is not necessary when using CoAP with TCP transport, for example. | Not defined |
| SN_COAP_RESENDING_QUEUE_SIZE_MSGS | The number of messages stored in the resending queue. | 5. Increase the number if you manage the application actively. This is the maximum number of messages that can be in transit at any given time, including client-generated internal messages like register update messages. |
| DEFAULT_RESPONSE_TIMEOUT | CoAP resend interval in seconds. | 10 seconds |
| SN_COAP_RESENDING_MAX_COUNT | The number of CoAP packet resending attempts. | 3 |
| SN_COAP_RESENDING_QUEUE_SIZE_BYTES | The size of the resending buffer. Setting this to 0 disables this feature. | Disabled. |
| SN_COAP_MAX_ALLOWED_RESENDING_COUNT | Maximum allowed number of resending attempts you can set at runtime using the sn_coap_protocol_set_retransmission_parameters() API. |
6 |
| SN_COAP_MAX_ALLOWED_RESPONSE_TIMEOUT | Longest allowed resend interval you can set at runtime using the sn_coap_protocol_set_retransmission_parameters() API. |
40 seconds |
| SN_COAP_MAX_ALLOWED_RESENDING_BUFF_SIZE_MSGS | Maximum number of messages that can be stored into resend buffer at runtime using the sn_coap_protocol_set_retransmission_buffer() API. |
6 |
| SN_COAP_MAX_ALLOWED_RESENDING_BUFF_SIZE_BYTES | Maximum size of messages that can be stored into resend buffer at runtime via sn_coap_protocol_set_retransmission_buffer() API. |
512 bytes |
Blockwise parameters
Use these macros to control blockwise parameters:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| SN_COAP_BLOCKWISE_MAX_TIME_DATA_STORED | Maximum time for storing messages and payload for blockwising. Longer times increase memory consumption in lossy networks. | 60 seconds |
| SN_COAP_MAX_INCOMING_BLOCK_MESSAGE_SIZE | Maximum size of blockwise message that can be received. | 65535 bytes |
| SN_COAP_MAX_BLOCKWISE_PAYLOAD_SIZE | Initial value for the maximum payload size to be sent and received in one blockwise message. Setting this value to 0 with SN_COAP_BLOCKWISE_ENABLED disables this feature and reduces ROM memory usage. Note: This define is common for both received and sent blockwise messages. |
Default 0. Accepted values: 0, 16, 32, 64, 128, 256, 512 and 1024 bytes |
| SN_COAP_MAX_INCOMING_MESSAGE_SIZE | The maximum message size to be handled while receiving a large payload in blockwise mode. An application can set this value based on its available storage capability. | 65535 bytes |
| SN_COAP_MAX_NONBLOCKWISE_PAYLOAD_SIZE | The maximum payload size before blockwising the message. You should use this option only when using TCP and TLS as transport with known maximum fragment size. This optimizes the number of messages if it is possible to send larger than 1kB messages without blockwise transfer. If the payload size is larger than SN_COAP_MAX_NONBLOCKWISE_PAYLOAD_SIZE it will be sent using blockwise transfer. |
By default, this feature is disabled. 0 disables the feature; set to positive value larger than SN_COAP_MAX_BLOCKWISE_PAYLOAD_SIZE to enable. The value should be less than transport layer maximum fragment size. Value has no effect if blockwise transfer is disabled. |
| SN_COAP_BLOCKWISE_ENABLED | Enables the blockwise functionality in CoAP library even when blockwise payload size is set to 0 in SN_COAP_MAX_BLOCKWISE_PAYLOAD_SIZE. |
Duplication parameters
Use these macros to control duplication parameters:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| SN_COAP_MAX_ALLOWED_DUPLICATION_MESSAGE_COUNT | The maximum number of saved messages for message duplicate searching that you can set using the sn_coap_protocol_set_duplicate_buffer_size API. |
6 |
| SN_COAP_DUPLICATION_MAX_MSGS_COUNT | The initial value for the maximum number of messages to be stored for duplication detection. Setting this value to 0 disables duplication detection, which reduces ROM usage. | 1 |
| SN_COAP_DUPLICATION_MAX_TIME_MSGS_STORED | The maximum time a message is kept for duplicate detection. | 60 seconds |
Event loop configuration
Device Management Client uses an event scheduler to handle its most critical operations (such as network socket handling). It uses an event loop running on its own thread. Configure the application stack size based on your needs. Normally, the heaviest operation for event loops is the TLS/DTLS handshake, which requires 6KB stack size on Mbed OS. However, if you are running your application on a debug profile, you may encounter stack overflow on the hardware.
You can modify the stack size with the Nanostack hardware abstraction layer (ns-hal-pal) configuration:
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CONF_NS_HAL_PAL_EVENT_LOOP_THREAD_STACK_SIZE | The stack size for an event loop. This is OS-specific and generally should match the normal stack size of the platform. This macro is used only in non-Mbed OS platforms. | 102400 bytes for Linux, otherwise not defined. |
Platform Abstraction Layer
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| PAL_SSL_SESSION_RESUME | Enables the DTLS Connection ID extension in Mbed TLS as specified in IETF. | Enabled by default for Linux and Mbed OS platforms when using UDP/UDP_QUEUE. Disabled otherwise. Set to 1 to enable, 0 to disable. |
| PAL_USE_SECURE_TIME | Enables client-side verification of certificate time expiration. | By default, feature is enabled. Set to 0 to disable. |
| PAL_DEFAULT_RTT_ESTIMATE | Defines the round-trip estimate for message exchange with the Pelion service. Used to configure the reconnection and DTLS timers. | Default 2-10s, depending on platform. Dynamic for Wi-SUN Mesh. |
| PAL_DEFAULT_STAGGER_ESTIMATE | Defines the bootstrap and registration delay times client should wait after starting. This feature is typically only relevant for Mesh networks, in which case the stack returns dynamic estimates based on network parameters. | Default is 0, which either disables the feature or, in the case of Mesh Wi-SUN, performs randomized staggered delays before bootstrap and registration. Defining to any positive value disables dynamic staggering and instead uses the given fixed time as delay. |