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:
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.
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.
Developers can refer to the Azure RTOS Device Samples for Verified Telemetry sample code.
-
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)
-
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
-
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))