Ameba IoT Hub Plug and Play 示例

Ameba IoT Hub Plug and Play 示例展示了 Ameba 与 Azure IoT 服务交互的能力。我们提供了两个分别使用 SAS 或 X509 认证的示例，其功能在 Realtek Ameba 系列模型文件中描述。我们将详细介绍 Ameba 支持的功能，以及使用 Azure IoT Explorer 向 Ameba 设备发送和接收数据的方法。

Ameba IoT Hub Plug and Play 示例

Ameba IoT Hub Plug and Play 示例是负责 Ameba SDK 组件与 Azure IoT 服务之间通信的应用程序。我们的 SDK 中基本提供了两个示例：example_azure_iot_rtk_pnp_x509 和 example_azure_iot_rtk_pnp_sas，二者功能完全相同，仅连接到 DPS 和 IoT Hub 的认证类型不同。

Wi-Fi 连接后，示例将继续运行。示例开始时，将连接到您的 DPS 并将设备注册到 IoT Hub。如果成功，您应该能在 Azure IoT Explorer 上看到您的设备，或者在 Azure IoT Central 上看到已预配的设备。接下来，示例将连接到 IoT Hub 上已预配的设备，并为 Ameba 设备启动 plug and play 流程：

通过 MQTT 订阅命令、设备孪生期望属性和响应。
初始化所有组件。如果有需要初始化的初始值或只读属性，可在此阶段完成。
首次为所有组件更新上报属性，然后发送孪生文档请求以检查 IoT Hub 上的设备状态。
启动遥测线程。该线程负责所有组件的遥测。
开始接收从 IoT Hub 订阅的消息。Ameba 设备将对传入消息做出反应，完成相应组件上的适当操作，并响应 IoT Hub。

X509 和 SAS 示例的配置如下：

X509:

Ameba IoT Hub Plug and Play 示例（X509 证书认证），通过 DPS 预配设备并启动 plug and play 流程。

在

example_azure_iot_entry.h 中选择 Ameba IoT Hub Plug and Play X509 示例

取消注释 EXAMPLE_AZURE_IOT_RTK_PNP_X509 以选择该示例。

修改 example_azure_iot_rtk_pnp_x509.c 中的参数

将 ID_SCOPE 修改为您自己的 DPS ID 范围。

将 REGISTRATION_ID 修改为您自己的 DPS 注册 ID。

将 X509CERTIFICATE 修改为您自己的 x509 证书。

将 X509PRIVATEKEY 修改为您自己的 x509 私钥。

请确保证书具有 x509 v3 扩展。如果要连接到 Azure IoT Central 进行设备预配，还需要确保 x509 证书中的颁发者和主体 CN 设置为您的设备 ID。

SAS:

Ameba IoT Hub Plug and Play 示例（SAS 认证），通过 DPS 预配设备并启动 plug and play 流程。

在

example_azure_iot_entry.h 中选择 Ameba IoT Hub Plug and Play SAS 示例

取消注释 EXAMPLE_AZURE_IOT_RTK_PNP_SAS 以选择该示例。

修改 example_azure_iot_rtk_pnp_sas.c 中的参数

将 ID_SCOPE 修改为您自己的 DPS ID 范围。

将 REGISTRATION_ID 修改为您自己的 DPS 注册 ID。

将 SAS_KEY 修改为您自己的 SAS 密钥。

Plug and Play 模型

Realtek plug and play 模型文件存放在 Microsoft 公共仓库的 Realtek 文件夹，使用数字孪生定义语言 (DTDL) 定义。模型文件分为多个组件，每个组件代表设备的一项功能，并详细描述其遥测、属性和命令，以便与 Azure IoT 服务进行交互。

Ameba IoT Hub PnP 示例成功执行后，您可以在 Azure IoT Explorer 上检查已注册的设备，其"IoT Plug and Play 设备"列显示为 dtmi:realtek:rtk_ameba_series;1。

