Docs › Connecting devices › Working with Device Management Client › Configuring Device Management Client › Advanced configuration options

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, which describes the application user-facing default behavior and configuration.
Mbed Client library, which is responsible for connectivity to Device Management.

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

These macros are required on all devices:

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 60s.
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 1024B.

Platform-specific macros

Set these macros for the specific platform you are using:

Macro name	Description	Defaults and restrictions
TARGET_LIKE_LINUX	Add this macro for Linux devices.
MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT	Enables Platform Security Architecture (PSA).	Disabled by default. You must enable this macro to work with a secure element.

Secure element macros

Set these macros if your device uses a secure element:

Macro name	Description	Defaults and restrictions
MBED_CONF_MBED_CLOUD_CLIENT_SECURE_ELEMENT_SUPPORT	Enables work with a secure element.	Disabled by default. You must enable this macro and `MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT` to work with a secure element.
MBED_CONF_MBED_CLOUD_CLIENT_NON_PROVISIONED_SECURE_ELEMENT	Defines whether the secure element is pre-provisioned.	Disabled by default. When disabled, the secure element is pre-provisioned. When enabled, the secure element is not pre-provisioned; in this state, you provision secure credentials onto the secure element in the factory.

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)

Set these parameters to configure firmware updates:

Macro name	Description	Defaults and restrictions
MBED_CLOUD_CLIENT_FOTA_ENABLE	Add this macro to enable firmware update functionality.
MBED_CLOUD_CLIENT_FOTA_DOWNLOAD	Define the protocol the device uses to download candidate images.	For Mbed OS targets, the only supported download protocol is CoAP. For Linux targets, the client supports CoAP and HTTP. The default Linux download protocol is HTTP. You can only activate one download protocol at a time.
MBED_CLOUD_CLIENT_FOTA_RESUME_SUPPORT	Enables the device application to resume download of the firmware image in the event of a power failure.	`FOTA_RESUME_SUPPORT_RESUME` - Device Management Client resumes download from the last successfully downloaded fragment. This is the default option. `FOTA_RESUME_SUPPORT_RESTART` - Device Management Client restarts download. This mode can be useful for constrained devices, and can help reduce code size. `FOTA_RESUME_UNSUPPORTED` - Device Management Client does not resume the update at all.
MBED_CLOUD_CLIENT_FOTA_ENCRYPTION_SUPPORT	Enables encryption of candidate image in Cloud and in Client. Encryption in cloud protects the image when Cloud storage is public. Encryption in client protects the image when Client stores the candidate image in external storage, like an SD card on SPIF flash.	Disabled by default. Encryption by cloud is not supported if `MBED_CLOUD_CLIENT_FOTA_CANDIDATE_BLOCK_SIZE` is different from 1024.
MBED_CLOUD_CLIENT_FOTA_KEY_ENCRYPTION	Defines which encryption key to use for image encryption.	`FOTA_USE_ENCRYPTED_ONE_TIME_FW_KEY` - Use one-time key. This is the default option. `FOTA_USE_DEVICE_KEY` - Use the device key. Deprecated from PDMC 4.10 due to security vulnerability.
MBED_CLOUD_CLIENT_FOTA_BLOCK_DEVICE_TYPE	Define the block device type the device application uses for firmware updates.	`FOTA_DEFAULT_MBED_OS_BD` - Uses the default Mbed OS block device for this target. `FOTA_INTERNAL_FLASH_MBED_OS_BD` - Uses the Mbed OS internal flash block device. `FOTA_CUSTOM_MBED_OS_BD` - Uses a custom Mbed OS block device. The application must supply the `mbed::BlockDevice *fota_bd_get_custom_bd()` function. `FOTA_EXTERNAL_BD` - The application needs its own implementation for `fota/fota_block_device.h`.
MBED_CLOUD_CLIENT_FOTA_LINUX_SINGLE_MAIN_FILE	Define to use our single-file Linux update implementation.
MBED_CLOUD_CLIENT_FOTA_LINUX_CANDIDATE_FILENAME	Define the path to the candidate firmware image on Linux systems.	On Linux systems, by default, Device Management Client saves the update candidate in the working directory from which the Device Management Client process is running.
MBED_CLOUD_CLIENT_FOTA_LINUX_HEADER_FILENAME	Define the path to the current firmware metadata file in binary format on Linux systems.	On Linux systems, by default, Device Management Client saves the current firmware metadata file in the working directory from which the Device Management Client process is running.
MBED_CLOUD_CLIENT_FOTA_STORAGE_SIZE	Define the maximum allowed candidate image size in bytes.	If you enable the device application to resume download of the firmware image in the event of a power failure (`MBED_CLOUD_CLIENT_FOTA_RESUME_SUPPORT`), the actual disk size required for update is 2 * `MBED_CLOUD_CLIENT_FOTA_STORAGE_SIZE`.
FOTA_NUM_COMPONENTS	Define the number of components supported by the device.	The default value is `1`, which means that only an update of the main application is supported. Set to a higher number to update additional components.
MBED_CLOUD_CLIENT_FOTA_SUB_COMPONENT_SUPPORT	Enables combined update.	Disabled by default. Supported for Linux targets only.
FOTA_MAX_NUM_OF_SUB_COMPONENTS	Define the maximum number of subcomponents to be updated simultaneously on the device in a combined update.

A multiple number of subcomponents installed simultaneously by FOTA combined update.

Multicast update on a Wi-SUN mesh network

To perform a multicast update on a Wi-SUN mesh network, define these macros:

Macro name	Description	Defaults and restrictions
MBED_CLOUD_CLIENT_SUPPORT_MULTICAST_UPDATE	Enables multicast update.	Disabled by default. You must enable this macro to perform multicast updates.
MBED_CLOUD_CLIENT_MULTICAST_INTERVAL	Defines how often the border router sends multicast messages (firmware fragments) to nodes.	Set to 60s by default.
MBED_CLOUD_CLIENT_FOTA_MULTICAST_SUPPORT	Identifies devices in a mesh network as border routers or nodes.	`FOTA_MULTICAST_BR_MODE` - Border router. `FOTA_MULTICAST_NODE_MODE` - Node.

For more information about multicast updates on a Wi-SUN mesh network, please see Update campaign types.

Secure Device Access (SDA)

Set this macro to enable Secure Device Access:

Macro name	Description	Defaults and restrictions
MBED_CLOUD_CLIENT_ENABLE_SDA	Enables SDA functionality.	Disabled by default.

Device Sentry

Set this macro to enable Device Sentry:

Macro name	Description	Defaults and restrictions
MBED_CONF_MBED_CLOUD_CLIENT_ENABLE_DEVICE_SENTRY	Enables Device Sentry 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.	1024B
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.	540s
MBED_CONF_MBED_CLIENT_DTLS_PEER_MAX_TIMEOUT	Timeout for DTLS negotiation.	80,000ms
MBED_CLIENT_MAX_RECONNECTION_TIMEOUT	Maximum backoff timer for client during reconnection.	14,400s
MBED_CLOUD_CLIENT_CUSTOM_URI_PORT	The server URI port can be set to `443` instead of the default `5684`.	Disabled. `5684` port will be used

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.	10s
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.	40s
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.	512B

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.	60s
SN_COAP_MAX_INCOMING_BLOCK_MESSAGE_SIZE	Maximum size of blockwise message that can be received.	65,535B
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 1024B
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.	65,535B
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.	60s

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.	102,400B 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 Izuma 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.

Documentation