Client Mode API Reference

This is an excerpt from the IOWA Full SDK.

Contact us

The functions explained below are defined inside the file include/iowa_client.h and the Objects folder include/objects.

Client pseudo code

#include "iowa_client.h"
#include "iowa_ipso.h"

int main(int argc,
         char *argv[])
{
    iowa_context_t iowaH;
    iowa_status_t result;
    iowa_device_info_t devInfo;
    iowa_sensor_t sensorId;

    /******************
    * Initialization
    */

    iowaH = iowa_init(NULL);

    devInfo.manufacturer = "IOTEROP";
    devInfo.deviceType = "Example device";
    devInfo.modelNumber = "1";
    devInfo.serialNumber = NULL;
    devInfo.hardwareVersion = NULL;
    devInfo.softwareVersion = NULL;
    devInfo.optFlags = 0;
    result = iowa_client_configure(iowaH, "IOWA_Sample_Client", devInfo, NULL);

    result = iowa_client_IPSO_add_sensor(iowaH,
                                         IOWA_IPSO_VOLTAGE, 12.0,
                                         "V", "Test DC", 0.0, 0.0,
                                         &sensorId);

    result = iowa_client_add_server(iowaH, 1234, "coap://localhost:5683", 0, 0, IOWA_SEC_NONE);

    /******************
    * "Main loop"
    */

    while (result == IOWA_COAP_NO_ERROR)
    {
        float sensorValue;

        result = iowa_step(iowaH, 5);

        sensorValue = read_battery_voltage();
        result = iowa_client_IPSO_update_value(iowaH,
                                               sensorId,
                                               sensorValue);
    }

    iowa_client_IPSO_remove_sensor(iowaH, sensorId);
    iowa_close(iowaH);

    return 0;
}

Data types

iowa_lwm2m_binding_t

typedef uint8_t iowa_lwm2m_binding_t;

IOWA_LWM2M_BINDING_UNKNOWN: The flag to define Unknown binding.
IOWA_LWM2M_BINDING_UDP: The flag to define UDP binding.
IOWA_LWM2M_BINDING_TCP: The flag to define TCP binding.
IOWA_LWM2M_BINDING_SMS: The flag to define SMS binding.
IOWA_LWM2M_BINDING_NON_IP: The flag to define Non-IP binding.

iowa_server_status_t

This is an enumeration of the following values:

IOWA_SERVER_STATUS_UNREGISTERED: This is the initial state of any server.
IOWA_SERVER_STATUS_REGISTERING: IOWA is currently registering to this server.
IOWA_SERVER_STATUS_REGISTERED: IOWA is registered to this server.
IOWA_SERVER_STATUS_REGISTRATION_FAILED: IOWA failed to register to this server.
IOWA_SERVER_STATUS_BOOTSTRAPPING: This server is the LwM2M Bootstrap Server and it is currently bootstrapping IOWA.

iowa_server_info_t

typedef struct
{
    uint16_t                shortId;
    const char             *uriP;
    int32_t                 lifetime;
    iowa_lwm2m_binding_t    binding;
    bool                    queueMode;
    iowa_server_status_t    status;
    uint16_t                securityObjectInstanceId;
    uint16_t                serverObjectInstanceId;
    uint16_t                oscoreObjectInstanceId;
    iowa_lwm2m_protocol_version_t lwm2mVersion;
} iowa_server_info_t;

The iowa_server_info_t structure is used to get the shortID and the parameters of the configured servers.

shortId: the Short ID assigned to the server.
uriP: The uri to connect with the server.
lifetime: The lifetime in seconds of the registration to the server.
binding: The binding used to connect to the server.
queueMode: The state of the Queue mode of the server.
status: The current registration status of the server.
securityObjectInstanceId: The ID of the Security Object Instance holding the server information.
serverObjectInstanceId: The ID of the Server Object Instance holding the server information. The value is IOWA_LWM2M_ID_ALL for a LwM2M Bootstrap-Server.
oscoreObjectInstanceId: The ID of the OSCORE Object Instance holding the server information. The value is IOWA_LWM2M_ID_ALL if the server does not use OSCORE or if IOWA_COAP_OSCORE_SUPPORT is not defined.
lwm2mVersion: The LwM2M protocol version used by the server. See iowa_lwm2m_protocol_version_t.

iowa_device_info_t

typedef struct
{
    const char *manufacturer;
    const char *deviceType;
    const char *modelNumber;
    const char *serialNumber;
    const char *hardwareVersion;
    const char *firmwareVersion;
    const char *softwareVersion;
    const char *msisdn;
    const char *altPath;
    uint16_t    optFlags;
    const char *utcOffsetP;
    const char *timezoneP;
    uint32_t    memoryTotal;
    uint32_t    memoryFree;
    iowa_client_time_update_callback_t    dataTimeUpdateCallback;
    iowa_client_factory_reset_callback_t  factoryResetCallback;
    void                                 *callbackUserDataP;
} iowa_device_info_t;

The iowa_device_info_t structure exists only for the sake of the readability of iowa_client_configure(). It contains pointers to nil-terminated strings described below. As all these information are optional in a LwM2M Client, these pointers can be nil. The LwM2M standard does not mandate any format for these strings. They are manufacturer specific.

manufacturer: A human readable manufacturer name.
deviceType: The type of the device.
modelNumber: The number of the model.
serialNumber: The serial number of the device.
hardwareVersion: The current version of the device hardware.
firmwareVersion: The current version of the device firmware.
softwareVersion: The current version of the device software.
msisdn: The phone number of the device.
altPath: The LwM2M Alternative Path.
optFlags: Flags used to enable optional features. This value is a combination of:

IOWA_DEVICE_RSC_BATTERY: enables the battery level and status exposed in the Device Object. To update battery level you need to call iowa_client_device_update_battery().
IOWA_DEVICE_RSC_POWER_SOURCE: enables the power sources information in the Device Object. To add any new power source you need to call iowa_client_add_device_power_source().
IOWA_DEVICE_RSC_CURRENT_TIME: enables the use of current time in the Device Object (default value: 0).
IOWA_DEVICE_RSC_UTC_OFFSET: enables the use of UTC offset in the Device Object (default value: utcOffsetP).
IOWA_DEVICE_RSC_TIMEZONE: enables the use of timezone in the Device Object (default value: 0). To update time information (current time, UTC offset, timezone) you need to call iowa_client_update_device_time_information()
IOWA_DEVICE_RSC_MEMORY_FREE: enables the Memory Free resource exposed in the Device Object (default value: memoryFree).
IOWA_DEVICE_RSC_EXTERNAL_INFO: enables the ExtDevInfo resource exposed in the Device Object. To set the Resource values, you need to call iowa_client_update_device_external_information().

utcOffsetP: Indicates the UTC offset currently in effect for this LwM2M Device. It should be in the ISO 8601 format (UTC+X).
timezoneP: Indicates in which time zone the LwM2M Device is located, in IANA Timezone (TZ) database format.
memoryTotal: Total amount of storage space which can store data and software in the LwM2M Device (expressed in kilobytes). Ignored if equal to zero.
memoryFree: Estimated current available amount of storage space which can store data and software in the LwM2M Device (expressed in kilobytes). Ignored if optFlags does not have IOWA_DEVICE_RSC_MEMORY_FREE set.
dataTimeUpdateCallback: The callback called when the time information is updated by the LwM2M Server.
factoryResetCallback: The callback called on a Factory Reset.
callbackUserDataP: Passed as argument to the callbacks dataTimeUpdateCallback and factoryResetCallback.

Notes

To update time information (current time, UTC offset, timezone) you need to call iowa_client_update_device_time_information()

To update device related information (manufacturer, model number, serial number, firmware version, device type, hardware version, software version.) you need to call iowa_client_update_device_information().

iowa_object_setting_id_t

typedef uint8_t iowa_object_setting_id_t;

Possible Values

IOWA_OBJECT_SETTING_VERSION: A flag to set the version of the object, value is an iowa_object_version_t.

iowa_event_type_t

