Documentation

Mistake on this page? Email us

Set up and register your client with Device Management

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

For a device to be accessible from the Device Management APIs and web applications, it first needs to register with Device Management services. Registration gives the device a unique ID, and tells the services what Resources the device offers; the services can then expose these resources to applications.

The client uses the Setup and Registration features to:

In the full setup and registration process, the 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 that the Device Management service requires to register the client.
  4. Starts a secure connection to the cloud service.
  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 the client.

Configuring your client

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

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

  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, and you need to pass this file to the Device Management Client API during the compilation. It then uses the file to set up the client, fetch its identity, and register the device with the cloud services.

    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
    

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

    Choosing the correct transport mode

    Mbed 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 via VPN-tunnel, UDP can in some cases be a more optimal choice. For power-efficient endpoints; UDP with queue is the recommended mode. See Optimizations for device use and server communication.

    For most use-cases, TCP or UDP_QUEUE should be the main choices. UDP, especially in IPv4 and/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 below one hour. For devices that do not have to be actively managed, lifetime of multiple hours or even days, would be advisable. 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), the application also does not benefit from having a short lifetime just for keeping the connection active. See Network configuration requirements and recommendations.

  3. Register all the resources that you would like to monitor using Device Management. To do this, 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. Please 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, please read the API documentation.

    For example, to create an integer type Resource, you can 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);
  1. 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.

  2. 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 the 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.