Skip to main content

Transports

A transport is a route to a node. The SDK ships one, mqtt, which reaches a node through the cloud, and lets an app register transports of its own. Every read and write on a node goes through this machinery, so it is worth knowing how a transport is chosen and why a node can become unreachable.

What makes a transport available​

A transport is used only when it is present in the node's availableTransports. The built-in mqtt entry is managed for you:

TransportAdded whenRemoved when
mqttThe node reports onlineThe node reports offline

Connectivity drives this directly. A node that has gone offline in the cloud has no transport left, and any read or write throws ESPAPICallValidationError with code NODE_UNREACHABLE.

How a transport is chosen​

The node's transportOrder is walked in order, modes absent from availableTransports are skipped, and the first success wins. Every failure falls through to the next mode; if all of them fail, the last error is thrown rather than a generic one.

Change the order​

Globally, for nodes created afterwards:

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

ESPRMNeoBase.setTransportOrder([ESPTransportMode.mqtt]);

Or for one node:

node.setTransportOrder([ESPTransportMode.mqtt]);
Set the global order after configure, not before

configure() disposes previous state when the SDK is already configured, and disposing resets the global order to its default. An order set before configure() therefore survives the first initialisation and is silently reverted by any later one. Call setTransportOrder() after configure().

Each node also copies the global order when it is built, so a later change does not retro-apply to nodes you already hold. Set those individually or re-fetch them. ESPRMNeoBase.getTransportOrder() returns a copy of the current order.

Both throw ESPConfigError with code INVALID_TRANSPORT_ORDER when given an empty array or a non-array.

Register a custom transport​

transportOrder accepts arbitrary strings, so a transport the SDK does not ship can take part. Register the implementation and make the mode available:

node.addCustomTransportManager("ble", myBleTransport);
node.addTransport("ble", { type: "ble", metadata: {} });
node.setTransportOrder(["ble", ESPTransportMode.mqtt]);

The implementation satisfies ESPTransportInterface, which is two methods:

  • setParam(payload, nodeRef?) where payload is { node_id, payload }
  • getParams(payload, nodeRef?) where payload is { node_id }

All three steps are required. A registered manager with no matching entry in availableTransports is never reached, and an available mode with no manager falls back to the built-in transport, which does not understand a custom mode.

Remove one with removeCustomTransportManager(mode), and drop the mode itself with removeTransport(mode).

Method summary​

MethodScope
ESPRMNeoBase.setTransportOrder(order)Global default
ESPRMNeoBase.getTransportOrder()Global default
node.setTransportOrder(order)One node
node.addTransport(mode, config)One node
node.removeTransport(mode)One node
node.addCustomTransportManager(mode, manager)One node
node.removeCustomTransportManager(mode)One node