typedef enum
{
    IOWA_EVENT_UNDEFINED = 0,
    IOWA_EVENT_REG_UNREGISTERED,
    IOWA_EVENT_REG_REGISTERING,
    IOWA_EVENT_REG_REGISTERED,
    IOWA_EVENT_REG_UPDATING,
    IOWA_EVENT_REG_FAILED,
    IOWA_EVENT_REG_UPDATE_FAILED,
    IOWA_EVENT_BS_PENDING,
    IOWA_EVENT_BS_FINISHED,
    IOWA_EVENT_BS_FAILED,
    IOWA_EVENT_OBSERVATION_STARTED,
    IOWA_EVENT_OBSERVATION_NOTIFICATION,
    IOWA_EVENT_OBSERVATION_NOTIFICATION_ACKED,
    IOWA_EVENT_OBSERVATION_NOTIFICATION_FAILED,
    IOWA_EVENT_OBSERVATION_CANCELED,
    IOWA_EVENT_OBJECT_INSTANCE_CREATED,
    IOWA_EVENT_OBJECT_INSTANCE_DELETED,
    IOWA_EVENT_EVALUATION_PERIOD,
    IOWA_EVENT_READ,
    IOWA_EVENT_SERVER_SETTING_CHANGED
} iowa_event_type_t;

The iowa_event_type_t contains the possible events that can be reported by the IOWA stack.

iowa_event_t

typedef struct
{
    iowa_event_type_t eventType;
    uint16_t          serverShortId;
    union
    {
        struct
        {
            uint32_t lifetime;
            bool internalError;
            iowa_status_t errorCode;
        } registration;
        struct
        {
            iowa_sensor_t sensorId;
            uint32_t notificationNumber;
            uint16_t resourceId;
            uint32_t minPeriod;
            uint32_t maxPeriod;
            uint32_t minEvalPeriod;
            uint32_t maxEvalPeriod;
        } observation;
        struct
        {
            iowa_lwm2m_uri_t * uriP;
        } objectInstance;
        struct
        {
            iowa_lwm2m_uri_t * uriP;
            uint32_t minEvalPeriod;
            uint32_t maxEvalPeriod;
        } evalPeriod;
        struct
        {
            iowa_sensor_t sensorId;
        } sensor;
        struct
        {
            iowa_server_setting_id_t id;
            union
            {
                bool asBoolean;
                uint32_t asUInt32;
                int32_t asInt32;
                iowa_lwm2m_binding_t asBinding;
            } value;
        } serverSetting;
    } details;
} iowa_event_t;

eventType: the event type.
serverShortId: the short server ID of the LwM2M Server generating this event.
details: the details of the event.
details::registration: filled when the event is of type IOWA_EVENT_REG_UNREGISTERED, IOWA_EVENT_REG_REGISTERING, IOWA_EVENT_REG_REGISTERED, IOWA_EVENT_REG_UPDATING, IOWA_EVENT_REG_FAILED or IOWA_EVENT_REG_UPDATE_FAILED.
details::registration::lifetime: the lifetime of the registration to the LwM2M Server generating this event.
details::registration::internalError: indicates if the error for a failed registration or registration update is coming from an internal issue or if it an error returned by the LwM2M Server. Set only when the event is of type IOWA_EVENT_REG_FAILED or IOWA_EVENT_REG_UPDATE_FAILED.
details::registration::errorCode: an iowa_status_t indicating the reason for a failed registration or registration update. Set only when the event is of type IOWA_EVENT_REG_FAILED or IOWA_EVENT_REG_UPDATE_FAILED.
details::observation: filled when the event is of type IOWA_EVENT_OBSERVATION_STARTED, IOWA_EVENT_OBSERVATION_NOTIFICATION, IOWA_EVENT_OBSERVATION_NOTIFICATION_ACKED, IOWA_EVENT_OBSERVATION_NOTIFICATION_FAILED, or IOWA_EVENT_OBSERVATION_CANCELED
details::observation::sensorId: the ID of the sensor under observation.
details::observation::resourceId: the ID of the specific resource under observation of the sensor. This may be IOWA_LWM2M_ID_ALL.
details::observation::minPeriod: the minimum time in seconds to wait between notifications for the observation. If not set the minPeriod is to 0.
details::observation::maxPeriod: the maximum time in seconds to wait between notifications for the observation. If not set the maxPeriod is to UINT32_MAX.
details::observation::minEvalPeriod: the minimum sample time in seconds for the observed sensor in LwM2M 1.1 or later. If not set the minEvalPeriod is to 0.
details::observation::maxEvalPeriod: the maximum sample time in seconds for the observed sensor in LwM2M 1.1 or later. If not set the maxEvalPeriod is to UINT32_MAX.
details::instance: filled when the event is of type IOWA_EVENT_OBJECT_INSTANCE_CREATED or IOWA_EVENT_OBJECT_INSTANCE_DELETED.
details::instance::uri: a pointer to the iowa_lwm2m_uri_t of the instance that has been created or deleted.
details::evalPeriod: filled when the event is of type IOWA_EVENT_EVALUATION_PERIOD. Available when the flag IOWA_LWM2M_VERSION_1_1 is set.
details::evalPeriod::uriP: a pointer to the iowa_lwm2m_uri_t of the uri where evaluation period has been set.
details::evalPeriod::minEvalPeriod: the minimum sample time in seconds for the concerned uri. If the LwM2M Server unsets it or does not set it, the value is 0.
details::evalPeriod::maxEvalPeriod: the maximum sample time in seconds for the concerned uri. If the LwM2M Server unsets it or does not set it, the value is UINT32_MAX.
details::sensor: filled when the event is of type IOWA_EVENT_READ.
details::sensor::sensorId: the ID of the sensor targeted by a Read operation from the LwM2M Server.
details::serverSetting: filled when the event is of type IOWA_EVENT_SERVER_SETTING_CHANGED.
details::serverSetting::id: the ID of the LwM2M Server setting that changed.
details::serverSetting::value: the value of the LwM2M Server setting depending on the setting ID. See iowa_server_setting_id_t.

The iowa_event_t is used by iowa_event_callback_t when an event occurred on a client. These events are described by iowa_event_type_t.

Notes

The IOWA stack handles the minimum and maximum observation periods. They are provided in iowa_event_t as an information for the application. Embedded devices may use this information to tune their measurement or sleeping schedule.

The IOWA stack does not handle the minimum and maximum evaluation observation periods. They are provided in iowa_event_t as sample times for the application. Embedded devices may use those sample times to tune their measurement or sleeping schedule.

For events of type IOWA_EVENT_REG_FAILED or IOWA_EVENT_REG_UPDATE_FAILED, details::registration::internalError set to true indicates an internal error. details::registration::errorCode indicates the type of error: * IOWA_COAP_406_NOT_ACCEPTABLE: the response from the LwM2M Server is not valid. * IOWA_COAP_500_INTERNAL_SERVER_ERROR: a memory allocation failed. * IOWA_COAP_503_SERVICE_UNAVAILABLE: lost connection to the LwM2M Server.

The IOWA stack generates events of type IOWA_EVENT_SERVER_SETTING_CHANGED when a LwM2M Server performs a LwM2M Write operation on the matching resource in the LwM2M server Object. The event is generated even if the written value is the same as the previous one.

iowa_device_time_info_t

typedef struct
{
    uint16_t    flags;
    int32_t     currentTime;
    const char *utcOffsetP;
    const char *timezoneP;
} iowa_device_time_info_t;

flags: Flags used to enable optional time information. This value is a combination of:

IOWA_DEVICE_RSC_CURRENT_TIME : current time has a new current time value from server
IOWA_DEVICE_RSC_UTC_OFFSET : current time has a new UTC offset value from server
IOWA_DEVICE_RSC_TIMEZONE : current time has a new timezone value from server

currentTime: Current UNIX time of the LwM2M Client in seconds.
utcOffsetP: Indicates the UTC offset currently in effect for this LwM2M Device. It should be in the ISO 8601 format (UTC+X). Could be nil, if not UTC offset is enable.
timezoneP: Indicates in which time zone the LwM2M Device is located, in IANA Timezone (TZ) database format. Could be nil, if not Timezone is enable.

iowa_ipso_timed_value_t

typedef struct
{
    float value;
    int32_t timestamp;
} iowa_ipso_timed_value_t;

value: The timestamped value.
timestamp: The timestamp associated to the value in seconds. This can not be negative.

iowa_sensor_t

This must be treated as an opaque type. It is internally mapped to a 32-bit unsigned integer.

Special Values

IOWA_INVALID_SENSOR_ID: Used to indicate an error by APIs returning an iowa_sensor_t.
IOWA_DEVICE_TIME_SENSOR_ID: The sensor ID of the Current Time of the device. This is internally mapped to the resource 13 in the Device Object.

iowa_lwm2m_resource_desc_t

This structure contains the description of a LwM2M resource.

typedef struct {
    uint16_t id;
    iowa_lwm2m_data_type_t type;
    uint8_t operations;
    uint8_t flags;
} iowa_lwm2m_resource_desc_t;

