使用 IoT Central 裝置橋接器將其他 IoT 雲端連線至 IoT Central

發行項
05/12/2024

IoT Central 裝置橋接器是一項開放原始碼解決方案，可將 Sigfox、Particle Device Cloud、The Things Network 等其他 IoT 雲端連線至 IoT Central 應用程式。裝置橋接器的運作方式是將資料從連線到其他 IoT 雲端的裝置轉送至 IoT Central 應用程式。裝置橋接器只會將資料轉送到 IoT Central，不會將命令或屬性更新從 IoT Central 傳送回裝置。

裝置橋接器可讓您將 IoT Central 的強大功能與以下之類的裝置結合：

連線到 Sigfox 低功耗廣域網路的資產追蹤裝置。
粒子裝置雲端上的空氣品質監視裝置。
物聯網上的土壤濕度監視裝置。

您可以使用 IoT Central 應用程式功能，例如資料的規則和分析、在 Power Automate 和 Azure Logic Apps 中建立工作流程，或匯出資料。

裝置橋接器解決方案會將數個 Azure 資源佈建到您的 Azure 訂用帳戶中，進而共同運作來轉換裝置訊息並轉送至 IoT Central。

必要條件

若要完成本操作指南中的步驟，您需要：

啟用中的 Azure 訂用帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
從自訂應用程式範本建立的 IoT Central 應用程式。若要深入了解，請參閱建立 IoT Central 應用程式和關於您的應用程式。

概觀

IoT Central 裝置橋接器是 GitHub 中的開放原始碼解決方案。其會使用自訂的 Azure Resource Manager 範本，將數個資源部署到您的 Azure 訂用帳戶，包括 Azure Functions 中的函數應用程式。

函數應用程式是裝置橋接器的核心部分。可透過簡單的 Webhook，從其他 IoT 平台接收 HTTP POST 要求。 Azure IoT Central 裝置橋接器存放庫包含範例，示範如何連線 Sigfox、Particle 和 The Things Network 雲端。如果您的平台可將 HTTP POST 要求傳送至函數應用程式，您即可擴充此解決方案以連線至您的自訂 IoT 雲端。

函數應用程式會將資料轉換成 IoT Central 接受的格式，並使用裝置佈建服務和裝置用戶端 API 轉送資料：

Screenshot of an Azure Functions definition showing the code.

如果您的 IoT Central 應用程式辨識轉送訊息中的裝置識別碼，則來自裝置的遙測會出現在 IoT Central 中。如果您的 IoT Central 應用程式無法辨識裝置識別碼，函式應用程式會嘗試使用該裝置識別碼註冊新裝置。新裝置會在 IoT Central 應用程式中的 [裝置] 頁面上顯示為未指派的裝置。從 [裝置] 頁面中，您可以將新裝置指派給裝置範本，然後檢視遙測。

部署裝置橋接器

若要將裝置橋接器部署至您的訂用帳戶：

在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組] 頁面。
1. 記下 [識別碼範圍]。部署裝置橋接器時會用到此值。
2. 在相同的頁面中，開啟 SAS-IoT-Devices 註冊群組。在 [SAS-IoT-Devices] 群組頁面上，複製 [主索引鍵]。部署裝置橋接器時會用到此值。
使用下列 [部署至 Azure] 按鈕，開啟將函式應用程式部署至您的訂用帳戶的自訂 Resource Manager 範本。使用上一個步驟中的識別碼範圍和主索引鍵：

部署完成後，您需要安裝函式所需的 npm 套件：

在 Azure 入口網站中，開啟已部署至您訂用帳戶的函數應用程式。然後，移至 [開發工具]>[主控台]。在主控台中，執行下列命令以安裝套件：
```
cd IoTCIntegration
npm install
```
這些命令可能需要幾分鐘才能完成執行。您可以放心地忽略任何警告訊息。
套件安裝完成之後，請在函數應用程式的 [概觀] 頁面上選取 [重新啟動]：
函式現在已可供使用。外部系統可以使用 HTTP POST 要求，透過裝置橋接器將裝置資料傳送至 IoT Central 應用程式。若要取得函式 URL，請瀏覽至 [函式] > [IoTCIntegration] > [程式碼 + 測試] > [取得函式 URL]：

傳送至裝置橋接器的訊息內文必須使用下列格式：

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

