设置传输顺序

备注

此处使用的 ESPRMBase 与设置 SDK 步骤中配置的实例相同。

setTransportOrder 方法允许你全局定义设备通信时传输模式的优先级顺序。这决定了 SDK 在对 ESPRMDevice 设置或获取参数时首先尝试哪种传输方式。

传输类型

SDK 当前支持两种传输类型：

传输方式	说明	使用场景
local	通过本地网络直接连接到节点。需要节点在同一网络下可被发现。	响应速度更快、延迟更低，无需互联网即可工作。
cloud	通过云后端与节点通信。只要有互联网即可工作。	可从任何位置可靠访问，即使不在同一网络下也能工作。

设置传输顺序

定义传输的优先级顺序：

import { ESPRMBase, ESPTransportMode } from "@espressif/rainmaker-base-sdk";

// 示例1：优先使用本地传输以获得更快的通信
const transportOrder: ESPTransportMode[] = [
  ESPTransportMode.local, // 首先尝试本地传输
  ESPTransportMode.cloud, // 回退到云传输
];

try {
  ESPRMBase.setTransportOrder(transportOrder);
  console.log("Transport order set successfully:", transportOrder);
} catch (error) {
  console.error("Error setting transport order:", error);
}

// 示例2：优先使用云传输以获得一致性
const cloudFirstOrder: ESPTransportMode[] = [
  ESPTransportMode.cloud,
  ESPTransportMode.local,
];

ESPRMBase.setTransportOrder(cloudFirstOrder);

传输顺序的工作原理

当你设置设备参数时：

1. SDK 检查可用传输：SDK 检查节点的 availableTransports（一个 Record<ESPTransportMode, ESPTransportConfig> 类型对象）以查看当前可用的传输方式。
2. 遵循定义的优先级：SDK 按你定义的顺序尝试使用传输方式进行通信。
3. 自动回退：如果第一种传输方式失败或不可用，SDK 会自动尝试顺序中的下一种传输方式。
4. 确保交付：此机制确保你的更新使用最佳可用传输方式送达。

// 示例工作流程：
ESPRMBase.setTransportOrder([ESPTransportMode.local, ESPTransportMode.cloud]);

// 获取节点
const node = await userInstance.getNodeDetails("node_id_123");

// 从节点获取设备
const lightbulbDevice = node.devices.find(
  (device) => device.name === "Lightbulb"
);

// 从设备参数中提取电源参数
const LightPowerParam = lightbulbDevice.params.find(
  (param) => param.name === "power"
);

// 设置参数值
await LightPowerParam.setValue(true);

// SDK 行为：
// 1. 检查节点的 availableTransports（Record 类型）中是否存在本地传输
// 2. 如果 node.availableTransports[ESPTransportMode.local] 存在，则使用本地传输
// 3. 如果本地传输失败或不可用，自动回退到云传输
// 4. 通过最佳可用传输方式成功交付命令

填充可用传输

若要使用本地传输，节点必须在其 availableTransports 字段（一个 Record<ESPTransportMode, ESPTransportConfig> 类型对象）中填充本地传输信息。这是通过本地发现事件完成的。

本地发现集成

要启用本地传输，你需要：

1. 订阅本地发现事件以接收节点在本地网络中被发现的通知。

2. 更新节点的 availableTransports 记录，添加发现事件接收到的本地传输详细信息。

   availableTransports 是一个 Record 结构，其中每个传输模式映射到其配置，例如：

   node.availableTransports[ESPTransportMode.local] = transportDetails;

更多信息请参阅事件与订阅。

传输优先级策略

根据应用程序需求选择合适的传输顺序：

策略1：本地优先（推荐）

ESPRMBase.setTransportOrder([ESPTransportMode.local, ESPTransportMode.cloud]);

优势：

• 在同一网络下响应速度更快。
• 实时控制延迟更低。
• 减少云 API 使用量。

最适合：

• 用户通常在同一网络下的智能家居应用。
• 需要实时响应的应用程序。

策略2：云优先

ESPRMBase.setTransportOrder([ESPTransportMode.cloud, ESPTransportMode.local]);

优势：

• 无论网络位置如何，行为一致。
• 本地网络不稳定时更可靠。

最适合：

• 用户经常远程访问设备的应用程序。
• 网络稳定性存在问题的场景。

完整示例

import {
  ESPRMBase,
  ESPRMEventType,
  ESPTransportMode,
} from "@espressif/rainmaker-base-sdk";

// 步骤1：设置传输顺序
ESPRMBase.setTransportOrder([ESPTransportMode.local, ESPTransportMode.cloud]);

// 步骤2：订阅本地发现以填充 availableTransports
userInstance.subscribe(ESPRMEventType.localDiscovery, (discoveredNodeData) => {
  const { nodeId, transportDetails } = discoveredNodeData;

  // 使用本地传输信息更新节点的 availableTransports 记录
  // availableTransports 是 Record<ESPTransportMode, ESPTransportConfig>类型
  const node = findNodeById(nodeId);
  if (node) {
    node.availableTransports = node.availableTransports || {};
    node.availableTransports[transportDetails.type] = transportDetails;
  }
});

// 步骤3：控制设备 - SDK 自动使用最佳传输方式
const node = await userInstance.getNodeDetails("node_id_123");

// 从节点获取设备
const lightbulbDevice = node.devices.find(
  (device) => device.name === "Lightbulb"
);

// 提取并设置电源参数
const powerParam = lightbulbDevice.params.find(
  (param) => param.name === "power"
);
await powerParam.setValue(true);
// 如果本地传输可用，SDK 使用本地传输，否则回退到云传输

相关文档

• 事件与订阅 - 了解如何设置本地发现和更新节点传输
• 设备控制 - 使用不同传输方式控制设备