Documentation

Mistake on this page? Email us
Docs › Developer guide › Registering Client Lite to Device Management

Registering Client Lite to Device Management

This chapter explains which APIs Client Lite uses to:

  • Register to Device Management.
  • Update the registration, in other words, maintain the client registration status with Device Management.
  • Deregister from Device Management.

This chapter assumes you have already created the Resources for your device. Please read the Using Client Lite API for LwM2M resource management.

Register

The Register API enables the client registration functionality.

When Client Lite registers, it:

  • Performs the Register operation and provides parameters that Device Management requires to register the client (for example endpoint name).
  • Maintains the registration and session (for example, it sets the Lifetime and Queue Mode to Device Management).
  • Provides information on the Objects the client supports.
  • Provides information on existing Object Instances in the client.

Registering the client

This section walks you through the registration process.

  1. Create all the Resources that you would like to monitor using Izuma Device Management. See the Using Client Lite APIs for LwM2M resource management chapter for details.

    Creating Resources does not automatically register them in Device Management. You need to explicitly add them.

  2. Add the Resources to Client Lite to be registered to Device Management. Use this API:

    int pdmc_connect_add_cloud_resource(registry_t *registry, registry_path_t *path,
                                        const int16_t object, const int16_t object_instance, const int16_t resource,
                                        bool auto_observable, registry_callback_t callback);
    • path is the path to the Resource. It will be populated with parameters object, object_instance and resource given to this function call.
    • object is the Object level in OMA Object ("object/x/x/x"), for example 300/0/0/0.
    • object_instance is the Object Instance level in OMA Object ("x/object_instance/x/x"), for example 300/1/0/0.
    • resource is the Resource level in OMA Object ("x/x/resource/x"), for example 300/1/3/0.
    • auto_observable means the auto observable Resources that are updated to the service side automatically.
    • callback is registry_callback_t type of callback that will be notified on changes in the Resource.

    An example of adding an OMA resource /3200/0/5501:

    const lwm2m_resource_meta_definition_t OMA_LWM2M_RESOURCE_DEFS_OBJECT_3200[] = {
    LWM2M_RESOURCE_DEFINITION(5501, LWM2M_RESOURCE_SINGLE_INSTANCE, LWM2M_RESOURCE_MANDATORY, LWM2M_RESOURCE_OPERATIONS_R, LWM2M_RESOURCE_TYPE_INTEGER, "button_resource")
};

    registry_status_t ret;
registry_path_t path;
registry_t *registry = &pdmc_connect_get_interface()->endpoint.registry;
pdmc_connect_add_cloud_resource(registry, &path, 3200, 0, 5501, true, button_callback);

    button_callback is the function pointer of type registry_callback_t defined in lwm2m_registry.h.

    Note If you do not create your OMA Object and Resource struct as defined in Using Client Lite APIs for LwM2M resource managment chapter and only call pdmc_connect_add_cloud_resource(), your application will register to Device Management but you will not see the Resources.

  3. Call the Register API:

    pdmc_connect_register(void *iface);

    iface is the Network interface Object your application must instantiate and call the connect() function of the NetworkInterface class. iface is expected to point to a connected network interface before calling this API.

Success or failure callback

Because this is an asynchronous operation, you will receive the result of it through an event handler callback defined in your application.

Success

If the register operation is successful and the client can register all your Resources to Device Management, your application will receive the following event in the event handler callback:

LWM2M_INTERFACE_OBSERVER_EVENT_OBJECT_REGISTERED

Once you receive a success callback, you can make queries using device's endpoint name and Device ID (Device Management REST API uses this ID to send requests to this application) with this API:

bool pdmc_connect_endpoint_info(pdmc_endpoint_info_s *endpoint_info);

endpoint_info contains information such as:

  • endpoint_name is the device's public name.
  • device_id is the Device ID the Device Management REST API uses to send requests to this application.

Failure

If the registration operation fails, your application will receive the following event in the event handler callback:

LWM2M_INTERFACE_OBSERVER_EVENT_ERROR

You will get more information about the error from the event->event_type parameter passed with the callback. It needs to be typecasted to lwm2m_interface_error_t and you can see the reason for the failure.

A typical error received during registration can be one of the following:

LWM2M_INTERFACE_ERROR_BOOTSTRAP_FAILED
LWM2M_INTERFACE_ERROR_INVALID_PARAMETERS
LWM2M_INTERFACE_ERROR_NETWORK_ERROR
LWM2M_INTERFACE_ERROR_MEMORY_FAIL
LWM2M_INTERFACE_ERROR_SECURE_CONNECTION_FAILED
LWM2M_INTERFACE_ERROR_DNS_RESOLVING_FAILED
LWM2M_INTERFACE_ERROR_UNKNOWN_ERROR

