Tutorial: Develop IoT Edge modules using Visual Studio Code

• .NET Core SDK
• C# Visual Studio Code extension

• C/C++ Visual Studio Code extension
• Installing the Azure IoT C SDK isn't required for this tutorial, but can provide helpful functionality like IntelliSense and reading program definitions. For installation information, see Azure IoT C SDKs and Libraries.

• Java SE Development Kit 11 and Maven. You need to set the JAVA_HOME environment variable to point to your JDK installation.
• Maven
• Java Extension Pack for Visual Studio Code

• Node.js.
• Yeoman
• Azure IoT Edge Node.js Module Generator.

To develop an IoT Edge module in Python, install these extra prerequisites on your development machine:

• Python and Pip.
• Cookiecutter.
• Python extension for Visual Studio Code.

The sample C# code that comes with the project template uses the ModuleClient Class from the IoT Hub SDK for .NET.

1. In the Visual Studio Code explorer, open modules > filtermodule > ModuleBackgroundService.cs.

2. Before the filtermodule namespace, add three using statements for types that are used later:

   using System.Collections.Generic;     // For KeyValuePair<>
   using Microsoft.Azure.Devices.Shared; // For TwinCollection
   using Newtonsoft.Json;                // For JsonConvert
   

3. Add the temperatureThreshold variable to the ModuleBackgroundService class. This variable sets the value that the measured temperature must exceed for the data to be sent to the IoT Hub.

   static int temperatureThreshold { get; set; } = 25;
   

4. Add the MessageBody, Machine, and Ambient classes. These classes define the expected schema for the body of incoming messages.

   class MessageBody
   {
       public Machine machine {get;set;}
       public Ambient ambient {get; set;}
       public string timeCreated {get; set;}
   }
   class Machine
   {
       public double temperature {get; set;}
       public double pressure {get; set;}
   }
   class Ambient
   {
       public double temperature {get; set;}
       public int humidity {get; set;}
   }
   

5. Find the ExecuteAsync function. This function creates and configures a ModuleClient object that allows the module to connect to the local Azure IoT Edge runtime to send and receive messages. After creating the ModuleClient, the code reads the temperatureThreshold value from the module twin's desired properties. The code registers a callback to receive messages from an IoT Edge hub via an endpoint called input1.

   Replace the call to the ProcessMessageAsync method with a new one that updates the name of the endpoint and the method that's called when input arrives. Also, add a SetDesiredPropertyUpdateCallbackAsync method for updates to the desired properties. To make this change, replace the last line of the ExecuteAsync method with the following code:

   // Register a callback for messages that are received by the module.
   // await _moduleClient.SetInputMessageHandlerAsync("input1", PipeMessage, cancellationToken);
   
   // Read the TemperatureThreshold value from the module twin's desired properties
   var moduleTwin = await _moduleClient.GetTwinAsync();
   await OnDesiredPropertiesUpdate(moduleTwin.Properties.Desired, _moduleClient);
   
   // Attach a callback for updates to the module twin's desired properties.
   await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertiesUpdate, null);
   
   // Register a callback for messages that are received by the module. Messages received on the inputFromSensor endpoint are sent to the FilterMessages method.
   await _moduleClient.SetInputMessageHandlerAsync("inputFromSensor", FilterMessages, _moduleClient);
   

6. Add the onDesiredPropertiesUpdate method to the ModuleBackgroundService class. This method receives updates on the desired properties from the module twin, and updates the temperatureThreshold variable to match. All modules have their own module twin, which lets you configure the code that's running inside a module directly from the cloud.

   static Task OnDesiredPropertiesUpdate(TwinCollection desiredProperties, object userContext)
   {
       try
       {
           Console.WriteLine("Desired property change:");
           Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
   
           if (desiredProperties["TemperatureThreshold"]!=null)
               temperatureThreshold = desiredProperties["TemperatureThreshold"];
   
       }
       catch (AggregateException ex)
       {
           foreach (Exception exception in ex.InnerExceptions)
           {
               Console.WriteLine();
               Console.WriteLine("Error when receiving desired property: {0}", exception);
           }
       }
       catch (Exception ex)
       {
           Console.WriteLine();
           Console.WriteLine("Error when receiving desired property: {0}", ex.Message);
       }
       return Task.CompletedTask;
   }
   

