Mistake on this page? Email us

Feature configurations

You can configure Client Lite features at build time through the mbed_app.json file. Many of the features are turned off by default as they have direct impact on application memory size, both RAM and ROM. See also Memory optimizations.

This chapter lists the high-level Client Lite features you can configure on application level.

Note: In addition to the features listed here, there are other component-level features, for example from Mbed OS. See Mbed OS configurations.

You can configure Client Lite features through the mbed_cloud_client_user_config_cert.h and mbed_app.json files. The configurable items for the mbed_app.json are defined in library-specific mbed_lib.json files:

  • mbed-cloud-client/mbed-client/mbed_lib.json
  • mbed-client/mbed_lib.json

Header file for compiling

You need to use the MBED_CLOUD_CLIENT_USER_CONFIG_FILE header file when compiling Client Lite. It is defined in the beginning of mbed_app.json file:

    "macros": [
        "MBED_CLOUD_CLIENT_USER_CONFIG_FILE=\"mbed_cloud_client_user_config_cert.h\""
    ]

The configuration values are documented in the Pelion Device Management documents, Client Advanced Configuration.

Do not modify the mbed_lib.json files. Instead, overrule the default values in your own mbed_app.json file.

Configurations in mbed-client/mbed_lib.json

The core defaults for Client Lite are in mbed_lib.json file in mbed-cloud-client/mbed-client. The default values should work for most cases.

event-loop-size

Event-loop-size is the default memory allocation for events. If your application uses a lot of events or is slow at handling some events (and thus events can pile up), you may have to increase the event-loop-size value. If you run out of space in the event loop stack:

  • The device will assert in debug builds.
  • The device will reset in release builds.

reconnection-count

Reconnection count specifies how many times an outgoing message is retransmitted. The default value is 3. The application will first receive ERROR_REASON_9 (Client in reconnection mode) and finally ERROR_REASON_10 (Client cannot connect anymore) if an error callback has been registered. Based on these callbacks, the application can decide on the actions, for example:

  • Restart the network stack or
  • Pause the client and activate an alternative network stack (switch from Wi-Fi to cellular, for example) and resume with a new connection.

reconnection-interval

Reconnection interval is the time the client waits before trying to retransmit an outgoing message. The default value is 5, which defines the first interval. The interval increases incrementally with subsequent retransmissions.

tcp-keepalive-interval

Interval for sending CoAP Ping to keep TCP connection open. The default is 90 seconds. This is not sent if you are using UDP mode.

sn-coap-duplication-max-msgs-count

If you operate in a lossy network with UDP, you may receive duplicate packets. To keep track of duplicate packets the client has the option to keep a message buffer for duplicate packet recognition. However, this consumes memory. The default value of the duplicate message buffer is set to 0.

enable-serialize-plaintext

Client has two ways of communicating with the LwM2M server:

  • The default mode for single resource updates is serialized, that is text-based value sending.
  • The alternative is Type-Length-Value (TLV), which decreases the RAM and ROM consumption in the client. It also makes the executable slightly smaller. However, the readability of the values in Device Management Portal may not be good enough.

Note: If you enable serialisation, you must also enable 64-bit printf. Also the configuration for enable-deserialize-plaintext (incoming content) needs to match this selection.

enable-float-value

If your application does not use float values at all, you can configure the float support off. This decreases client ROM consumption a bit. However, the official LwM2M/IPSO objects are often float-based, so this might not always be an option.

Note: If you enable float values, you must also enable the full printf library: "target.printf_lib" : "std"

enable-observation-parameters

If you do not need full LwM2M specification observation parameter capability, you can set this to null to save on client RAM and ROM consumption. This is enabled by default.

Configurations in mbed-cloud-client/mbed_lib.json

Higher-level Client Lite default values are in the mbed_lib.json file in mbed-cloud-client. The default values should work for most cases.

storage-type

The default storage type is KVStore, which will use the underlying storage. Mbed OS typically defaults to TDBStore. Alternatively, you can use RAM.

Note: If you want to run your application on a new board with no proven storage support, you can use RAM with FOTA support as storage type. With RAM storage, credentials are not saved and all reboots generate a new endpoint identity for the device through the bootstrap process.

storage-reset-dev-credentials

This option enables you to wipe out the contents of the KVStore. This is useful if you want to recreate the identity for the device when using a developer certificate. The default value is false.

A new device bootstraps and gets an identify from the bootstrap server. This identity is stored (as an LwM2M certificate) to the KVStore on the device with correct configurations. This means the device identity is retained even if you flash in a new application. However, in some cases you may want to erase the contents and start from the scratch (for example automated test setups or a device being transferred over to another account).

Alternatively, you can use the pyocd tool to erase the device flash. Use the command:

pyocd erase --mass-erase

Then reflash the application and the bootloader. This clears the KVStore and the device bootstraps and gets a new identity.

update-storage

This parameter defines the location of the firmware image storage. The default is ARM_UCP_FLASHIAP, which typically means the internal flash of a device. Other option is ARM_UCP_FLASHIAP_BLOCKDEVICE which means a block device - (Q)SPI-flash or SD card, for example.

This value is already used in the Client Lite example mbed_app.json for the supported reference configurations.