IOWA Reference

https://ioterop.github.io/IOWA/
Admin
IOWA is an open-source LwM2M client and server implementation, providing a robust framework for IoT...
Tokens:174,004
Snippets:664
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### IOWA Client Initialization and Main Loop Example

Source: https://ioterop.github.io/IOWA/ClientAPI

Demonstrates the basic setup and operation of an IOWA client. It covers initialization, device configuration, adding an IPSO sensor, updating its value in a loop, and cleanup. Requires 'iowa_client.h' and 'iowa_ipso.h'.

```c
#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;
}

```

--------------------------------

### Basic FreeRTOS Project Setup

Source: https://ioterop.github.io/IOWA/Porting

A minimal FreeRTOS project structure that includes necessary headers, starts the scheduler, and enters an infinite loop. This serves as the entry point for an embedded application using FreeRTOS.

```C
#include "FreeRTOS.h"
#include "task.h"
#include "semphr.h"

#define INFINITE_LOOP() while (1);

int main(void)
{
    // Start the scheduler
    vTaskStartScheduler();

    // We should never get here as control is now taken by the scheduler
    INFINITE_LOOP();
}
```

--------------------------------

### IOWA and System Task Setup (C)

Source: https://ioterop.github.io/IOWA/Porting

Demonstrates the creation and configuration of IOWA and system tasks using FreeRTOS. It includes semaphore synchronization, IOWA client initialization, sensor setup, and value updates.

```c
typedef struct
{
    SemaphoreHandle_t initMutex;
    iowa_context_t contextP;
    iowa_sensor_t tempSensorId;
} iowa_user_data_t;

void iowa_task(void const* argument)
{
    // Task dedicated for IOWA operations
    iowa_user_data_t *iowaUserDataP;
    platform_user_data_t platformUserData;
    iowa_status_t result;

    initPlatform(&platformUserData);

    iowaUserDataP = (iowa_user_data_t *)argument;

    // Initialize the IOWA context
    iowaUserDataP->contextP = iowa_init(platformUserData);
    if (iowaUserDataP->contextP == NULL)
    {
        INFINITE_LOOP();
    }

    // Initialize the Client context
    result = iowa_client_configure(iowaUserDataP->contextP, "IOWA_Client_FreeRTOS", NULL, NULL);
    if (result != IOWA_COAP_NO_ERROR)
    {
        INFINITE_LOOP();
    }

    // Add a server
    result = iowa_client_add_server(iowaUserDataP->contextP, 1234, "coap://127.0.0.1:5683", 3600, 0, IOWA_SEC_NONE);
    if (result != IOWA_COAP_NO_ERROR)
    {
        INFINITE_LOOP();
    }

    // Add a sensor object
    result = iowa_client_IPSO_add_sensor(iowaUserDataP->contextP, IOWA_IPSO_TEMPERATURE, 24, "Cel", NULL, -20.0, 50.0, &(iowaUserDataP->tempSensorId));
    if (result != IOWA_COAP_NO_ERROR)
    {
        INFINITE_LOOP();
    }

    xSemaphoreGive(iowaUserData->initMutex); // Synchronization

    // Start the IOWA step
    (void)iowa_step(iowaUserDataP->contextP, -1);

    // We should never get here as control is now taken by IOWA
    INFINITE_LOOP();
}

void system_task(void const* argument)
{
    // Task dedicated for system operations
    iowa_user_data_t *iowaUserDataP;

    iowaUserDataP = (iowa_user_data_t *)argument;

    xSemaphoreTake(iowaUserData->initMutex, portMAX_DELAY); // Synchronization

    while (1)
    {
        float newValue;

        newValue = GET_TEMPERATURE_VALUE();

        (void)iowa_client_IPSO_update_value(iowaUserDataP->contextP, iowaUserDataP->tempSensorId, newValue);

        vTaskDelay(5000);
    }
}

int main(void)
{
    iowa_user_data_t iowaUserData;

    // Create the init semaphore
    iowaUserData->initMutex = xSemaphoreCreateMutex();

    // Create the tasks for IOWA
    xTaskCreate((TaskFunction_t)iowa_task, "iowa", 512, &iowaUserData, tskIDLE_PRIORITY+2, NULL);
    xTaskCreate((TaskFunction_t)system_task, "system", 256, &iowaUserData, tskIDLE_PRIORITY+1, NULL);

    // Start the scheduler
    vTaskStartScheduler();

    // We should never get here as control is now taken by the scheduler
    while (1); // Infinite loop
}

```

--------------------------------

### IOWA SDK Initialization and Main Loop Example

Source: https://ioterop.github.io/IOWA/print_page