Out of these, LWM2M_INTERFACE_ERROR_BOOTSTRAP_FAILED, LWM2M_INTERFACE_ERROR_NETWORK_ERROR, LWM2M_INTERFACE_ERROR_SECURE_CONNECTION_FAILED, LWM2M_INTERFACE_ERROR_DNS_RESOLVING_FAILED and LWM2M_INTERFACE_ERROR_UNKNOWN_ERROR are temporary errors. Client Lite keeps retrying to register (exponentially backing off with every error occurrence) until it connects.

LWM2M_INTERFACE_ERROR_INVALID_PARAMETERS and LWM2M_INTERFACE_ERROR_MEMORY_FAIL are halting errors that require attention from the application. Client Lite will stop its execution on these errors.

Register update

Periodically, in response to events within the client or as initiated by Device Management, the client updates its registration information with Device Management by sending it an Update operation.

Normally, the client updates the registration automatically. If you want to renew the registration before that, use this API:

pdmc_connect_register_update()

Success or failure callback

Success

If the update operation is successful, your application will receive the following event in the event handler callback:

LWM2M_INTERFACE_OBSERVER_EVENT_REGISTRATION_UPDATED

Failure

If the update operation fails, your application will receive the following event in the event handler callback:

LWM2M_INTERFACE_OBSERVER_EVENT_ERROR

You will get more information about the error from the event->event_type parameter passed with the callback. It needs to be typecasted to lwm2m_interface_error_t and you can see the reason for the failure.

A typical error received during registration update can be one of the following:

LWM2M_INTERFACE_ERROR_NOT_REGISTERED
LWM2M_INTERFACE_ERROR_NETWORK_ERROR
LWM2M_INTERFACE_ERROR_MEMORY_FAIL
LWM2M_INTERFACE_ERROR_SECURE_CONNECTION_FAILED
LWM2M_INTERFACE_ERROR_DNS_RESOLVING_FAILED
LWM2M_INTERFACE_ERROR_NOT_ALLOWED
LWM2M_INTERFACE_ERROR_UNKNOWN_ERROR

Out of these, LWM2M_INTERFACE_ERROR_NETWORK_ERROR, LWM2M_INTERFACE_ERROR_SECURE_CONNECTION_FAILED, LWM2M_INTERFACE_ERROR_DNS_RESOLVING_FAILED and LWM2M_INTERFACE_ERROR_UNKNOWN_ERROR are temporary errors. Client Lite will keep retrying to register (exponentially backing off with every error occurrence) until it completes the registration update.

LWM2M_INTERFACE_ERROR_NOT_REGISTERED, LWM2M_INTERFACE_ERROR_MEMORY_FAIL and LWM2M_INTERFACE_ERROR_NOT_ALLOWED, are halting errors that require attention from the application. Client Lite will stop its execution on these errors.

Deregister

The client can deregister from Device Management when it no longer requires access to the server. When Device Management receives the Deregister message, it removes the device's registration information from its database. When the client needs to contact Device Management, it must register again.

To deregister your client:

pdmc_connect_close()

Note: This API is for removing devices from Device Management, not for managing their connection intervals and sleep cycles.

Success or failure callback

Because this is an asynchronous operation, you will receive the result of it through an event handler callback defined in your application.

Success

If the client is successfully deregistered from Device Management, your application will receive the following event in the event handler callback:

LWM2M_INTERFACE_OBSERVER_EVENT_OBJECT_UNREGISTERED

Failure

If the deregistration operation fails, your application will receive the following event in the event handler callback:

LWM2M_INTERFACE_OBSERVER_EVENT_ERROR

You will get more information about the error from the event->event_type parameter passed with the callback. It needs to be typecasted to lwm2m_interface_error_t and you can see the reason for the failure.

A typical error received during deregistration can be one of the following:

LWM2M_INTERFACE_ERROR_NOT_REGISTERED
LWM2M_INTERFACE_ERROR_NETWORK_ERROR
LWM2M_INTERFACE_ERROR_MEMORY_FAIL
LWM2M_INTERFACE_ERROR_SECURE_CONNECTION_FAILED
LWM2M_INTERFACE_ERROR_DNS_RESOLVING_FAILED
LWM2M_INTERFACE_ERROR_NOT_ALLOWED
LWM2M_INTERFACE_ERROR_UNKNOWN_ERROR
LWM2M_INTERFACE_ERROR_UNREGISTRATION_FAILED

All of these are halting errors that require attention from the application. Client Lite will stop its execution on these errors.

Previous Next