image_pnp_device

接下来，您可以在 Azure IoT Explorer 上检查所有组件并与 Ameba 进行交互。

每个组件上有四种类型的接口可供检查。点击"IoT Plug and Play 组件"页面上的任意组件，将看到组件详情和如下所示的选项卡。

[Property] 只读属性。您可以在"Properties (read-only)"选项卡中查看属性。
[Writable Property] 可写属性。您可以在"Properties (writable)"选项卡中修改可写属性。
[Telemetry] 遥测。您可以在"Telemetry"选项卡中查看收到的遥测消息。
[Command] 命令。您可以在"Commands"选项卡中发送命令。

Ameba 系列

Ameba 系列是 Ameba 设备模型文件入口，是包含设备所有组件的默认组件。我们的 plug and play 示例在连接到 DPS 和 IoT Hub 时注册此模型文件的模型 ID。在 Azure IoT Explorer 上已注册设备的 IoT Plug and Play 组件页面中点击后，将看到此组件页面。

Audio:

音频组件定义了设备的音频功能。目前仅包含一个支持属性，未来可进行扩展。

[Property] audio_support：设备音频支持。

GPIO:

GPIO 组件定义了设备的 GPIO 功能。在示例中，引脚复用 PA 12 和 PB 10 为默认值，可直接用于 gpio 命令，但需要使用 gpio_set 进行初始化。PB 10 是 PullNone 模式的输出引脚，可用作 LED 引脚。PA 12 是 PullUp 模式的输入引脚，可用作按键引脚。您可以使用以下命令在 Ameba 设备上测试这两个 GPIO 引脚。

引脚复用是端口号和引脚号的组合。端口号有 PA 和 PB 两种类型。有关特定端口号的详细信息，请联系 Realtek FAE 获取更多信息。

[Property] gpio_support：设备 GPIO 支持。
[Command] gpio_set：给定引脚模式和方向的引脚复用，Ameba 设备将设置对应的 GPIO 引脚。如果引脚号超出范围，您将在 Azure IoT Explorer 上收到错误请求响应，否则将收到成功响应。
[Command] gpio_read：从设备读取 GPIO 状态。引脚低电平返回 0，引脚高电平返回 1。如果 GPIO 引脚未初始化（默认状态或通过 gpio_set），将收到错误请求响应，否则将收到成功响应。
[Command] gpio_write：向所选输出端口引脚写入值。可选择 OFF 将引脚设为低电平，选择 ON 将引脚设为高电平。如果 GPIO 引脚未初始化（默认状态或通过 gpio_set），将收到错误请求响应，否则将收到成功响应。

System:

系统组件定义了设备的系统详情。

[Property] build_info：固件的编译信息，以包含 4 个字段的对象表示：fw_compile_time （固件生成时间）、fw_compile_by （编译固件的人员姓名）、fw_compile_host （编译固件的主机设备）和 fw_compiler （编译器信息）。此信息由 Ameba SDK 自动生成。
[Property] os_info：固件的 OS 信息。
[Property] processor_architecture：设备处理器架构。
[Telemetry] device_runtime：显示设备已运行时长，以秒为单位。
[Telemetry] cpu_usage：显示每个运行任务的 CPU 占用率。此信息直接从 Ameba 设备 OS 检索，以单个字符串表示。消息包含多个任务状态，每个任务状态显示为 "pnp_telem\t30772\t\t3%\r\n"。其中 "pnp_telem" 为任务名称，"30772" 为目前分配给该任务的总运行时间，"3%" 为该任务已使用的总运行时间百分比。要从 OS 检索任务状态，需要在 project_km4\inc\FreeRTOSConfig.h 中启用 configGENERATE_RUN_TIME_STATS。
[Writable Property] telemetry_enable_device_runtime：启用遥测中的 device_runtime 选项。设为 true 启用，设为 false 禁用。
[Writable Property] telemetry_enable_cpu_usage：启用遥测中的 cpu_usage 选项。设为 true 启用，设为 false 禁用。
[Writable Property] telemetry_interval：系统组件遥测的时间间隔，设置的数值以秒为单位。上述两项系统遥测将设置为相同的时间间隔。
[Command] reboot：系统在给定时间后重启。我们将预留 5 秒用于重启设备，以确保命令响应从设备正确发送。如果您设置的时间距现在不足 5 秒，或设置的时间已过，设备将在 5 秒后重启。
[Command] switch_to_upgraded_image：切换到 OTA 升级固件，并在 5 秒后重启设备。切换固件前应完成 OTA 流程，并确保 OTA 固件能够连接到 IoT Hub 并正常运行。
[Command] switch_to_default_image：切换回默认固件，并在 5 秒后重启设备。