Demonstrates the basic structure for initializing the IOWA context, entering a main loop to process network events, and properly closing the context. This is a fundamental example for any IOWA application.

```c
#include "iowa.h"

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

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

    iowaH = iowa_init(NULL);

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

    do
    {
        result = iowa_step(iowaH, 5);
    } while (result == IOWA_COAP_NO_ERROR)

    iowa_close(iowaH);

    return 0;
}
```

--------------------------------

### FreeRTOS Main Task Setup with IOWA

Source: https://ioterop.github.io/IOWA/print_page

This snippet demonstrates the essential FreeRTOS setup for an IOWA application. It includes the necessary headers, defines an infinite loop for the main task, and starts the FreeRTOS scheduler. The scheduler takes control, so the infinite loop should ideally never be reached.

```c
#include "FreeRTOS.h"
#include "task.h"
#include "semphr.h"

#define INFINITE_LOOP() while (1);

int main(void)
{
    // Start the scheduler
    vTaskStartScheduler();

    // We should never get here as control is now taken by the scheduler
    INFINITE_LOOP();
}
```

--------------------------------

### IOWA Client Initialization and Main Loop Example

Source: https://ioterop.github.io/IOWA/print_page

Demonstrates the typical workflow for initializing the IOWA client, configuring device information, adding sensors and servers, and running the main event loop to process IOWA operations and update sensor values.

```c
#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;
}

```

--------------------------------

### CMake Configuration for IOWA Build

Source: https://ioterop.github.io/IOWA/Building

Example of launching CMake to configure the build process for IOWA samples. It specifies the build type as 'Debug' and points to the root directory containing the CMakeLists.txt file.

```cmake
cmake -DCMAKE_BUILD_TYPE=Debug ..
```

--------------------------------

### Example Security Credentials for tinydtls Client

Source: https://ioterop.github.io/IOWA/secure_client_tinydtls

An example illustrating the format for providing a simple string identity and a byte array value for the Pre-Shared Key in the tinydtls secure client.

```c
uint8_t keyIdentity[] = { 't', 'e', 's', 't' };
uint8_t keyValue[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };
```

--------------------------------

### Server-Side Provisioning Guide (CONNECTicut)

Source: https://ioterop.github.io/IOWA/print_page

Instructions for provisioning a client on IoTerop's CONNECTicut platform using Pre-Shared Key security. This involves entering the client name, PSK identity, and PSK secret (base64 encoded).

```text
On IoTerop's [CONNECTicut](https://iowa-server.ioterop.com/), click on the "Configuration" tab, then on the "Add new client configuration" button.

In the "Client name" field, enter the client name you chose.

In the "Security mode" drop-down list, select **Pre-Shared Key**.

In the "PSK Identity" field, enter the key identity you chose.

In the "PSK Secret" field, enter the key you chose **encoded in base64**.

Then click on the "Validate" button.
```

--------------------------------

### Linked List Macro Usage Example

Source: https://ioterop.github.io/IOWA/print_page

Shows how to use macros for common linked list operations, providing a cleaner alternative to direct function calls.

```c
// Instead of calling:
// listHead = (struct myData *)iowa_utils_list_add((iowa_list_t *)listHead, (iowa_list_t *)newDataP);

// You can use:
// listHead = (struct myData *)IOWA_UTILS_LIST_ADD(listHead, newDataP);
```

--------------------------------

### IOWA Task and System Task Setup

Source: https://ioterop.github.io/IOWA/print_page

Demonstrates the creation and configuration of two FreeRTOS tasks: one for IOWA operations and another for system-level sensor updates. Includes semaphore synchronization for initialization.

