Skip to main content

Set Transport Order

note

ESPRMBase used here is the same which configured in Setting up the SDK step

The setTransportOrder method allows you to define the priority order of transport modes globally for communicating with devices. This determines which transport the SDK will attempt first when setting/getting parameters on an ESPRMDevice.

Transport Types​

The SDK currently supports two types of transports:

TransportDescriptionUse Case
localDirect connection to the node over the local network. Requires the node to be discoverable on the same network.Faster response times, lower latency, works without internet.
cloudCommunication with the node through the cloud backend. Works from anywhere with internet.Reliable access from any location, works even when not on the same network.

Setting Transport Order​

Define the priority order of transports:

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

// Example 1: Prefer local transport for faster communication
const transportOrder: ESPTransportMode[] = [
  ESPTransportMode.local, // Try local first
  ESPTransportMode.cloud, // Fallback to cloud
];

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

// Example 2: Prefer cloud transport for consistency
const cloudFirstOrder: ESPTransportMode[] = [
  ESPTransportMode.cloud,
  ESPTransportMode.local,
];

ESPRMBase.setTransportOrder(cloudFirstOrder);

How Transport Order Works​

When you set a device parameter:

  1. SDK checks available transports: The SDK examines the node's availableTransports (a Record<ESPTransportMode, ESPTransportConfig>) to see which transports are currently available
  2. Follows defined priority: The SDK attempts communication using transports in the order you defined
  3. Automatic fallback: If the first transport fails or is unavailable, the SDK automatically tries the next transport in the order
  4. Ensures delivery: This mechanism ensures your updates are delivered using the best available transport
// Example workflow:
ESPRMBase.setTransportOrder([ESPTransportMode.local, ESPTransportMode.cloud]);

// Get the node
const node = await userInstance.getNodeDetails("node_id_123");

// Get the device from the node
const lightbulbDevice = node.devices.find(
  (device) => device.name === "Lightbulb"
);

// Extract the power parameter from device params
const LightPowerParam = lightbulbDevice.params.find(
  (param) => param.name === "power"
);

// Set the parameter value
await LightPowerParam.setValue(true);

// SDK behavior:
// 1. Checks if local transport exists in node.availableTransports (Record)
// 2. If node.availableTransports[ESPTransportMode.local] exists, uses local transport
// 3. If local fails or unavailable, automatically falls back to cloud
// 4. Command is delivered successfully via the best available transport

Populating Available Transports​

For local transport to be used, nodes must have their availableTransports field (a Record<ESPTransportMode, ESPTransportConfig>) populated with local transport information. This is done through local discovery events.

Local Discovery Integration

To enable local transport, you need to:

  1. Subscribe to local discovery events to receive notifications when nodes are discovered on the local network
  2. Update node's availableTransports record with the local transport details received from discovery events

The availableTransports is structured as a Record where each transport mode maps to its configuration, for example:

node.availableTransports[ESPTransportMode.local] = transportDetails;

Learn more in Events and Subscriptions.

Transport Priority Strategies​

Choose your transport order based on your application's needs:

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

Advantages:

  • Faster response times when on the same network
  • Lower latency for real-time control
  • Reduces cloud API usage

Best for:

  • Smart home applications where users are typically on the same network
  • Applications requiring real-time responsiveness

Strategy 2: Cloud First​

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

Advantages:

  • Consistent behavior regardless of network location
  • Reliable when local network is unstable

Best for:

  • Applications where users frequently access devices remotely
  • Scenarios where network stability is a concern

Complete Example​

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

// Step 1: Set transport order
ESPRMBase.setTransportOrder([ESPTransportMode.local, ESPTransportMode.cloud]);

// Step 2: Subscribe to local discovery to populate availableTransports
userInstance.subscribe(ESPRMEventType.localDiscovery, (discoveredNodeData) => {
  const { nodeId, transportDetails } = discoveredNodeData;

  // Update node's availableTransports Record with local transport info
  // availableTransports is Record<ESPTransportMode, ESPTransportConfig>
  const node = findNodeById(nodeId);
  if (node) {
    node.availableTransports = node.availableTransports || {};
    node.availableTransports[transportDetails.type] = transportDetails;
  }
});

// Step 3: Control devices - SDK automatically uses the best transport
const node = await userInstance.getNodeDetails("node_id_123");

// Get the device from the node
const lightbulbDevice = node.devices.find(
  (device) => device.name === "Lightbulb"
);

// Extract and set the power parameter
const powerParam = lightbulbDevice.params.find(
  (param) => param.name === "power"
);
await powerParam.setValue(true);
// SDK uses local transport if available, otherwise falls back to cloud

On this page