measurements 物件中的每個索引鍵都必須符合 IoT Central 應用程式中裝置範本內的遙測類型名稱。此解決方案不支援在訊息內文中指定介面識別碼。因此，如果兩個不同的介面具有名稱相同的遙測類型，度量就會出現在 IoT Central 應用程式中的這兩個遙測串流中。

您可以在內文中包含 timestamp 欄位，以指定訊息的 UTC 日期和時間。欄位必須是 ISO 8601 格式。例如： 2020-06-08T20:16:54.602Z 。如果您沒有包含時間戳記，則會使用目前的日期和時間。

您可以在內文中包含 modelId 欄位。使用此欄位，即可在佈建期間將裝置指派給裝置範本。

deviceId 必須是英數字元、小寫字母且可包含連字號。

如果您沒有包含 modelId 欄位，或 IoT Central 無法辨識模型識別碼，則其中 deviceId 無法辨識的訊息會在 IoT Central 中建立新的未指派裝置。操作員可以手動將裝置遷移至正確的裝置範本。若要深入了解，請參閱在您的 Azure IoT Central 應用程式中管理裝置 > 將裝置遷移至範本。

注意

在將裝置指派給範本之前，對函式執行的所有 HTTP 呼叫都會傳回 403 錯誤狀態。

若要使用 Application Insights 開啟函數應用程式的記錄功能，請在 Azure 入口網站中瀏覽至函數應用程式中的 [監視] > [記錄]。選取 [開啟 Application Insights]。

佈建的資源

Resource Manager 範本會在您的 Azure 訂用帳戶中佈建下列資源：

函式應用程式
App Service 方案
儲存體帳戶
金鑰保存庫

金鑰保存庫會儲存 IoT Central 應用程式的 SAS 群組金鑰。

函數應用程式會在取用方案上執行。雖然此選項不提供專用的計算資源，但可讓裝置橋接器每分鐘處理數百個裝置訊息，適用於較小型的裝置群或較不頻繁傳送訊息的裝置。如果您的應用程式需要串流處理大量的裝置訊息，請將取用方案取代為專用的 App Service 方案。此方案提供專用的計算資源，可提供更快的伺服器回應時間。若使用標準 App Service 方案，在此存放庫中，我們觀察到 Azure 函式的最大效能大約是每分鐘 1,500 個裝置訊息。若要深入了解，請參閱 Azure Functions 主控選項。

若要使用專用 App Service 方案，而不是取用方案，請在部署之前先編輯自訂範本。選取 [編輯範本]。

Screenshot that shows the edit template option for an Azure Resource Manager template.

取代下列區段：

{
  "type": "Microsoft.Web/serverfarms",
  "apiVersion": "2015-04-01",
  "name": "[variables('planName')]",
  "location": "[resourceGroup().location]",
  "properties": {
    "name": "[variables('planName')]",
    "computeMode": "Dynamic",
    "sku": "Dynamic"
  }
},

取代為

{
  "type": "Microsoft.Web/serverfarms",
  "sku": {
      "name": "S1",
      "tier": "Standard",
      "size": "S1",
      "family": "S",
      "capacity": 1
  },
  "kind": "app",
  "name": "[variables('planName')]",
  "apiVersion": "2016-09-01",
  "location": "[resourceGroup().location]",
  "tags": {
      "iotCentral": "device-bridge",
      "iotCentralDeviceBridge": "app-service-plan"
  },
  "properties": {
      "name": "[variables('planName')]"
  }
},

接下來，請編輯範本，將 "alwaysOn": true 包含在 "properties": {"SiteConfig": {...}} 底下的 functionapp 資源設定中。alwaysOn 設定可確保函數應用程式永遠處於執行狀態。

範例

下列範例概述如何為各種 IoT 雲端設定裝置橋接器：

範例 1：透過裝置橋接器連線 Particle 裝置

若要透過裝置橋接器將 Particle 裝置連線到 IoT Central，請移至 Particle 主控台並建立新的 Webhook 整合。將 [要求格式] 設定為 [JSON]。在 [進階設定] 底下，使用下列自訂內文格式：

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

從函數應用程式貼上函式 URL，您會看到 Particle 裝置在 IoT Central 中顯示為未指派的裝置。若要深入了解，請參閱說明如何整合 Particle 支援的專案與 Azure IoT Central部落格文章。

範例 2：透過裝置橋接器連線 Sigfox 裝置

某些平台可能無法讓您指定透過 Webhook 傳送的裝置訊息格式。對於這類系統，您必須在裝置橋接器處理訊息之前，將訊息承載轉換成預期的內文格式。您可以在執行裝置橋接器的相同函式中執行轉換。