7. Add the FilterMessages method. This method is called whenever the module receives a message from the IoT Edge hub. It filters out messages that report temperatures below the temperature threshold set via the module twin. It also adds the MessageType property to the message with the value set to Alert.

   async Task<MessageResponse> FilterMessages(Message message, object userContext)
   {
       var counterValue = Interlocked.Increment(ref _counter);
       try
       {
           ModuleClient moduleClient = (ModuleClient)userContext;
           var messageBytes = message.GetBytes();
           var messageString = Encoding.UTF8.GetString(messageBytes);
           Console.WriteLine($"Received message {counterValue}: [{messageString}]");
   
           // Get the message body.
           var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);
   
           if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
           {
               Console.WriteLine($"Machine temperature {messageBody.machine.temperature} " +
                   $"exceeds threshold {temperatureThreshold}");
               using (var filteredMessage = new Message(messageBytes))
               {
                   foreach (KeyValuePair<string, string> prop in message.Properties)
                   {
                       filteredMessage.Properties.Add(prop.Key, prop.Value);
                   }
   
                   filteredMessage.Properties.Add("MessageType", "Alert");
                   await moduleClient.SendEventAsync("output1", filteredMessage);
               }
           }
   
           // Indicate that the message treatment is completed.
           return MessageResponse.Completed;
       }
       catch (AggregateException ex)
       {
           foreach (Exception exception in ex.InnerExceptions)
           {
               Console.WriteLine();
               Console.WriteLine("Error in sample: {0}", exception);
           }
           // Indicate that the message treatment is not completed.
           var moduleClient = (ModuleClient)userContext;
           return MessageResponse.Abandoned;
       }
       catch (Exception ex)
       {
           Console.WriteLine();
           Console.WriteLine("Error in sample: {0}", ex.Message);
           // Indicate that the message treatment is not completed.
           ModuleClient moduleClient = (ModuleClient)userContext;
           return MessageResponse.Abandoned;
       }
   }
   

8. Save the ModuleBackgroundService.cs file.

9. In the Visual Studio Code explorer, open the deployment.template.json file in your IoT Edge solution workspace.

10. Since we changed the name of the endpoint that the module listens on, we also need to update the routes in the deployment manifest so that the edgeHub sends messages to the new endpoint.

    Find the routes section in the $edgeHub module twin. Update the sensorTofiltermodule route to replace input1 with inputFromSensor:

    "sensorTofiltermodule": "FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/inputFromSensor\")"
    

11. Add the filtermodule module twin to the deployment manifest. Insert the following JSON content at the bottom of the modulesContent section, after the $edgeHub module twin:

       "filtermodule": {
           "properties.desired":{
               "TemperatureThreshold":25
           }
       }
    

12. Save the deployment.template.json file.

1. The data from the sensor in this scenario comes in JSON format. To filter messages in JSON format, import a JSON library for C. This tutorial uses Parson.

   1. Download the Parson GitHub repository. Copy the parson.c and parson.h files into the filtermodule folder.

   2. Open modules > filtermodule > CMakeLists.txt. At the top of the file, import the Parson files as a library called my_parson.

      add_library(my_parson
          parson.c
          parson.h
      )
      

   3. Add my_parson to the list of libraries in the target_link_libraries function of CMakeLists.txt.

   4. Save the CMakeLists.txt file.

   5. Open modules > filtermodule > main.c. At the bottom of the list of include statements, add a new one to include parson.h for JSON support:

      #include "parson.h"
      

2. In the main.c file, add a global variable called temperatureThreshold after the include section. This variable sets the value that the measured temperature must exceed in order for the data to be sent to IoT Hub.

   static double temperatureThreshold = 25;
   

