### nx_azure_iot_adu_agent_update_download_and_install prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_adu_agent.md

Prototype for starting to download and install a new update. Returns NX_AZURE_IOT_SUCCESS on success or NX_AZURE_IOT_INVALID_PARAMETER on invalid parameter. Allowed from threads.

```c
UINT nx_azure_iot_adu_agent_update_download_and_install(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr);
```

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

### nx_azure_iot_adu_agent_update_download_and_install

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_adu_agent.md

Starts to download and install the new update.

```APIDOC
## nx_azure_iot_adu_agent_update_download_and_install

### Description
Starts to download and install the new update.

### Prototype
```c
UINT nx_azure_iot_adu_agent_update_download_and_install(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr);
```

### Parameters
- **adu_agent_ptr** (NX_AZURE_IOT_ADU_AGENT *) - Required - A pointer to a `NX_AZURE_IOT_ADU_AGENT`.

### Return Values
- **NX_AZURE_IOT_SUCCESS** - Successfully started to download and install the new update.
- **NX_AZURE_IOT_INVALID_PARAMETER** - Fail to download and install the new update due to invalid parameter.

### Allowed From
Threads

### Example
(No example provided in source)

### See Also
(No additional references provided in source)
```

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

### nx_azure_iot_adu_agent_start prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_adu_agent.md

Starts the Azure IoT ADU agent. The manufacturer and model identify the device, and installed criteria is used to determine if an update is already installed. If installed criteria is not set, the agent will issue NX_AZURE_IOT_ADU_AGENT_DRIVER_UPDATE_CHECK to the driver.

```c
UINT nx_azure_iot_adu_agent_start(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr,
                                  NX_AZURE_IOT_HUB_CLIENT *iothub_client_ptr,
                                  const UCHAR *manufacturer, UINT manufacturer_length,
                                  const UCHAR *model, UINT model_length,
                                  const UCHAR *installed_criteria, UINT installed_criteria_length,
                                  VOID (*adu_agent_update_notify)(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr,
                                                                  UCHAR *provider, UINT provider_length,
                                                                  UCHAR *name, UINT name_length,
                                                                  UCHAR *version, UINT version_length),
                                  VOID (*adu_agent_driver)(NX_AZURE_IOT_ADU_AGENT_DRIVER *));
```

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

### nx_azure_iot_adu_agent_start

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_adu_agent.md

Starts the Azure IoT ADU agent.

```APIDOC
## nx_azure_iot_adu_agent_start

### Description
Starts the Azure IoT ADU agent.

### Prototype
```c
UINT nx_azure_iot_adu_agent_start(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr);
```

### Parameters
- **adu_agent_ptr** (NX_AZURE_IOT_ADU_AGENT *) - Required - A pointer to a `NX_AZURE_IOT_ADU_AGENT`.

### Return Values
- **NX_AZURE_IOT_SUCCESS** - Successfully started the Azure IoT ADU agent.
- **NX_AZURE_IOT_INVALID_PARAMETER** - Fail to start the Azure IoT ADU agent due to invalid parameter.
- **NX_AZURE_IOT_NO_MORE_ENTRIES** - Fail to start the Azure IoT ADU agent due to no more entries.

### Allowed From
Threads

### Example
(No example provided in source)

### See Also
(No additional references provided in source)
```

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

### nx_azure_iot_adu_agent_start

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_adu_agent.md

Starts the Azure IoT ADU agent with the specified device properties and installed criteria. The agent can check updates internally or delegate to a driver.

```APIDOC
## nx_azure_iot_adu_agent_start

### Description
Starts the Azure IoT ADU agent. The agent uses the provided manufacturer, model, and installed criteria to manage device updates. If installed criteria is provided, the agent checks updates internally; otherwise, it delegates to the driver.

### Prototype
```c
UINT nx_azure_iot_adu_agent_start(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr,
                                  NX_AZURE_IOT_HUB_CLIENT *iothub_client_ptr,
                                  const UCHAR *manufacturer, UINT manufacturer_length,
                                  const UCHAR *model, UINT model_length,
                                  const UCHAR *installed_criteria, UINT installed_criteria_length,
                                  VOID (*adu_agent_update_notify)(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr,
                                                                  UCHAR *provider, UINT provider_length,
                                                                  UCHAR *name, UINT name_length,
                                                                  UCHAR *version, UINT version_length),
                                  VOID (*adu_agent_driver)(NX_AZURE_IOT_ADU_AGENT_DRIVER *));
