Connecting a LoLin NodeMcu v3 IoT to the Azure IoT Hub using the Arduino IDE

An overview of how to connect a LoLin NodeMCU v3 IoT device to the Azure IoT Hub using the Arduino IDE.

The Azure IoT Hub provides a cloud-hosted solution back-end to connect backend applications with IoT devices.

The LoLin NodeMCU v3 device is a wireless IoT device based on the ESP8266 microchip. For more info see First Impressions of the LoLin MCUv3 

The high-level steps to connect the LoLin NodeMCU IoT to the Azure IoT cloud are

1. Create an Azure IoT Hub service (Azure offers a basic free version)
2. Manually register a device with your Azure IoT Hub service (easily done in the Azure portal)
   
3. Install the Arduino IDE and install the Azure IoT libraries via the Arduino IDE library manager
   
4. Use the Azure IoT device SDK for C to write a program for the device to connect to your Azure IoT Hub service or use the Microsoft provided sample program.
   

For steps 1 to 3 refer to the following guide for step by step instructions to setup an Azure IoT Hub, register a LoLin device, setup the Arduino libraries and run your first IoT program

Azure IoTHub setup instructions for Arduino environment

 

Microsoft Azure IoT C SDK

Microsoft publish a C SDK that supports a wide range of IoT devices including the LoLin NodeMCU. Developers can use this C SDK to develop programs to connect devices to the Azure IoT Hub.

The LoLin NodeMCU is based on the ESP8266 Microcontroller (MCU) and is what Microsoft call a constrained device in that it has comparatively limited resources, such as memory, compared to devices based on a CPU.

The Azure IoT C SDK includes a version that is optimised to run on constrained devices. For example, it is single threaded whereas some of the functions in the unconstrained version will spin up seperate threads to complete jobs in the background.

These C libraries need to be installed in the Arduino IDE environment using its Library Manager as explained in the guide above. Once installed we can include these libraries in our programs with

#include <AzureIoTHub.h>

Azure IoT SDK for C developer documentation 

Microsoft publish a detailed developer how-to guide for the Azure IoT device SDK which explains how to use the API with examples. Find it here Dev guide for the Azure IoT device SDK for C     

The Azure IoT SDK reference provides detailed information on the C library functions and data structures and can be found on GitHub here Github for Azure IoT C SDKs and Libraries

Sample program

Microsoft provide a sample program 'iothub_ll_telemetry_sample' to demonstrate use of the Azure IoT SDK on the ESP8266. 

The key functions called by the demo program are

esp8266_sample_init(const char* ssid, const char* password)
Connect to wLAN

 

IoTHub_Init() 

Initialise the IoTHub client system

 

device_ll_handle = IoTHubDeviceClient_LL_CreateFromConnectionString(connectionString, protocol)
Creates a IoT Hub client for communication with an existing IoT Hub using the specified connection string parameter.

 

 IoTHubDeviceClient_LL_SetOption(device_ll_handle, OPTION_TRUSTED_CERT, certificates)

Set the Azure Server certificate used to validate TLS connection to iothub

 

 message_handle = IoTHubMessage_CreateFromString(telemetry_msg)

Creates a new IoT hub message from a null terminated string. The type of the message will be set to IOTHUBMESSAGE_STRING

 

IoTHubDeviceClient_LL_SendEventAsync(device_ll_handle, message_handle, send_confirm_callback, NULL)

Asynchronous call to send the message specified by eventMessageHandle

The call back mesage 'send_confirm_callback' is called with the results of the message transmission. 

 

IoTHubDeviceClient_LL_DoWork

This function MUST be called by the user so work (sending/receiving data on the wire, computing and enforcing timeout controls, managing the connection to the IoT Hub) can be done by the IoTHubClient. The recommended call frequency is at least once every 100 milliseconds.

 

In the demo program it attempts to send several messages and once sent counts the number of times the call_back function is called. Once the number of call backs equals the total number of messages sent it exits. Throughout it is calling the Do Work function.