Set up and register your client with Device Management

This section offers a brief overview of the full registration process and then explains what your application needs to do to connect to Device Management with Device Management Client.

To make a device accessible from the Device Management APIs and web applications, you must first register the device with Device Management services. Registration gives the device a unique ID and tells the services what Resources the device offers; the services can then provide these Resources to applications.

Device Management Client uses the Setup and Registration features to:

• Set up and register with the Device Management service.
• Update its registration.
• Deregister.

In the full setup and registration process, Device Management Client:

1. Uses Device Management services to create a unique identity based on the credentials stored on the device (bootstrap).
2. Stores this identity and the device's certificates.
3. Using the stored information, performs the register operation, where it provides the parameters the Device Management service requires to register Device Management Client.
4. Starts a secure connection to Device Management.
5. Maintains the registration and session (for example, it sets the Lifetime and Queue Mode).
6. Provides information about the supported Objects and the existing Object Instances on Device Management Client.

Configuring your client

To provide the necessary information to the Device Management service and issue the setup command:

1. Prepare the device credentials you will use to register your client with Device Management service. There are different ways to set up these credentials on your device; please see the registration options page for details.

2. Device Management Client defines the configuration parameters in the MbedCloudClientConfig.h file. Your application needs to set or overwrite these parameters in a file called mbed_cloud_client_user_config.h (supplied in the example). This file is processed by the compiler during the build process to configure the client behaviour.

   Your application must define the following parameters in the mbed_cloud_client_user_config.h file:

   #define MBED_CLOUD_CLIENT_SUPPORT_CLOUD
   #define MBED_CLOUD_CLIENT_ENDPOINT_TYPE          "default"
   #define MBED_CLOUD_CLIENT_LIFETIME               3600
   #define MBED_CLOUD_CLIENT_TRANSPORT_MODE_TCP
   

   You can define or change a few other parameters to configure your device. For details, please see the API documentation of MbedCloudClientConfig.h.

   Choosing the correct transport mode

   Device Management Client supports three transport modes: TCP, UDP or UDP_QUEUE. For a device which is expected to maintain constant connection to the server over open internet, TCP is the recommended option. Inside local networks or through VPN-tunnel, UDP can in some cases be a better choice. For power-efficient endpoints, UDP with queue is the recommended mode. Please see Optimizations for device use and server communication for more details.

   For most use cases, TCP or UDP_QUEUE are the best candidates. UDP, especially in IPv4 or behind NAT, can be highly unreliable for maintaining connection.

   Choosing the correct lifetime for your endpoint

   For energy-efficient devices, the lifetime should never be less than one hour. We advise a lifetime of multiple hours or even days for devices that do not have to be actively managed. This limits the need to send resource-intensive register update messages. If the application is sending notification(s) frequently (at least once every few minutes), a short lifetime is not feasible just to keep the connection active. See Network configuration requirements and recommendations.

3. Register all the Resources you would like to monitor using Device Management. Create the Resource Objects, and add them to Device Management Client for registration purposes.

   For example, to register your OMA LwM2M based Device Object, create the Object, and set the values for mandatory Resources:

   #include "mbed-client/m2mdevice.h"
   M2MDevice* device = M2MInterfaceFactory::create_device();
   if(device) {
      device->create_resource(M2MDevice::Manufacturer, MANUFACTURER);
      device->create_resource(M2MDevice::DeviceType, TYPE);
      device->create_resource(M2MDevice::ModelNumber, MODEL_NUMBER);
      device->create_resource(M2MDevice::SerialNumber, SERIAL_NUMBER);
   }
   

   Note: You can also register other Resources, including custom Resources. See the API documentation for a detailed description of the M2MObject, M2MObjectInstance and M2MResource classes.

4. Optional: You can use a wrapper API in Device Management Client to create a Resource based on integers and strings. For more information, read the API documentation.

   For example, to create an integer type Resource, use:

   SimpleM2MResourceInt btn_count(&client, "3200/0/1", 0, M2MBase::GET_ALLOWED);
   

5. Call the API to add your Resources into the registered list:

   MbedCloudClient::add_objects(const M2MObjectList& object_list);
   

6. Set a callback function to get information on the registration status, deregistration status or error status occurring during the setup phase or during the client's lifecycle. To set the callbacks:

   • Registration status: MbedCloudClient::on_registered(void(*fn)(void));
   • Deregistration status: MbedCloudClient::on_unregistered(void(*fn)(void));
   • Error status: MbedCloudClient::on_error(void(*fn)(int));

   You can see the mapped error codes in the MbedCloudClient::Error enum.

7. Call the setup API to set up the device identity (if not present already) and register your device and Resources to the Device Management service.

   MbedCloudClient::setup();
   

Success and failure callbacks

Success

If the register operation is successful and Device Management Client can register all your Resources to Device Management Connect, your application receives the result through your registered callback:

MbedCloudClient::on_registered(void(*fn)(void));

Failure

If the registration operation fails, you receive the result through your error callback:

MbedCloudClient::on_error(void(*fn)(int));

The error parameter passed with the callback contains more information on the error; use it to fix the problem.