Skip to main content

Building Custom Apps

If the stock app is not enough, you can build your own against your ESP RainMaker Neo deployment. This page covers what you need from the deployment, which SDK to use, and the parts that differ from building against ESP RainMaker.

What you need from your deployment​

Everything a client needs is published in one place: your deployment's client configuration file. It carries the API endpoints, the identity pool and user pool identifiers, the IoT endpoint, and the region — the values that would otherwise have to be hard-coded per deployment.

Fetch it rather than embedding it. A deployment that moves region or rotates an endpoint then does not require an app release. Deployment Details shows where the file is published.

Create a project with the RainMaker Home app CLI​

Use the RainMaker Home app CLI to scaffold a Home app project pointed at your Neo deployment. Requires Node.js 22 or later.

# One-shot (no install)
npx @espressif/rainmaker-home-app-cli init

# Or install globally
npm install -g @espressif/rainmaker-home-app-cli
rainmaker-home-app-cli init

To bake in your deployment's endpoints, pass the published client configuration URL (or a local path to the same JSON) with --config:

npx @espressif/rainmaker-home-app-cli init \
  --config https://rmng-public-assets-<ACCOUNT_ID>.s3.us-east-1.amazonaws.com/<APP_REGION>/rmng-client-outputs.json

That URL is the same client-outputs file described in Deployment Details. The CLI fills the Neo backend fields from it; in the wizard choose ESP RainMaker Neo if you are not using --config.

The SDK​

Neo has its own TypeScript SDK, @espressif/rainmaker-neo-base-sdk, covering provisioning, user management, device control and MQTT. It is distinct from @espressif/rainmaker-base-sdk, which is the ESP RainMaker SDK — the two have separate models and should not be mixed in one app.

Install it from npm:

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

Requirements, the initialisation call, and how the configuration values map onto your deployment's client configuration file are in Getting started.

The full per-method reference — every class, method, type and error the package exports — is the ESP RainMaker Neo SDK section.

This page therefore stays on what is stable and Neo-specific: what your deployment hands a client, how identity works, and the two model details that catch people out.

Above the SDK, the Home app uses the State Manager (CDF) (@espressif/rainmaker-base-cdf) to bind SDK data to reactive UI entities. You do not need to rewrite CDF adaptors for Neo — use the Home app path, or call the SDK directly if you already own state management.

Authentication, in one paragraph​

Sign the user in against Cognito, hold the resulting token, and send it on REST calls. For direct MQTT, exchange that token for temporary AWS credentials and sign with SigV4. The full chain, with the actual calls and their order, is already written up in API getting started — read that rather than a second version of it here.

What an app adds on top of that chain is the part worth thinking about:

  • Token storage — keep tokens in the platform's secure storage, not in plain preferences.
  • Refresh — refresh before expiry rather than reacting to a 401 mid-interaction.
  • Credential lifetime — the credentials MQTT uses expire on their own, so a long-lived connection needs re-signing, not just reconnecting.

Working with nodes and devices​

The model is the same one the firmware publishes: a node carries devices and services, each carrying parameters. Read Terminology once and the API shapes stop being surprising.

Two practical points:

  • Render reported state, not desired, or your UI will show changes that have not happened yet. See Node–cloud communication.
  • Access is scoped by Group membership, so your app's "home" concept should map onto Groups rather than inventing its own grouping.

Direct MQTT from the app​

An app can subscribe to the same MQTT topics a node publishes on, which is how you get live updates without polling. This is what the SigV4 credentials above are for. The topic reference is MQTT user reference.