3. Find the CreateMessageInstance function in main.c. Replace the inner if-else statement with the following code that adds a few lines of functionality:

       if ((messageInstance->messageHandle = IoTHubMessage_Clone(message)) == NULL)
       {
           free(messageInstance);
           messageInstance = NULL;
       }
       else
       {
           messageInstance->messageTrackingId = messagesReceivedByInput1Queue;
           MAP_HANDLE propMap = IoTHubMessage_Properties(messageInstance->messageHandle);
           if (Map_AddOrUpdate(propMap, "MessageType", "Alert") != MAP_OK)
           {
              printf("ERROR: Map_AddOrUpdate Failed!\r\n");
           }
       }
   

   The new lines of code in the else statement add a new property to the message, which labels the message as an alert. This code labels all messages as alerts, because we'll add functionality that only sends messages to IoT Hub if they report high temperatures.

4. Replace the entire InputQueue1Callback function with the following code. This function implements the actual messaging filter. When a message is received, it checks whether the reported temperature exceeds the threshold. If yes, then it forwards the message through its output queue. If not, then it ignores the message.

   static unsigned char *bytearray_to_str(const unsigned char *buffer, size_t len)
   {
       unsigned char *ret = (unsigned char *)malloc(len + 1);
       memcpy(ret, buffer, len);
       ret[len] = '\0';
       return ret;
   }
   
   static IOTHUBMESSAGE_DISPOSITION_RESULT InputQueue1Callback(IOTHUB_MESSAGE_HANDLE message, void* userContextCallback)
   {
       IOTHUBMESSAGE_DISPOSITION_RESULT result;
       IOTHUB_CLIENT_RESULT clientResult;
       IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle = (IOTHUB_MODULE_CLIENT_LL_HANDLE)userContextCallback;
   
       unsigned const char* messageBody;
       size_t contentSize;
   
       if (IoTHubMessage_GetByteArray(message, &messageBody, &contentSize) == IOTHUB_MESSAGE_OK)
       {
           messageBody = bytearray_to_str(messageBody, contentSize);
       } else
       {
           messageBody = "<null>";
       }
   
       printf("Received Message [%zu]\r\n Data: [%s]\r\n",
               messagesReceivedByInput1Queue, messageBody);
   
       // Check if the message reports temperatures higher than the threshold
       JSON_Value *root_value = json_parse_string(messageBody);
       JSON_Object *root_object = json_value_get_object(root_value);
       double temperature;
       if (json_object_dotget_value(root_object, "machine.temperature") != NULL && (temperature = json_object_dotget_number(root_object, "machine.temperature")) > temperatureThreshold)
       {
           printf("Machine temperature %f exceeds threshold %f\r\n", temperature, temperatureThreshold);
           // This message should be sent to next stop in the pipeline, namely "output1".  What happens at "output1" is determined
           // by the configuration of the Edge routing table setup.
           MESSAGE_INSTANCE *messageInstance = CreateMessageInstance(message);
           if (NULL == messageInstance)
           {
               result = IOTHUBMESSAGE_ABANDONED;
           }
           else
           {
               printf("Sending message (%zu) to the next stage in pipeline\n", messagesReceivedByInput1Queue);
   
               clientResult = IoTHubModuleClient_LL_SendEventToOutputAsync(iotHubModuleClientHandle, messageInstance->messageHandle, "output1", SendConfirmationCallback, (void *)messageInstance);
               if (clientResult != IOTHUB_CLIENT_OK)
               {
                   IoTHubMessage_Destroy(messageInstance->messageHandle);
                   free(messageInstance);
                   printf("IoTHubModuleClient_LL_SendEventToOutputAsync failed on sending msg#=%zu, err=%d\n", messagesReceivedByInput1Queue, clientResult);
                   result = IOTHUBMESSAGE_ABANDONED;
               }
               else
               {
                   result = IOTHUBMESSAGE_ACCEPTED;
               }
           }
       }
       else
       {
           printf("Not sending message (%zu) to the next stage in pipeline.\r\n", messagesReceivedByInput1Queue);
           result = IOTHUBMESSAGE_ACCEPTED;
       }
   
       messagesReceivedByInput1Queue++;
       return result;
   }
   