id: ID of the resource.
type: The datatype of the resource.
operations: The operations allowed on the resource.; This is a mask of values IOWA_OPERATION_READ, IOWA_OPERATION_WRITE and IOWA_OPERATION_EXECUTE.
flags: The flags of the resource.; This is a mask of values IOWA_RESOURCE_FLAG_NONE, IOWA_RESOURCE_FLAG_OPTIONAL, IOWA_RESOURCE_FLAG_MANDATORY, IOWA_RESOURCE_FLAG_MULTIPLE, and IOWA_RESOURCE_FLAG_ASYNCHRONOUS.

iowa_sensor_uri_t

This structure describes a sensor URI.

typedef struct
{
    iowa_sensor_t id;
    uint16_t resourceId;
} iowa_sensor_uri_t;

id: ID of the object.
resourceId: The ID of the resource. This can be IOWA_LWM2M_ID_ALL.

Callbacks

iowa_event_callback_t

This is the event callback, called when an event such as registration update or unregister occurred.

typedef void(*iowa_event_callback_t) (iowa_event_t* eventP,
                                      void * userData,
                                      iowa_context_t contextP);

eventP: The event stored in a structure.
userData: A pointer to application specific data. This is a parameter of iowa_init().
contextP: The IOWA context on which iowa_client_configure() was called.

iowa_client_time_update_callback_t

This callback is called when time information are updated by server.

typedef void(*iowa_client_time_update_callback_t) (iowa_device_time_info_t *timeInfoP,
                                                   void  *userDataP,
                                                   iowa_context_t contextP);

timeInfoP: Current device time information.
userDataP: A pointer to application specific data. This is the parameter of iowa_client_configure().
contextP: The IOWA context on which iowa_client_configure() was called.

iowa_client_factory_reset_callback_t

This callback is called when a factory reset is requested.

typedef void(*iowa_client_factory_reset_callback_t) (void *userDataP,
                                                     iowa_context_t contextP);

userDataP: A pointer to application specific data. This is the parameter of iowa_client_configure().
contextP: The IOWA context on which iowa_client_configure() was called.

iowa_RWE_callback_t

This callback is called when a Read, Write or Execute operation is performed on a resource of a custom LwM2M Object.

typedef iowa_status_t(*iowa_RWE_callback_t) (iowa_dm_operation_t operation,
                                             iowa_lwm2m_data_t * dataP,
                                             size_t numData,
                                             void * userData,
                                             iowa_context_t contextP);

operation: The operation to perform on the resource among IOWA_DM_READ, IOWA_DM_WRITE and IOWA_DM_EXECUTE.
dataP: An array of the URIs of the targeted resources.; For a Write operation, it also contains the value to write.; For a Read operation, the result is to be stored in this.
numData: Number of resources in dataP.
userData: A pointer to application specific data. This is the parameter of iowa_client_add_custom_object().
contextP: The IOWA context on which iowa_client_add_custom_object() was called.

Notes

Before calling this callback, the IOWA stack performs checks on the resource existence and its allowed operations. In case of a Write operation, the data type is also checked for conformance.
The LwM2M Execute operation may have parameters. If so, they are provided as a string in dataP.
After IOWA_DM_READ operation, the callback is called with IOWA_DM_FREE operation to permit the deallocation of memory that may have been allocated by the callback previously.
In case of a write operation on resource-instances level, if the Write operation is a Replace, and not a Partial Update, the callback will be called first with IOWA_DM_DELETE to erase the current resource-instances, then it will be called with IOWA_DM_WRITE to write the new values. in case of a Partial Update Write operation, the callback will be called with IOWA_DM_WRITE only, where it will change or append the current resource-instances values.

iowa_CD_callback_t

This callback is called when a Create or Delete operation is performed on an instance of a custom LwM2M Object.

typedef iowa_status_t(*iowa_CD_callback_t) (iowa_dm_operation_t operation,
                                            uint16_t objectID,
                                            uint16_t instanceID,
                                            void * userData,
                                            iowa_context_t contextP);

operation: The operation to perform on the instance among IOWA_DM_CREATE and IOWA_DM_DELETE.
objectID: The ID of the targeted Object.
instanceID: The ID of the targeted instance.
userData: A pointer to application specific data. This is the parameter of iowa_client_add_custom_object().
contextP: The IOWA context on which iowa_client_add_custom_object() was called.

iowa_RI_callback_t

This callback is called to retrieve the list of current resource instance IDs for a multiple resource.

typedef iowa_status_t(*iowa_RI_callback_t) (uint16_t objectID,
                                            uint16_t instanceID,
                                            uint16_t resourceID,
                                            uint16_t * nbResInstanceP,
                                            uint16_t ** resInstanceArrayP,
                                            void * userData,
                                            iowa_context_t contextP);

objectID: The ID of the Object the resource belongs to.
instanceID: The ID of the Object Instance the resource belongs to.
resourceID: The ID of the targeted resource.
nbResInstanceP: Used to store the number of elements in resInstanceArrayP.
resInstanceArrayP: Used to store an array containing the resource instances IDs. This array will be freed by the caller by calling iowa_system_free().
userData: A pointer to application specific data. This is the parameter of iowa_client_add_custom_object().
contextP: The IOWA context on which iowa_client_add_custom_object() was called.

API

iowa_client_configure

Prototype

iowa_status_t iowa_client_configure(iowa_context_t contextP,
                                    const char * identity,
                                    iowa_device_info_t * infoP,
                                    iowa_event_callback_t eventCb);

Description

iowa_client_configure() sets the information of the LwM2M Client.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
identity: The unique identity of the LwM2M Client as a nil-terminated string.
infoP: The optional information of the LwM2M Client. This can be nil.
eventCb: The callback called when an event occurred. This can be nil.

Return Value

IOWA_COAP_NO_ERROR

success.

COAP_400_BAD_REQUEST

either:

identity is nil or empty and LWM2M_VERSION_1_1_SUPPORT is not set.

the maximum length of infoP->msisdn is 15 digits.

infoP->msisdn is not nil, but IOWA_SMS_SUPPORT is not defined.

infoP->altPath contains an invalid URI path.

IOWA_COAP_412_PRECONDITION_FAILED

the client was already configured in this context. To reconfigure the client, close than reopen a fresh IOWA context with iowa_close() and iowa_init().

IOWA_COAP_500_INTERNAL_SERVER_ERROR

a memory allocation failed.

Header File

iowa_client.h

Notes

The nil-terminated strings pointed by the fields of infoP are not duplicated nor freed by IOWA. Make sure they are available until iowa_close() is called. It is advised to use static strings.

Device Object Resources

The LwM2M Client information is exposed to the LwM2M Server through the Resources of the Device Object (ID: 3). The following table explained the mapping:

