Getting started

Requirements

• Node.js 18 or later, and npm 8 or later
• TypeScript 5 or later, recommended rather than required

Runtime dependencies are deliberately thin: a Cognito client and protocol buffers for provisioning. The SDK pulls in no MQTT client, no HTTP client and no connectivity module of its own; those arrive as adaptors.

Install

npm install @espressif/rainmaker-neo-base-sdk

Configure

Get the deployment details from your published client configuration (rmng-client-outputs.json). The URL and QR code are in Deployment Details.

Client outputs key	SDK configuration
rmng-base → ApiGatewayUrl	baseUrl
espuser-base → EspUserApiUrl	userApiBase
rmng-base → StackRegion	awsRegion
rmng-base → IoTEndpointUrl	iotEndpoint

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

ESPRMNeoBase.configure({
  baseUrl: "https://<api-id>.execute-api.<region>.amazonaws.com/prod",
  userApiBase: "https://<user-api-id>.execute-api.<region>.amazonaws.com/prod",
  awsRegion: "<region>",
  iotEndpoint: "<iot-endpoint-host>",
  mqttAdapter: myMqttAdapter,

  // Optional
  customStorageAdapter: myStorageAdapter,
  provisionAdapter: myProvisionAdapter,
});

note

Configure the SDK before you start using it. configure() must run before any other SDK call.

Name	Usage	Optional
baseUrl	Main API base URL (include the API Gateway stage on a default execute-api host; a trailing slash is stripped)	No
userApiBase	User and auth API base URL	No
awsRegion	AWS region, such as us-east-1	No
iotEndpoint	IoT endpoint host	No
mqttAdapter	MQTT client for device communication — required for live updates and control over MQTT	No
customStorageAdapter	Persist sessions and tokens on the device	Yes
provisionAdapter	BLE or SoftAP provisioning	Yes

init() is a back-compat alias that forwards to configure().

Handle configuration failures

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

try {
  ESPRMNeoBase.configure(config);
} catch (error) {
  if (error instanceof ESPConfigError) {
    console.error(error.code, error.message);
  }
  throw error;
}

Every SDK error carries a stable code you can branch on; Errors lists the classes and their codes.

Related

• Adaptors — the five injection points and their contracts
• Configuration reference — every field of ESPRMNeoBaseConfig
• Authentication — sign-up, sign-in and session restore
• Deployment Details — where the client configuration is published
• Errors — error classes and their codes