```

### Parameters
- **adu_agent_ptr** (NX_AZURE_IOT_ADU_AGENT*) - Required - A pointer to a `NX_AZURE_IOT_ADU_AGENT`.
- **iothub_client_ptr** (NX_AZURE_IOT_HUB_CLIENT*) - Required - A pointer to a `NX_AZURE_IOT_HUB_CLIENT`.
- **manufacturer** (const UCHAR*) - Required - A pointer to the manufacturer. Must be NULL terminated string.
- **manufacturer_length** (UINT) - Required - Length of the manufacturer.
- **model** (const UCHAR*) - Required - A pointer to the model. Must be NULL terminated string.
- **model_length** (UINT) - Required - Length of the model.
- **installed_criteria** (const UCHAR*) - Required - A pointer to the installed criteria string, such as: version string. Must be NULL terminated string.
- **installed_criteria_length** (UINT) - Required - Length of the installed_criteria.
- **adu_agent_update_notify** (function pointer) - Required - Pointer to a callback function invoked once update is received.
- **adu_agent_driver** (function pointer) - Required - User supplied driver for flash operation.

### Return Values
- **NX_AZURE_IOT_SUCCESS** - Successfully started the Azure IoT ADU agent.
- **NX_AZURE_IOT_INVALID_PARAMETER** - Fail to start the Azure IoT ADU agent due to invalid parameter.
- **NX_AZURE_IOT_NO_AVAILABLE_CIPHER** - Fail to start the Azure IoT ADU agent due to no available cipher.
- **NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE** - Fail to start the Azure IoT ADU agent due to insufficient buffer space.

### Allowed From
Threads
```

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

### CMake project setup and NetX Duo inclusion

Source: https://github.com/eclipse-threadx/netxduo/blob/master/test/cmake/netxduo64/CMakeLists.txt

Sets the minimum CMake version, applies policies, defines the project, sets the NX user file, and includes the NetX Duo CMakeLists.txt.

```cmake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
cmake_policy(SET CMP0054 NEW)
cmake_policy(SET CMP0057 NEW)
cmake_policy(SET CMP0077 NEW)

project(netx_test LANGUAGES C)

set(NX_USER_FILE ${CMAKE_CURRENT_SOURCE_DIR}/nx_user.h)
include(${CMAKE_CURRENT_SOURCE_DIR}/../netxduo/CMakeLists.txt)
```

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

### nx_azure_iot_adu_agent_update_apply

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_adu_agent.md

Starts to apply the new update.

```APIDOC
## nx_azure_iot_adu_agent_update_apply

### Description
Starts to apply the new update. The device may reboot after applying the update successfully.

### Prototype
```c
UINT nx_azure_iot_adu_agent_update_apply(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr);
```

### Parameters
- **adu_agent_ptr** (NX_AZURE_IOT_ADU_AGENT *) - Required - A pointer to a `NX_AZURE_IOT_ADU_AGENT`.

### Return Values
- **NX_AZURE_IOT_SUCCESS** - Successfully started to apply the new update.
- **NX_AZURE_IOT_INVALID_PARAMETER** - Fail to apply the new update due to invalid parameter.

### Allowed From
Threads

### Example
(No example provided in source)

### See Also
(No additional references provided in source)
```

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

### nx_azure_iot_provisioning_client_iothub_device_info_get

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_provisioning_client.md

Gets IoTHub device info into user supplied buffer.

```APIDOC
## Function: nx_azure_iot_provisioning_client_iothub_device_info_get

### Description
This routine gets IoTHub device info into user supplied buffer.

### Prototype
```c
UINT nx_azure_iot_provisioning_client_iothub_device_info_get(NX_AZURE_IOT_PROVISIONING_CLIENT *prov_client_ptr,
                                                             UCHAR *iothub_hostname, UINT *iothub_hostname_len,
                                                             UCHAR *device_id, UINT *device_id_len);
```

### Parameters
- **prov_client_ptr** [in] - A pointer to a `NX_AZURE_IOT_PROVISIONING_CLIENT`.
- **iothub_hostname** [out] - Buffer pointer that will contain IoTHub hostname.
- **iothub_hostname_len** [inout] - Pointer to UINT that contains size of buffer supplied, once successfully return it contains bytes copied to buffer.
- **device_id** [out] - Buffer pointer that will contain IoTHub deviceId.
- **device_id_len** [inout] - Pointer to UINT that contains size of buffer supplied, once successfully return it contains bytes copied to buffer.

### Return Values
- **NX_AZURE_IOT_SUCCESS** - The device info is successfully retrieved to user supplied buffers.
- **NX_AZURE_IOT_INVALID_PARAMETER** - Fail to retrieve device info due to invalid parameter.
- **NX_AZURE_IOT_WRONG_STATE** - Fail to retrieve device info due to wrong state.
- **NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE** - Fail to retrieve device info due to buffer size is too small.

### Allowed From
Threads

### Example
(No example provided in source)

### See Also
(No additional references provided in source)
```

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

### Function header comment example

Source: https://github.com/eclipse-threadx/netxduo/blob/master/README.md

Shows the standard function header comment format used in NetX Duo source files, including fields for function name, author, description, inputs, outputs, calls, called by, and release history. The header includes placeholders like '6.x' and 'xx-xx-xxxx' indicating unreleased versions. Use this format when documenting functions in the codebase.