```c
typedef struct {
    SemaphoreHandle_t initMutex;
    iowa_context_t contextP;
    iowa_sensor_t tempSensorId;
} iowa_user_data_t;

void iowa_task(void const* argument)
{
    // Task dedicated for IOWA operations
    iowa_user_data_t *iowaUserDataP;
    platform_user_data_t platformUserData;
    iowa_status_t result;

    initPlatform(&platformUserData);

    iowaUserDataP = (iowa_user_data_t *)argument;

    // Initialize the IOWA context
    iowaUserDataP->contextP = iowa_init(platformUserData);
    if (iowaUserDataP->contextP == NULL)
    {
        INFINITE_LOOP();
    }

    // Initialize the Client context
    result = iowa_client_configure(iowaUserDataP->contextP, "IOWA_Client_FreeRTOS", NULL, NULL);
    if (result != IOWA_COAP_NO_ERROR)
    {
        INFINITE_LOOP();
    }

    // Add a server
    result = iowa_client_add_server(iowaUserDataP->contextP, 1234, "coap://127.0.0.1:5683", 3600, 0, IOWA_SEC_NONE);
    if (result != IOWA_COAP_NO_ERROR)
    {
        INFINITE_LOOP();
    }

    // Add a sensor object
    result = iowa_client_IPSO_add_sensor(iowaUserDataP->contextP, IOWA_IPSO_TEMPERATURE, 24, "Cel", NULL, -20.0, 50.0, &(iowaUserDataP->tempSensorId));
    if (result != IOWA_COAP_NO_ERROR)
    {
        INFINITE_LOOP();
    }

    xSemaphoreGive(iowaUserData->initMutex); // Synchronization

    // Start the IOWA step
    (void)iowa_step(iowaUserDataP->contextP, -1);

    // We should never get here as control is now taken by IOWA
    INFINITE_LOOP();
}

void system_task(void const* argument)
{
    // Task dedicated for system operations
    iowa_user_data_t *iowaUserDataP;

    iowaUserDataP = (iowa_user_data_t *)argument;

    xSemaphoreTake(iowaUserData->initMutex, portMAX_DELAY); // Synchronization

    while (1)
    {
        float newValue;

        newValue = GET_TEMPERATURE_VALUE();

        (void)iowa_client_IPSO_update_value(iowaUserDataP->contextP, iowaUserDataP->tempSensorId, newValue);

        vTaskDelay(5000);
    }
}

int main(void)
{
    iowa_user_data_t iowaUserData;

    // Create the init semaphore
    iowaUserData->initMutex = xSemaphoreCreateMutex();

    // Create the tasks for IOWA
    xTaskCreate((TaskFunction_t)iowa_task, "iowa", 512, &iowaUserData, tskIDLE_PRIORITY+2, NULL);
    xTaskCreate((TaskFunction_t)system_task, "system", 256, &iowaUserData, tskIDLE_PRIORITY+1, NULL);

    // Start the scheduler
    vTaskStartScheduler();

    // We should never get here as control is now taken by the scheduler
    while (1); // Infinite loop
}

```

--------------------------------

### Linked List Data Structure Example

Source: https://ioterop.github.io/IOWA/print_page

Demonstrates the structure of a linked list node and variable declaration for managing linked lists in C.

```c
struct myData
{
    struct myData *nextP;   // Used by the linked list functions
    char          *aString;
    int            anInt;
};

struct myData *listHead;
```

--------------------------------

### IOWA Queue Mode API Usage Example

Source: https://ioterop.github.io/IOWA/print_page

Demonstrates the initialization, configuration, and operation of the IOWA client in Queue Mode, utilizing functions like `iowa_flush_before_pause` and `iowa_client_send_heartbeat` for device standby and communication.

```C
#include "iowa_client.h"

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

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

    iowaH = iowa_init(NULL);

    iowa_client_configure(iowaH, "IOWA_Sample_QM_Client", NULL, NULL);

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

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

    do
    {
        uint32_t iowaDelay;

        // Run for 93 seconds
        result = iowa_step(iowaH, 93);

        // Prepare to stand by for 60 minutes
        result = iowa_flush_before_pause(iowaH, 3600, &iowaDelay);
        if (iowaDelay < 3600)
        {
            STAND_BY(iowaDelay);
        }
        else
        {
            STAND_BY(3600);
            iowa_client_send_heartbeat(iowaH, 1234);
        }
    } while (result == IOWA_COAP_NO_ERROR)

    iowa_client_remove_server(iowaH, 1234);
    iowa_close(iowaH);

    return 0;
}

```

--------------------------------

### LwM2M Client Custom Object Addition Example

Source: https://ioterop.github.io/IOWA/custom_object_multiple_instances

Demonstrates the C code for adding a custom LwM2M object with multiple instances, including resource descriptions and instance data.

