Create a Cloud Connector

Cloud connectors are a feature of the Zentri Device Management Service (DMS) that provides a secure authenticated connection between a device and a 3rd party cloud service such as Amazon Web Services, Microsoft Azure, and more. In this section of the tutorial, you will learn how to create a cloud connector and use it to send data to a cloud application called Graffiti located at https://graffiti.zentri.com. Graffiti enables a way to quickly evaluate and demonstrate DMS cloud connectors. It is not a production cloud application and cannot be used for real-world IoT application.

Note! Before continuing complete the basic tutorial found here: Native C Application Development Tutorial. This section will build upon the steps found in that tutorial.

The source code for the completed could connector tutorial can be found here: main.c.

Create a Cloud Connector on DMS

STEP 1. As discussed in Setting up your device for development, a development product for your device is automatically created on the DMS when you set up the device. To set up a cloud connector, first log into DMS and view your development products.

STEP 2. Click on the <User Code>-WEATHER project then select Connectors.

STEP 3. Select the Create Connector button then create a connector as shown below.

FieldDescription
TitleEnter a title for your connector
CodeA code used to identify the Connector for the product. The code must be unique for YOUR Product and becomes part of the cloud URL where the sensor data is accessed online. The example below uses the customer code to make the unique code 03MWMCWEATHER but this code can be anything as long as it is unique.
TypeWebhook
EndpointREST
URLhttps://graffiti.zentri.com/connector/<code> where <code> matches the code entered above; when used with a Graffiti URL, the otherwise case-sensitive code is automatically converted to lower case
AuthenticationNone

STEP 4. Select Save

Send Data to the Connector

Modify the function read_and_report_event_handler() to post data to the cloud connector as shown below. The changes are highlighted in blue.

Note! The cloud connector <code> created in the previous step is used again in the source-code below. Change the highlighted source to exactly match the <code> for the DMS connector created in the previous section. The <code> is case-sensitive.


static void read_and_report_event_handler(void *arg)
{ gos_result_t result = GOS_SUCCESS;
    uint32_t rh_data;
    int32_t temp_data;
    char temp_float_str[10];
    char rh_float_str[10];
    gos_msgpack_context_t *weather_msgpack = NULL;
    const gos_dms_messsage_config_t config =
    {
      .length                 = 0,
      .is_response            = false,
      .response.handler       = 0,
      .response.timeout_ms    = 90000     //90 second timeout
    };

    //Read the measurement results
    Si7013_ReadNoHoldRHAndTemp(&si7021_device, 0, &rh_data, &temp_data);

    //Format the results to a floating point number and output to the console
    GOS_LOG("Temp: %s C | RH: %s %%",
             float_to_str((float)(temp_data/1000.0), temp_float_str, 1),
             float_to_str((float)(rh_data/1000.0), rh_float_str, 1));

    // Initialize the write context
    if(GOS_FAILED(result, gos_dms_message_write_init(&weather_msgpack, &config)))
    { GOS_LOG("Failed to initialize DMS message.  Error %d", result);
      return;
    }

    gos_msgpack_write_dict_marker(weather_msgpack, 3);
    gos_msgpack_write_dict_str(weather_msgpack, "request", "webhook");      // the connector is of type webhook
    gos_msgpack_write_dict_str(weather_msgpack, "code", "03MWMCWEATHER");   // code must match connector setup on DMS
    gos_msgpack_write_dict_dict(weather_msgpack, "data", 2);                // container for the data

    // Add ambient light data to the msgpack
    gos_msgpack_write_dict_dict(weather_msgpack, "Temperature", 5);
    gos_msgpack_write_dict_str(weather_msgpack, "value", temp_float_str);
    gos_msgpack_write_dict_str(weather_msgpack, "min", "0");
    gos_msgpack_write_dict_str(weather_msgpack, "max", "50");
    gos_msgpack_write_dict_str(weather_msgpack, "units", "");
    gos_msgpack_write_dict_str(weather_msgpack, "precision", "1");

    // Add prox data to the msgpack
    gos_msgpack_write_dict_dict(weather_msgpack, "Humidity", 5);
    gos_msgpack_write_dict_str(weather_msgpack, "value", rh_float_str);
    gos_msgpack_write_dict_str(weather_msgpack, "min", "0");
    gos_msgpack_write_dict_str(weather_msgpack, "max", "1000");
    gos_msgpack_write_dict_str(weather_msgpack, "units", "");
    gos_msgpack_write_dict_str(weather_msgpack, "precision", "1");

    // Send the message to the DMS
    if(GOS_FAILED(result, gos_dms_message_write_flush(weather_msgpack)))
    {
      GOS_LOG("Failed to flush DMS message.  Error %d", result);
      gos_dms_message_context_destroy(weather_msgpack);
      return;
    }

    GOS_LOG("Posting sensor data to the cloud via a DMS Cloud Connector");

}

Configure the Application to Connect to DMS

Configure the device to automatically connect to DMS using the Gecko OS setting dms.auto_start_enabled. This can be set by typing the command set dms.auto_start_enabled 1 then save in the device console or by changing the default of this setting for you application by adding dms.auto_start_enabled 1 to your settings.ini file as discussed here: Configuring Gecko OS for your Application.

View the Sensor Data in the Cloud Service

Build and download the application to the device. Then using a browser, go to https://graffiti.zentri.com/<code> where <code> is the same code used for the cloud connector (the code should be lower case in the URL!). Weather data from your board should appear similar to the screen capture below.

Troubleshooting Tips

If the https://graffiti.zentri.com/<code> page displays a simple black screen then it is not receiving any data. If this occurs, double check the following:

  • Log into DMS and verify that the connector is setup properly as described above
  • Verify that the <code> used in the connector and in the source code is exactly the same. Note that the <code> is case-sensitive.
  • Verify that the graffiti URL used is correct as https://graffiti.zentri.com/<code>
  • Log into DMS and verify that the device is activated to the correct DMS product. More information on how to activate a device to a particular product can be found at Sharing Your Development Product with Other Users or Other Devices.
  • Verify that the application is not reporting any error messages.