# 連線至適用於 Amazon Sidewalk 的 AWS IoT Core
本節展示如何加入 Sidewalk 終端裝置，然後將您的裝置連接至 Sidewalk 網路。其描述了您於加入教學課程中所執行的步驟，如 [加入 Sidewalk 裝置簡介](sidewalk-gs-workflow.md) 中所述。您將了解如何使用 AWS IoT 主控台和適用於 Amazon Sidewalk 的 AWS IoT Core API 操作來加入裝置。您還會了解執行這些作業的 AWS CLI 命令。
## 必要條件
如要將終端裝置和目的地新增至適用於 Amazon Sidewalk 的 AWS IoT Core，您必須設定 AWS 帳戶。如要使用 AWS IoT Wireless API 或 AWS CLI 命令執行這些操作，您還必須設定 AWS CLI。如需有關先決條件與設定的更多資訊，請參閱 [安裝 Python 和 AWS CLI](setting-up-iotwireless.md#wireless-onboard-prereq)。
**注意**
如要執行佈建和註冊終端裝置及連線至硬體開發套件 (HDK) 的完整加入工作流程，您還必須設定 Sidewalk 閘道和 HDK。如需詳細資訊，請參閱《Amazon Sidewalk 文件》**中的[設定硬體開發套件 (HDK)](https://docs.sidewalk.amazon/getting-started/sidewalk-onboard-prereq-hdk.html) 和[設定 Sidewalk 閘道](https://docs.sidewalk.amazon/getting-started/sidewalk-onboard-prereq-gateway.html)。
## 描述您的 Sidewalk 資源
在您開始使用並建立資源之前，建議您考慮 Sidewalk 終端裝置、裝置設定檔和目的地的命名慣例。適用於 Amazon Sidewalk 的 AWS IoT Core 會為您建立的資源指派一個唯一識別碼。但是，您可為其提供更多描述性的名稱，新增描述或新增選用標籤，協助其進行識別和管理。
**注意**
目的地名稱建立後便無法變更。使用一個對您 AWS 帳戶 和 AWS 區域 的唯一名稱。
如需詳細資訊，請參閱[描述您的 AWS IoT Wireless 資源](iotwireless-describe-resources.md)。
**Topics**
+ [
## 必要條件
](#sidewalk-connect-prereq)
+ [
## 描述您的 Sidewalk 資源
](#sidewalk-connect-resources)
+ [
# 將您的裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core
](iot-sidewalk-create-device.md)
+ [
# 為您的 Sidewalk 終端裝置新增目的地
](iot-sidewalk-qsg-destination.md)
+ [
# 連接您的 Sidewalk 裝置並檢視上行中繼資料格式
](iot-sidewalk-connect-uplink-metadata.md)
# 將您的裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core
建立無線裝置之前，請先建立裝置設定檔。裝置設定檔定義 Sidewalk 裝置的裝置功能及其他參數。單一裝置設定檔可與多個裝置建立關聯。
建立裝置設定檔後，當您擷取設定檔的相關資訊時，其會傳回一個 `DeviceTypeId`。當您佈建終端裝置時，將會使用此 ID、裝置憑證、應用程式伺服器公有金鑰和 SMSN。
## 如何建立和新增您的裝置
1. 建立您 Sidewalk 終端裝置的裝置設定檔。將要用於您 Sidewalk 裝置的設定檔名稱指定為英數字串。設定檔將有助於識別要與其關聯的裝置。
+ (主控台) 新增您的 Sidewalk 裝置時，您也可建立新的設定檔。這樣有助於快速將您的裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core，並將其與設定檔建立關聯。
+ (API) 透過指定設定檔名稱和 Sidewalk 物件 `sidewalk {}` 來使用 `CreateDeviceProfile` API 操作。API 回應將包含設定檔 ID 和 ARN (Amazon Resource Name)。
1. 將您的無線裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core。指定目的地名稱，並選擇您於上一個步驟中所建立的裝置設定檔。
+ (主控台) 新增 Sidewalk 裝置時，請輸入目的地名稱，然後選擇您所建立的設定檔。
+ (API) 使用 `CreateWirelessDevice` API 操作。指定目的地名稱及先前所取得的裝置設定檔 ID。
**無線裝置參數**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-wireless/latest/developerguide/iot-sidewalk-create-device.html)
1. 取得包含佈建終端裝置所需資訊的 JSON 檔案。
+ (主控台) 從您所建立 Sidewalk 裝置的詳細資訊頁面下載此檔案。
+ (API) 使用 `GetDeviceProfile` 和 `GetWirelessDevice` API 操作擷取有關您裝置設定檔和無線裝置的資訊。將 API 回應資訊儲存為 JSON 檔案，例如 *`device_profile.json`* 和 *`wireless_device.json`*。
# 新增您的裝置設定檔和 Sidewalk 終端裝置
本節展示如何建立裝置設定檔。此外也將說明如何使用 AWS IoT 主控台和 AWS CLI，將 Sidewalk 終端裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core。
## 新增您的 Sidewalk 裝置 (主控台)
如要使用 AWS IoT 主控台新增您的 Sidewalk 裝置，請移至[裝置中樞的 Sidewalk 索引標籤](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk)，選擇**佈建裝置**，然後執行下列步驟。
![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/iot-wireless/latest/developerguide/images/iot-sidewalk-provision-device.PNG)
1.
**指定裝置詳細資訊**
指定您 Sidewalk 裝置的組態資訊。您還可建立新的裝置設定檔，或為您的 Sidewalk 裝置選擇現有的設定檔。
1. 指定裝置名稱和選用說明。該說明的長度最多可達 2,048 個字元。您可在建立裝置後編輯這些欄位。
1. 選擇要與 Sidewalk 裝置建立關聯的裝置設定檔。若您有任何現有的裝置設定檔，則可選擇您的設定檔。如要建立新的設定檔，請選擇**建立新設定檔**，接著輸入該設定檔的名稱。
**注意**
如要將標籤附加至裝置設定檔，在建立設定檔之後，請移至[設定檔中樞](https://console.aws.amazon.com/iot/home#/wireless/profiles)，然後編輯您的設定檔以新增此資訊。
1. 指定將訊息從您的裝置路由至其他 AWS 服務 的目的地名稱。若您尚未建立目的地，請移至[目的地中樞](https://console.aws.amazon.com/iot/home#/wireless/destinations)，來建立目的地。接著，您可選擇您 Sidewalk 裝置的目的地。如需詳細資訊，請參閱[為您的 Sidewalk 終端裝置新增目的地](iot-sidewalk-qsg-destination.md)。
1. 選擇**下一步**，繼續新增您的 Sidewalk 裝置。
1.
**將 Sidewalk 裝置與 AWS IoT 物件產生關聯 (選用)**
您可選擇將 Sidewalk 裝置與 AWS IoT 物件產生關聯。IoT 物件是 AWS IoT 裝置登錄檔中的項目。物件可讓您更輕鬆地搜尋和管理您的裝置。將物件與您的裝置相關連可讓您的裝置存取其他 AWS IoT Core 功能。
如要將裝置與物件建立關聯，請選擇**自動物件註冊**。
1. 為您要與 Sidewalk 裝置建立關聯的 IoT 物件輸入唯一名稱。物件名稱區分大小寫，且在 AWS 帳戶 和 AWS 區域 中必須是唯一的。
1. 為您的 IoT 物件提供任何其他組態，例如使用物件類型，或可用來從物件清單中篩選的可搜尋屬性。
1. 選擇**下一步**，並驗證 Sidewalk 裝置的相關資訊，然後選擇**建立**。
## 新增您的 Sidewalk 裝置 (CLI)
如要新增您的 Sidewalk 裝置，並下載將用來佈建您 Sidewalk 裝置的 JSON 檔案，請執行下列 API 操作。
**Topics**
+ [
### 步驟 1：建立裝置設定檔
](#iot-sidewalk-profile-create)
+ [
### 步驟 2：新增您的 Sidewalk 裝置
](#iot-sidewalk-device-create)
### 步驟 1：建立裝置設定檔
如要於 AWS 帳戶 中建立一個裝置設定檔，請使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDeviceProfile.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html) CLI 命令。當您建立裝置設定檔時，請指定名稱並提供任何選用標籤為名稱/值組。
例如，下列命令會建立 Sidewalk 裝置的裝置設定檔。
```
aws iotwireless create-device-profile \
--name sidewalk_profile --sidewalk {}
```
執行此命令會傳回 Amazon Resource Name (ARN) 和裝置設定檔 ID 作為輸出。
```
{
"DeviceProfileArn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"DeviceProfileId": "12345678-a1b2-3c45-67d8-e90fa1b2c34d"
}
```
### 步驟 2：新增您的 Sidewalk 裝置
如要將您的 Sidewalk 裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core 帳戶，請使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateWirelessDevice.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html) CLI 命令。當您建立裝置時，除了您 Sidewalk 裝置的選用名稱和描述之外，請指定下列參數。
**注意**
若您想要建立 Sidewalk 裝置與 AWS IoT 物件的關聯，請使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_AssociateWirelessDeviceWithThing.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_AssociateWirelessDeviceWithThing.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/associate-wireless-device-with-thing.html](https://docs.aws.amazon.com/cli/latest/reference/associate-wireless-device-with-thing.html) CLI 命令。
下列命令顯示建立 Sidewalk 裝置的範例：
```
aws iotwireless create-wireless-device \
--cli-input-json "file://device.json"
```
下列顯示 `device.json` 檔案的內容。
**device.json 的內容**
```
{
"Type": "Sidewalk",
"Name": "SidewalkDevice",
"DestinationName": "SidewalkDestination",
"Sidewalk": {
"DeviceProfileId": "12345678-a1b2-3c45-67d8-e90fa1b2c34d"
}
}
```
執行此命令會傳回裝置 ID 與 Amazon Resource Name (ARN) 作為輸出。
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:WirelessDevice/23456789-abcd-0123-bcde-fabc012345678",
"Id": "23456789-abcd-0123-bcde-fabc012345678"
}
```
# 取得裝置 JSON 檔案，進行佈建
將 Sidewalk 裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core 後，請下載包含佈建終端裝置所需資訊的 JSON 檔案。您可以使用 AWS IoT 主控台或 AWS CLI 來擷取此資訊。如需有關如何佈建裝置的詳細資訊，請參閱《Amazon Sidewalk 文件》**中的[佈建和註冊您的終端裝置](https://docs.sidewalk.amazon/provisioning/)。
## 取得 JSON 檔案 (主控台)
如要取得 JSON 檔案，以佈建您的 Sidewalk 裝置：
1. 請移至 [Sidewalk 裝置中樞](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk)。
1. 選擇您新增至適用於 Amazon Sidewalk 的 AWS IoT Core 的裝置，以檢視其詳細資訊。
1. 在您新增裝置的詳細資料頁面中選擇**下載裝置 JSON 檔案**，以取得 JSON 檔案。
將會下載 `certificate.json` 檔案，其包含佈建終端裝置所需的資訊。下列顯示範本 JSON 檔案。其包含裝置憑證、私有金鑰、Sidewalk 製造序號 (SMSN) 和 `DeviceTypeID`。
```
{
"p256R1": "grg8izXoVvQ86cPVm0GMyWuZYHEBbbH ... DANKkOKoNT3bUGz+/f/pyTE+xMRdIUBZ1Bw==",
"eD25519": "grg8izXoVvQ86cPVm0GMyWuZYHEBbbHD ... UiZmntHiUr1GfkTOFMYqRB+Aw==",
"metadata": {
"devicetypeid": "fe98",
"applicationDeviceArn": "arn:aws:iotwireless:us-east-1:123456789012:WirelessDevice/897ce68e-3ca2-4ed0-85a2-30b0666c4052",
"applicationDeviceId": "897ce68e-3ca2-4ed0-85a2-30b0666c4052",
"smsn": "82B83C8B35E856F43CE9C3D59B418CC96B996071016DB1C3BE5901F0F3071A4A",
"devicePrivKeyP256R1": "3e704bf8d319b3a475179f1d68c60737b28c708f845d0198f2d00d00c88ee018",
"devicePrivKeyEd25519": "17dacb3a46ad9a42d5c520ca5f47f0167f59ce54d740aa13918465faf533b8d0"
},
"applicationServerPublicKey": "5ce29b89c2e3ce6183b41e75fe54e45f61b8bb320efbdd2abd7aefa5957a316b"
}
```
在 Sidewalk 裝置的詳細資訊頁面中，您也會看到下列相關資訊：
+ 裝置 ID、其 Amazon Resource Name (ARN)，及裝置與之關聯的任何 AWS IoT 物件的相關詳細資訊。
+ 裝置設定檔和目的地詳細資訊。
+ 從裝置所收到最後一則上行訊息的時間。
+ 指出您裝置是否已佈建或註冊的狀態。
## 取得 JSON 檔案 (CLI)
如要使用適用於 Amazon Sidewalk 的 AWS IoT Core API 或 AWS CLI 取得 JSON 檔案來佈建 Sidewalk 終端裝置，請將擷取裝置設定檔和無線裝置相關資訊的 API 回應以 JSON 檔案形式暫存為 *`wireless_device.json`* 和 *`device_profile.json`* 等檔案。您將會使用它們佈建您的 Sidewalk 裝置。
下列顯示如何擷取 JSON 檔案。
**Topics**
+ [
### 步驟 1：取得裝置設定檔資訊作為 JSON 檔案
](#iot-sidewalk-profile-get)
+ [
### 步驟 2：取得 Sidewalk 裝置資訊作為 JSON 檔案
](#iot-sidewalk-get-device)
### 步驟 1：取得裝置設定檔資訊作為 JSON 檔案
使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetDeviceProfile.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html) CLI 命令，以取得您為適用於 Amazon Sidewalk 的 AWS IoT Core 新增至帳戶之裝置設定檔的相關資訊。如要擷取裝置設定檔的相關資訊，請指定設定檔 ID。
接著，API 將會傳回與所指定識別符與裝置 ID 相符之裝置設定檔的資訊。您可將此回應資訊另存為檔案，並為其命名，如 *`device_profile.json`*。
下列顯示範例 CLI 命令：
```
aws iotwireless get-device-profile \
--id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" > device_profile.json
```
執行此命令會傳回裝置設定檔的參數、應用程式伺服器公有金鑰，和 `DeviceTypeID`。下列顯示 JSON 檔案，其包含來自 API 的範例回應資訊。如需有關 API 回應中參數的詳細資訊，請參閱 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetDeviceProfile.html)。
**`GetDeviceProfile` API 回應 (`device_profile.json` 的內容)**
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Name": "Sidewalk_profile",
"LoRaWAN": null,
"Sidewalk":
{
"ApplicationServerPublicKey": "a123b45c6d78e9f012a34cd5e6a7890b12c3d45e6f78a1b234c56d7e890a1234",
"DAKCertificateMetadata": [
{
"DeviceTypeId: "fe98",
"CertificateId": "43564A6D2D50524F544F54595045",
"FactorySupport": false,
"MaxAllowedSignature": 1000
}
],
"QualificationStatus": false
}
}
```
### 步驟 2：取得 Sidewalk 裝置資訊作為 JSON 檔案
使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetWirelessDevice.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device.html) CLI 命令，以取得您為適用於 Amazon Sidewalk 的 AWS IoT Core 新增至帳戶之 Sidewalk 裝置的相關資訊。如要取得終端裝置的相關資訊，請提供您在新增裝置時取得的無線裝置識別符。
接著，API 將會傳回與所指定識別符及裝置 ID 相符之裝置的資訊。將此回應資訊儲存為 JSON 檔案。為檔案提供一個有意義的名稱，例如 *`wireless_device.json`*。
下列顯示使用 CLI 執行命令的範例：
```
aws iotwireless get-wireless-device --identifier-type WirelessDeviceId \
--identifier "23456789-abcd-0123-bcde-fabc012345678" > wireless_device.json
```
執行此命令會傳回裝置詳細資訊、裝置憑證、私有金鑰和 Sidewalk 製造序號 (SMSN)。下列會顯示執行此命令的範例輸出。如需有關 API 回應中參數的詳細資訊，請參閱 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetWirelessDevice.html)。
**`GetWirelessDevice` API 回應 (`wireless_device.json` 的內容)**
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:WirelessDevice/23456789-abcd-0123-bcde-fabc012345678",
"Id": "23456789-abcd-0123-bcde-fabc012345678",
"DestinationName": "SidewalkDestination",
"Type": "Sidewalk",
"Sidewalk": {
"CertificateId": "4C7438772D50524F544F54595045",
"DeviceCertificates": [
{
"SigningAlg": "Ed25519",
"Value": "hDdkJw9L2uMCORjImjMHqzNR6nYYh6QKncSl5GthQNl7NKe4ounb5UMQtLjnm7zOUPYOqghCeVOLCBUiQe2ZiMBEW18JDUXIhffPobqZgohK91+LKFJ10X/F+GeltcafZcFKhS+O5NPcVNR/fHYaf/cn5iUbRwlz/T+ODXvGdwkBkgDyFgoUJgn7JdzFjaneE5qzTWXUbL79i1sXToGGjP8hiD9jJhidPWhIswleydAWgO1OZGA4CjzIaSGVM1VtaLB0VDphAkEpjMkZrtVDH3S8U1vDZTVi6YSbnkYZgfWv/uMMBfgAeL8Tdv5LkFIPIB3ZX9zt8zzmAuFRzI4MuNjWfIDnOF6AKu37WWU6/QYhZoQrW9D/wndiCcsRGl+ANn367r/HE02Re4DOiCfs9f2rjc4LT1LKt7g/KW2ii+W+9HYvvY0bBAI+AHx6Cx4j+djabTsvrgW2k6NU2zUSM7bdDP3z2a2+Z4WzBji/jYwt/OP8rpsy5Ee4ywXUfCsfQ0rKOr0zay6yh27p3I3MZle2oCO4JIlqK0VbIQqsXzSSyp6XXS0lhmuGugZ1AAADGz+gFBeX/ZNN8VJwnsNfgzj4me1HgVJdUo4W9kvx9cr2jHWkC3Oj/bdBTh1+yBjOC53yHlQK/l1GHrEWiWPPnE434LRxnWkwr8EHD4oieJxC8fkIxkQfj+gHhU79Z+oAAYAAAzsnf9SDIZPoDXF0TdC9POqTgld0oXDl2XPaVD4CvvLearrOSlFv+lsNbC4rgZn23MtIBM/7YQmJwmQ+FXRup6Tkubg1hpz04J/09dxg8UiZmntHiUr1GfkTOFMYqRB+Aw=="
},
{
"SigningAlg": "P256r1",
"Value": "hDdkJw9L2uMCORjImjMHqzNR6nYYh6QKncSl5GthQNmHmGU8a+SOqDXWwDNt3VSntpbTTQl7cMIusqweQo+JPXXWElbGh7eaxPGz4ZeF5yM2cqVNUrQr1lX/6lZ+OLuycrFrLzzB9APi0NIMLqV/Rt7XJssHQs2RPcT1ul/2XVpa6ztULJeQi2JwhTb/k48wbh/EvafG/ibrIBIx9v7/dwGRAPKHq7Uwb9hHnhpa8qNOUtjeUdIwJNh9vCBFX9s22t4PdortoFxbXo9C149PDDD4wqUHJGYlCsVX/Sqqjf7Aug3h5dwdYN6cDgsuuiOm0+aBcXBGpkh7OxVxlwXkIP+11dt23TkrSUKd0B01sc9Mc/0yEBCzx5RutKBwsefzyOl4vQX3AHgV7oD/XV73THMgGiDxQ55CPaaxN/pm791VkQ76BSZaBeF+Su6tg0k/eQneklt8Du5uqkyBHVxy8MvxsBIMZ73vIFwUrLHjDeq3+nOOyQqSBMnrHKU2mAwN3zb2LolwjPkKNOh1+NNnv99L2pBcNCnhnoBULWmWAZNXJpMx9QrcSwI9AHylcgUbGQJgf9Ryun+BgewzYNdWrXyKkp4O3ZDa4f+5SVWvbY5eyDDXcohvz/OcCtuRjAkzKBCvIjBDnCv1McjVdCO3+utizGntfhAo1RZstnOoRkgVF2WuMT9IrUmzYximuTXUmWtjyFSTqgNBZwHWUTlMmjlpLCVzZQWM4zOisXUAAALPsP34BS6EzJO5AsS5pC7QTpjBtAbLN9SdXOT9w4H1x8Nkp0ujLxWRN37IEy0V9DrPK2w1g74uqWPfUPnSBjtvM55JnQpmm23WQNvHa1Vr6zmWDjzjHpcNirPbzXyBlKEhkX4xylaSMnm4UrVXtAMaAJ/csC4HPTKr3dazdvEkhwGAAAIFByCjSp/5WHc4AhsyjMvKCsZQiKgiI8ECwjfXBaSZdY4zYsRlO3FC428H1atrFChFCZT0Bqt5LPXD38bMSB+vAUJiP8XqiEdXeqf2mYMJ5ykoDpwkve/cUQfPpjzFQlQfvwjBwiJDANKkOKoNT3bUGz+/f/pyTE+xMRdIUBZ1Bw=="
}
],
"DeviceProfileId": "0ff5b0c6-f149-4498-af34-21993acd52a7",
"PrivateKeys": [
{
"SigningAlg": "Ed25519",
"Value": "2c24d4572327f23b9bef38097137c29224a9e979081b3d90124ac9dfa477934e"
},
{
"SigningAlg": "P256r1",
"Value": "38d526f29cfaf142f596deca187bd809ef71bc13435eedc885b63bb825d63def"
}
],
"SidewalkManufacturingSn": "843764270F4BDAE3023918C89A3307AB3351EA761887A40A9DC4A5E46B6140D9",
"Status": "PROVISIONED"
},
...
}
```
## 後續步驟
暫時儲存 JSON 檔案 *`wireless_device.json`* 和 *`device_profile.json`*，因為您會在下一個步驟中使用這些檔案來佈建和註冊您的終端裝置以連線至硬體平台。如需詳細資訊，請參閱《Amazon Sidewalk 文件》**中的[佈建和註冊您的終端裝置](https://docs.sidewalk.amazon/provisioning/)。
# 為您的 Sidewalk 終端裝置新增目的地
使用 AWS IoT 規則來處理資料和裝置訊息，並將其路由至其他服務。您還可定義規則來處理從裝置接收的二進位訊息，並將訊息轉換為其他格式，讓其他服務可輕鬆加以使用。目的地會將您的 Sidewalk 終端裝置與規則建立關聯，而此規則會處理裝置資料以傳送至其他 AWS 服務。
## 如何建立和使用目的地
1. 建立目的地的 AWS IoT 規則 和 IAM 角色。AWS IoT 規則指定將處理裝置資料並將其路由以供其他 AWS 服務 和您應用程式使用的規則。IAM 角色授予存取規則的權限。
1. 使用 `CreateDestination` API 操作，建立您 Sidewalk 裝置的目的地。指定目的地名稱、規則名稱、角色名稱和任何選用的參數。API 會傳回目的地的唯一識別碼，您可於將終端裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core 時加以指定。
下列展示如何建立目的地，及目的地的 AWS IoT 規則和 IAM 角色。
**Topics**
+ [
## 如何建立和使用目的地
](#iot-sidewalk-destination-how)
+ [
# 建立您 Sidewalk 裝置的目的地
](iot-sidewalk-destination-create.md)
+ [
# 為您的目的地建立 IAM 角色和 IoT 規則
](sidewalk-destination-rule-role.md)
# 建立您 Sidewalk 裝置的目的地
您可從使用[目的地中樞](https://console.aws.amazon.com/iot/home#/wireless/destinations)或使用 `CreateDestination`，將目的地新增至您的適用於 Amazon Sidewalk 的 AWS IoT Core 帳戶。建立目的地時，請指定：
+ 一個用於您 Sidewalk 終端裝置之目的地的唯一名稱。
**注意**
若您已使用目的地名稱新增裝置，則在建立目的地時必須使用該名稱。如需詳細資訊，請參閱[步驟 2：新增您的 Sidewalk 裝置](iot-sidewalk-add-device.md#iot-sidewalk-device-create)。
+ 將要處理裝置資料的 AWS IoT 規則名稱，及訊息將要發佈的主題。
+ 授予裝置資料存取規則權限的 IAM 角色。
下列章節說明如何建立您目的地的 AWS IoT 規則和 IAM 角色。
## 建立目的地 (主控台)
如要使用 AWS IoT 主控台建立目的地，請移至[目的地中樞](https://console.aws.amazon.com/iot/home#/wireless/destinations)，並選擇**新增目的地**。
![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/iot-wireless/latest/developerguide/images/iot-sidewalk-add-destination.PNG)
如要處理裝置的資料，請在建立目的地時指定下列欄位，然後選擇**新增目的地**。
+
**目的地詳細資訊**
為您的目的地輸入 **Destination name** (目的地名稱) 和選用描述。
+
**規則名稱**
AWS IoT 規則被設定為評估裝置傳送的訊息並處理裝置的資料。規則名稱會映射至目的地。目的地需要規則來處理接收到的訊息。您可以選擇透過叫用 AWS IoT 規則或發佈至 AWS IoT 訊息代理程式的方式來處理訊息。
+ 如果選擇 **Enter a rule name** (輸入規則名稱)，請輸入名稱然後選擇 **Copy** (複製)，來複製您在建立 AWS IoT 規則時將輸入的規則名稱。您可以選擇 **Create rule** (建立規則) 來立即建立規則，或導覽至 AWS IoT 主控台的[規則](https://console.aws.amazon.com/iot/home#/create/rule)中樞，並使用該名稱建立規則。
您也可以輸入規則，再使用 **Advanced** (進階) 設定來指定主題名稱。主題名稱會在規則叫用期間提供，而且可以使用規則中的 `topic` 運算式存取。如需有關 AWS IoT 規則的更多資訊，請參閱 [AWS IoT 規則](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)。
+ 若您選擇**發佈至 AWS IoT 訊息代理程式**，請輸入主題名稱。然後您可以複製 MQTT 主題名稱，多位訂閱者可以訂閱此主題，以接收發佈至該主題的訊息。如需更多詳細資訊，請參閱 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
如需有關目的地之 AWS IoT 規則的詳細資訊，請參閱[建立規則來處理 LoRaWAN 裝置訊息](https://docs.aws.amazon.com/iot/latest/developerguide/connect-iot-lorawan-destination-rules.html)。
+
**角色名稱**
授予裝置資料許可，以存取在 **Rule name** (規則名稱) 中命名之規則的 IAM 角色。您可以在主控台中建立新的服務角色，或選取現有的服務角色。如果正在建立新的服務角色，您可以輸入角色名稱 (例如 **SidewalkDestinationRole**)，或為 AWS IoT Core for LoRaWAN 保留為空白以產生新的角色名稱。AWS IoT Core for LoRaWAN 會代表您自動建立具有適當許可的 IAM 角色。
## 建立目的地 (CLI)
如要建立一個目的地，請使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDestination.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDestination.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/create-destination.html](https://docs.aws.amazon.com/cli/latest/reference/create-destination.html) CLI 命令。例如，下列命令會建立一個 Sidewalk 終端裝置的目的地。
```
aws iotwireless create-destination --name SidewalkDestination \
--expression-type RuleName --expression SidewalkRule \
--role-arn arn:aws:iam::123456789012:role/SidewalkRole
```
執行此命令會傳回目的地詳細資訊，此包括 Amazon Resource Name (ARN) 和目的地名稱。
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:Destination/SidewalkDestination",
"Name": "SidewalkDestination"
}
```
如需有關建立目的地的詳細資訊，請參閱[建立規則來處理 LoRaWAN 裝置訊息](https://docs.aws.amazon.com/iot/latest/developerguide/connect-iot-lorawan-destination-rules.html)。
# 為您的目的地建立 IAM 角色和 IoT 規則
AWS IoT 規則會將裝置訊息傳送至其他服務。AWS IoT 規則還可處理從 Sidewalk 終端裝置接收的二進位訊息，以供其他服務使用。適用於 Amazon Sidewalk 的 AWS IoT Core 目的地會將無線裝置與規則建立關聯，而此規則會處理裝置訊息資料以傳送至其他服務。一旦適用於 Amazon Sidewalk 的 AWS IoT Core 收到裝置資料，該規則就會對裝置資料採取行動。對於將其資料傳送至相同服務的所有裝置，您可建立可供所有裝置共用的目的地。您還需建立 IAM 角色，授與將資料傳送至規則的權限。
## 為您的目的地建立 IAM 角色
建立 IAM 角色，將傳送資料至 AWS IoT 規則的許可授予適用於 Amazon Sidewalk 的 AWS IoT Core。如要建立該角色，請使用 [https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iam/create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role) CLI 命令。您可將該角色命名為 *`SidewalkRole`*。
```
aws iam create-role --role-name SidewalkRole \
--assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
```
您也可使用 JSON 檔案來定義角色的信任政策。
```
aws iam create-role --role-name SidewalkRole \
--assume-role-policy-document file://trust-policy.json
```
下列顯示 JSON 檔案的內容。
**trust-policy.json 的內容**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
## 為您的目的地建立規則
請使用 AWS IoT Core API 操作 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html)，或 AWS CLI 命令 [https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) 來建立一個規則。您的目的地將使用主題規則，將從 Sidewalk 終端裝置接收的資料路由至其他 AWS 服務。例如，您可建立一個將訊息傳送至 Lambda 函數的規則動作。您可以定義 Lambda 函數，使其從您的裝置接收應用程式資料，並使用 base64 解碼承載資料，則其他應用程式可以使用該函數。
下列步驟顯示如何建立 Lambda 函數，接著建立將訊息傳送至此函數的主題規則。
1.
**建立執行角色和原則**
建立一個 IAM 角色，授予您函數存取 AWS 資源的權限。您也可使用 JSON 檔案來定義角色的信任政策。
```
aws iam create-role --role-name lambda-ex \
--assume-role-policy-document file://lambda-trust-policy.json
```
下列顯示 JSON 檔案的內容。
**lambda-trust-policy.json 的內容**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
1.
**建立並測試 Lambda 函數**
執行下列步驟來建立 base64 解碼承載資料的 AWS Lambda 函數。
1. 撰寫用於解碼負載資料的程式碼。例如，您可使用下列 Python 程式碼範例。指定指令碼的名稱，例如 *`base64_decode.py`*。
**base64\$1decode.py 的內容**
```
// -----------------------------------------------------------
// ----- Python script to decode incoming binary payload -----
// -----------------------------------------------------------
import json
import base64
def lambda_handler(event, context):
message = json.dumps(event)
print (message)
payload_data = base64.b64decode(event["PayloadData"])
print(payload_data)
print(int(payload_data,16))
```
1. 將部署套件建立為一個包含 Python 檔案的 zip 檔案，並將其命名為 `base64_decode.zip`。使用 `CreateFunction` API 或 `create-function` CLI 命令，為範例程式碼 *`base64_decode.py`* 建立 Lambda 函數。
1.
```
aws lambda create-function --function-name my-function \
--zip-file fileb://base64_decode.zip --handler index.handler \
--runtime python3.9 --role arn:aws:iam::123456789012:role/lambda-ex
```
您應該會看到下列輸出。建立主題規則時，您將會使用輸出 `FunctionArn` 中的 Amazon Resource Name (ARN) 值。
```
{
"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function",
"Runtime": "python3.9",
"Role": "arn:aws:iam::123456789012:role/lambda-ex",
"Handler": "index.handler",
"CodeSha256": "FpFMvUhayLkOoVBpNuNiIVML/tuGv2iJQ7t0yWVTU8c=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "PassThrough"
},
"RevisionId": "88ebe1e1-bfdf-4dc3-84de-3017268fa1ff",
...
}
```
1. 如要從命令列取得某次調用的日誌，請使用具有 `invoke` 命令的 `--log-type` 選項。該回應包括 LogResult 欄位，其內含該次調用的 base64 編碼日誌 (最大達 4 KB)。
```
aws lambda invoke --function-name my-function out --log-type Tail
```
您應該會收到 `StatusCode` 為 200 的回應。如需有關從 AWS CLI 建立並使用 Lambda 函數的詳細資訊，請參閱 [Lambda 與 AWS CLI 搭配使用](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-awscli.html)。
1. 建立主題規則
使用 `CreateTopicRule` API 或 `create-topic-rule` CLI 命令，建立將訊息傳送至此 Lambda 函數的主題規則。您還可新增一個重新發佈至 AWS IoT 主題的第二個規則動作。將此主題規則命名為 `Sidewalkrule`。
```
aws iot create-topic-rule --rule-name Sidewalkrule \
--topic-rule-payload file://myrule.json
```
您可使用 `myrule.json` 檔案，來指定有關規則的更多詳細資訊。例如，下列 JSON 檔案顯示如何重新發佈至 AWS IoT 主題，及如何將訊息傳送至 Lambda 函數。
```
{
"sql": "SELECT * ",
"actions": [
{
// You obtained this functionArn when creating the Lambda function using the
// create-function command.
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function"
}
},
{
// This topic can be used to observe messages exchanged between the device and
// AWS IoT Core for Amazon Sidewalk after the device is connected.
"republish": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/SidewalkRepublishRole",
"topic": "project/sensor/observed"
}
}
],
}
```
# 連接您的 Sidewalk 裝置並檢視上行中繼資料格式
於本教學課程中，您將會使用 MQTT 測試用戶端來測試連線，並查看在您終端裝置和 AWS 雲端 之間的訊息交換。如要接收訊息，請於 MQTT 測試用戶端中訂閱在建立目的地的 IoT 規則時所指定的主題。您還可使用 `SendDataToWirelessDevice` API 操作，將下行訊息從適用於 Amazon Sidewalk 的 AWS IoT Core 傳送至您的裝置。您可啟用訊息傳遞狀態事件通知，確認訊息已傳遞。
**注意**
如需連接硬體平台並進行設定的相關資訊，請參閱《Amazon Sidewalk 文件》**中的[佈建和註冊終端裝置](https://docs.sidewalk.amazon/provisioning/)和[設定硬體開發套件 (HDK)](https://docs.sidewalk.amazon/getting-started/sidewalk-onboard-prereq-hdk.html)。
## 將下行訊息傳送至您的終端設備
使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_SendDataToWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_SendDataToWirelessDevice.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html) CLI 指令，將下行訊息從適用於 Amazon Sidewalk 的 AWS IoT Core 傳送至您的 Sidewalk 終端裝置。下列顯示如何執行此命令的範例。承載資料是要傳送的二進位，以 base64 編碼。
```
aws iotwireless send-data-to-wireless-device \
--id "" \
--payload-data "SGVsbG8gVG8gRGV2c2lt" \
--wireless-metadata Sidewalk={Seq=1,AckModeRetryDurationSecs=10}
```
下列顯示執行此命令的範例輸出，這是傳送至裝置的下行訊息 ID。
```
{
MessageId: "6011dd36-0043d6eb-0072-0008"
}
```
**注意**
`SendDataToWirelessDevice` API 可以傳回訊息 ID，但該訊息可能無法成功傳遞。如要檢查傳送至裝置的訊息狀態，您可為 Sidewalk 帳戶和裝置啟用訊息傳遞狀態事件。如需如何啟用這些事件的詳細資訊，請參閱 [Sidewalk 資源的事件通知](iot-sidewalk-events.md)。如需此事件類型的詳細資訊，請參閱[訊息傳遞事件](https://docs.aws.amazon.com/iot/latest/developerguide/iot-sidewalk-message-delivery-events.html)。
## 檢視從裝置傳送的上行訊息格式
在連接至您的裝置後，您可訂閱主題 (例如，*`project/sensor/observed`*)，此主題是您在建立目的地規則，並從裝置觀察上行訊息時所指定的。
若您在建立目的地時指定了主題名稱，則可訂閱從您終端裝置監控上行訊息的主題。請移至 AWS IoT 主控台之**測試**頁面上的 [MQTT 測試用戶端](https://console.aws.amazon.com/iot/home#/test)，輸入主題名稱 (例如，*`project/sensor/observed`*)，接著選擇**訂閱**。
下列範例顯示從 Sidewalk 裝置傳送至 AWS IoT 之上行訊息的格式。`WirelessMetadata` 包含有關訊息請求的中繼資料。
```
{
"PayloadData":"ZjRlNjY1ZWNlNw==",
"WirelessDeviceId":"wireless_device_id",
"WirelessMetadata":{
"Sidewalk":{
"CmdExStatus":"Cmd",
"SidewalkId":"device_id",
"Seq":0,
"MessageType":"messageType"
}
}
}
```
下表顯示上行中繼資料中不同參數的定義。此 `device-id` 是無線裝置的 ID，如 `ABCDEF1234`，而 `messageType` 是從裝置所接收之上行訊息的類型。
**Sidewalk 上行中繼資料參數**
| 參數 | 描述 | 類型 | 必要 |
| --- | --- | --- | --- |
| PayloadData | 從無線裝置傳送之訊息承載。 | 字串 | 是 |
| WirelessDeviceID | 發送資料的無線裝置識別符 | 字串 | 是 |
| Sidewalk.CmdExStatus | 命令執行時間狀態。回應類型訊息應該包含狀態碼 `COMMAND_EXEC_STATUS_SUCCESS`。不過，通知可能未包含狀態碼。 | 列舉 | 否 |
| Sidewalk.NackExStatus | 回應未確認狀態，可以是 `RADIO_TX_ERROR` 或 `MEMORY_ERROR`。 | 字串陣列 | 否 |