Resource ID	Resource Name	API
0	Manufacturer	manufacturer field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_MANUFACTURER must be defined.
1	Model Number	modelNumber field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_MODEL_NUMBER must be defined.
2	Serial Number	serialNumber field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_SERIAL_NUMBER must be defined.
3	Firmware Version	firmwareVersion field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_FIRMWARE_VERSION must be defined.
4	Reboot
5	Factory Reset	Set the callback factoryResetCallback of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_FACTORY_RESET must be defined.
6	Available Power Sources	Set the flag IOWA_DEVICE_RSC_POWER_SOURCE in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_..._device_power_source` to control it. IOWA_DEVICE_SUPPORT_RSC_POWER_SOURCE must be defined.
7	Power Source Voltage	Set the flag IOWA_DEVICE_RSC_POWER_SOURCE in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_..._device_power_source` to control it. IOWA_DEVICE_SUPPORT_RSC_POWER_SOURCE must be defined.
8	Power Source Current	Set the flag IOWA_DEVICE_RSC_POWER_SOURCE in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_..._device_power_source` to control it. IOWA_DEVICE_SUPPORT_RSC_POWER_SOURCE must be defined.
9	Battery Level	Set the flag IOWA_DEVICE_RSC_BATTERY in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_device_update_battery` to control it. IOWA_DEVICE_SUPPORT_RSC_BATTERY must be defined.
10	Memory Free	memoryFree field of the `iowa_device_info_t` structure when the flag IOWA_DEVICE_RSC_MEMORY_FREE in the optFlags field is set. IOWA_DEVICE_SUPPORT_RSC_MEMORY_FREE must be defined.
11	Error Code	Use `iowa_client_..._device_error_code` to control it.
12	Reset Error Code	Set the flag IOWA_DEVICE_RSC_RESET_ERROR in optFlags field of the structure `iowa_device_info_t`. IOWA_DEVICE_SUPPORT_RSC_RESET_ERROR must be defined.
13	Current Time	Set the flag IOWA_DEVICE_RSC_CURRENT_TIME in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_update_device_time_information` to control it. IOWA_DEVICE_SUPPORT_RSC_CURRENT_TIME must be defined.
14	UTC Offset	utcOffsetP field and set the flag IOWA_DEVICE_RSC_UTC_OFFSET in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_update_device_time_information` to control it. IOWA_DEVICE_SUPPORT_RSC_UTC_OFFSET must be defined.
15	Timezone	timezoneP field and set the flag IOWA_DEVICE_RSC_TIMEZONE in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_update_device_time_information` to control it. IOWA_DEVICE_SUPPORT_RSC_TIMEZONE must be defined.
16	Supported Binding and Modes	Cannot be updated directly but depends on the Server URI schema.
17	Device Type	deviceType field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_DEVICE_TYPE must be defined.
18	Hardware Version	hardwareVersion field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_HARDWARE_VERSION must be defined.
19	Software Version	softwareVersion field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_SOFTWARE_VERSION must be defined.
20	Battery Status	Set the flag IOWA_DEVICE_RSC_BATTERY in optFlags field of the structure `iowa_device_info_t`. Then use `iowa_client_device_update_battery` to control it. IOWA_DEVICE_SUPPORT_RSC_BATTERY must be defined.
21	Memory Total	memoryTotal field of the `iowa_device_info_t` structure. IOWA_DEVICE_SUPPORT_RSC_MEMORY_TOTAL must be defined.
22	ExtDevInfo	Set the flag IOWA_DEVICE_RSC_EXTERNAL_INFO in optFlags field of the structure `iowa_device_info_t` to enable it. Then use `iowa_client_update_device_external_information` to control it. IOWA_DEVICE_SUPPORT_RSC_EXTERNAL_INFO must be defined.

iowa_client_add_server

Prototype

iowa_status_t iowa_client_add_server(iowa_context_t contextP,
                                     uint16_t shortID,
                                     const char *uri,
                                     uint32_t lifetime,
                                     uint16_t configFlags,
                                     iowa_security_mode_t securityMode);

Description

iowa_client_add_server() declares a new LwM2M Server for the LwM2M Client to connect to.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime. The context MUST be configured with iowa_client_configure() to add a server.
shortID: The ID assigned to this server. This cannot be zero nor IOWA_LWM2M_ID_ALL nor an existing one.
uri: The URI to reach this server as a nil-terminated string e.g. "coaps://[::1]:5684", "coap://lwm2m.example.org:5683" or "sms://+331020304050".
lifetime: The lifetime in seconds of the registration to this server.
configFlags: A bit-mask of configuration flags for this LwM2M Server.
securityMode: The security mode to use when connecting to this LwM2M Server. See iowa_security_mode_t.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_400_BAD_REQUEST: uri is nil.
IOWA_COAP_403_FORBIDDEN: shortID is either zero, IOWA_LWM2M_ID_ALL or already in use.
IOWA_COAP_404_NOT_FOUND: client is not configured. Call first iowa_client_configure().
IOWA_COAP_406_NOT_ACCEPTABLE: uri is invalid. For example, if the transport is not supported or if uri does not match securityMode.
IOWA_COAP_500_INTERNAL_SERVER_ERROR: a memory allocation failed.

Header File

iowa_client.h

Notes

If lifetime is set to zero, the registration lifetime is set to a default value of:

30 days (2,592,000 seconds) for LoRaWAN transport
24 hours (86,400 seconds) for other transports (UDP, TCP, SMS ...)

uri is duplicated internally by IOWA and can be freed by the caller.

configFlags is a combination of the following:

IOWA_LWM2M_QUEUE_MODE: Enable LwM2M Queue Mode for this LwM2M Server.

Server Object Resources

The LwM2M Server information is exposed through the Resources of the Server Object (ID: 1). The following table explained the mapping:

Resource ID	Resource Name	API
0	Short Server ID	In `iowa_client_add_server`(), fill shortID.
1	Lifetime	In `iowa_client_add_server`(), fill lifetime.
2	Default Minimum Period	Use `iowa_client_set_notification_default_periods` to control it. IOWA_SERVER_SUPPORT_RSC_DEFAULT_PERIODS must be defined.
3	Default Maximum Period	Use `iowa_client_set_notification_default_periods` to control it. IOWA_SERVER_SUPPORT_RSC_DEFAULT_PERIODS must be defined.
4	Disable	IOWA_SERVER_SUPPORT_RSC_DISABLE_TIMEOUT must be defined.
5	Disable Timeout	By default it is 86400 seconds. To change this default value, use IOWA_SERVER_RSC_DISABLE_TIMEOUT_DEFAULT_VALUE. IOWA_SERVER_SUPPORT_RSC_DISABLE_TIMEOUT must be defined.
6	Notification Storing When Disabled or Offline	By default it is false. To change this default value, use IOWA_SERVER_RSC_STORING_DEFAULT_VALUE.
7	Binding	Determined with the uri passed to `iowa_client_add_server`().
8	Registration Update Trigger
9	Bootstrap-Request Trigger	IOWA_SERVER_SUPPORT_RSC_BOOTSTRAP_TRIGGER must be defined. Bootstrap feature is required.
10	APN Link	Not exposed by IOWA.
11	TLS-DTLS Alert Code	Not exposed by IOWA.
12	Last Bootstrapped	Not exposed by IOWA.
13	Registration Priority Order	IOWA_SERVER_SUPPORT_RSC_REGISTRATION_BEHAVIOUR must be defined. LwM2M version must be 1.1 or later.
14	Initial Registration Delay Timer	IOWA_SERVER_SUPPORT_RSC_REGISTRATION_BEHAVIOUR must be defined. LwM2M version must be 1.1 or later.
15	Registration Failure Block	IOWA_SERVER_SUPPORT_RSC_REGISTRATION_BEHAVIOUR must be defined. LwM2M version must be 1.1 or later.
16	Bootstrap on Registration Failure	IOWA_SERVER_SUPPORT_RSC_REGISTRATION_BEHAVIOUR must be defined. LwM2M version must be 1.1 or later.
17	Communication Retry Count	IOWA_SERVER_SUPPORT_RSC_COMMUNICATION_ATTEMPTS must be defined. LwM2M version must be 1.1 or later.
18	Communication Retry Timer	IOWA_SERVER_SUPPORT_RSC_COMMUNICATION_ATTEMPTS must be defined. LwM2M version must be 1.1 or later.
19	Communication Sequence Delay Timer	IOWA_SERVER_SUPPORT_RSC_COMMUNICATION_ATTEMPTS must be defined. LwM2M version must be 1.1 or later.
20	Communication Sequence Retry Count	IOWA_SERVER_SUPPORT_RSC_COMMUNICATION_ATTEMPTS must be defined. LwM2M version must be 1.1 or later.
21	Trigger	Not exposed by IOWA.
22	Preferred Transport	Not exposed by IOWA.
23	Mute Send	By default it is false. To change this default value, use IOWA_SERVER_RSC_MUTE_SEND_DEFAULT_VALUE. IOWA_SERVER_SUPPORT_RSC_MUTE_SEND must be defined. Data Push operation feature is required.

iowa_client_remove_server

Prototype

iowa_status_t iowa_client_remove_server(iowa_context_t contextP,
                                        uint16_t shortID);

Description

iowa_client_remove_server() removes a LwM2M Server added by iowa_client_add_server() from the LwM2M Client.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
shortID: The ID assigned to this server or IOWA_LWM2M_ID_ALL.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_403_FORBIDDEN: shortID is zero.
IOWA_COAP_404_NOT_FOUND: shortID does not match any known server.

Header File

iowa_client.h

iowa_client_get_server_count

Prototype

iowa_status_t iowa_client_get_server_count(iowa_context_t contextP,
                                           size_t *serversCountP);

Description

iowa_client_get_server_count() get the count of all configured LwM2M Servers.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
serversCountP: A pointer to the count of all configured LwM2M Servers.

Return Value

IOWA_COAP_NO_ERROR: success.

Header File

iowa_client.h

iowa_client_get_server_array

Prototype

iowa_status_t iowa_client_get_server_array(iowa_context_t contextP,
                                           size_t serversCount,
                                           iowa_server_info_t *serverArrayP);

Description

iowa_client_get_server_array() retrieves the configured LwM2M Servers with theirs associated information.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
serversCount: A pointer to the count of LwM2M Servers.
serverArrayP: An Array of iowa_server_info_t with a size equal to the count of the current configured LwM2M Servers.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_404_NOT_FOUND: No LwM2M Servers are configured in the Client.
IOWA_COAP_406_NOT_ACCEPTABLE: serverArrayP is nil.
IOWA_COAP_408_REQUEST_ENTITY_INCOMPLETE: The count of configured LwM2M servers has been changed since the call of iowa_client_get_server_count(). However, serverArrayP was filled with valid information.

Header File

iowa_client.h

Notes

To get the count of the current configured LwM2M Servers you need to call iowa_client_get_server_count().

iowa_client_get_server_coap_peer

Prototype

iowa_coap_peer_t * iowa_client_get_server_coap_peer(iowa_context_t contextP,
                                                    uint16_t shortId);

Description

iowa_client_get_server_coap_peer() returns the CoAP peer associated to a LwM2M Server.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
shortID: The ID assigned to the server.

Return Value

A pointer to the iowa_coap_peer_t associated to the LwM2M Server.

This pointer may be nil if shortId is invalid or if IOWA did not yet initiate the registration to the LwM2M Server.

Header File

iowa_client.h

iowa_client_set_notification_default_periods

Prototype

iowa_status_t iowa_client_set_notification_default_periods(iowa_context_t contextP,
                                                           uint16_t shortID,
                                                           uint32_t minPeriod,
                                                           uint32_t maxPeriod);

Description

iowa_client_set_notification_default_periods() configures the default periods for notifications sent to a LwM2M Server.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
shortID: The ID assigned to the server or IOWA_LWM2M_ID_ALL.
minPeriod: The default minimum time in seconds between two notifications sent to the LwM2M Server for the same observation.
maxPeriod: The default maximum time in seconds between two notifications sent to the LwM2M Server for the same observation.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_403_FORBIDDEN: shortID is zero.
IOWA_COAP_404_NOT_FOUND: shortID does not match any known server.

Header File

iowa_client.h

Notes

When IOWA_LWM2M_ID_ALL is used as shortID, only already known LwM2M Servers will have the default periods configured. If a LwM2M Server is added after the call to this API, by default it will not have default periods.

Setting the default periods does not affect already running observations.

A minimum period set to zero is equivalent to having no minimum period defined. Same for maximum period.

If maxPeriod is inferior to minPeriod, it is cleared (i.e. set to zero).

iowa_client_use_reliable_notifications

Prototype

iowa_status_t iowa_client_use_reliable_notifications(iowa_context_t contextP,
                                                     uint16_t shortId,
                                                     bool enable);

Description

iowa_client_use_reliable_notifications() configures the LwM2M Client to ensure that notifications are received by the LwM2M Server.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
shortId: The ID assigned to the server or IOWA_LWM2M_ID_ALL.
enable: If true, notifications will be reliable.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_403_FORBIDDEN: shortID is zero.
IOWA_COAP_404_NOT_FOUND: shortID does not match any known server.

Header File

iowa_client.h

Notes

When IOWA_LWM2M_ID_ALL is used as shortID, only already known LwM2M Servers will have reliable notifications. If a LwM2M Server is added after the call to this API, by default it will not use reliable notifications.

If enable is true:

on unreliable transports like UDP, the notifications are sent as Confirmable messages.
events IOWA_EVENT_OBSERVATION_NOTIFICATION_ACKED and IOWA_EVENT_OBSERVATION_NOTIFICATION_FAILED are emitted.
when storage queues are enabled, if a notification does not reach the LwM2M Server, IOWA stores it until the LwM2M Server is reachable again. See LWM2M_STORAGE_QUEUE_SUPPORT and LWM2M_STORAGE_QUEUE_PEEK_SUPPORT.

iowa_client_object_set_mode

Prototype

iowa_status_t iowa_client_object_set_mode(iowa_context_t contextP,
                                          iowa_sensor_t id,
                                          uint8_t mode);

Description

iowa_client_object_set_mode() sets the sensor mode.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
id: The ID of the sensor.
mode: Flags used to enable modes.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_404_NOT_FOUND: id does not match any known sensor.

Header File

iowa_client.h

Notes

To use this API, the compilation flag LWM2M_CLIENT_ASYNCHRONOUS_OPERATION_SUPPORT must be set.

To set the sensor mode, you can use the following flag:

IOWA_OBJECT_MODE_DEFAULT
IOWA_OBJECT_MODE_ASYNCHRONOUS

By default, sensors are synchronous.

A call to iowa_client_object_set_mode() affects all the sensors of the same type.

iowa_client_object_set_configuration

Prototype

iowa_status_t iowa_client_object_set_configuration(iowa_context_t contextP,
                                                   uint16_t objectId,
                                                   iowa_object_setting_id_t settingId,
                                                   void *argP);

Description

iowa_client_object_set_configuration() sets the object configuration.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
objectId: The ID of the object.
settingId: The setting to set. See iowa_object_setting_id_t.
argP: A pointer to the setting value. Dependent on settingId.

settingId	argP type
IOWA_OBJECT_SETTING_VERSION	iowa_object_version_t *

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_402_BAD_OPTION: settingId is unknown.
IOWA_COAP_404_NOT_FOUND: objectId does not match any known object.
IOWA_COAP_406_NOT_ACCEPTABLE: argP is nil.

Header File

iowa_client.h

iowa_client_device_update_battery

Prototype

iowa_status_t iowa_client_device_update_battery(iowa_context_t contextP,
                                                uint8_t batteryLevel,
                                                iowa_device_battery_status_t batteryStatus);

Description

iowa_client_device_update_battery() updates the battery level and status exposed in the Device Object.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
batteryLevel: The battery level in percent.
batteryStatus: The battery status.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_405_METHOD_NOT_ALLOWED: client has been configured without the flag IOWA_DEVICE_RSC_BATTERY in the iowa_device_info_t structure. To reconfigure the client, close than reopen a fresh IOWA Client context with iowa_close(), iowa_init() and iowa_client_configure().
IOWA_COAP_406_NOT_ACCEPTABLE: batteryLevel is outside the range [0, 100].
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().

Header File

iowa_client.h

Notes

For the device to expose its battery level and status, iowa_client_configure() must have been to called with the IOWA_DEVICE_RSC_BATTERY flag.

Before the first call to iowa_client_device_update_battery(), default value of batteryStatus is IOWA_DEVICE_BATTERY_STATUS_UNKNOWN.

When IOWA_REMOVE_ALL_OPTIONAL_RESOURCES is defined, iowa_client_device_update_battery() can only be called when IOWA is built with the flag IOWA_DEVICE_SUPPORT_RSC_BATTERY.

iowa_device_battery_status_t

This is an enumeration of the following values:

IOWA_DEVICE_BATTERY_STATUS_NORMAL: The battery is operating normally and not on power.
IOWA_DEVICE_BATTERY_STATUS_CHARGING: The battery is currently charging.
IOWA_DEVICE_BATTERY_STATUS_CHARGE_COMPLETE: The battery is fully charged and still on power.
IOWA_DEVICE_BATTERY_STATUS_DAMAGED: The battery has some problem.
IOWA_DEVICE_BATTERY_STATUS_LOW_BATTERY: The battery is low on charge.
IOWA_DEVICE_BATTERY_STATUS_NOT_INSTALLED: The battery is not installed.
IOWA_DEVICE_BATTERY_STATUS_UNKNOWN: The battery information is not available.

iowa_client_add_device_power_source

Prototype

iowa_status_t iowa_client_add_device_power_source(iowa_context_t context,
                                                  iowa_power_source_type_t type,
                                                  int voltageValue,
                                                  int currentValue,
                                                  iowa_sensor_t *idP);

Description

iowa_client_add_device_power_source() adds a power source to Device object with initial value of voltage and current.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
type: power source type.
voltageValue: initial voltage value (mV).
currentValue: initial current value (mA).
idP: Used to store the ID of the created power source. Not checked at runtime.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().
IOWA_COAP_405_METHOD_NOT_ALLOWED: client has been configured without the flag IOWA_DEVICE_RSC_POWER_SOURCE in the iowa_device_info_t structure. To reconfigure the client, close than reopen a fresh IOWA Client context with iowa_close(), iowa_init() and iowa_client_configure().
IOWA_COAP_500_INTERNAL_SERVER_ERROR: a memory allocation failed.

Header File

iowa_client.h

Notes

For the device to expose its power source information, iowa_client_configure() must have been to called with the IOWA_DEVICE_RSC_POWER_SOURCE flag.

To update a power source values, you need to call iowa_client_update_device_power_source().

To remove a power source, you need to call iowa_client_remove_device_power_source().

When IOWA_REMOVE_ALL_OPTIONAL_RESOURCES is defined, iowa_client_add_device_power_source() can only be called when IOWA is built with the flag IOWA_DEVICE_SUPPORT_RSC_POWER_SOURCE.

iowa_power_source_type_t

This is an enumeration of the following values:

IOWA_POWER_SOURCE_DC_POWER: DC power supply.
IOWA_POWER_SOURCE_INTERNAL_BATTERY: Internal battery.
IOWA_POWER_SOURCE_EXTERNAL_BATTERY: External battery.
IOWA_POWER_SOURCE_FUEL_CELL: Fuel Cell
IOWA_POWER_SOURCE_POWER_OVER_ETHERNET: Power Over Ethernet.
IOWA_POWER_SOURCE_USB: USB.
IOWA_POWER_SOURCE_AC_MAIN_POWER: AC power supply.
IOWA_POWER_SOURCE_SOLAR: Solar energy.

iowa_client_remove_device_power_source

Prototype

iowa_status_t iowa_client_remove_device_power_source(iowa_context_t context,
                                                     iowa_sensor_t id);

Description

iowa_client_remove_device_power_source() removes a power source from the Device object.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
id: ID of the power source to remove.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().
IOWA_COAP_404_NOT_FOUND: id is not a device's power source. Valid id are only returned by iowa_client_add_device_power_source().
IOWA_COAP_405_METHOD_NOT_ALLOWED: client has been configured without the flag IOWA_DEVICE_RSC_POWER_SOURCE in the iowa_device_info_t structure. To reconfigure the client, close than reopen a fresh IOWA Client context with iowa_close(), iowa_init() and iowa_client_configure().
IOWA_COAP_500_INTERNAL_SERVER_ERROR: a memory allocation failed.

Header File

iowa_client.h

Notes

For the device to expose its power source information, iowa_client_configure() must have been to called with the IOWA_DEVICE_RSC_POWER_SOURCE flag.

When IOWA_REMOVE_ALL_OPTIONAL_RESOURCES is defined, iowa_client_remove_device_power_source() can only be called when IOWA is built with the flag IOWA_DEVICE_SUPPORT_RSC_POWER_SOURCE.

iowa_client_update_device_power_source

Prototype

iowa_status_t iowa_client_update_device_power_source(iowa_context_t context,
                                                     iowa_sensor_t id,
                                                     int voltageValue,
                                                     int currentValue);

Description

iowa_client_update_device_power_source() updates a power source values to Device object.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
id: ID of the power source.
voltageValue: new voltage value (mV).
currentValue: new current value (mA).

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().
IOWA_COAP_404_NOT_FOUND: id is not a device's power source. Valid id are only returned by iowa_client_add_device_power_source().
IOWA_COAP_405_METHOD_NOT_ALLOWED: client has been configured without the flag IOWA_DEVICE_RSC_POWER_SOURCE in the iowa_device_info_t structure. To reconfigure the client, close than reopen a fresh IOWA Client context with iowa_close(), iowa_init() and iowa_client_configure().

Header File

iowa_client.h

Notes

For the device to expose its power source information, iowa_client_configure() must have been to called with the IOWA_DEVICE_RSC_POWER_SOURCE flag.

When IOWA_REMOVE_ALL_OPTIONAL_RESOURCES is defined, iowa_client_update_device_power_source() can only be called when IOWA is built with the flag IOWA_DEVICE_SUPPORT_RSC_POWER_SOURCE.

iowa_client_update_device_information

Prototype

iowa_status_t iowa_client_update_device_information(iowa_context_t contextP,
                                                    iowa_device_info_t *deviceInfoP);

Description

iowa_client_update_device_information() updates the device information.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
deviceInfoP: pointer to the new device's information.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_400_BAD_REQUEST: deviceInfoP is nil.
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().

Header File

iowa_client.h

Notes

This function update only the supported device resources that has been set previously in iowa_client_configure().

The parameters that can be updated are :

Manufacturer.
Model number.
Serial number.
Firmware version.
Device type.
Hardware version.
Software version.
Free memory when the flag IOWA_DEVICE_RSC_MEMORY_FREE in optFlags field is set.
Total memory.

Nil values in deviceInfoP will be ignored and won't make any changes except for the free memory.

iowa_client_set_device_error_code

Prototype

iowa_status_t iowa_client_set_device_error_code(iowa_context_t context,
                                                uint8_t errorCode);

Description

iowa_client_set_device_error_code() sets an error code on Device object.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
errorCode: The error code value to set between 1 and 32.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().
IOWA_COAP_402_BAD_OPTION: errorCode is not a valid parameter.
IOWA_COAP_404_NOT_FOUND: errorCode is IOWA_ERROR_CODE_NO_ERROR but there is no error to clear.
IOWA_COAP_409_CONFLICT: errorCode has already been set.

Header File

iowa_client.h

Notes

To clear one error code, you need to call iowa_client_clear_device_error_code().

To clear all error codes, you can call iowa_client_set_device_error_code() with errorCode argument set to IOWA_ERROR_CODE_NO_ERROR.

The error code is an integer between 1 and 32. The LwM2M protocol defines eight values between 1 and 8 detailed below. Values between 9 and 15 are reserved for future use. The device maker or the application can use the values between 16 and 32 as proprietary error codes.

LwM2M defined error code values are:

IOWA_ERROR_CODE_NO_ERROR

No error.
IOWA_ERROR_CODE_LOW_BATTERY_POWER (1)

Low battery power.
IOWA_ERROR_CODE_EXTERNAL_POWER_SUPPLY_OFF (2)

External power supply off.
IOWA_ERROR_CODE_GPS_MODULE_FAILURE (3)

GPS module failure.
IOWA_ERROR_CODE_LOW_RECEIVED_SIGNAL_STRENGTH (4)

Low received signal strength.
IOWA_ERROR_CODE_OUT_OF_MEMORY (5)

Out of memory.
IOWA_ERROR_CODE_SMS_FAILURE (6)

SMS failure.
IOWA_ERROR_CODE_IP_CONNECTIVITY_FAILURE (7)

IP connectivity failure.
IOWA_ERROR_CODE_PERIPHERAL_MALFUNCTION (8)

Peripheral malfunction.

iowa_client_clear_device_error_code

Prototype

iowa_status_t iowa_client_clear_device_error_code(iowa_context_t context,
                                                  uint8_t errorCode);

Description

iowa_client_clear_device_error_code() clears an error code from the Device object.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
errorCode: The error code to clear between 1 and 32. It can't be IOWA_ERROR_CODE_NO_ERROR.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().
IOWA_COAP_402_BAD_OPTION: The error code IOWA_ERROR_CODE_NO_ERROR can't be cleared.
IOWA_COAP_404_NOT_FOUND: The error code is not set.

Header File

iowa_client.h

Notes

LwM2M defined error code values are enumerated in iowa_client_set_device_error_code().

iowa_client_update_device_time_information

Prototype

iowa_status_t iowa_client_update_device_time_information(iowa_context_t contextP,
                                                         iowa_device_time_info_t *timeInfoP);

Description

iowa_client_update_device_time_information() updates time information to Device object.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
timeInfoP: Current device time information: iowa_device_time_info_t.

Return Value

IOWA_COAP_NO_ERROR

success.

IOWA_COAP_406_NOT_ACCEPTABLE

either:

timeInfoP is nil.

currentTime in timeInfoP is set with a negative value.

IOWA_COAP_412_PRECONDITION_FAILED

client is not configured. Call first iowa_client_configure().

Header File

iowa_client.h

Notes

For the device to expose its time information, iowa_client_configure() must have been to called with time information used.

iowa_client_update_device_time_information() can only be called when IOWA is built with at least one of the following flag: * IOWA_DEVICE_SUPPORT_RSC_CURRENT_TIME * IOWA_DEVICE_SUPPORT_RSC_UTC_OFFSET * IOWA_DEVICE_SUPPORT_RSC_TIMEZONE

iowa_client_update_device_external_information

Prototype

iowa_status_t iowa_client_update_device_external_information(iowa_context_t contextP,
                                                             size_t extLinkCount,
                                                             iowa_lwm2m_object_link_t *extLinkArray);

Description

iowa_client_update_device_external_information() updates the external device information exposed in the Device object.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
extLinkCount: The number of links in extLinkArray.
extLinkArray: An array of object links referencing object instance containing "external device" information.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_406_NOT_ACCEPTABLE: extLinkArray is nil while extLinkCount is not 0.
IOWA_COAP_412_PRECONDITION_FAILED: client is not configured. Call first iowa_client_configure().
IOWA_COAP_500_INTERNAL_SERVER_ERROR: a memory allocation failed.

Header File

iowa_client.h

Notes

The Resource "ExtDevInfo" must have been enabled by setting the optional flag IOWA_DEVICE_RSC_EXTERNAL_INFO when calling iowa_client_configure().

The field version in the iowa_lwm2m_object_link_t structure is ignored.

When IOWA_REMOVE_ALL_OPTIONAL_RESOURCES is defined, iowa_client_update_device_external_information() can only be called when IOWA is built with the flag IOWA_DEVICE_SUPPORT_RSC_EXTERNAL_INFO.

iowa_client_add_custom_object

Prototype

iowa_status_t iowa_client_add_custom_object(iowa_context_t contextP,
                                            uint16_t objectID,
                                            size_t instanceCount,
                                            uint16_t * instanceIDs,
                                            size_t resourceCount,
                                            iowa_lwm2m_resource_desc_t * resourceArray,
                                            iowa_RWE_callback_t dataCallback,
                                            iowa_CD_callback_t instanceCallback,
                                            iowa_RI_callback_t resInstanceCallback,
                                            void * userData);

Description

iowa_client_add_custom_object() adds a new custom Object for the LwM2M Client to handle. The object is defined by its ID and a the list of the resources it contains.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
objectID: The ID of the Object.
instanceCount: The number of elements in instanceIDs. This can be 0.
instanceIDs: The IDs of the instances of the Object. This can be nil.
resourceCount: The number of elements in resourceArray.
resourceArray: An array of iowa_lwm2m_resource_desc_t composing the Object.
dataCallback: The callback to perform Read, Write and Execute operations on the resources.
instanceCallback: The callback to perform Create and Delete operations on Object instances. This can be nil.
resInstanceCallback: The callback to retrieve the list of instances of resources declared as multiple. This can be nil.
userData: Passed as argument to the callbacks.

Return Value

IOWA_COAP_NO_ERROR

success.

IOWA_COAP_500_INTERNAL_SERVER_ERROR

a memory allocation failed.

IOWA_COAP_403_FORBIDDEN

objectID is 0, 1 or 3 which are reserved Object IDs.

IOWA_COAP_406_NOT_ACCEPTABLE

either:

objectID is IOWA_LWM2M_ID_ALL (65535).

resourceCount is zero.

resourceArray is nil.

dataCallback is nil.

instanceIDs is nil and instanceCount is not zero.

resInstanceCallback is nil and one of the resources in resourceArray has the IOWA_RESOURCE_FLAG_MULTIPLE flag set.

an instance ID is IOWA_LWM2M_ID_ALL.

a resource ID is IOWA_LWM2M_ID_ALL.

a resource has no operation defined.

a resource is both set as streamable and asynchronous.

a resource is set as executable with another operation.

two resources have the same ID.

IOWA_COAP_409_CONFLICT

this object already exists. Call first iowa_client_remove_custom_object().

Header File

iowa_client.h

Notes

Object IDs 0, 1 and 3 are reserved and cannot be used.

Per Lightweight M2M specification, the ID of the instance of a single-instance Object is 0. When creating a single-instance Object, you can set instanceCount to zero and instanceCallback to nil. IOWA will automatically create an instance with ID 0.

When the LwM2M Server creates a new instance of the custom object, instanceCallback is first called with the new instance ID then dataCallback is called with operation set to IOWA_DM_WRITE to initialize the instance. Thus if instanceCallback is defined, dataCallback must handle the Write operation even on resources declared as read-only.

iowa_client_remove_custom_object

Prototype

iowa_status_t iowa_client_remove_custom_object(iowa_context_t contextP,
                                               uint16_t objectID);

Description

iowa_client_remove_custom_object() removes a custom Object created with iowa_client_add_custom_object().

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
objectID: The ID of the Object.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_403_FORBIDDEN: objectID is 0, 1 or 3 which are reserved Object IDs.
IOWA_COAP_404_NOT_FOUND: objectID does not match any known object.
IOWA_COAP_406_NOT_ACCEPTABLE: objectID is IOWA_LWM2M_ID_ALL (65535).

Notes

This API does not check if the LwM2M Object was added by calling iowa_client_add_custom_object() or by calling another high-level API like iowa_client_IPSO_add_sensor().

Header File

iowa_client.h

iowa_client_object_resource_changed

Prototype

iowa_status_t iowa_client_object_resource_changed(iowa_context_t contextP,
                                                  uint16_t objectID,
                                                  uint16_t instanceID,
                                                  uint16_t resourceID);

Description

iowa_client_object_resource_changed() informs the IOWA stack that the value of a LwM2M Object resource changed.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
objectID: The ID of the Object containing the resource.
instanceID: The ID of the Instance containing the resource. This can be IOWA_LWM2M_ID_ALL.
resourceID: The ID of the resource. This can be IOWA_LWM2M_ID_ALL.

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_403_FORBIDDEN: objectID is 0, 1 or 3 which are reserved Object IDs.
IOWA_COAP_406_NOT_ACCEPTABLE: objectID is IOWA_LWM2M_ID_ALL (65535).

Header File

iowa_client.h

Notes

This API does not check if the LwM2M Object resource exists. That's why this API does not return IOWA_COAP_404_NOT_FOUND. Actually, iowa_client_object_resource_changed() is only searching a match between the running observation and the URI provided. If a match is found a notification is sent, else nothing happens.

iowa_client_object_instance_changed

Prototype

iowa_status_t iowa_client_object_instance_changed(iowa_context_t contextP,
                                                  uint16_t objectID,
                                                  uint16_t instanceID,
                                                  iowa_dm_operation_t operation);

Description

iowa_client_object_instance_changed() informs the IOWA stack that an instance of a LwM2M Object was created or deleted.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
objectID: The ID of the Object containing the instance.
instanceID: The ID of the created or deleted Instance.
operation: IOWA_DM_CREATE if it is a new instance. IOWA_DM_DELETE if the instance was removed.

Return Value

IOWA_COAP_NO_ERROR

success.

IOWA_COAP_500_INTERNAL_SERVER_ERROR

a memory allocation failed.

IOWA_COAP_403_FORBIDDEN

objectID is 0, 1 or 3 which are reserved Object IDs.

IOWA_COAP_404_NOT_FOUND

either:

objectID does not match any known object.

operation is IOWA_DM_DELETE and instanceID does not match any known instance.

IOWA_COAP_405_METHOD_NOT_ALLOWED

operation is neither IOWA_DM_CREATE nor IOWA_DM_DELETE.

IOWA_COAP_406_NOT_ACCEPTABLE

either:

objectID is IOWA_LWM2M_ID_ALL (65535).

operation is IOWA_DM_CREATE and instanceID was already present.

Header File

iowa_client.h

iowa_client_notification_lock

Prototype

void iowa_client_notification_lock(iowa_context_t contextP,
                                   bool enter);

Description

iowa_client_notification_lock() prevents or allows the IOWA stack to send notifications and registration updates.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
enter: true to stop the notification, false to resume the notification.

Return Value

None.

Header File

iowa_client.h

Notes

The main use is to perform several calls to iowa_client_object_resource_changed() on an Object without generating a notification each time if the Object is under observation.

Registration updates are also blocked, allowing to add or remove several Objects or Object Instances.

This function is useful only if IOWA is built with the IOWA_MULTITHREAD_SUPPORT flag. Inside a custom object callback, notifications are already disabled.

iowa_client_send_heartbeat

Prototype

iowa_status_t iowa_client_send_heartbeat(iowa_context_t contextP,
                                         uint16_t shortID);

Description

iowa_client_send_heartbeat() sends an heartbeat message to a server.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
shortID: The Short ID assigned to this Server. Can be equal to IOWA_LWM2M_ID_ALL.

Return Value

IOWA_COAP_NO_ERROR

success.

IOWA_COAP_403_FORBIDDEN

shortID is zero.

IOWA_COAP_404_NOT_FOUND

shortID does not match any known server.

IOWA_COAP_412_PRECONDITION_FAILED

client is not connected to the server with shortID. This can happen when:

The Server is a Bootstrap Server and the Client is already connect to a Server.

The Client is configured with more than one Server and has established the connection with only one.

IOWA_COAP_500_INTERNAL_SERVER_ERROR

a memory allocation failed.

IOWA_COAP_503_SERVICE_UNAVAILABLE

heartbeat message has not been sent by the platform.

Header File

iowa_client.h

Notes

If shortID is equal to IOWA_LWM2M_ID_ALL, the heartbeat message will be sent to all servers.

For non LoRaWAN Servers, a registration update message is sent to the Server. The iowa_event_callback_t will be called with a IOWA_EVENT_REG_UPDATING event. Then, if a reply is received from the Server, the iowa_event_callback_t will be called with either a IOWA_EVENT_REG_REGISTERED or IOWA_EVENT_REG_FAILED event. Nothing is done when no reply is received from the Server.

In the IOWA_EVENT_REG_REGISTERED case, the registration lifetime timer for the LwM2M Server is resetted.

IPSO Objects

This part allows the possibility to manipulate several IPSO Objects.

To be able to use these objects, iowa_ipso.h must be included.

iowa_client_IPSO_add_sensor

Prototype

iowa_status_t iowa_client_IPSO_add_sensor(iowa_context_t contextP,
                                          iowa_IPSO_ID_t type,
                                          float value,
                                          const char * unit,
                                          const char * appType,
                                          float rangeMin, float rangeMax,
                                          iowa_sensor_t * idP);

Description

iowa_client_IPSO_add_sensor() adds a new IPSO sensor for the LwM2M Client to handle. The sensor is defined by its type.

The unit, the application type and the range are only informative and reported as-is to the LwM2M Server. Note that the LwM2M Server can modify the application type.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
type: The type of sensor. See below.
value: The initial value measured by the sensor.
unit: The unit of the measured value as a nil-terminated string. This can be nil.
appType: The application type of the sensor as a free-form nil-terminated string. This can be nil.
rangeMin: The minimum value that can be measured by the sensor.
rangeMax: The maximum value that can be measured by the sensor.
idP: Used to store the ID of the created sensor. Not checked at runtime.

Return Value

IOWA_COAP_NO_ERROR

success.

IOWA_COAP_402_BAD_OPTION

type is unknown.

IOWA_COAP_406_NOT_ACCEPTABLE

either:

the sensor uses a Boolean value and value is neither 0.0 nor 1.0.

the sensor uses a percentage value and value is outside the [0.0, 100.0] range.

the sensor uses a compass direction value and value is outside the [0.0, 360.0] range.

IOWA_COAP_500_INTERNAL_SERVER_ERROR

a memory allocation or a call to iowa_system_gettime() failed.

Header File

objects/iowa_ipso.h

Notes

If both rangeMin and rangeMax are set to zero, the matching resources are ignored in the LwM2M Object.

unit is not duplicated nor freed by IOWA. Make sure it is available until iowa_close() or iowa_client_IPSO_remove_sensor() is called. It is advised to use static strings.

appType is duplicated internally by IOWA and can be reused or freed by the caller.

Only a call to iowa_client_IPSO_remove_sensor() can free the memory allocated by iowa_client_IPSO_add_sensor().

iowa_IPSO_ID_t

This is an enumeration of the LwM2M IDs of the supported sensor types. See below.

Float value sensors

IOWA_IPSO_ANALOG_INPUT (3202)
IOWA_IPSO_GENERIC (3300)
IOWA_IPSO_ILLUMINANCE (3301)
IOWA_IPSO_TEMPERATURE (3303)
IOWA_IPSO_HUMIDITY (3304)
IOWA_IPSO_BAROMETER (3315)
IOWA_IPSO_VOLTAGE (3316)
IOWA_IPSO_CURRENT (3317)
IOWA_IPSO_FREQUENCY (3318)
IOWA_IPSO_DEPTH (3319)
IOWA_IPSO_PERCENTAGE (3320)
IOWA_IPSO_ALTITUDE (3321)
IOWA_IPSO_LOAD (3322)
IOWA_IPSO_PRESSURE (3323)
IOWA_IPSO_LOUDNESS (3324)
IOWA_IPSO_CONCENTRATION (3325)
IOWA_IPSO_ACIDITY (3326)
IOWA_IPSO_CONDUCTIVITY (3327)
IOWA_IPSO_POWER (3328)
IOWA_IPSO_POWER_FACTOR (3329)
IOWA_IPSO_RATE (3346)
IOWA_IPSO_DISTANCE (3330)
IOWA_IPSO_ENERGY (3331)

Boolean value sensors

For these sensors, the value must be either 0.0 or 1.0:

IOWA_IPSO_DIGITAL_INPUT (3200)
IOWA_IPSO_PRESENCE (3302)
IOWA_IPSO_ON_OFF_SWITCH (3342)
IOWA_IPSO_PUSH_BUTTON (3347)

Compass direction value sensors

For these sensors, the value must be between 0.0 and 360.0:

IOWA_IPSO_DIRECTION (3332)

Notes

The enumeration value IOWA_IPSO_LEVEL_CONTROL no longer exists.

The Dimmer APIs is now responsible of adding, removing and updating percentage sensors, by using the following functions:

iowa_client_add_dimmer_object(): to add a new dimmer sensor.
iowa_client_remove_dimmer_object(): to remove a dimmer sensor.
iowa_client_dimmer_update_value(): to update the dimmer's level value.
iowa_client_dimmer_update_values(): to update the dimmer's multiple level values.

iowa_client_IPSO_update_value

Prototype

iowa_status_t iowa_client_IPSO_update_value(iowa_context_t contextP,
                                            iowa_sensor_t id,
                                            float value);

Description

iowa_client_IPSO_update_value() updates the value of an IPSO sensor.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
id: The ID of the sensor as returned by iowa_client_IPSO_add_sensor().
value: The new value measured by the sensor.

Return Value

IOWA_COAP_NO_ERROR

success.

IOWA_COAP_404_NOT_FOUND

id does not match any known sensor.

IOWA_COAP_406_NOT_ACCEPTABLE

either:

the sensor uses a Boolean value and value is neither 0.0 nor 1.0.

the sensor uses a percentage value and value is outside the [0.0, 100.0] range.

the sensor uses a compass direction value and value is outside the [0.0, 360.0] range.

IOWA_COAP_500_INTERNAL_SERVER_ERROR

a memory allocation or a call to iowa_system_gettime() failed.

Header File

objects/iowa_ipso.h

iowa_client_IPSO_update_values

Prototype

iowa_status_t iowa_client_IPSO_update_values(iowa_context_t contextP,
                                             iowa_sensor_t id,
                                             size_t valueCount,
                                             iowa_ipso_timed_value_t *valueArray);

Description

iowa_client_IPSO_update_values() updates multiple times the value of an IPSO Object sensor.

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
id: The ID of the sensor as returned by iowa_client_IPSO_add_sensor().
valueCount: The number of values in valueArray.
valueArray: The iowa_ipso_timed_value_t list of new values.

Return Value

IOWA_COAP_NO_ERROR

success.

IOWA_COAP_404_NOT_FOUND

id does not match any known sensor.

IOWA_COAP_406_NOT_ACCEPTABLE

either:

one of the timestamped value has an negative value.

the sensor uses a Boolean value and value is neither 0.0 nor 1.0.

the sensor uses a percentage value and value is outside the [0.0, 100.0] range.

the sensor uses a compass direction value and value is outside the [0.0, 360.0] range.

IOWA_COAP_500_INTERNAL_SERVER_ERROR

a memory allocation or a call to iowa_system_gettime() failed.

Header File

objects/iowa_ipso.h

Notes

iowa_client_IPSO_update_values() can only be used when the define LWM2M_SUPPORT_TIMESTAMP is set.

The timestamp must be absolute and not relative to the current time, meaning negative values are not accepted. If the timestamp is equal to zero, it is ignored.

Calling iowa_client_IPSO_update_values() will overwrite the previous values list. This has multiple consequences:

If the values have not been sent to the Server, the previous values are lost. Values are only sent if the Server do a Read operation or if the Server has set an Observation.
If the values are in the way to be sent to the Server and iowa_client_IPSO_update_values() is called during the process, some old values will be lost. This API is trying to send the values in best effort. Recent timestamped values are processed in priority before the oldest ones.

Timestamp information is only present if the used Content Format is:

iowa_client_IPSO_remove_sensor

Prototype

iowa_status_t iowa_client_IPSO_remove_sensor(iowa_context_t contextP,
                                             iowa_sensor_t id);

Description

iowa_client_IPSO_remove_sensor() removes from the LwM2M Client an IPSO sensor created with iowa_client_IPSO_add_sensor().

Arguments

contextP: An iowa_context_t as returned by iowa_init(). Not checked at runtime.
id: The ID of the sensor as returned by iowa_client_IPSO_add_sensor().

Return Value

IOWA_COAP_NO_ERROR: success.
IOWA_COAP_402_BAD_OPTION: id is not an IPSO sensor. Valid id are only returned by iowa_client_IPSO_add_sensor().
IOWA_COAP_404_NOT_FOUND: IPSO referred by id does not exist.

Header File

objects/iowa_ipso.h