Skip to content

Latest commit

 

History

History
237 lines (181 loc) · 13 KB

tutorial-deploy-function.md

File metadata and controls

237 lines (181 loc) · 13 KB
title description services keywords author manager ms.author ms.date ms.topic ms.service
Deploy Azure Function with Azure IoT Edge | Microsoft Docs
Deploy Azure Function as a module to an edge device
iot-edge
JimacoMS2
timlt
v-jamebr
11/15/2017
article
iot-edge

Deploy Azure Function as an IoT Edge module - preview

You can use Azure Functions to deploy code that implements your business logic directly to your IoT Edge devices. This tutorial walks you through creating and deploying an Azure Function that filters sensor data on the simulated IoT Edge device that you created in the Deploy Azure IoT Edge on a simulated device on Windows or Linux tutorials. In this tutorial, you learn how to:

[!div class="checklist"]

  • Use Visual Studio Code to create an Azure Function
  • Use VS Code and Docker to create a Docker image and publish it to your registry
  • Deploy the module to your IoT Edge device
  • View generated data

The Azure Function that you create in this tutorial filters the temperature data generated by your device and only sends messages upstream to Azure IoT Hub when the temperature is above a specified threshold.

Prerequisites

Set up a Docker registry

In this tutorial, you use the Azure IoT Edge extension for VS Code to create an Azure Function and build a Docker image with it. Then you push this Docker image to a Docker repository hosted by a Docker registry. Finally, you deploy your Docker image packaged as a Docker container from your registry to your IoT Edge device.

You can use any Docker-compatible registry for this tutorial. Two popular Docker registry services available in the cloud are Azure Container Registry and Docker Hub:

Throughout this tutorial, where appropriate, commands are provided for both Azure Container Registry and Docker Hub.

Create a function project

The following steps show you how to create an IoT Edge function using Visual Studio Code and the Azure IoT Edge extension.

  1. Open VS Code.

  2. Use the View | Integrated Terminal menu command to open the VS Code integrated terminal.

  3. In the integrated terminal, enter the following command to install (or update) the AzureIoTEdgeFunction template in dotnet:

    dotnet new -i Microsoft.Azure.IoT.Edge.Function

  4. In the integrated terminal, enter the following command to create a project for the new module:

    dotnet new aziotedgefunction -n FilterFunction

    [!NOTE] This command creates the project folder, FilterFunction, in the current working folder. If you want to create it in another location, change directories before running the command.

  5. Use the File | Open Folder menu command, browse to the FilterFunction folder, and click Select Folder to open the project in VS Code.

  6. In VS Code explorer, click the EdgeHubTrigger-Csharp folder, then click the run.csx file to open it.

  7. Add the following statement after the #r "Microsoft.Azure.Devices.Client" statement:

    #r "Newtonsoft.Json"

  8. Add the following using statements after the existing using statements:

    using Newtonsoft.Json;

  9. Add the following 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;}         
}

  10. Replace the body of the Run method with the following code. It filters messages based on the temperature value in the body of the message and the temperature threshold value.

    const int temperatureThreshold = 25;

byte[] messageBytes = messageReceived.GetBytes();
var messageString = System.Text.Encoding.UTF8.GetString(messageBytes);

if (!string.IsNullOrEmpty(messageString))
{
    // Get the body of the message and deserialize it
    var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);
    
    if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
    {
        // We will send the message to the output as the temperature value is greater than the threashold
        var filteredMessage = new Message(messageBytes);
        // We need to copy the properties of the original message into the new Message object
        foreach (KeyValuePair<string, string> prop in messageReceived.Properties)
        {
            filteredMessage.Properties.Add(prop.Key, prop.Value);
        }
        // We are adding a new property to the message to indicate it is an alert
        filteredMessage.Properties.Add("MessageType", "Alert");
        // Send the message        
        await output.AddAsync(filteredMessage);
        log.Info("Received and transfered a message with temperature above the threshold");
    }
}

  11. Save the file.