Wireless:

无线组件定义了设备的 Wi-Fi 功能。

[Property] wireless_support：设备无线支持。
[Property] specification：无线规格。
[Telemetry] wifi_info：显示当前 Wi-Fi 连接信息的遥测消息，以包含 Station 模式连接信息和 Station 模式接口配置的对象表示。

Station 模式连接信息：ssid （已连接 AP 的 SSID）、channel （连接到 AP 的信道）、security （连接 AP 的安全类型，为 OPEN/WEP/TKIP/AES/UNKNOWN 之一）、password （连接 AP 的密码，开放模式下为空）。

Station 模式接口配置：mac （设备 Station 模式接口的 MAC 地址）、ip （分配的 IP 地址）、gw （网关）、msk （网络掩码）。
[Writable Property] telemetry_enable_wifi_info：启用遥测中的 wifi_info 选项。设为 true 启用，设为 false 禁用。
[Writable Property] telemetry_interval：无线组件遥测的时间间隔，设置的数值以秒为单位。
[Command] wifi_connect：使用给定的 SSID 和密码连接到指定 AP。将以成功响应回复，并在 5 秒后启动 Wi-Fi 连接线程连接到指定 AP。
[Command] wifi_scan：扫描设备周围的网络接入点。可通过提供信道号数组元素指定要扫描的信道。留空则默认扫描所有信道。请注意，扫描所有信道可能需要较长时间，并导致响应超时。响应最多包含 5 个对象，每个对象记录：idx （扫描到的 AP 索引，从 1 开始）、bss_type （Adhoc 或 Infra）、mac （AP 的 MAC 地址）、signal_strength （信号强度，单位 dB）、channel （AP 信道）、wps_type （DEFAULT/USER_SPECIFIED/MACHINE_SPECIFIED/REKEY/PUSHBUTTON/REGISTRAR_SPECIFIED/NONE/WSC/Unknown 之一）、security （Open/WEP/WPA TKIP/WPA AES/WPA2 AES/WPA2 TKIP/WPA2 Mixed/WPA/WPA2 AES/WPA3-SAE AES/Unknown 之一）、ssid （扫描到的 AP 的 SSID）。
[Command] ota：通过 Wi-Fi 进行空中固件更新。OTA 固件应放置在本地服务器上，设备将从本地服务器下载升级固件。提供 "ip_address" 作为本地服务器 IP，提供 "port" 作为本地服务器端口。OTA 完成后，可使用系统组件中的 "switch_to_upgraded_image" 和 "switch_to_default_image" 命令切换固件。有关 OTA 流程和 OTA 固件生成的详细信息，请参考 Ameba 在线文档或联系 Realtek FAE 获取更多信息。
[Command] ping：向指定主机发送 ping 请求。提供 host_address （有效 IP，如 127.0.0.1）、number （ping 次数，默认 4，最大 20）和 buffer_size （有效载荷大小，默认 32 字节）。ping 响应包含：info （您提供的 ping 信息）、content （ping 结果数组元素）和 result （ping 过程结论）。