Overview

This is the companion API documentation for the Verified Telemetry GitHub Repository.

The following API documentation outlines the structure for both the Azure RTOS and the FreeRTOS Verified Telemetry SDK:

Library Structure

The Verified Telemetry library has been structured around the following components:

core
Core functions to support verified telemetry, such as functions to collect, validate and evaluate sensor fingerprints.

middleware
The implementations to support interactions with Azure IoT Middleware for Azure RTOS and FreeRTOS.

platform
The hardware compatibility layer.

File Structure

The file structure is as follows:

inc/
Contains header files for core, middleware and platform components.

src/
Contains the library implementations.

PnPModel/
Contains sample Plug and Play device models to support Verified Telemetry.

Azure RTOS integration guide

Developers can refer to the Azure RTOS Device Samples for Verified Telemetry sample code.

Step 1 - Include Verified Telemetry library

In the root folder, run the following command

 git submodule add https://github.com/Azure/Verified-Telemetry.git core/lib/verified-telemetry

Include library files in getting-started/MXChip/AZ3166/lib/CMakeLists.txt

 add_subdirectory(${CORE_LIB_DIR}/verified-telemetry verified_telemetry)

Step 2 - Initialize Verified Telemetry

Global Verified Telemetry needs to be initialized with the device specific platform functions
Similarly, to initialize Verified Telemetry for a particular sensor/telemetry the details of sensor connection must be passed using the nx_vt_signature_init function
An example of usage of nx_vt_init and nx_vt_signature_init functions is shown below
Include headers for VT
```
 #include "nx_verified_telemetry.h"
```
Include header which define platform specific device drivers
```
 #include "sample_vt_device_driver.h"
```
Define Verified Telemetry DB which will store configuration, platform specific device drivers and runtime information
```
 static NX_VERIFIED_TELEMETRY_DB verified_telemetry_DB;
```
Define variable of VT_DEVICE_DRIVER type which will contain pointers to platform specific functions required by VT
```
 static VT_DEVICE_DRIVER sample_device_driver;
```
Define scratch buffer of length VT_RECOMMENDED_BUFFER_SIZE_BYTES (2500 bytes). Thus buffer would be used by the library to store runtime signatures
```
 static char scratch_buffer[VT_RECOMMENDED_BUFFER_SIZE_BYTES];
```

Define a variables of NX_VT_OBJECT type for each telemetry that will be supporting Verified Telemetry

 static NX_VT_OBJECT sample_signature_sensor_1;
 // static NX_VT_OBJECT sample_signature_sensor_2;
 static NX_VT_OBJECT sample_signature_sensor_N;

Define variables of VT_SENSOR_HANDLE type which will contain connection information for each sensor

static VT_SENSOR_HANDLE sample_handle_sensor_1;
// static VT_SENSOR_HANDLE sample_handle_sensor_2;
static VT_SENSOR_HANDLE sample_handle_sensor_N;

Define a Verified Telemetry User Initialization wrapper function which will make calls to necessary initialization function from the vT library and return pointer to the configured NX_VERIFIED_TELEMETRY_DB variable

NX_VERIFIED_TELEMETRY_DB* sample_nx_verified_telemetry_user_init()
{
    UINT status;

    sample_device_driver.adc_init          = &vt_adc_init;
    sample_device_driver.adc_read          = &vt_adc_read;
    sample_device_driver.gpio_on           = &vt_gpio_on;
    sample_device_driver.gpio_off          = &vt_gpio_off;
    sample_device_driver.tick_init         = &vt_tick_init;
    sample_device_driver.tick_deinit       = &vt_tick_deinit;
    sample_device_driver.tick              = &vt_tick;
    sample_device_driver.interrupt_enable  = &vt_interrupt_enable;
    sample_device_driver.interrupt_disable = &vt_interrupt_disable;

    if ((status = nx_vt_init(&verified_telemetry_DB, (UCHAR*)"vTDevice", true, &sample_device_driver, scratch_buffer)))
    {
        printf("Failed to configure Verified Telemetry settings: error code = 0x%08x\r\n", status);
    }

    sample_handle_sensor_1.adc_id         = vt_adc_id_sensor_1;
    sample_handle_sensor_1.adc_controller = (void*)&vt_adc_controller_sensor_1;
    sample_handle_sensor_1.adc_channel    = (void*)&vt_adc_channel_sensor_1;
    sample_handle_sensor_1.gpio_id        = vt_gpio_id_sensor_1;
    sample_handle_sensor_1.gpio_port      = (void*)vt_gpio_port_sensor_1;
    sample_handle_sensor_1.gpio_pin       = (void*)&vt_gpio_pin_sensor_1;

    if ((status = nx_vt_signature_init(&verified_telemetry_DB,
        &sample_signature_sensor_1,
        (UCHAR*)"soilMoistureExternal1",
        VT_SIGNATURE_TYPE_FALLCURVE,
        (UCHAR*)"soilMoistureExternal1",
        true,
        &sample_handle_sensor_1)))
    {
        printf("Failed to initialize VT for soilMoistureExternal1 telemetry: error code = 0x%08x\r\n", status);
    }

    return (&verified_telemetry_DB);
}

Call the Verified Telemetry User Initialization wrapper function and update verified_telemetry_DB
```
verified_telemetry_DB = sample_pnp_verified_telemetry_user_init();
```
A complete sample can be found here

Step 3 - Use VT Middleware APIs based on the following guidelines

Use this function to initialize VT PnP Components

 nx_vt_azure_iot_pnp_client_component_add(verified_telemetry_DB, iotpnp_client_ptr)

Call these functions once after boot

 nx_vt_send_desired_property_after_boot(verified_telemetry_DB, pnp_client_ptr, message_type)

 nx_vt_process_reported_property_sync(
     verified_telemetry_DB, pnp_client_ptr, component_ptr, component_len, &name_value_reader, version)

Call these functions at fixed time intervals

 nx_vt_properties(verified_telemetry_DB, &(context->iotpnp_client))

 nx_vt_compute_evaluate_fingerprint_all_sensors(verified_telemetry_DB)

Use this function to send telemetry

 nx_vt_verified_telemetry_message_create_send(handle->verified_telemetry_DB,
     iotpnp_client_ptr,
     handle->component_name_ptr,
     handle->component_name_length,
     NX_WAIT_FOREVER,
     (UCHAR*)scratch_buffer,
     buffer_length)

Desired Property Callback

 nx_vt_process_property_update(
     verified_telemetry_DB, pnp_client_ptr, component_ptr, component_len, &name_value_reader, version)

Command Callback

 nx_vt_process_command(verified_telemetry_DB,
     &(sample_context_ptr->iotpnp_client),
     UCHAR*)component_name_ptr,
     component_name_length,
     (UCHAR*)pnp_command_name_ptr,
     pnp_command_name_length,
     &json_reader,
     &json_writer,
     &status_code))