Skip to main content

Helpers

Alongside its classes the SDK exports a set of stateless helper functions. They exist because hiding them would only make apps reimplement them, but they are a smaller, more selective surface than the barrel's full export list suggests. This page covers the ones worth using.

Nothing here holds state or a lifecycle. Anything that does (API managers, storage, MQTT engines, orchestrators) is deliberately internal; reach that behaviour through the domain classes instead.

Logging​

import { Logger, LogLevel } from "@espressif/rainmaker-neo-base-sdk";

Logger.setLogLevel(LogLevel.DEBUG);

The SDK logs through this class throughout, at INFO by default. Turning it up to DEBUG is the fastest way to see which REST paths and MQTT topics a call actually used; useful when a write appears to succeed but the device does not react.

LogLevel is ERROR, WARN, INFO, DEBUG in increasing verbosity. setLogLevel is static and process-wide. You can construct your own new Logger("<context>") to log in the same format.

Waiting for a node to come online​

import { waitForNodeOnline, DEFAULT_NODE_ONLINE_TIMEOUT_MS } from "@espressif/rainmaker-neo-base-sdk";

await waitForNodeOnline({
  nodeId,
  groupId: group.groupId,
  user,
  timeoutMs: DEFAULT_NODE_ONLINE_TIMEOUT_MS,
});

Resolves when the node reports online, and rejects with ESPProvError code NODE_ONLINE_TIMEOUT if it does not. It watches the node's shadow over MQTT and polls as a fallback, connecting MQTT itself if needed. timeoutMs defaults to 120000 and pollIntervalMs to 5000.

provision() calls this for you when passed waitForOnline, use it directly to wait for a node you did not just provision, such as one recovering after a network change.

isNodeOnlineFromShadowPayload(payload) reads the online flag out of a raw shadow payload, for code that has a payload but no node.

Validators​

import { isNonEmptyString, isValidUrl, isValidObject } from "@espressif/rainmaker-neo-base-sdk";

The three predicates configure() validates with. Useful for checking a deployment's client configuration before handing it over, so a bad value surfaces as your own error rather than an ESPConfigError:

if (!isValidUrl(outputs.ApiGatewayUrl)) {
  // reject the configuration before calling configure()
}

Coercion​

coerceToFiniteNumber(raw), coerceToNonEmptyString(raw) and coerceToString(raw) each return the coerced value or undefined. They are what the SDK uses to read firmware-supplied parameter values, which arrive loosely typed. Reach for them when reading a value off a parameter whose dataType you have not checked.

Shadow names and topics​

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

const shadowName = constructShadowName(node.groupId, node.subgroupIds);

constructShadowName(groupId, subgroups?) builds params-<groupId>, appending sorted subgroup IDs when a node belongs to subgroups. Sorting is what makes the name stable regardless of membership order, which is why a node must be read through its root group for its shadow name to be right.

constructShadowTopic() and constructDeviceParamsTopic() build the full topics. node.getShadowName() and node.getParamsTopic() are the instance shortcuts and are usually what you want.

The buildShadow* and getReportedParams* family in the same module parse and construct raw shadow documents. They are exported for apps that consume MQTT payloads directly rather than through the SDK's subscription.

Time series​

import { fetchRawTSData, fetchLatestTSData, fetchAggregatedTSData } from "@espressif/rainmaker-neo-base-sdk";

The three fetchers behind the time-series methods, each taking a FetchTSDataConfig. Use them to compose queries the methods do not cover; paginating several parameters in parallel, for instance. See Time series.

TIME_SERIES_PROPERTY is the property flag marking a parameter as recorded.

Node identity​

resolveNodeId(node) reads an ID from a NodeLike, preferring id over nodeId. Use it when handling objects that may be full nodes or lightweight proxies.

isChildGroup(group) returns whether a group is nested; it reads parentId, and is clearer at a call site than the check itself.

Token inspection​

decodeToken(token) decodes a JWT payload without verifying it. It is exported so an app can read claims such as expiry from a token it is holding.

Decoding is not verification

decodeToken does no signature check; it only base64-decodes the payload. Never make an authorisation decision from its output. Read expiry from it to decide whether to refresh, and let the deployment reject anything it does not trust.

Concurrency​

concurrentFetchPool(items, worker, limit) maps over items with a bounded number in flight. The SDK uses it for the per-node calls behind group-wide operations; it is exported for apps doing the same over their own lists.

Everything else in the barrel​

The barrel also re-exports SigV4 signing helpers, AWS session plumbing, node-config cache readers, ncfg-version markers, schedule and trigger converters, and around a dozen message catalogues. Those are internal machinery that happens to be visible, not supported API. See the caution in Constants and enums.