Add Azure IoT Hub integration documentation (#528)

* doc: Add Azure IoT Hub integration documentation

* doc: Remove Microsoft Azure integration guide

doc/content/integrations/cloud-integrations/azure-iot-hub/_index.md

@@ -0,0 +1,18 @@
+---
+title: "Azure IoT Hub"
+description: ""
+distributions: ["Cloud", "Dedicated Cloud", "Enterprise", "Community"]
+weight: 1
+---
+
+This guide will help you setup the [Azure IoT Hub](https://azure.microsoft.com/en-us/services/iot-hub/) integration.
+
+The key features of the Azure IoT Hub integration are:
+
+- **Handling uplink messages**: {{% tts %}} publishes uplink messages to an Azure IoT Hub
+- **Creating and deleting devices**: manage end device in Azure IoT Hub, using the [LoRaWAN device repository](https://github.com/TheThingsNetwork/lorawan-devices)
+- **Updating device state in Device Twin**: update the device reported properties based on the decoded payloads, and schedule downlinks based on the device desired properties
+
+{{< note >}} This integration comes with a [Azure Resource Manager Template](https://azure.microsoft.com/en-us/services/arm-templates/) template to deploy in your Azure account. {{</ note >}}
+
+{{< figure src="overview.svg" alt="Default integration overview" class="plain" >}}

doc/content/integrations/cloud-integrations/azure-iot-hub/architecture.md

@@ -0,0 +1,21 @@
+---
+title: "Architecture"
+description: ""
+weight: 10
+---
+
+The Azure IoT Hub integration is a serverless deployment that scales automatically as your deployment grows.
+
+<!--more-->
+
+{{< figure src="../architecture.svg" alt="Default integration architecture" class="plain" >}}
+
+The key resources deployed in your Azure account are:
+
+- IoT Hub to manage your end devices and their Device Twins
+- IoT Hub Shared Access Policy that allows {{% tts %}} to register devices, submit traffic and update Device Twins
+- EventHub Namespace and EventHub for {{% tts %}} communication
+- Azure Function to submit events to {{% tts %}}
+- Storage Account used by the Azure Functions for trigger management
+
+This is a serverless deployment: there are no compute resources being deployed. The only continuous charges are by the Azure IoT Hub and the EventHub Namespace. All permissions are the minimum permissions for the integration to function.

doc/content/integrations/cloud-integrations/azure-iot-hub/deployment.md

@@ -0,0 +1,49 @@
+---
+title: "Deployment Guide"
+description: ""
+weight: 20
+---
+
+Learn how to deploy the Azure IoT Hub integration for {{% tts %}}.
+
+<!--more-->
+
+## Prerequisites
+
+1. Access to an Azure account. [Create a new account](https://signup.azure.com/)
+2. An application in {{% tts %}}. [See instructions]({{< ref "/integrations/adding-applications" >}})
+
+## Create API Key
+
+Go to your application in {{% tts %}} Console, navigate to **Integrations &#8594; Azure IoT Hub** on the left hand menu and click **Generate API Key**.
+
+{{< figure src="../create-api-key.png" alt="Create API key" >}}
+
+Copy the generated API key and store it in a safe place, because you will need it in the next section.
+
+## Deploy Azure Resource Manager Template
+
+<a href="https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fttsiothubintegration.blob.core.windows.net%2Fintegration-releases%2Flatest%2Fmain.json" target="_blank" class="button is-primary">Deploy template</a>
+
+View template as [JSON](https://ttsiothubintegration.blob.core.windows.net/integration-releases/latest/main.json) or [Bicep](https://ttsiothubintegration.blob.core.windows.net/integration-releases/latest/main.bicep)
+
+### Settings
+
+The following parameters configure the integration:
+
+- **Location**: The region in which the Azure resources will be deployed. Defaults to the region used by the selected Resource Group.
+- **Name Suffix**: The suffix added to the Azure Resources. Defaults to a random string.
+- **Stack Cluster Address**: The address of your {{% tts %}} deployment. Can be retrieved from the **Azure IoT Hub** integration page in {{% tts %}} (see image above).
+- **Stack Application ID**: The application ID of your application. Can be retrieved from the **Azure IoT Hub** integration page in {{% tts %}} (see image above).
+- **Stack API Key**: The application API key that you generated in the previous step.
+- **Enable fallback route**: Defines if the Azure IoT Hub fallback route should be added. If enabled, uplink messages will be submitted to the default `events` endpoint in your Azure IoT Hub.
+
+{{< figure src="../deploy-template.png" alt="Deploy Azure Resource Manager Template" >}}
+
+Click **Review + Create**, then **Create**.
+
+{{< note >}} Creating all resources can take up to five minutes.  ☕ {{</ note >}}
+
+When the deployment is done, you'll see the status `Your deployment is complete`.
+
+> Congratulations! 🎉 You have now set up the Azure IoT Hub integration for {{% tts %}}!

doc/content/integrations/cloud-integrations/azure-iot-hub/device-twin.md

@@ -0,0 +1,61 @@
+---
+title: "Messages and Device Twin"
+description: ""
+weight: 40
+---
+
+{{% tts %}} publishes uplink messages to Azure IoT Hub as device telemetry. {{% tts %}} updates the [Device Twin](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins) reported properties of the device, and schedules downlinks when the [Device Twin](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins) desired properties are changed.
+
+<!--more-->
+
+> {{% tts %}} automatically creates the end device in Azure IoT Hub in case it is not yet created. See [Managing Devices]({{< relref "devices" >}}) for details.
+
+> See [Architecture]({{< relref "architecture" >}}) for the flow.
+
+{{< note >}} The [Device Twin](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins) properties functionality depends on the presence of [Payload Formatters]({{< ref "/integrations/payload-formatters" >}}). Devices which are configured using [LoRaWAN Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) will automatically have payload formatters. {{</ note >}}
+
+## Reported Properties
+
+The Azure IoT Hub integration will automatically update the [Device Twin](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins) reported properties when an uplink message arrives, using [Payload Formatters]({{< ref "/integrations/payload-formatters" >}}).
+
+In the Azure Console, open your Azure IoT Hub resource. In the menu on the left, click **IoT Devices**.
+
+{{< figure src="../device-list.png" alt="IoT Devices" >}}
+
+Click on the device you want to view.
+
+{{< figure src="../device-created.png" alt="Device View" >}}
+
+Click on **Device Twin**. The device reported properties will be visible under the `properties.reported.decodedPayload` key.
+
+{{< figure src="../reported-properties.png" alt="Reported Properties" >}}
+
+## Desired Properties
+
+The Azure IoT Hub integration will automatically schedule a downlink when the [Device Twin](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins) desired properties are updated.
+
+In the Azure Console, open your Azure IoT Hub resource. In the menu on the left, click **IoT Devices**.
+
+{{< figure src="../device-list.png" alt="IoT Devices" >}}
+
+Click on the device you want to view.
+
+{{< figure src="../device-created.png" alt="Device View" >}}
+
+Click on **Device Twin**. The device reported desired will be visible under the `properties.desired.decodedPayload` key. If the key is missing, you will have to manually create it. The contents of the object should be compatible with the device's payload formatter.
+
+The final JSON `properties.desired` object should look as follows:
+
+```json
+{
+   "decodedPayload":{
+      "color":"red"
+   }
+}
+```
+
+When finished editing the JSON `tags` object, click on **Save** in the top-left corner.
+
+{{< figure src="../desired-properties.png" alt="Desired Properties" >}}
+
+A downlink message will be generated in {{% tts %}}.

doc/content/integrations/cloud-integrations/azure-iot-hub/devices.md

@@ -0,0 +1,97 @@
+---
+title: "Managing Devices"
+description: ""
+weight: 30
+---
+
+The Azure IoT Hub integration for {{% tts %}} synchronizes the device registry: you can create devices in Azure IoT Hub which trigger an Azure Function that creates the device in {{% tts %}}.
+
+<!--more-->
+
+{{< note >}} Devices that you create in {{% tts %}} are automatically created as Azure IoT Hub devices as soon as they activate or send their first uplink message.
+
+In Azure IoT Hub, create only devices that are not yet in your {{% tts %}} application. {{</ note >}}
+
+## Device Names
+
+Devices are created automatically as they join the network or send an uplink message. For the name of new devices, the end device ID in {{% tts %}} is used as the device ID in Azure IoT Hub.
+
+## Creating Devices
+
+You can use Azure IoT Hub to create and claim devices in {{% tts %}}. This is useful to manage all your devices in one place, without having to use {{% tts %}} Console, CLI or API.
+
+**Creating** a device allows you to add any LoRaWAN device by manually entering its information and security keys.
+
+In the Azure Console, open your Azure IoT Hub resource. In the menu on the left, click **IoT Devices**.
+
+Click **Add Device**.
+
+{{< figure src="../device-list.png" alt="IoT Devices" >}}
+
+As **Device ID**, enter any device ID you like. Hit **Save**.
+
+{{< note >}}
+See [ID and EUI constraints]({{< ref "reference/id-eui-constraints" >}}) for guidelines about choosing a unique ID.
+{{</ note >}}
+
+{{< figure src="../add-device.png" alt="Add Device" >}}
+
+You will now have to setup the LoRaWAN specific settings of the device. Click on **Device Twin**.
+
+{{< figure src="../device-created.png" alt="Device Created" >}}
+
+You will now be presented with a JSON document containing the Device Twin. You now have to add a new object called `tags`, which will contain an object called `lorawan` with the LoRaWAN specific tags. You will have to specify the following tags:
+
+- `devEui`: the hexadecimal LoRaWAN DevEUI.
+- `joinEui`: the hexadecimal LoRaWAN JoinEUI (or AppEUI).
+- `lorawanVersion`: either `1.0`, `1.0.1`, `1.0.2`, `1.0.3` or `1.1`.
+- `regionalParametersVersion`: either `1.0`, `1.0.1`, `1.0.2` (or `1.0.2-a`), `1.0.2-b`, `1.0.3-a`, `1.1-a` or `1.1-b`.
+- `appKey`: the hexadecimal LoRaWAN AppKey.
+- `nwkKey`: the hexadecimal LoRaWAN NwkKey (only when using LoRaWAN 1.1 or higher).
+- `frequencyPlanId`: the frequency plan ID. See [Frequency Plans]({{< ref "/reference/frequency-plans" >}}) for the supported values.
+
+If your end device is a part of the [LoRaWAN Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}), you may provide the identifiers of the device as part of an optional `versionIdentifiers` object. You can specify the following information as part of the identifiers:
+
+- `bandId`: the band ID.
+- `brandId`: the brand ID.
+- `firmwareVersion`: the firmware version.
+- `hardwareVersion`: the hardware version.
+- `modelId`: the model ID.
+
+{{< note >}} If the version identifiers are provided, the end device will automatically load the [Payload Formatters]({{< ref "/integrations/payload-formatters" >}}) from [LoRaWAN Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}). {{</ note >}}
+
+The final JSON `tags` object should look as follows:
+
+```json
+{
+   "lorawan":{
+      "devEui":"0004A30B001C5838",
+      "joinEui":"0000000000000000",
+      "lorawanVersion":"1.0.2",
+      "regionalParametersVersion":"1.0.2-b",
+      "frequencyPlanId":"EU_863_870_TTN",
+      "appKey":"459B77D46A08C427254822A33F6FA1A3",
+      "versionIdentifiers":{
+         "bandId":"EU_863_870",
+         "brandId":"the-things-products",
+         "firmwareVersion":"1.0",
+         "hardwareVersion":"1.0",
+         "modelId":"the-things-node"
+      }
+   }
+}
+```
+
+{{< figure src="../add-tags.png" alt="Add Tags" >}}
+
+Click on **Save** in the top-left corner. The end device will now be created in {{% tts %}}.
+
+## Deleting Devices
+
+In the Azure Console, open your Azure IoT Hub resource. In the menu on the left, click **IoT Devices**.
+
+Click on the checkbox in front of the device you want to delete, then click **Delete**.
+
+{{< figure src="../select-device.png" alt="Select Device" >}}
+
+The end device will be deleted from Azure IoT Hub and {{% tts %}}.

doc/content/integrations/cloud-integrations/azure-iot-hub/uninstall.md

@@ -0,0 +1,7 @@
+---
+title: "Uninstall"
+description: ""
+weight: 70
+---
+
+You can uninstall the Azure IoT Hub integration for {{% tts %}} by deleting the Resource Group in which the Deployment was done.

doc/content/integrations/cloud-integrations/azure-iot-hub/update.md

@@ -0,0 +1,41 @@
+---
+title: "Update"
+description: ""
+weight: 60
+---
+
+You can update the Azure IoT Hub integration for {{% tts %}} using [Azure Resource Manager](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview) easily. In most cases, this is without service interruptions.
+
+<!--more-->
+
+> Download the latest template from [here](https://ttsiothubintegration.blob.core.windows.net/integration-releases/latest/main.json)
+
+In the Azure Console, open your Resource Group and go to **Deployments**.
+
+In the list of deployments, go to the deployment that you created when deploying the integration. See [Deployment Guide]({{< relref "deployment" >}}).
+
+In the top-right, click **Redeploy**.
+
+{{< figure src="../deployments.png" alt="Deployments" >}}
+
+Click **Edit template**.
+
+{{< figure src="../deployment-1.png" alt="Deployment View" >}}
+
+Click **Load file** and select the template you have just downloaded.
+
+{{< figure src="../load-template-1.png" alt="Edit Template" >}}
+
+Click **Save**.
+
+Now, create a new API key as described in the [Deployment Guide]({{< relref "deployment" >}}). Provide the created API key for **Stack API Key**.
+
+{{< figure src="../deployment-1.png" alt="Deployment View" >}}
+
+Review the parameters. Unless new functionality adds new parameters, you can leave the current values unchanged.
+
+Click **Review + Create**, then **Create**.
+
+{{< note >}} Updating all resources can take up to 5 minutes. {{</ note >}}
+
+When the deployment is updated, you'll see the status `Your deployment is complete`.