Publish a Docker image

  1. Build the Docker image.

    1. In VS Code explorer, click the Docker folder to open it. Then select the folder for your container platform, either linux-x64 or windows-nano.
    2. Right-click the Dockerfile file and click Build IoT Edge module Docker image.
    3. In the Select Folder box, navigate to the project folder, FilterFunction, and click Select Folder as EXE_DIR.
    4. In the pop-up text box at the top of the VS Code window, enter the image name. For example, <docker registry address>/filterfunction:latest; where docker registry address is your Docker ID if you are using Docker Hub or is similar to <your registry name>.azurecr.io, if you are using Azure Container Registry.

  2. Sign in to Docker. In integrated terminal, enter the following command:

    • Docker Hub (enter your credentials when prompted):

      docker login

    • Azure Container Registry:

      docker login -u <username> -p <password> <Login server>

      To find the user name, password and login server to use in this command, go to the [Azure portal] (https://portal.azure.com). From All resources, click the tile for your Azure container registry to open its properties, then click Access keys. Copy the values in the Username, password, and Login server fields. The login server sould be of the form: <your registry name>.azurecr.io.

  3. Push the image to your Docker repository. Use the View | Command Palette ... | Edge: Push IoT Edge module Docker image menu command and enter the image name in the pop-up text box at the top of the VS Code window. Use the same image name you used in step 1.c.

Add registry credentials to your Edge device

Add the credentials for your registry to the Edge runtime on the computer where you are running your Edge device. This gives the runtime access to pull the container.

  • For Windows, run the following command:

    iotedgectl login --address <docker-registry-address> --username <docker-username> --password <docker-password>

  • For Linux, run the following command:

    sudo iotedgectl login --address <docker-registry-address> --username <docker-username> --password <docker-password>

Run the solution

  1. In the Azure portal, navigate to your IoT hub.

  2. Go to IoT Edge (preview) and select your IoT Edge device.

  3. Select Set Modules.

  4. Add the tempSensor module. This step is only required if you have not previously deployed the tempSensor module to your IoT Edge device.

    1. Select Add IoT Edge Module.
    2. In the Name field, enter tempSensor.
    3. In the Image URI field, enter microsoft/azureiotedge-simulated-temperature-sensor:1.0-preview.
    4. Leave the other settings unchanged and click Save.

  5. Add the filterfunction module.

    1. Select Add IoT Edge Module again.
    2. In the Name field, enter filterfunction.
    3. In the Image field, enter your image address; for example <docker registry address>/filterfunction:latest.
    4. Click Save.

  6. Click Next.

  7. In the Specify Routes step, copy the JSON below into the text box. Modules publish all messages to the Edge runtime. Declarative rules in the runtime define where those messages flow. In this tutorial, you need two routes. The first route transports messages from the temperature sensor to the filter module via the "input1" endpoint, which is the endpoint that you configured with the FilterMessages handler. The second route transports messages from the filter module to IoT Hub. In this route, upstream is a special destination that tells Edge Hub to send messages to IoT Hub.

    {
   "routes":{
      "sensorToFilter":"FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filterfunction/inputs/input1\")",
      "filterToIoTHub":"FROM /messages/modules/filterfunction/outputs/* INTO $upstream"
   }
}

  8. Click Next.

  9. In the Review Template step, click Submit.

  10. Return to the IoT Edge device details page and click Refresh. You should see the new filterfunction module running along with the tempSensor module and the IoT Edge runtime.

View generated data

To monitor device to cloud messages sent from your IoT Edge device to your IoT hub:

  1. Configure the Azure IoT Toolkit extension with connection string for your IoT hub:

    1. Use the View | Explorer menu command to open the VS Code explorer.

    2. In the explorer, click IOT HUB DEVICES and then click .... Click Set IoT Hub Connection String and enter the connection string for the IoT hub that your IoT Edge device connects to in the pop-up window.

      To find the connection string, click the tile for your IoT hub in the Azure portal and then click Shared access policies. In Shared access policies, click the iothubowner policy and copy the IoT Hub connection string in the iothubowner window.

  2. To monitor data arriving at the IoT hub, use the View | Command Palette... | IoT: Start monitoring D2C message menu command.

  3. To stop monitoring data, use the View | Command Palette... | IoT: Stop monitoring D2C message menu command.

Next steps

In this tutorial, you created an Azure Function that contains code to filter raw data generated by your IoT Edge device. To keep exploring Azure IoT Edge, learn how to use an IoT Edge device as a gateway.

[!div class="nextstepaction"] Create an IoT Edge gateway device