# 连接到适用于 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 资源名称）。
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_cn/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_cn/iot-wireless/latest/developerguide/images/iot-sidewalk-provision-device.PNG)
1.
**指定设备详细信息**
指定 Sidewalk 设备的配置信息。您也可以创建新的设备配置文件，或者为 Sidewalk 设备选择现有的配置文件。
1. 指定设备名称和可选描述。描述长度最多为 2048 个字符。创建设备后，可以编辑这些字段。
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 资源名称（ARN）和设备配置文件的 ID 作为输出。
```
{
"DeviceProfileArn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"DeviceProfileId": "12345678-a1b2-3c45-67d8-e90fa1b2c34d"
}
```
### 步骤 2：添加 Sidewalk 设备
要针对适用于 Amazon Sidewalk 的 AWS IoT Core 将 Sidewalk 设备添加到您的账户中，请使用 [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 资源名称（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 文件（控制台）
要获取用于预置 Sidewalk 设备的 JSON 文件，请执行以下操作：
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 资源名称（ARN）以及与设备关联的任何 AWS IoT 事物的详细信息。
+ 设备配置文件和目标详细信息。
+ 从设备收到最后一条上行链路消息的时间。
+ 表示您的设备是已预置还是已注册的状态。
## 获取 JSON 文件（CLI）
要使用适用于 Amazon Sidewalk 的 AWS IoT Core API 或 AWS CLI 获取用于预置 Sidewalk 终端设备的 JSON 文件，请将检索有关设备配置文件和无线设备的信息时获得的 API 响应临时保存为 JSON 文件，例如 *`wireless_device.json`* 和 *`device_profile.json`*。您将使用它们来预置 Sidewalk 设备。
以下内容说明如何检索这些 JSON 文件。
**Topics**
+ [
### 步骤 1：以 JSON 文件格式获取设备配置文件信息
](#iot-sidewalk-profile-get)
+ [
### 步骤 2：以 JSON 文件形式获取 Sidewalk 设备信息
](#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：以 JSON 文件形式获取 Sidewalk 设备信息
使用 [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_cn/iot-wireless/latest/developerguide/images/iot-sidewalk-add-destination.PNG)
要处理设备的数据，请在创建目标时指定以下字段，然后选择**添加目标**。
+
**目标详细信息**
输入 **Destination name**（目标名称）以及您的目标描述（可选）。
+
**Rule name（规则名称）**
被配置为评估设备发送的消息并处理设备数据的 AWS IoT 规则。规则名称将映射到您的目标。目标要求规则来处理收到的消息。您可以通过调用 AWS IoT 规则或通过发布到 AWS IoT 消息代理。
+ 如果选择 **Enter a rule name**（输入规则名称），请输入名称，然后选择 **Copy**（复制）以复制创建 AWS IoT 规则时要输入的规则名称。您可以选择 **Create rule**（创建规则）以立即创建规则，或导航到 AWS IoT 控制台的 [Rule](https://console.aws.amazon.com/iot/home#/create/rule)（规则）中心并使用该名称创建规则。
您也可以输入规则并使用**高级**设置以指定主题名称。主题名称是在规则调用期间提供的，可通过使用 `topic` 规则中的表达式访问。有关 AWS IoT 规则的更多信息，请参阅 [AWS IoT 规则](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)。
+ 如果选择 **Publish to AWS IoT message broker**（发布到消息代理），输入主题名称。然后，您可以复制 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)。
+
**角色名称**
IAM 角色，该角色授予设备数据权限以访问在 **Rule name**（规则名称）中命名的规则。在控制台中，您可以创建新的服务角色或选择现有的服务角色。如果要创建新的服务角色，可以输入角色名称（例如，**SidewalkDestinationRole**)，或将其留白 适用于 LoRaWAN 的 AWS IoT Core 以生成新的角色名称。然后 适用于 LoRaWAN 的 AWS IoT Core 将代表您自动创建具有适当权限的 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 资源名称（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 角色来授予适用于 Amazon Sidewalk 的 AWS IoT Core 向 AWS IoT 规则发送数据的权限。要创建角色，请使用 [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 命令为示例代码创建 Lambda 函数 *`base64_decode.py`*。
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
```
您应当看到如下输出。创建主题规则时，您将使用输出中的 Amazon 资源名称（ARN）值 `FunctionArn`。
```
{
"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. 要从命令行获取调用的日志，请将 `--log-type` 选项与 `invoke` 命令一起使用。响应包含一个 LogResult 字段，该字段包含来自调用的多达 4KB 的 base64 编码日志。
```
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 | 响应 nack 状态，可以为 `RADIO_TX_ERROR` 或者 `MEMORY_ERROR`。 | 字符串数组 | 否 |