跳到主要内容
ESP RainMaker Classic 文档

语音助手使用指南

about

任何智能家居物联网系统都离不开语音助手集成。ESP RainMaker 支持与亚马逊 Alexa 和谷歌语音助手 (GVA) 集成，用户可通过语音命令控制物联网设备。

查阅此文档了解语音助手集成的应用场景。

查阅此文档了解如何在私有 RainMaker 部署中集成语音助手 （仅限商业客户）。

备注

ESP RainMaker SDK 中的标准示例，如 switch、led_light、fan 和 temperature_sensor 均支持 Alexa/GVA。本文将以这些标准示例为例，说明如何在固件代码中集成语音助手。

更多标准参数列表请参考此文档。

工作原理​

ESP RainMaker 有设备和参数的概念，并为常见场景（如开关、灯泡）预定义了一些标准类型。我们实现了一层映射，将这些参数转换为 Alexa 和 GVA 能识别的格式。因此，RainMaker 中的设备类型（如 light、switch 等）会映射到对应平台的设备类型，电源、亮度、色调、饱和度、强度等参数也会映射到相应的特性。如果只包含电源和亮度参数，则为简单的亮度可控灯；若包含色调、饱和度、强度，则在 Alexa 和 GVA 中为彩色灯。

使用指南​

本指南将引用 ESP RainMaker SDK 中的标准示例代码。

实现标准设备的代码非常简单。以下为彩色灯示例 (led_light) 的相关代码片段，注释已说明用途。

/* 创建标准灯泡设备（内部自动添加名称和电源参数） */
light_device = esp_rmaker_lightbulb_device_create("Light", NULL, DEFAULT_POWER);
esp_rmaker_device_add_cb(light_device, write_cb, NULL);

/* 添加标准亮度参数 */
esp_rmaker_device_add_param(light_device, esp_rmaker_brightness_param_create("brightness", DEFAULT_BRIGHTNESS));
/* 添加标准色调参数 */
esp_rmaker_device_add_param(light_device, esp_rmaker_hue_param_create("hue", DEFAULT_HUE));
/* 添加标准饱和度参数 */
esp_rmaker_device_add_param(light_device, esp_rmaker_saturation_param_create("saturation", DEFAULT_SATURATION));

esp_rmaker_node_add_device(node, light_device);

GitHub 上的 switch、fan 和 temperature sensor 示例也可直接用于 Alexa/GVA。编译并烧录这些示例后，通过 ESP RainMaker 手机应用配网并绑定账号。建议为设备设置易于识别的名称。

custom devices

如需自定义设备，请参考下方章节。

启用 Alexa​

  1. 在手机上打开 Alexa 应用，进入菜单的 Skills and Games，搜索 "ESP RainMaker"。
  2. 选择该技能，点击 Enable to Use，输入 RainMaker 账号信息。
  3. 账号绑定成功后，允许 Alexa 发现设备。
  4. 设备发现成功后，即可通过 Alexa 控制设备。
提示

在最新版 ESP RainMaker 手机应用中，前往 设置 > 语音服务 > Amazon Alexa，可直接在应用内启用 Alexa。

启用 Google 语音助手 (GVA)​

  1. 打开手机上的 Google Home 应用。
  2. 点击 + > Set up Device 设置设备。
  3. 选择 Works with Google（已设置的设备）。
  4. 搜索 "ESP RainMaker" 并用 RainMaker 账号登录。
  5. 账号绑定成功后，RainMaker 设备会自动显示，可直接使用。

构建自定义设备​

RainMaker 中的设备会映射到 Alexa 的 Display Categories 和 GVA 的 Devices。RainMaker 的参数会映射到 Alexa 的 Capabilities 和 GVA 的 Traits。当前支持的设备和参数列表请参考此文档。后续会持续增加支持类型。如需支持其他标准设备，可联系我们。

除标准设备外，Alexa 也支持自定义设备。未被 Alexa 支持的设备类型会以 Other 类型显示。可为其添加如 esp.param.power 等标准参数，或使用 Alexa 的通用控制器：

  • Toggle controller: esp.param.toggle
  • Mode controller: esp.param.mode
  • Range controller: esp.param.range

以空调扇为例，包含如下控制：

  • 电源控制开关
  • 摇头开关 (Toggle)
  • 风速调节 (Range)
  • 模式切换 (Auto、Turbo、Sleep)

代码如下：

     /* 创建空调扇设备并添加相关参数
      * 可自定义设备类型，如 "my.device.air-cooler"
      */
     esp_rmaker_device_t *device = esp_rmaker_device_create("Air Cooler", "my.device.air-cooler", NULL);
     esp_rmaker_device_add_cb(device, write_cb, NULL);

     /* 标准电源参数 */
     esp_rmaker_param_t *primary = esp_rmaker_power_param_create("Power", true);
     esp_rmaker_device_add_param(device, primary);
     esp_rmaker_device_assign_primary_param(device, primary);

     /* 通用 Toggle 参数 */
     esp_rmaker_param_t *swing = esp_rmaker_param_create("Swing", "esp.param.toggle", esp_rmaker_bool(true), PROP_FLAG_READ | PROP_FLAG_WRITE);
     esp_rmaker_param_add_ui_type(swing, ESP_RMAKER_UI_TOGGLE);
     esp_rmaker_device_add_param(device, swing);

     /* 通用 Range 参数 */
     esp_rmaker_param_t *speed = esp_rmaker_param_create("Speed", "esp.param.range", esp_rmaker_int(3), PROP_FLAG_READ | PROP_FLAG_WRITE);
     esp_rmaker_param_add_ui_type(speed, ESP_RMAKER_UI_SLIDER);
     esp_rmaker_param_add_bounds(speed, esp_rmaker_int(0), esp_rmaker_int(5), esp_rmaker_int(1));
     esp_rmaker_device_add_param(device, speed);

     /* 通用 Mode 参数 */
     esp_rmaker_param_t *mode = esp_rmaker_param_create("Mode", "esp.param.mode", esp_rmaker_str("Auto"), PROP_FLAG_READ | PROP_FLAG_WRITE);
     static const char *valid_strs[] = {"Auto", "Turbo", "Sleep"};
     esp_rmaker_param_add_valid_str_list(mode, valid_strs, 3);
     esp_rmaker_param_add_ui_type(mode, ESP_RMAKER_UI_DROPDOWN);
     esp_rmaker_device_add_param(device, mode);

     esp_rmaker_node_add_device(node, device);

该设备在 Alexa 中被发现后，将显示如下控制界面：

alexa-custom-device
提示

同样可通过语音控制，例如：

🗣️ Alexa，

“打开空调扇。” “关闭空调扇的摇头。” “将空调扇设置为 Turbo 模式。” “将空调扇风速调到 4。”

On this page