IoT Central cloud to cloud integration

This repository contains a sample Azure Function that can be used to integrate device messages from other IoT platforms into IoT Central using webhooks.

Instructions

The Deploy to Azure button above can be used to deploy this Azure Function in your subscription. The following steps are needed for a successful deployment:

1. Set the Scope Id parameter as the value found in your IoT Central application Administration > Device Connection > Scope ID

2. In Iotc Sas Key, enter the primary SAS key for you IoT Central app, found in Administration > Device Connection > Primary Key (this key will be stored in a Key Vault provisioned with the function).

3. After the deployment is done, install the NPM packages needed for the function to work. To do this, go to the Function App that was deployed to your subscription Functions > IoTCIntegration > Console tab. In the console, run the command npm install (this command usually takes around 15 minutes to complete).

4. After the package installation finishes, the Function App needs to be restarted by clicking the Restart button in Overview page.

5. The function is now ready to use. External systems can emit device data to an IoT Central device by making a POST HTTP request to the function URL. The URL can be obtained in the newly created function App Functions > IoTCIntegration > Get function URL.

The following sample shows the format of the POST body:

{
    "device": {
        "deviceId": "my-cloud-device"
    },
    "measurements": {
        "temp": 20.31,
        "pressure": 50,
        "humidity": 8.5
    }
}

NOTE: deviceId must be alphanumeric, lowercase, and may contain hyphens. The values of the fields in measurements must be numbers (i.e., not quoted).

The device will be automatically created in IoT Central when the first message is received. It will show up in your application under Device Explorer > Unassociated devices. Until the device is associated to a template, HTTP calls to the function will return a 403 error status.

What is being provisioned? (pricing)

The template in this repository will provision the following Azure resources:

• Key Vault, needed to store your IoT Central key
• Storage Account
• App Service Plan (S1 tier)
• Function App

The estimated total cost of these resources is $75/month. The majority of this value ($73) comes from the App Service Plan being provisioned. We chose this plan because it offers dedicated compute resources, which leads to faster server response times, a critical factor for many cloud IoT platforms that allow streaming of device data through webhooks. With this setup, the maximum observed performance of the Azure Function in this repository was around 1,500 device messages per minute.

In addition to removing the provisioned resources when not in use, the cost of the solution can be significantly reduced by replacing the App Service Plan by a Consumption Plan. While this option does not offer dedicated compute resources, it may be enough for testing purposes or applications that tolerate higher server response times (more information on Azure Function hosting options can be found here). To use a Consumption Plan instead of an App Service Plan, edit the template before deploying, making the appropriate changes (a sample template for a Consumption Plan can be found here).

Limitations

Due to the unidirectional nature of this solution, settings and commands will not work for devices that connect to Azure IoT Central through this Azure Function. To use these features, a device must be connected using one of the Azure IoT device SDKs.

Example: connecting a Particle device

To connect a Particle device to Azure IoT Central, create a new webhook integration in the Particle console. Set the Request Format to JSON and, under Advanced Settings, use the following custom body format:

{
  "device": {
    "deviceId": "{{{PARTICLE_DEVICE_ID}}}"
  },
  "measurements": {
    "{{{PARTICLE_EVENT_NAME}}}": {{{PARTICLE_EVENT_VALUE}}}
  }
}

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.