```C
sample_object_values_t objectValues;

iowa_lwm2m_resource_desc_t sample_object_resources[SAMPLE_RES_COUNT] =
{
    {5500, IOWA_LWM2M_TYPE_BOOLEAN, IOWA_OPERATION_READ,                        IOWA_RESOURCE_FLAG_NONE},
    {5750, IOWA_LWM2M_TYPE_STRING,  IOWA_OPERATION_READ | IOWA_OPERATION_WRITE, IOWA_RESOURCE_FLAG_NONE},
    {5503, IOWA_LWM2M_TYPE_INTEGER, IOWA_OPERATION_READ | IOWA_OPERATION_WRITE, IOWA_RESOURCE_FLAG_NONE}
};

sample_instance_values_t instanceValues[3];
uint16_t instanceIds[2];

instanceValues[0].id = 0;   // ID of the first instance
instanceValues[0].booleanValue = true;
instanceValues[0].integerValue = 10;
instanceValues[0].stringValue = strdup("First instance");

instanceValues[1].id = 3;   // ID of the first instance
instanceValues[1].booleanValue = false;
instanceValues[1].integerValue = 34;
instanceValues[1].stringValue = strdup("Second instance");

instanceValues[2].id = 5;   // ID of the first instance
instanceValues[2].booleanValue = true;
instanceValues[2].integerValue = 256;
instanceValues[2].stringValue = strdup("Third instance");

instanceIds[0] = instanceValues[0].id;
instanceIds[1] = instanceValues[1].id;

result = iowa_client_add_custom_object(iowaH,
                                       SAMPLE_OBJECT_ID,
                                       2, instanceIds, // Number of instances and their IDs
                                       SAMPLE_RES_COUNT, sample_object_resources,
                                       sample_object_dataCallback,
                                       NULL,
                                       NULL,
                                       &instanceValues);

```

--------------------------------

### Secure Client tinydtls Client-Side Setup

Source: https://ioterop.github.io/IOWA/print_page

Configures the secure client using tinydtls with Pre-Shared Key (PSK) security. This involves defining the PSK identity and value, and setting a unique client name within the main.c file.

```c
    uint8_t keyIdentity[] = { /*Enter your Pre-Shared Key identity here*/ };
    uint8_t keyValue[] = { /*Enter your Pre-Shared Key value here*/ };

    // For instance:
    // uint8_t keyIdentity[] = { 't', 'e', 's', 't' };
    // uint8_t keyValue[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };

    result = iowa_client_configure(iowaH, ""/*Enter your client name here*/, &devInfo, NULL);
```

--------------------------------

### Bootstrap Client Sample

Source: https://ioterop.github.io/IOWA/Security

Demonstrates the functionality of a bootstrap client, enabling devices to obtain initial configuration from a bootstrap server.

```C
// Example snippet for Bootstrap Client
// This is a placeholder and actual code would be more extensive.
#include "iowa.h"
#include "iowa_bootstrap.h"

int main() {
    // Initialize IOWA bootstrap client
    iowa_bootstrap_client_init();

    // Configure bootstrap server
    iowa_bootstrap_client_set_server("coap://bootstrap.example.com:5683");

    // Initiate bootstrap process
    iowa_bootstrap_client_start();

    // The bootstrap client will handle receiving configuration and
    // subsequently connecting to the LwM2M server.

    // Keep the process running
    while(1) {
        iowa_bootstrap_client_process();
        // sleep or yield
    }

    return 0;
}
```

--------------------------------

### GET Request via Forward Proxy

Source: https://ioterop.github.io/IOWA/Changelog

Provides an API to perform a GET request through a forward proxy. This is useful in network configurations where direct access is not possible.

```APIDOC
iowa_coap_peer_proxied_get(peer, uri, proxy_uri)
  - Performs a GET request through a specified proxy.
  - Parameters:
    - peer: The target peer.
    - uri: The URI to GET.
    - proxy_uri: The URI of the forward proxy.
```

--------------------------------

### LwM2M Client Basics Sample

Source: https://ioterop.github.io/IOWA/Security

Demonstrates the fundamental operations of an LwM2M client using the IOWA framework, including registration and basic data handling.

```C
// Example snippet for LwM2M Client Basics
// This is a placeholder and actual code would be more extensive.
#include "iowa.h"

int main() {
    // Initialize IOWA client
    iowa_client_init();

    // Configure server endpoint and port
    iowa_client_set_server("coap://example.com:5683");

    // Register the client
    iowa_client_register();

    // ... perform other client operations ...

    // Start the client event loop
    iowa_client_run();

    return 0;
}
```

--------------------------------

### Perform GET Through Forward-Proxy

Source: https://ioterop.github.io/IOWA/print_page

Introduces a new API to perform a GET request through a specified forward-proxy. This is useful for network configurations where direct access is not possible.

```c
iowa_coap_peer_proxied_get(peer, proxy_uri, ...);
```

--------------------------------

### IOWA LwM2M Client SDK Functions

Source: https://ioterop.github.io/IOWA/baseline_client

Documentation for core IOWA LwM2M client SDK functions. Covers initialization, client configuration, server registration, stepping the client loop, server removal, and cleanup.