```c
/**************************************************************************/
/*                                                                        */
/*  FUNCTION                                               RELEASE        */
/*                                                                        */
/*    _tx_initialize_low_level                          Cortex-M23/GNU    */
/*                                                           6.x          */
/*  AUTHOR                                                                */
/*                                                                        */
/*    Scott Larson, Microsoft Corporation                                 */
/*                                                                        */
/*  DESCRIPTION                                                           */
/*                                                                        */
/*    This function is responsible for any low-level processor            */
/*    initialization, including setting up interrupt vectors, setting     */
/*    up a periodic timer interrupt source, saving the system stack       */
/*    pointer for use in ISR processing later, and finding the first      */
/*    available RAM memory address for tx_application_define.             */
/*                                                                        */
/*  INPUT                                                                 */
/*                                                                        */
/*    None                                                                */
/*                                                                        */
/*  OUTPUT                                                                */
/*                                                                        */
/*    None                                                                */
/*                                                                        */
/*  CALLS                                                                 */
/*                                                                        */
/*    None                                                                */
/*                                                                        */
/*  CALLED BY                                                             */
/*                                                                        */
/*    _tx_initialize_kernel_enter           ThreadX entry function        */
/*                                                                        */
/*  RELEASE HISTORY                                                       */
/*                                                                        */
/*    DATE              NAME                      DESCRIPTION             */
/*                                                                        */
/*  09-30-2020      Scott Larson            Initial Version 6.1           */
/*  xx-xx-xxxx      Scott Larson            Include tx_user.h,            */
/*                                            resulting in version 6.x    */
/*                                                                        */
/**************************************************************************/ 
```

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

### Clone NetX Duo repository with submodules

Source: https://github.com/eclipse-threadx/netxduo/blob/master/README.md

Clones the NetX Duo repository recursively to fetch all submodule dependencies. Use this as the first step after installing the required tools and building the ThreadX library.

```bash
$ git clone --recursive https://github.com/eclipse-threadx/netxduo.git
```

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

### nx_azure_iot_provisioning_client_register prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_provisioning_client.md

Registers the device with the Azure IoT Provisioning service. Returns NX_AZURE_IOT_SUCCESS on success, NX_AZURE_IOT_PENDING if registration started but not completed, and various error codes for failures such as invalid parameters, SDK core errors, server response errors, disconnection, DNS query failure, no packet, TLS issues, or MQTT errors.

```c
UINT nx_azure_iot_provisioning_client_register(NX_AZURE_IOT_PROVISIONING_CLIENT *prov_client_ptr, UINT wait_option);
```

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

### Symmetric key connection macros for sample_config.h

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/samples/README.md

Define HOST_NAME, DEVICE_ID, and DEVICE_SYMMETRIC_KEY from the device connection string (HostName=<>;DeviceId=<>;SharedAccessKey=<>) to connect to IoTHub. Add these macros to your compiler options.

```c
#define HOST_NAME                                   "<Hostname from connection string>"
#define DEVICE_ID                                   "<DeviceId from connection string>"
#define DEVICE_SYMMETRIC_KEY                        "<SharedAccessKey from connection string>"
```

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

### nx_azure_iot_provisioning_client_initialize

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_provisioning_client.md

Initializes the device to the Azure IoT provisioning service. Requires a valid endpoint, ID scope, registration ID, crypto methods, cipher map, metadata buffer, and trusted certificate. Returns NX_AZURE_IOT_SUCCESS on success or an error code for invalid parameters, SDK core errors, or insufficient buffer space.

```c
UINT nx_azure_iot_provisioning_client_initialize(NX_AZURE_IOT_PROVISIONING_CLIENT *prov_client_ptr,
                                                 NX_AZURE_IOT *nx_azure_iot_ptr,
                                                 const UCHAR *endpoint, UINT endpoint_length,
                                                 const UCHAR *id_scope, UINT id_scope_length,
                                                 const UCHAR *registration_id, UINT registration_id_length,
                                                 const NX_CRYPTO_METHOD **crypto_array, UINT crypto_array_size,
                                                 const NX_CRYPTO_CIPHERSUITE **cipher_map, UINT cipher_map_size,
                                                 UCHAR *metadata_memory, UINT memory_size,
                                                 NX_SECURE_X509_CERT *trusted_certificate);
```

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

### Reported properties JSON payload example

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client_properties.md

Example of the JSON payload structure generated by the reported properties component functions.

```json
"reported": {
    "<component_name>": {
        "__t": "c",
        "temperature": 23
    }
}
```

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

### nx_azure_iot_adu_agent_proxy_update_add

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_adu_agent.md

Adds a proxy update to the device update agent. The agent checks if the update is installed based on the provided installed criteria or delegates to the driver.