5. Add a moduleTwinCallback function. This method receives updates on the desired properties from the module twin, and updates the temperatureThreshold variable to match. All modules have their own module twin, which lets you configure the code running inside a module directly from the cloud.

   static void moduleTwinCallback(DEVICE_TWIN_UPDATE_STATE update_state, const unsigned char* payLoad, size_t size, void* userContextCallback)
   {
       printf("\r\nTwin callback called with (state=%s, size=%zu):\r\n%s\r\n",
           MU_ENUM_TO_STRING(DEVICE_TWIN_UPDATE_STATE, update_state), size, payLoad);
       JSON_Value *root_value = json_parse_string(payLoad);
       JSON_Object *root_object = json_value_get_object(root_value);
       if (json_object_dotget_value(root_object, "desired.TemperatureThreshold") != NULL) {
           temperatureThreshold = json_object_dotget_number(root_object, "desired.TemperatureThreshold");
       }
       if (json_object_get_value(root_object, "TemperatureThreshold") != NULL) {
           temperatureThreshold = json_object_get_number(root_object, "TemperatureThreshold");
       }
   }
   

6. Find the SetupCallbacksForModule function. Replace the function with the following code that adds an else if statement to check if the module twin is updated.

   static int SetupCallbacksForModule(IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle)
   {
       int ret;
   
       if (IoTHubModuleClient_LL_SetInputMessageCallback(iotHubModuleClientHandle, "input1", InputQueue1Callback, (void*)iotHubModuleClientHandle) != IOTHUB_CLIENT_OK)
       {
           printf("ERROR: IoTHubModuleClient_LL_SetInputMessageCallback(\"input1\")..........FAILED!\r\n");
           ret = MU_FAILURE;
       }
       else if (IoTHubModuleClient_LL_SetModuleTwinCallback(iotHubModuleClientHandle, moduleTwinCallback, (void*)iotHubModuleClientHandle) != IOTHUB_CLIENT_OK)
       {
           printf("ERROR: IoTHubModuleClient_LL_SetModuleTwinCallback(default)..........FAILED!\r\n");
           ret = MU_FAILURE;
       }
       else
       {
           ret = 0;
       }
   
       return ret;
   }
   

7. Save the main.c file.

8. In the Visual Studio Code explorer, open the deployment.template.json file in your IoT Edge solution workspace.

9. Add the filtermodule module twin to the deployment manifest. Insert the following JSON content at the bottom of the moduleContent section, after the $edgeHub module twin:

   "filtermodule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }
   

10. Save the deployment.template.json file.

1. In the Visual Studio Code explorer, open modules > filtermodule > src > main > java > com > edgemodule > App.java.

2. Add the following code at the top of the file to import new referenced classes.

   import java.io.StringReader;
   import java.util.concurrent.atomic.AtomicLong;
   import java.util.HashMap;
   import java.util.Map;
   
   import javax.json.Json;
   import javax.json.JsonObject;
   import javax.json.JsonReader;
   
   import com.microsoft.azure.sdk.iot.device.DeviceTwin.Pair;
   import com.microsoft.azure.sdk.iot.device.DeviceTwin.Property;
   import com.microsoft.azure.sdk.iot.device.DeviceTwin.TwinPropertyCallBack;
   

3. Add the following definition into class App. This variable sets a temperature threshold. The measured machine temperature isn't reported to IoT Hub until it goes over this value.

   private static final String TEMP_THRESHOLD = "TemperatureThreshold";
   private static AtomicLong tempThreshold = new AtomicLong(25);
   