本節說明如何將 Sigfox Webhook 整合的承載轉換為裝置橋接器預期的內文格式。 Sigfox 雲端會以十六進位字串格式傳輸裝置資料。為了方便起見，裝置橋接器已包含此格式的轉換函式，可接受 Sigfox 裝置承載中的一小組可能欄位類型：int 及 uint (8、16、32 或 64 位元)；float (32 位或 64 位元)；little-endian 和 big-endian。若要處理來自 Sigfox Webhook 整合的訊息，請在函數應用程式中對 IoTCIntegration/index.js 檔案進行下列變更。

若要轉換訊息承載，請在第 21 行呼叫 handleMessage 之前新增下列程式碼，並將 payloadDefinition 取代為您的 Sigfox 承載定義：

const payloadDefinition = 'gforce::uint:8 lat::uint:8 lon::uint:16'; // Replace this with your payload definition

req.body = {
    device: {
        deviceId: req.body.device
    },
    measurements: require('./converters/sigfox')(payloadDefinition, req.body.data)
};

Sigfox 裝置的回應碼應是 204。在第 21 行中的 handleMessage 呼叫之後新增下列程式碼：

context.res = {
    status: 204
};

範例 3：透過裝置橋接器從 The Things Network 連線裝置

若要將 The Things Network 裝置連線到 IoT Central：

在 The Things Network 中，將新的 HTTP 整合新增至您的應用程式：應用程式 > 整合 > 新增整合 > HTTP 整合。
請確定您的應用程式包含解碼器函式，以在傳送至函式之前，可自動將裝置訊息的承載轉換成 JSON：應用程式 > 承載函式 > 解碼器。

下列範例顯示 JavaScript 解碼器函式，可用來解碼二進位資料的一般數數值類型：

function Decoder(bytes, port) {
  function bytesToFloat(bytes, decimalPlaces) {
    var bits = (bytes[3] << 24) | (bytes[2] << 16) | (bytes[1] << 8) | bytes[0];
    var sign = (bits >>> 31 === 0) ? 1.0 : -1.0;
    var e = bits >>> 23 & 0xff;
    var m = (e === 0) ? (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000;
    var f = Math.round((sign * m * Math.pow(2, e - 150)) * Math.pow(10, decimalPlaces)) / Math.pow(10, decimalPlaces);
    return f;
  }

  function bytesToInt32(bytes, signed) {
    var bits = bytes[0] | (bytes[1] << 8) | (bytes[2] << 16) | (bytes[3] << 24);
    var sign = 1;

    if (signed && bits >>> 31 === 1) {
      sign = -1;
      bits = bits & 0x7FFFFFFF;
    }

    return bits * sign;
  }

  function bytesToShort(bytes, signed) {
    var bits = bytes[0] | (bytes[1] << 8);
    var sign = 1;

    if (signed && bits >>> 15 === 1) {
      sign = -1;
      bits = bits & 0x7FFF;
    }

    return bits * sign;
  }

  return {
    temperature: bytesToFloat(bytes.slice(0, 4), 2),
    presscounter: bytesToInt32(bytes.slice(4, 8), true),
    blueLux: bytesToShort(bytes.slice(8, 10), false)
  };
}

定義整合之後，請在函數應用程式 IoTCIntegration/index.js 檔案的 handleMessage 呼叫 (第 21 行) 之前新增下列程式碼。此程式碼會將 HTTP 整合的內文轉譯為預期的格式。

req.body = {
  device: {
    deviceId: req.body.end_device_ids.device_id.toLowerCase()
  },
  measurements: req.body.uplink_message.decoded_payload
};

注意

上一個程式碼片段會使用人類易記的裝置識別碼。 The Things Network 訊息也包含您可以使用 req.body.dev_eui.toLowerCase() 存取的技術識別碼。若要深入了解，請參閱 The Things Network - 資料格式。

限制

裝置橋接器只會將訊息轉送至 IoT Central，而且不會將訊息傳回裝置。此限制就是為什麼屬性和命令不適用於透過此裝置橋接器連線到 IoT Central 的裝置。由於不支援裝置對應項作業，因此無法透過裝置橋接器更新裝置屬性。若要使用這些功能，裝置必須使用其中一個 Azure IoT 裝置 SDK 直接連線到 IoT Central。

下一步

您現在已了解如何部署 IoT Central 裝置橋接器，以下是建議的後續步驟：

管理您的裝置

共用方式為