Device Management Client advanced configuration
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: Describes the application user-facing default behavior and configuration.
- Mbed Client library.
Device Management Client specific configuration is done through an application configuration file, such as mbed_cloud_client_user_config.h.
Pass parameters to Device Management Client by defining MACRO:
MBED_CLOUD_CLIENT_USER_CONFIG_FILE="mbed_cloud_client_user_config.h"
You must always define these mandatory macros when compiling Device Management Client.
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CLOUD_CLIENT_LIFETIME | Expected lifetime of the registration of the LwM2M client in seconds. | Minimum registration lifetime period is 60 seconds. |
| MBED_CLOUD_CLIENT_ENDPOINT_TYPE | String-type value which can be provided for endpoint identification. | default is default value. MBED_GW is a reserved value for Edge devices. |
| SN_COAP_MAX_BLOCKWISE_PAYLOAD_SIZE | Maximum size of single CoAP message in bytes. | Accepted values: 16, 32, 64, 128, 256, 512, or 1024. |
Choose one of the following transport modes:
| Mode | Configuration |
|---|---|
| MBED_CLOUD_CLIENT_TRANSPORT_MODE_TCP | Default. Device Management Client is configured to use TCP. Typically for Ethernet and Wi-Fi devices. |
| MBED_CLOUD_CLIENT_TRANSPORT_MODE_UDP | Device Management Client is configured to use 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 is configured to use 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/POST, will be queued in Device Management, until the device reconnects and the operations can be forwarded to it. |
To enable the Firmware-Over-The-Air (FOTA) feature, see the following configuration flags:
| 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 in bytes. | Default 1024 bytes. Must be at least 1024 bytes. |
| MBED_CLOUD_CLIENT_UPDATE_DOWNLOAD_PROTOCOL | Defines 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. |
Mbed Client configuration
This component is responsible for connectivity to Device Management.
Here is the list of all available configuration parameters 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 | Defines the size of memory allocated for event loop (in bytes) for timer and network event handling of Mbed Client. | 1024 bytes |
| MBED_CONF_NS_HAL_PAL_EVENT_LOOP_THREAD_STACK_SIZE | ||
| MBED_CLIENT_RECONNECTION_COUNT | Defines how many times the client tries to re-send the CoAP packet. | 3 |
| MBED_CLIENT_RECONNECTION_INTERVAL | Defines what is the interval between retrials. | 5 |
| MBED_CLIENT_TCP_KEEPALIVE_INTERVAL | Interval in seconds how often CoAP ping is sent in TCP mode. | 90 seconds |
| MBED_CONF_MBED_CLIENT_DTLS_PEER_MAX_TIMEOUT | Timeout in milliseconds for DTLS negotiation. | 80 000 ms |
For memory optimization purposes:
| 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, then you cannot handle POST requests asynchronously from 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 | This controls the usage of LwM2M Write attributes for LwM2M resources. Disabling this feature will allow you to save RAM used by observation parameters per 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.
There are three categories of parameters that you can modify:
- Retransmission.
- Blockwise payload.
- Message duplication control.
Macros to control CoAP retransmission parameters
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| SN_COAP_DISABLE_RESENDINGS | Define to disable the resending feature. Resending feature is not necessary when using CoAP with TCP transport, for example. | Not defined. |
| SN_COAP_RESENDING_QUEUE_SIZE_MSGS | Defines the number of messages stored in the resending queue. | 2 |
| DEFAULT_RESPONSE_TIMEOUT | Defines the CoAP resend interval in seconds. | 10 seconds |
| SN_COAP_RESENDING_MAX_COUNT | Defines how many times a CoAP packet is resent. | 3 |
| SN_COAP_RESENDING_QUEUE_SIZE_BYTES | Defines the size of the resending buffer in bytes. Setting this to 0 disables this feature. | Disabled. |
| SN_COAP_MAX_ALLOWED_RESENDING_COUNT | Maximum allowed count of resending that can be set at runtime via sn_coap_protocol_set_retransmission_parameters() API. |
6 |
| SN_COAP_MAX_ALLOWED_RESPONSE_TIMEOUT | Maximum allowed re-send interval in seconds that can be set at runtime via sn_coap_protocol_set_retransmission_parameters() API. |
40 |
| SN_COAP_MAX_ALLOWED_RESENDING_BUFF_SIZE_MSGS | Maximum allowed count of messages that can be stored into resend buffer at runtime via sn_coap_protocol_set_retransmission_buffer() API. |
6 |
| SN_COAP_MAX_ALLOWED_RESENDING_BUFF_SIZE_BYTES | Maximum size of messages in bytes that can be stored into resend buffer at runtime via sn_coap_protocol_set_retransmission_buffer() API. |
512 |
Macros to control CoAP blockwise parameters
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| SN_COAP_BLOCKWISE_MAX_TIME_DATA_STORED | Maximum time in seconds how long messages and payload are stored 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 at one blockwise message in bytes. 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. |
0. Accepted values: 0, 16, 32, 64, 128, 256, 512 and 1024. |
| SN_COAP_MAX_INCOMING_MESSAGE_SIZE | Defines the maximum size in bytes that library will allow to be handled while receiving big payload in blockwise mode. Application can set this value based on their available storage capability. | 65535 bytes |
| SN_COAP_MAX_NONBLOCKWISE_PAYLOAD_SIZE | Defines the maximum payload size allowed before blockwising the message. This option should only be used 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 payload length 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. 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. |
Macros to control CoAP duplication parameters
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| SN_COAP_MAX_ALLOWED_DUPLICATION_MESSAGE_COUNT | Maximum allowed number of saved messages for message duplicate searching that can be set via sn_coap_protocol_set_duplicate_buffer_size API. |
6 |
| SN_COAP_DUPLICATION_MAX_MSGS_COUNT | Initial value for the maximum count 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 | Maximum time in seconds 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). To do this, it uses an event loop running on its own thread. Configure the application stack size based on need. Normally, the heaviest operation for event loops is the TLS/DTLS handshake, which requires 6 KB stack size on Mbed OS. However, if you are running your application on a debug profile, you may run encounter stack overflow on hardware. You can, however, modify stack size with the following configuration option.
Nanostack hardware abstraction layer (ns-hal-pal) configuration
| Macro name | Description | Defaults and restrictions |
|---|---|---|
| MBED_CONF_NS_HAL_PAL_EVENT_LOOP_THREAD_STACK_SIZE | Defines stack size for event loop in bytes. | 6144 bytes |