```APIDOC
IOWA LwM2M Client SDK Functions:

iowa_context_t iowa_init(void *user_data)
  - Initializes the IOWA SDK and creates a new context.
  - Parameters:
    - user_data: User-defined pointer passed to system abstraction functions.
  - Returns: A handle to the IOWA context.

iowa_status_t iowa_client_configure(iowa_context_t iowaH, const char *endpoint_name, const iowa_device_info_t *devInfo, iowa_event_callback_t callback)
  - Configures the LwM2M client with an endpoint name and optional device information.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - endpoint_name: The unique name for the LwM2M client.
    - devInfo: Optional structure containing device information (manufacturer, deviceType, modelNumber).
    - callback: Optional event callback function.
  - Returns: IOWA status code indicating success or failure.

iowa_status_t iowa_client_add_server(iowa_context_t iowaH, uint16_t server_short_id, const char *server_uri, uint32_t lifetime)
  - Declares a LwM2M server for the client to connect to.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - server_short_id: A short identifier for the server.
    - server_uri: The URI of the LwM2M server (e.g., "coap://host:port").
    - lifetime: The registration lifetime in seconds.
  - Returns: IOWA status code.

void iowa_step(iowa_context_t iowaH, uint32_t timeout_ms)
  - Advances the LwM2M client's state machine by the specified timeout.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - timeout_ms: The duration in milliseconds to step the client.

iowa_status_t iowa_client_remove_server(iowa_context_t iowaH, uint16_t server_short_id)
  - Removes a previously declared LwM2M server.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - server_short_id: The short identifier of the server to remove.
  - Returns: IOWA status code.

void iowa_close(iowa_context_t iowaH)
  - Cleans up and releases resources used by the IOWA SDK.
  - Parameters:
    - iowaH: Handle to the IOWA context.

```

--------------------------------

### IOWA Interrupt Handler Example (C)

Source: https://ioterop.github.io/IOWA/CustomObject

An example C code snippet demonstrating an interrupt handler that updates device state and notifies the IOWA stack about these changes using `iowa_client_object_resource_changed`. It also shows the optional use of `iowa_client_notification_lock`.

```C
switch (interrupt)
{
(...)
case SWITCH_ON:
    if (switchState == false)
    {
        iowa_client_object_resource_changed(contextP, 3312, 0, 5850);
    }
    switchState = true;
    break;

case SWITCH_OFF:
    if (switchState == true)
    {
        iowa_client_object_resource_changed(contextP, 3312, 0, 5850);
    }
    switchState = false;
    break;

case TIMER:
    if (switchState == true)
    {
        onTime++;
        iowa_client_notification_lock(contextP, true);
        iowa_client_object_resource_changed(contextP, 3312, 0, 5852);
        iowa_client_notification_lock(contextP, false);
    }
    break;
(...)
}
```

--------------------------------

### Firmware Update Client (Push Method) Sample

Source: https://ioterop.github.io/IOWA/Security

Illustrates how to implement a firmware update client using the 'Push' method, where the firmware is sent directly to the device.

```C
// Example snippet for Firmware Update Client (Push Method)
// This is a placeholder and actual code would be more extensive.
#include "iowa_fw_update.h"

void handle_firmware_update_push(const char* url, const char* data, size_t size) {
    // Process the received firmware data
    // This would involve saving the firmware, verifying it, and initiating the update process.
    iowa_log(IOWA_INFO, "Received firmware data of size %zu via push.", size);
    // ... firmware update logic ...
}

// In the client's main loop or handler:
// iowa_fw_update_register_handler(IOWA_FW_UPDATE_PUSH, handle_firmware_update_push);
```

--------------------------------

### API: iowa_coap_peer_proxied_get

Source: https://ioterop.github.io/IOWA/print_page

Performs a CoAP GET request through a specified forward-proxy. Useful for routing requests in complex network environments.

```APIDOC
Function Signature:
  int iowa_coap_peer_proxied_get(iowa_coap_peer_t *peer, const char *proxy_uri, ...);

Parameters:
  peer: Pointer to the CoAP peer structure.
  proxy_uri: The URI of the forward-proxy server.
  ...: Other GET request parameters (e.g., URI path, options).

Returns:
  0 on success, negative error code on failure.
```

--------------------------------

### Firmware Update Client (Pull Method) Sample

Source: https://ioterop.github.io/IOWA/Security

Demonstrates the firmware update process using the 'Pull' method, where the client fetches firmware from a specified URL.