```APIDOC
## nx_azure_iot_adu_agent_proxy_update_add

### Description
Adds a proxy update on the device update agent. The agent uses the provided manufacturer, model, and installed criteria to determine if the update is installed. If installed criteria is provided, the agent checks internally; otherwise, it delegates to the driver via the NX_AZURE_IOT_ADU_AGENT_DRIVER_UPDATE_CHECK command.

### Prototype
```c
UINT nx_azure_iot_adu_agent_proxy_update_add(NX_AZURE_IOT_ADU_AGENT *adu_agent_ptr,
                                             const UCHAR *manufacturer, UINT manufacturer_length,
                                             const UCHAR *model, UINT model_length,
                                             const UCHAR *installed_criteria, UINT installed_criteria_length,
                                             VOID (*adu_agent_driver)(NX_AZURE_IOT_ADU_AGENT_DRIVER *));
```

### Parameters
- **adu_agent_ptr** (NX_AZURE_IOT_ADU_AGENT*) - Required - A pointer to a `NX_AZURE_IOT_ADU_AGENT`.
- **manufacturer** (const UCHAR*) - Required - A pointer to the manufacturer. Must be NULL terminated string.
- **manufacturer_length** (UINT) - Required - Length of the manufacturer.
- **model** (const UCHAR*) - Required - A pointer to the model. Must be NULL terminated string.
- **model_length** (UINT) - Required - Length of the model.
- **installed_criteria** (const UCHAR*) - Required - A pointer to the installed criteria string, such as: version string. Must be NULL terminated string.
- **installed_criteria_length** (UINT) - Required - Length of the installed_criteria.
- **adu_agent_driver** (function pointer) - Required - User supplied driver for flash operation.

### Return Values
- **NX_AZURE_IOT_SUCCESS** - Successfully added the proxy update.
- **NX_AZURE_IOT_INVALID_PARAMETER** - Failed to add the proxy update due to invalid parameter.
- **NX_AZURE_IOT_NO_AVAILABLE_CIPHER** - Failed to add the proxy update due to no available cipher.
- **NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE** - Failed to add the proxy update due to insufficient buffer space.

### Allowed From
Threads
```

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

### nx_azure_iot_hub_client_initialize prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client.md

Initializes the Azure IoT Hub client with the provided parameters, including host name, device ID, module ID, crypto methods, and trusted certificate. Returns NX_AZURE_IOT_SUCCESS on success or an error code on failure.

```c
UINT nx_azure_iot_hub_client_initialize(NX_AZURE_IOT_HUB_CLIENT* hub_client_ptr,
                                        NX_AZURE_IOT *nx_azure_iot_ptr,
                                        const UCHAR *host_name, UINT host_name_length,
                                        const UCHAR *device_id, UINT device_id_length,
                                        const UCHAR *module_id, UINT module_id_length,
                                        const NX_CRYPTO_METHOD **crypto_array, UINT crypto_array_size,
                                        const NX_CRYPTO_CIPHERSUITE **cipher_map, UINT cipher_map_size,
                                        UCHAR * metadata_memory, UINT memory_size,
                                        NX_SECURE_X509_CERT *trusted_certificate);
```

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

### nx_azure_iot_provisioning_client_initialize

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_provisioning_client.md

Initializes the Azure IoT Provisioning client with the required parameters.

```APIDOC
## nx_azure_iot_provisioning_client_initialize

### Description
Initializes the device to the IoT provisioning service.

### Prototype
```c
UINT nx_azure_iot_provisioning_client_initialize(NX_AZURE_IOT_PROVISIONING_CLIENT *prov_client_ptr,
                                                 NX_AZURE_IOT *nx_azure_iot_ptr,
                                                 const UCHAR *endpoint, UINT endpoint_length,
                                                 const UCHAR *id_scope, UINT id_scope_length,
                                                 const UCHAR *registration_id, UINT registration_id_length,
                                                 const NX_CRYPTO_METHOD **crypto_array, UINT crypto_array_size,
                                                 const NX_CRYPTO_CIPHERSUITE **cipher_map, UINT cipher_map_size,
                                                 UCHAR *metadata_memory, UINT memory_size,
                                                 NX_SECURE_X509_CERT *trusted_certificate);