4. Replace the execute method of MessageCallbackMqtt with the following code. This method is called whenever the module receives an MQTT message from the IoT Edge hub. It filters out messages that report temperatures below the temperature threshold set via the module twin.

   protected static class MessageCallbackMqtt implements MessageCallback {
       private int counter = 0;
       @Override
       public IotHubMessageResult execute(Message msg, Object context) {
           this.counter += 1;
   
           String msgString = new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET);
           System.out.println(
                  String.format("Received message %d: %s",
                           this.counter, msgString));
           if (context instanceof ModuleClient) {
               try (JsonReader jsonReader = Json.createReader(new StringReader(msgString))) {
                   final JsonObject msgObject = jsonReader.readObject();
                   double temperature = msgObject.getJsonObject("machine").getJsonNumber("temperature").doubleValue();
                   long threshold = App.tempThreshold.get();
                   if (temperature >= threshold) {
                       ModuleClient client = (ModuleClient) context;
                       System.out.println(
                           String.format("Temperature above threshold %d. Sending message: %s",
                           threshold, msgString));
                       client.sendEventAsync(msg, eventCallback, msg, App.OUTPUT_NAME);
                   }
               } catch (Exception e) {
                   e.printStackTrace();
               }
           }
           return IotHubMessageResult.COMPLETE;
       }
   }
   

5. Add the following two static inner classes into class App. These classes update the tempThreshold variable when the module twin's desired property changes. All modules have their own module twin, which lets you configure the code that's running inside a module directly from the cloud.

   protected static class DeviceTwinStatusCallBack implements IotHubEventCallback {
       @Override
       public void execute(IotHubStatusCode status, Object context) {
           System.out.println("IoT Hub responded to device twin operation with status " + status.name());
       }
   }
   
   protected static class OnProperty implements TwinPropertyCallBack {
       @Override
       public void TwinPropertyCallBack(Property property, Object context) {
           if (!property.getIsReported()) {
               if (property.getKey().equals(App.TEMP_THRESHOLD)) {
                   try {
                       long threshold = Math.round((double) property.getValue());
                       App.tempThreshold.set(threshold);
                   } catch (Exception e) {
                       System.out.println("Failed to set TemperatureThread with exception");
                       e.printStackTrace();
                   }
               }
           }
       }
   }
   

6. Add the following lines in to main method after client.open() to subscribe the module twin updates.

   client.startTwin(new DeviceTwinStatusCallBack(), null, new OnProperty(), null);
   Map<Property, Pair<TwinPropertyCallBack, Object>> onDesiredPropertyChange = new HashMap<Property, Pair<TwinPropertyCallBack, Object>>() {
       {
           put(new Property(App.TEMP_THRESHOLD, null), new Pair<TwinPropertyCallBack, Object>(new OnProperty(), null));
       }
   };
   client.subscribeToTwinDesiredProperties(onDesiredPropertyChange);
   client.getTwin();
   

7. Save the App.java file.

8. In the Visual Studio Code explorer, open the deployment.template.json file in your IoT Edge solution workspace.

9. Add the filtermodule module twin to the deployment manifest. Insert the following JSON content at the bottom of the moduleContent section, after the $edgeHub module twin:

     "filtermodule": {
         "properties.desired":{
             "TemperatureThreshold":25
         }
     }
   

10. Save the deployment.template.json file.

1. In the Visual Studio Code explorer, open modules > filtermodule > app.js.

2. Add a temperature threshold variable to the beginning of app.js. The temperature threshold sets the value that the measured temperature must exceed in order for the data to be sent to IoT Hub.

   var temperatureThreshold = 25;
   

3. Replace the entire PipeMessage function with the FilterMessage function.

   // This function filters out messages that report temperatures below the temperature threshold.
   // It also adds the MessageType property to the message with the value set to Alert.
   function filterMessage(client, inputName, msg) {
       client.complete(msg, printResultFor('Receiving message'));
       if (inputName === 'input1') {
           var message = msg.getBytes().toString('utf8');
           var messageBody = JSON.parse(message);
           if (messageBody && messageBody.machine && messageBody.machine.temperature && messageBody.machine.temperature > temperatureThreshold) {
               console.log(`Machine temperature ${messageBody.machine.temperature} exceeds threshold ${temperatureThreshold}`);
               var outputMsg = new Message(message);
               outputMsg.properties.add('MessageType', 'Alert');
               client.sendOutputEvent('output1', outputMsg, printResultFor('Sending received message'));
           }
       }
   }
   
   