```C
// Example snippet for Firmware Update Client (Pull Method)
// This is a placeholder and actual code would be more extensive.
#include "iowa_fw_update.h"
#include "iowa_http_client.h"

void handle_firmware_update_pull(const char* url) {
    // Fetch firmware from the provided URL using an HTTP client
    char* firmware_data = NULL;
    size_t firmware_size = 0;
    
    if (iowa_http_get(url, &firmware_data, &firmware_size) == IOWA_SUCCESS) {
        iowa_log(IOWA_INFO, "Successfully fetched firmware from %s. Size: %zu", url, firmware_size);
        // ... process and apply firmware ...
        free(firmware_data);
    } else {
        iowa_log(IOWA_ERROR, "Failed to fetch firmware from %s.", url);
    }
}

// In the client's main loop or handler:
// iowa_fw_update_register_handler(IOWA_FW_UPDATE_PULL, handle_firmware_update_pull);
```

--------------------------------

### LwM2M Write Attributes

Source: https://ioterop.github.io/IOWA/print_page

Details on setting and clearing attributes for LwM2M observations, including parameter definitions, constraints, and examples.

```APIDOC
Write Attributes:
  Description: The LwM2M Server can set or clear parameters that control observation behavior.

  Attributes:
    pmin:
      Level: Object, Object Instance, Resource
      Description: The minimum period in seconds to wait between notifications.

    pmax:
      Level: Object, Object Instance, Resource
      Description: The maximum period in seconds to wait between notifications.

    gt:
      Level: Numerical Resource
      Description: An upper threshold. A notification is sent when the resource value crosses this threshold.

    lt:
      Level: Numerical Resource
      Description: A lower threshold. A notification is sent when the resource value crosses this threshold.

    st:
      Level: Numerical Resource
      Description: A minimum difference in a resource value for a notification to be sent.

    epmin:
      Level: Object, Object Instance, Resource
      Description: The minimum sample time in seconds for the observed sensor (LwM2M 1.1+).

    epmax:
      Level: Object, Object Instance, Resource
      Description: The maximum sample time in seconds for the observed sensor (LwM2M 1.1+).

  Constraints:
    - lt value < gt value
    - lt value + 2 * st value < gt value
    - If pmax < pmin, pmax is ignored
    - epmax > epmin

  Clearing Attributes:
    Format: Name (e.g., 'pmin')

  Setting Attributes:
    Format: Name = value (e.g., 'pmax=60')

  Examples:
    - Receiving a notification every minute at most: "pmax=60"
    - Receiving only one notification per hour: "pmin=3600"
    - Receiving exactly one notification every sixty seconds: "pmin=59&pmax=60"
    - Receiving notification on crossing thresholds: "lt=10&gt=95"
    - Clearing pmin and setting pmax to 5 minutes: "pmin&pmax=300"
```

--------------------------------

### IOWA LwM2M Client SDK Functions

Source: https://ioterop.github.io/IOWA/print_page

Documentation for core IOWA LwM2M client SDK functions. Covers initialization, client configuration, server registration, stepping the client loop, server removal, and cleanup.

```APIDOC
IOWA LwM2M Client SDK Functions:

iowa_context_t iowa_init(void *user_data)
  - Initializes the IOWA SDK and creates a new context.
  - Parameters:
    - user_data: User-defined pointer passed to system abstraction functions.
  - Returns: A handle to the IOWA context.

iowa_status_t iowa_client_configure(iowa_context_t iowaH, const char *endpoint_name, const iowa_device_info_t *devInfo, iowa_event_callback_t callback)
  - Configures the LwM2M client with an endpoint name and optional device information.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - endpoint_name: The unique name for the LwM2M client.
    - devInfo: Optional structure containing device information (manufacturer, deviceType, modelNumber).
    - callback: Optional event callback function.
  - Returns: IOWA status code indicating success or failure.

iowa_status_t iowa_client_add_server(iowa_context_t iowaH, uint16_t server_short_id, const char *server_uri, uint32_t lifetime)
  - Declares a LwM2M server for the client to connect to.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - server_short_id: A short identifier for the server.
    - server_uri: The URI of the LwM2M server (e.g., "coap://host:port").
    - lifetime: The registration lifetime in seconds.
  - Returns: IOWA status code.

void iowa_step(iowa_context_t iowaH, uint32_t timeout_ms)
  - Advances the LwM2M client's state machine by the specified timeout.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - timeout_ms: The duration in milliseconds to step the client.

iowa_status_t iowa_client_remove_server(iowa_context_t iowaH, uint16_t server_short_id)
  - Removes a previously declared LwM2M server.
  - Parameters:
    - iowaH: Handle to the IOWA context.
    - server_short_id: The short identifier of the server to remove.
  - Returns: IOWA status code.

void iowa_close(iowa_context_t iowaH)
  - Cleans up and releases resources used by the IOWA SDK.
  - Parameters:
    - iowaH: Handle to the IOWA context.

```

--------------------------------

### Get LwM2M Server Count