```

### Parameters
- **prov_client_ptr** (NX_AZURE_IOT_PROVISIONING_CLIENT*) - Required - A pointer to a `NX_AZURE_IOT_PROVISIONING_CLIENT`.
- **nx_azure_iot_ptr** (NX_AZURE_IOT*) - Required - A pointer to a `NX_AZURE_IOT`.
- **endpoint** (const UCHAR*) - Required - A pointer to IoT Provisioning endpoint. Must be NULL terminated string.
- **endpoint_length** (UINT) - Required - Length of the IoT Provisioning endpoint.
- **id_scope** (const UCHAR*) - Required - A pointer to ID Scope.
- **id_scope_length** (UINT) - Required - Length of the ID Scope.
- **registration_id** (const UCHAR*) - Required - A pointer to registration ID.
- **registration_id_length** (UINT) - Required - Length of the registration ID.
- **crypto_array** (const NX_CRYPTO_METHOD**) - Required - A pointer to `NX_CRYPTO_METHOD`.
- **crypto_array_size** (UINT) - Required - Size of crypto method array.
- **cipher_map** (const NX_CRYPTO_CIPHERSUITE**) - Required - A pointer to `NX_CRYPTO_CIPHERSUITE`.
- **cipher_map_size** (UINT) - Required - Size of cipher map.
- **metadata_memory** (UCHAR*) - Required - A pointer to metadata memory buffer.
- **memory_size** (UINT) - Required - Size of metadata buffer.
- **trusted_certificate** (NX_SECURE_X509_CERT*) - Required - A pointer to `NX_SECURE_X509_CERT`, which is server side certs.

### Return Values
- NX_AZURE_IOT_SUCCESS - Successfully initialized to Azure IoT Provisioning Client.
- NX_AZURE_IOT_INVALID_PARAMETER - Fail to initialize the Azure IoT Provisioning Client due to invalid parameter.
- NX_AZURE_IOT_SDK_CORE_ERROR - Fail to initialize the Azure IoT Provisioning Client due to SDK core error.
- NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE - Fail to initialize the Azure IoT Provisioning Client due to buffer size is too small.

### Allowed From
Threads
```

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

### nx_azure_iot_json_reader_token_double_get

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_json.md

Gets the JSON token's number as a double.

```APIDOC
## nx_azure_iot_json_reader_token_double_get

### Description
Gets the JSON token's number as a `double`.

### Prototype
```c
UINT nx_azure_iot_json_reader_token_double_get(NX_AZURE_IOT_JSON_READER *reader_ptr,
                                               double *value_ptr);
```

### Parameters
- **reader_ptr** (NX_AZURE_IOT_JSON_READER*) - Required - A pointer to an #NX_AZURE_IOT_JSON_READER instance containing the JSON to read.
- **value_ptr** (double*) - Required - A pointer to a variable to receive the value.

### Return Values
- NX_AZURE_IOT_SUCCESS - The number is returned.

### Allowed From
Threads

```

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

### Define X509 connection macros for compiler options

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/samples/README.md

Add these macros to your compiler options to configure the sample for X509 authentication. Set HOST_NAME and DEVICE_ID from the connection string, enable USE_DEVICE_CERTIFICATE, and choose the key type (RSA or EC).

```c
#define HOST_NAME                                   "<Hostname from connection string>"
#define DEVICE_ID                                   "<DeviceId from connection string>"
#define USE_DEVICE_CERTIFICATE                      1
#define DEVICE_KEY_TYPE                             NX_SECURE_X509_KEY_TYPE_RSA_PKCS1_DER /* NX_SECURE_X509_KEY_TYPE_RSA_PKCS1_DER for RSA, NX_SECURE_X509_KEY_TYPE_EC_DER for ECC */
```

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

### nx_azure_iot_json_reader_token_bool_get

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_json.md

Gets the JSON token's boolean value.

```APIDOC
## [C] nx_azure_iot_json_reader_token_bool_get

### Description
Gets the JSON token's boolean value.

### Method
C function

### Prototype
```c
UINT nx_azure_iot_json_reader_token_bool_get(NX_AZURE_IOT_JSON_READER *reader_ptr,
                                             UINT *value_ptr);
```

### Parameters
- **reader_ptr** (NX_AZURE_IOT_JSON_READER *) - Input - A pointer to an #NX_AZURE_IOT_JSON_READER instance containing the JSON to read.
- **value_ptr** (UINT *) - Output - A pointer to a variable to receive the value.

### Return Values
- NX_AZURE_IOT_SUCCESS - The boolean value is returned.

### Allowed From
Threads

### Example
(Not provided)

### See Also
(Not provided)
```

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

### CMake configuration for NetX Duo samples

Source: https://github.com/eclipse-threadx/netxduo/blob/master/test/cmake/netxduo/samples/CMakeLists.txt

This CMake script configures the build of NetX Duo sample applications. It sets the minimum CMake version, defines the project, and conditionally includes sample source files based on build options. The script creates an executable for each sample and links it with the azrtos library.