4. Replace the function name pipeMessage with filterMessage in the client.on() call.

   client.on('inputMessage', function (inputName, msg) {
       filterMessage(client, inputName, msg);
       });
   

5. Copy the following code snippet into the client.open() function callback, after client.on() inside the else statement. This function is invoked when the desired properties are updated.

   client.getTwin(function (err, twin) {
       if (err) {
           console.error('Error getting twin: ' + err.message);
       } else {
           twin.on('properties.desired', function(delta) {
               if (delta.TemperatureThreshold) {
                   temperatureThreshold = delta.TemperatureThreshold;
               }
           });
       }
   });
   

6. Save the app.js file.

7. In the Visual Studio Code explorer, open the deployment.template.json file in your IoT Edge solution workspace.

8. Add the filtermodule module twin to the deployment manifest. Insert the following JSON content at the bottom of the moduleContent section, after the $edgeHub module twin:

     "filtermodule": {
         "properties.desired":{
             "TemperatureThreshold":25
         }
     }
   

9. Save the deployment.template.json file.

In this section, add the code that expands the filtermodule to analyze the messages before sending them. You add code that filters messages where the reported machine temperature is within the acceptable limits.

1. In the Visual Studio Code explorer, open modules > filtermodule > main.py.

2. At the top of the main.py file, import the json library:

   import json
   

3. Add global definitions for TEMPERATURE_THRESHOLD, RECEIVED_MESSAGES and TWIN_CALLBACKS variables. The temperature threshold sets the value that the measured machine temperature must exceed for the data to be sent to the IoT Hub.

   # global counters
   TEMPERATURE_THRESHOLD = 25
   TWIN_CALLBACKS = 0
   RECEIVED_MESSAGES = 0
   

4. Replace the create_client function with the following code:

   def create_client():
       client = IoTHubModuleClient.create_from_edge_environment()
   
       # Define function for handling received messages
       async def receive_message_handler(message):
           global RECEIVED_MESSAGES
           print("Message received")
           size = len(message.data)
           message_text = message.data.decode('utf-8')
           print("    Data: <<<{data}>>> & Size={size}".format(data=message.data, size=size))
           print("    Properties: {}".format(message.custom_properties))
           RECEIVED_MESSAGES += 1
           print("Total messages received: {}".format(RECEIVED_MESSAGES))
   
           if message.input_name == "input1":
               message_json = json.loads(message_text)
               if "machine" in message_json and "temperature" in message_json["machine"] and message_json["machine"]["temperature"] > TEMPERATURE_THRESHOLD:
                   message.custom_properties["MessageType"] = "Alert"
                   print("ALERT: Machine temperature {temp} exceeds threshold {threshold}".format(
                       temp=message_json["machine"]["temperature"], threshold=TEMPERATURE_THRESHOLD
                   ))
                   await client.send_message_to_output(message, "output1")
   
       # Define function for handling received twin patches
       async def receive_twin_patch_handler(twin_patch):
           global TEMPERATURE_THRESHOLD
           global TWIN_CALLBACKS
           print("Twin Patch received")
           print("     {}".format(twin_patch))
           if "TemperatureThreshold" in twin_patch:
               TEMPERATURE_THRESHOLD = twin_patch["TemperatureThreshold"]
           TWIN_CALLBACKS += 1
           print("Total calls confirmed: {}".format(TWIN_CALLBACKS))
   
       try:
           # Set handler on the client
           client.on_message_received = receive_message_handler
           client.on_twin_desired_properties_patch_received = receive_twin_patch_handler
       except:
           # Cleanup if failure occurs
           client.shutdown()
           raise
   
       return client
   

5. Save the main.py file.

6. In the Visual Studio Code explorer, open the deployment.template.json file in your IoT Edge solution workspace.

7. Add the filtermodule module twin to the deployment manifest. Insert the following JSON content at the bottom of the modulesContent section, after the $edgeHub module twin:

       "filtermodule": {
           "properties.desired":{
               "TemperatureThreshold":25
           }
       }
   

8. Save the deployment.template.json file.