Source: https://ioterop.github.io/IOWA/ClientAPI

Retrieves the total count of configured LwM2M Servers within the LwM2M Client. It requires the client context and a pointer to store the count.

```C
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`](CommonAPI.html#iowa_context_t) as returned by [`iowa_init()`](CommonAPI.html#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_system_connection_get_peer_identifier: Get Peer Identifier

Source: https://ioterop.github.io/IOWA/AbstractionLayer

Retrieves a unique identifier for the peer associated with a connection. This is used for security layers or when endpoint names are not found.

```APIDOC
iowa_system_connection_get_peer_identifier: Get Peer Identifier

Prototype:
size_t iowa_system_connection_get_peer_identifier(void * connP,
                                                  uint8_t * addrP,
                                                  size_t length,
                                                  void * userData);

Description:
Returns an unique identifier for the peer of a connection (e.g. IP address, LoRaWAN DevEUI, SMS MSISDN).

Arguments:
*connP*: The connection as returned by [`iowa_system_connection_open()`].
*addrP*: A pre-allocated buffer to store the identifier.
*length*: The length of *addrP* in bytes.
*userData*: The argument passed to [`iowa_init()`].

Return Value:
The number of bytes of the identifier or 0 in case of error.

Header File:
iowa_platform.h

Notes:
This function is required only if IOWA is built with [IOWA_SECURITY_LAYER] different from **IOWA_SECURITY_LAYER_NONE**, or with **LWM2M_SERVER_MODE** or **LWM2M_BOOTSTRAP_SERVER_MODE** flags.
This is used when the endpoint name has not been found in the registration payload.
```

--------------------------------

### Build IOWA Samples on Linux

Source: https://ioterop.github.io/IOWA/Building

Steps to compile the IOWA client and server applications on a Linux environment. This process involves creating a build directory, configuring the build with CMake, and then executing the build command using Make.

```shell
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j 4
```

--------------------------------

### Linked List Head Declaration Example

Source: https://ioterop.github.io/IOWA/UtilsAPI

Shows how to declare a pointer that will serve as the head of a linked list, which is essential for using the Iowa list utility functions.

```C
struct myData *listHead;

```

--------------------------------

### IOWA SDK Basic Structure

Source: https://ioterop.github.io/IOWA/CommonAPI

Demonstrates the fundamental structure of an IOWA application, including initialization with iowa_init(), the main loop using iowa_step(), and cleanup with iowa_close().

```c
#include "iowa.h"

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

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

    iowaH = iowa_init(NULL);

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

    do
    {
        result = iowa_step(iowaH, 5);
    } while (result == IOWA_COAP_NO_ERROR)

    iowa_close(iowaH);

    return 0;
}

```

--------------------------------

### Bootstrap Server APIs Reference

Source: https://ioterop.github.io/IOWA/Security

Details the APIs for implementing a LwM2M Bootstrap Server using the IOWA framework.

```APIDOC
BootstrapServerAPI:
  Description: APIs for creating and managing a LwM2M Bootstrap Server.
  Related APIs: [Server APIs](ServerAPI.html), [Client APIs](ClientAPI.html)
  Content:
    - Bootstrap initiation and configuration.
    - Storing and retrieving bootstrap information for devices.
    - Security context management for bootstrap.
    - Handling bootstrap requests from clients.
```

--------------------------------

### iowa_client_configure and Device Information Management

Source: https://ioterop.github.io/IOWA/print_page

Details the `iowa_device_info_t` structure used with `iowa_client_configure()`. Explains optional fields, LwM2M standard compliance, and specific flags for enabling device resources like battery, power source, and time information.

```APIDOC
iowa_device_info_t:
  Structure for device configuration and information.
  All string pointers can be null if the information is optional.

  Fields:
    manufacturer: Human-readable manufacturer name.
    deviceType: The type of the device.
    modelNumber: The model number.
    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 to enable optional features. Combination of:
      IOWA_DEVICE_RSC_BATTERY: Enables battery level/status. Requires iowa_client_device_update_battery().
      IOWA_DEVICE_RSC_POWER_SOURCE: Enables power source info. Requires iowa_client_add_device_power_source().
      IOWA_DEVICE_RSC_CURRENT_TIME: Enables current time in Device Object.
      IOWA_DEVICE_RSC_UTC_OFFSET: Enables UTC offset in Device Object.
      IOWA_DEVICE_RSC_TIMEZONE: Enables timezone in Device Object. Requires iowa_client_update_device_time_information() for time updates.
      IOWA_DEVICE_RSC_MEMORY_FREE: Enables Memory Free resource. Requires iowa_client_update_device_information() for other device info updates.
      IOWA_DEVICE_RSC_EXTERNAL_INFO: Enables ExtDevInfo resource. Requires iowa_client_update_device_external_information().
    utcOffsetP: UTC offset in ISO 8601 format (e.g., UTC+X).
    timezoneP: Timezone in IANA Timezone (TZ) database format.
    memoryTotal: Total storage space in kilobytes. Ignored if zero.
    memoryFree: Available storage space in kilobytes. Ignored if IOWA_DEVICE_RSC_MEMORY_FREE is not set in optFlags.
    dataTimeUpdateCallback: Callback for time updates from LwM2M Server.
    factoryResetCallback: Callback for Factory Reset.
    callbackUserDataP: User data passed to callbacks.

Related API Calls:
  iowa_client_configure(device_info: *iowa_device_info_t):
    Configures the LwM2M client with device information.

  iowa_client_device_update_battery():
    Updates battery level and status.

  iowa_client_add_device_power_source():
    Adds new power source information.

  iowa_client_update_device_time_information():
    Updates current time, UTC offset, and timezone.

  iowa_client_update_device_information():
    Updates device-related information (manufacturer, model, versions, etc.).

  iowa_client_update_device_external_information():
    Sets ExtDevInfo resource values.
```

--------------------------------

### Get Security Session Mode

Source: https://ioterop.github.io/IOWA/SecurityAPI

Retrieves the security mode of a given IOWA security session. It takes a session handle and returns the security mode type.

```APIDOC
iowa_security_session_get_security_mode

**Prototype**
```c
iowa_security_mode_t
iowa_security_session_get_security_mode(iowa_security_session_t securityS);
```

**Description**
`iowa_security_session_get_security_mode()` retrieves the security mode of a security session.

**Arguments**
*securityS*
:   An iowa_security_session_t pointing to a security session.

**Return Value**
The security mode as an [`iowa_security_mode_t`](SecurityAPI.html#iowa_security_mode_t).
```

--------------------------------

### Get Security Session Context

Source: https://ioterop.github.io/IOWA/SecurityAPI

Retrieves the IOWA context associated with a specific security session. This function requires a valid session handle and returns the context pointer.

```APIDOC
iowa_security_session_get_context

**Prototype**
```c
iowa_context_t iowa_security_session_get_context(iowa_security_session_t securityS);
```

**Description**
`iowa_security_session_get_context()` retrieves the IOWA context in which a security session exists.

**Arguments**
*securityS*
:   An iowa_security_session_t pointing to a security session.

**Return Value**
The IOWA context.
```

--------------------------------

### Dynamic Custom Object - Main Function Breakdown

Source: https://ioterop.github.io/IOWA/custom_object_dynamic

Details the essential steps within the main function for setting up and running a client with a dynamic custom object. Covers initialization, configuration, object addition, server declaration, the main loop, and cleanup.

```c
// Initialization
iowa_init();

// LwM2M Client Configuration
iowa_client_config_t client_config;
// ... populate client_config ...
iowa_client_init(&client_config);

// Custom Object Addition
// Define and add your custom object definition here
// e.g., iowa_custom_object_add(...);

// LwM2M Server Declaration
iowa_server_info_t server_info;
// ... populate server_info ...
iowa_server_add(&server_info);

// "Main Loop"
// Start the client and enter the main processing loop
iowa_client_start();

// Cleanup
iowa_client_stop();
iowa_client_destroy();
iowa_destroy();
```

--------------------------------

### Custom Object Multiple Instances Sample

Source: https://ioterop.github.io/IOWA/Changelog

The `custom_object_multiple_instances` sample, which demonstrates managing multiple instances of a custom LwM2M Object, has been simplified and documented.

```C
// Example snippet structure for custom_object_multiple_instances.c
// ... code demonstrating creation, update, and deletion of multiple instances ...
```

--------------------------------

### Get Security Session Context User Data

Source: https://ioterop.github.io/IOWA/SecurityAPI

Retrieves a pointer to application-specific data within the IOWA context of a security session. This data is typically passed during IOWA initialization.

```APIDOC
iowa_security_session_get_context_user_data

**Prototype**
```c
void * iowa_security_session_get_context_user_data(iowa_security_session_t securityS);
```

**Description**
`iowa_security_session_get_context_user_data()` retrieves the pointer to application-specific data of the IOWA context in which a security session exists.

**Arguments**
*securityS*
:   An iowa_security_session_t pointing to a security session.

**Return Value**
The pointer to application-specific data as passed to [`iowa_init()`](CommonAPI.html#iowa_init).
```
Tokens:
Raw