```cmake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
cmake_policy(SET CMP0057 NEW)

project(samples LANGUAGES C)

set(SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../../samples)

set(sample_files
    ${SOURCE_DIR}/demo_netxduo_dns.c
    ${SOURCE_DIR}/demo_netxduo_ftp.c
    ${SOURCE_DIR}/demo_netxduo_http.c
    ${SOURCE_DIR}/demo_netxduo_snmp.c
    ${SOURCE_DIR}/demo_netxduo_sntp_client.c
    ${SOURCE_DIR}/demo_netxduo_telnet.c
    ${SOURCE_DIR}/demo_netxduo_tftp.c
    ${SOURCE_DIR}/demo_netx_duo_tcp.c
    ${SOURCE_DIR}/demo_netx_duo_udp.c)

if("-DNX_BSD_ENABLE" IN_LIST ${CMAKE_BUILD_TYPE})
  list(APPEND sample_files ${SOURCE_DIR}/demo_bsd_raw.c
       ${SOURCE_DIR}/demo_bsd_tcp.c ${SOURCE_DIR}/demo_bsd_udp.c)
endif()
if("-DNX_MAX_PHYSICAL_INTERFACES" IN_LIST ${CMAKE_BUILD_TYPE})
  list(APPEND sample_files ${SOURCE_DIR}/demo_netx_duo_multihome_tcp.c
       ${SOURCE_DIR}/demo_netx_duo_multihome_udp.c)
endif()
if(("-DNX_PPP_PPPOE_ENABLE" IN_LIST ${CMAKE_BUILD_TYPE})
   AND NOT ("-DNX_PPPOE_CLIENT_INITIALIZE_DRIVER_ENABLE" IN_LIST
            ${CMAKE_BUILD_TYPE}))
  list(APPEND sample_files ${SOURCE_DIR}/demo_netx_pppoe_client.c
       ${SOURCE_DIR}/demo_netx_pppoe_server.c)
endif()
if(NOT ("-DNX_DISABLE_IPV6" IN_LIST ${CMAKE_BUILD_TYPE}))
  list(APPEND sample_files ${SOURCE_DIR}/demo_netxduo_dhcpv6_client.c)
endif()
if(NOT "-DNX_DISABLE_IPV4" IN_LIST ${CMAKE_BUILD_TYPE})
  list(
    APPEND
    sample_files
    ${SOURCE_DIR}/demo_netxduo_smtp_client.c
    ${SOURCE_DIR}/demo_netxduo_multihome_dhcp_client.c
    ${SOURCE_DIR}/demo_netx_ppp.c
    ${SOURCE_DIR}/demo_netx_duo_ptp_client.c
    ${SOURCE_DIR}/demo_netxduo_dhcp.c
    ${SOURCE_DIR}/demo_netxduo_pop3_client.c
    ${SOURCE_DIR}/demo_netx_auto_ip.c)
endif()
if((NOT "-DNX_DISABLE_IPV4" IN_LIST ${CMAKE_BUILD_TYPE})
    AND NOT ("-DNX_DISABLE_PACKET_CHAIN" IN_LIST ${CMAKE_BUILD_TYPE}))
  list(APPEND sample_files ${SOURCE_DIR}/demo_netx_secure_tls.c)
endif()

if("-DNX_BSD_RAW_SUPPORT" IN_LIST ${CMAKE_BUILD_TYPE})
  set(sample_files "")
endif()

foreach(sample_file ${sample_files})
  get_filename_component(sample_file_name ${sample_file} NAME_WE)
  add_executable(${sample_file_name} ${sample_file})
  target_link_libraries(${sample_file_name} PRIVATE azrtos::${PRODUCT})
endforeach()
```

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

### nx_azure_iot_json_reader_token_string_get

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_json.md

Gets the JSON token's string after unescaping it, if required.

```APIDOC
## nx_azure_iot_json_reader_token_string_get

### Description
Gets the JSON token's string after unescaping it, if required.

### Prototype
```c
UINT nx_azure_iot_json_reader_token_string_get(NX_AZURE_IOT_JSON_READER *reader_ptr,
                                               UCHAR *buffer_ptr, UINT buffer_size, UINT *bytes_copied);
```

### Parameters
- **reader_ptr** (NX_AZURE_IOT_JSON_READER*) - Required - A pointer to an #NX_AZURE_IOT_JSON_READER instance containing the JSON to read.
- **buffer_ptr** (UCHAR*) - Required - A pointer to a buffer where the string should be copied into.
- **buffer_size** (UINT) - Required - The maximum available space within the buffer referred to by buffer_ptr.
- **bytes_copied** (UINT*) - Required - Contains the number of bytes written to the destination which denote the length of the unescaped string.

### Return Values
- NX_AZURE_IOT_SUCCESS - The string is returned.

### Allowed From
Threads

```

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

### Create test utility library and link dependencies

Source: https://github.com/eclipse-threadx/netxduo/blob/master/test/cmake/nx_secure_interoperability/regression/CMakeLists.txt

Creates the test_utility library from test_utility_files, links it to azrtos::netxduo, includes the utility source directory, and defines BATCH_TEST and CTEST compile definitions.

```cmake
add_library(test_utility ${test_utility_files})
target_link_libraries(test_utility PUBLIC azrtos::netxduo)
target_include_directories(test_utility PUBLIC ${UTILITY_SOURCE_DIR})
target_compile_definitions(test_utility PUBLIC BATCH_TEST CTEST)
```

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

