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

  • 發行項

IoT Central 裝置橋接器是一種開放原始碼解決方案，可連接其他 IoT 雲端，例如 Sigfox 、 粒子裝置雲端 和 物聯網網路 至 IoT Central 應用程式。 裝置橋接器的運作方式是將資料從連線到其他 IoT 雲端的裝置轉送至 IoT Central 應用程式。 裝置橋接器只會將資料轉送至 IoT Central，它不會將命令或屬性更新從 IoT Central 傳回裝置。

裝置橋接器可讓您結合 IoT Central 的強大功能與裝置，例如：

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

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

裝置橋接器解決方案會將數個 Azure 資源布建到您的 Azure 訂用帳戶，以一起將裝置訊息轉換和轉送至 IoT Central。

必要條件

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

概觀

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

函式應用程式是裝置橋接器的核心部分。 它會透過簡單的 Webhook 接收來自其他 IoT 平臺的 HTTP POST 要求。 Azure IoT Central Device Bridge 存放 庫包含範例，示範如何連接 Sigfox、粒子和物聯網雲端。 如果您的平臺可以將 HTTP POST 要求傳送至函式應用程式，您可以擴充此解決方案以連線到您的自訂 IoT 雲端。

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

Screenshot of an Azure Functions definition showing the code.

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

部署裝置橋接器

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

  1. 在您的 IoT Central 應用程式中，流覽至 [ 許可權 > 裝置連線群組 ] 頁面。

    1. 記下識別碼 範圍 。 當您部署裝置橋接器時，請使用此值。

    2. 在相同的頁面中，開啟 SAS-IoT-Devices 註冊群組。 在 [SAS-IoT-Devices ] 群組頁面上，複製 [主要金鑰 ]。 當您部署裝置橋接器時，請使用此值。

  2. 使用下列 [部署至 Azure ] 按鈕，開啟將函式應用程式部署至訂用帳戶的自訂 Resource Manager 範本。 使用上一個步驟中的識別碼 範圍 和 主鍵 ：

    Deploy to Azure Button

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

  1. 在Azure 入口網站中，開啟已部署至您訂用帳戶的函式應用程式。 然後，移至 [開發工具 > 主控台 ]。 在主控台中，執行下列命令來安裝套件：

    cd IoTCIntegration
npm install

    這些命令可能需要幾分鐘的時間才能執行。 您可以放心地忽略任何警告訊息。

  2. 套件安裝完成之後，在函式應用程式的 [ 概觀 ] 頁面上選取 [重新開機 ]：

    Screenshot that shows the restart option in Azure Functions.

  3. 函式現在已可供使用。 外部系統可以使用 HTTP POST 要求，透過裝置橋接器將裝置資料傳送至 IoT Central 應用程式。 若要取得函式 URL，請流覽至 Functions > IoTCIntegration > Code + Test > Get 函式 URL ：

    Screenshot that shows the get function URL in Azure Functions.

傳送至裝置橋接器的訊息主體必須具有下列格式：

"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": truefunctionapp [ alwaysOn 組態] 底下的 "properties": {"SiteConfig": {...}} 資源組態 中，確保函式應用程式一律執行。

範例

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

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

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

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

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

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

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

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

若要轉換訊息承載，請在呼叫 handleMessage 第 21 行之前新增下列程式碼，並將 取代 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：透過裝置橋接器連線裝置

若要將物聯網裝置連線到 IoT Central：

  • 在 [物聯網：應用程式整合] 中，將新的 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 檔案第 21 行呼叫 handleMessage 之前，新增下列程式碼。 此程式碼會將 HTTP 整合的主體轉譯為預期的格式。

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

注意

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

限制

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

下一步

既然您已瞭解如何部署 IoT Central 裝置橋接器，以下是建議的下一個步驟：

管理您的裝置