### nx_azure_iot_hub_client_properties_version_get prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client_properties.md

Prototype for getting the property version from a properties document.

```c
UINT nx_azure_iot_hub_client_properties_version_get(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
                                                    NX_AZURE_IOT_JSON_READER *reader_ptr,
                                                    UINT message_type, ULONG *version_ptr);
```

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

### nx_azure_iot_log_init

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot.md

Initializes logging with a customer-specific callback for outputting logs by classification.

```APIDOC
## nx_azure_iot_log_init

### Description
Initializes logging with a customer-specific callback to output logs for different classifications. Supported classifications include AZ_LOG_IOT_AZURERTOS, AZ_LOG_MQTT_RECEIVED_TOPIC, AZ_LOG_MQTT_RECEIVED_PAYLOAD, AZ_LOG_IOT_RETRY, and AZ_LOG_IOT_SAS_TOKEN.

### Prototype
```c
VOID nx_azure_iot_log_init(VOID(*log_callback)(az_log_classification classification, UCHAR *msg, UINT msg_len));
```

### Parameters
- **log_callback** (function pointer) - Required - A pointer to a callback.

### Allowed From
Threads
```

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

### nx_azure_iot_json_reader_token_int32_get

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_json.md

Gets the JSON token's number as a 32-bit signed integer.

```APIDOC
## nx_azure_iot_json_reader_token_int32_get

### Description
Gets the JSON token's number as a 32-bit signed integer.

### Prototype
```c
UINT nx_azure_iot_json_reader_token_int32_get(NX_AZURE_IOT_JSON_READER *reader_ptr,
                                              int32_t *value_ptr);
```

### Parameters
- **reader_ptr** (NX_AZURE_IOT_JSON_READER*) - Required - A pointer to an #NX_AZURE_IOT_JSON_READER instance containing the JSON to read.
- **value_ptr** (int32_t*) - Required - A pointer to a variable to receive the value.

### Return Values
- NX_AZURE_IOT_SUCCESS - The number is returned.

### Allowed From
Threads

```

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

### nx_azure_iot_log_init prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot.md

Prototype for initializing logging with a custom callback. Use this to set up logging for different Azure IoT classifications.

```c
VOID nx_azure_iot_log_init(VOID(*log_callback)(az_log_classification classification, UCHAR *msg, UINT msg_len));
```

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

### nx_azure_iot_json_reader_token_uint32_get

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_json.md

Gets the JSON token's number as a 32-bit unsigned integer.

```APIDOC
## [C] nx_azure_iot_json_reader_token_uint32_get

### Description
Gets the JSON token's number as a 32-bit unsigned integer.

### Method
C function

### Prototype
```c
UINT nx_azure_iot_json_reader_token_uint32_get(NX_AZURE_IOT_JSON_READER *reader_ptr,
                                               uint32_t *value_ptr);
```

### Parameters
- **reader_ptr** (NX_AZURE_IOT_JSON_READER *) - Input - A pointer to an #NX_AZURE_IOT_JSON_READER instance containing the JSON to read.
- **value_ptr** (uint32_t *) - Output - A pointer to a variable to receive the value.

### Return Values
- NX_AZURE_IOT_SUCCESS - The value is returned.

### Allowed From
Threads

### Example
(Not provided)

### See Also
(Not provided)
```

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

### nx_azure_iot_json_writer_init Prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_json.md

Initializes an NX_AZURE_IOT_JSON_WRITER that writes JSON text into an NX_PACKET. The writer is initialized with a pointer to the writer instance, a packet pointer, and a wait option for allocating the next packet. Returns NX_AZURE_IOT_SUCCESS on success.

```c
UINT nx_azure_iot_json_writer_init(NX_AZURE_IOT_JSON_WRITER *json_writer_ptr,
                                   NX_PACKET *packet_ptr, UINT wait_option);
```

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

### nx_azure_iot_hub_client_properties_version_get

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client_properties.md

Gets the property version from a properties document. The version is stored in the provided pointer.

```APIDOC
## [FUNCTION] nx_azure_iot_hub_client_properties_version_get

### Description
Gets the property version from a properties document. The version is stored in the provided pointer.

### Prototype
```c
UINT nx_azure_iot_hub_client_properties_version_get(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
                                                    NX_AZURE_IOT_JSON_READER *reader_ptr,
                                                    UINT message_type, ULONG *version_ptr);
```

### Parameters
- **hub_client_ptr** (NX_AZURE_IOT_HUB_CLIENT*) - Required - A pointer to a `NX_AZURE_IOT_HUB_CLIENT`.
- **reader_ptr** (NX_AZURE_IOT_JSON_READER*) - Required - A pointer to a #NX_AZURE_IOT_JSON_READER containing properties document.
- **message_type** (UINT) - Required - Type of message response, only valid values are NX_AZURE_IOT_HUB_PROPERTIES or NX_AZURE_IOT_HUB_WRITABLE_PROPERTIES.
- **version_ptr** (ULONG*) - Required - The numeric version of the properties in JSON payload.

### Return Values
- NX_AZURE_IOT_SUCCESS - Successful if got the property version.

### Allowed From
Threads

### Example
(No example provided in source.)

### See Also
(No additional references provided in source.)
```

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

### nx_azure_iot_json_writer_with_buffer_init Prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_json.md

Initializes an NX_AZURE_IOT_JSON_WRITER that writes JSON text into a caller-provided buffer. The writer is initialized with a pointer to the writer instance, a buffer pointer, and the buffer length. Returns NX_AZURE_IOT_SUCCESS on success.

```c
UINT nx_azure_iot_json_writer_with_buffer_init(NX_AZURE_IOT_JSON_WRITER *json_writer_ptr,
                                               UCHAR *buffer_ptr, UINT buffer_len);
```

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

### nx_azure_iot_hub_client_properties_component_property_next_get prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client_properties.md

Prototype for getting the next desired or reported property in a properties document.

```c
UINT nx_azure_iot_hub_client_properties_component_property_next_get(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
                                                                    NX_AZURE_IOT_JSON_READER *reader_ptr,
                                                                    UINT message_type, UINT property_type,
                                                                    const UCHAR **component_name_pptr,
                                                                    USHORT *component_name_length_ptr);
```

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

### Configure DPS with symmetric key macros

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/samples/README.md

Defines the required macros for DPS symmetric key enrollment. Replace placeholders with actual values from the provisioning service overview and individual enrollment pages. Enable DPS by defining ENABLE_DPS_SAMPLE.

```c
#define ENDPOINT                                    "<Service Endpoint or Global device endpoint from Provisioning service overview page>"
#define ID_SCOPE                                    "<ID Scope value from Provisioning service overview page>"
#define REGISTRATION_ID                             "<RegistrationId provide when doing Individual registration>"
#define DEVICE_SYMMETRIC_KEY                        "<Symmetric key from Individual registration detail page>"

/* Enable DPS */
#define ENABLE_DPS_SAMPLE
```

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

### Reported property status payload without component

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client_properties.md

Example of the JSON payload structure for a property status without a component.

```c
//{
//  "<property_name>":{
//    "ac": <status_code>,
//    "av": <version>,
//    "ad": "<description>",
//    "value": <user_value>
//  }
//}
```

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

### nx_azure_iot_hub_client_cloud_message_enable prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client.md

Prototype for enabling cloud-to-device (C2D) message reception from Azure IoT Hub. Call this to start receiving C2D messages.

```c
UINT nx_azure_iot_hub_client_cloud_message_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr);
```

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

### Build NetX Duo static library for Cortex-M4

Source: https://github.com/eclipse-threadx/netxduo/blob/master/README.md

Configures and builds the NetX Duo library as a standalone static library for the Cortex-M4 target using CMake and Ninja. The first command sets up the build directory with the toolchain file, and the second builds the library.

```bash
$ cmake -Bbuild -GNinja -DCMAKE_TOOLCHAIN_FILE=cmake/cortex_m4.cmake .
```

```bash
$ cmake --build ./build
```

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

### nx_azure_iot_provisioning_client_iothub_device_info_get prototype

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_provisioning_client.md

Prototype for retrieving IoTHub device info into user-supplied buffers. Returns NX_AZURE_IOT_SUCCESS on success, or NX_AZURE_IOT_INVALID_PARAMETER, NX_AZURE_IOT_WRONG_STATE, or NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE on failure.

```c
UINT nx_azure_iot_provisioning_client_iothub_device_info_get(NX_AZURE_IOT_PROVISIONING_CLIENT *prov_client_ptr,
                                                             UCHAR *iothub_hostname, UINT *iothub_hostname_len,
                                                             UCHAR *device_id, UINT *device_id_len);
```

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

### Reported property status with component API call flow

Source: https://github.com/eclipse-threadx/netxduo/blob/master/addons/azure_iot/docs/azure_rtos_iot_hub_client_properties.md

Example of the API call flow for sending a property status for a component, including the generated JSON payload.

```c
nx_azure_iot_hub_client_reported_properties_component_begin()
nx_azure_iot_hub_client_reported_properties_status_begin()
// Append user value here (<user_value>)
nx_azure_iot_hub_client_reported_properties_status_end()
nx_azure_iot_hub_client_reported_properties_component_end()

//{
//  "<component_name>": {
//    "__t": "c",
//    "<property_name>": {
//      "ac": <status_code>,
//      "av": <version>,
//      "ad": "<description>",
//      "value": <user_value>
//    }
//  }
//}
```