ESP RainMaker Neo Cloud Specifications

ESP RainMaker Neo is Espressif’s next-generation RainMaker platform. This is the specification for its cloud backend: an AWS serverless deployment (CDK, Go Lambdas, IoT Core) that owns identity, node lifecycle, groups, timeseries, notifications and the voice-assistant integrations.

It documents how the backend behaves — data models, flows, access control and the contracts it holds with nodes and apps. The node side of those same contracts is specified in the ESP RainMaker Neo firmware documentation.

Each page is self-contained and covers one feature area. Start with User Identity & Credentials and Node Association — almost everything else assumes the identity and ownership model they establish.

User Identity

User Identity & Credentials — Cognito user pools, the identity pool, the three IAM roles, and the two credential planes (identity-pool credentials vs. AssumeRole with a per-session policy).

The remaining pages are the ESP User provider itself — the endpoint-level detail behind that overview:

OIDC Discovery & JWKS — the discovery document and the published signing keys.
Authorization Endpoint — the browser login: the authorization-code + PKCE handshake, and the flow record behind it.
Token Endpoint — refresh-token rotation and the token, userinfo and revoke endpoints.
Brokered Federation — upstream identity providers, brokered rather than passed through.
External Identity Providers — the external providers a deployment can attach.
Native Auth — the /v1/user/auth/* surface kept for backward compatibility.
Email Senders — how the sender address for an outbound OTP is chosen.

Node Identity

Assisted Claiming — how a node acquires its identity: the claim-initiate and claim-verify APIs, the reservation table, and the KMS-backed certificate issuer behind them.
Node Registration — node registration, including the asynchronous bulk CSV job that runs on ECS Fargate.
Node Connection Lifecycle — the connection lifecycle: the actors involved, the clocks that govern them, and what each timeout does.

User Node Management

Node Association — user–node association: how a node is claimed, what makes the claim secure, and how ownership is torn down.
Groups — the group model, group permissions and access control, naming rules, capacity limits, and the group APIs.

Node Control

Node Parameters & Messaging — device↔cloud messaging: shadow vs. to_cloud/from_cloud vs. indexed params.
Schedules — the schedule data model and payload shape, its access control, and the schedules (API) ↔ Schedules (firmware) key translation.
Triggers & Automations — per-node triggers (pushed to the node as service config) and group-scoped automations (evaluated in the cloud).
Group Control — one publish controlling many devices, mapped onto subgroups and addressed by device type.

Node Data

Indexed Parameters — the iparams indexed-params shadow: who writes each section, the DynamoDB mirror rule, and the document shape.
Time Series — the ingest path (MQTT → IoT rule → DynamoDB → stream → aggregator) and the read path.
Device File Storage — per-device file storage in S3.
Camera Streaming — Kinesis Video Streams camera streaming.

User messaging

Notifications — the dispatcher and service-registry model that the individual channels plug into.
Mobile Push Notifications — the mobile push channel.
Outbound Webhooks — the outbound webhook channel.

Admin Identity

Admin Authentication — the provider side of admin login.
Admin Sessions & Permissions — how an admin session is established, and the IAM permissions it carries.
RBAC & Authorization — roles, and what each may do.

Admin User Management

OAuth Client Registry — the runtime configuration surface every OAuth flow reads: redirect URIs, PKCE enforcement, and confidential-client secrets.

Admin Node Management

Data Model — the tables behind the admin plane.
Fleet Indexing — fleet indexing and shadow access.
Admin APIs — the admin lambda endpoints, plus the regular user APIs an admin may call.
Admin Dashboard — the dashboard itself.

Admin OTA

OTA Firmware Updates — AWS IoT Jobs and Streams driven entirely from the dashboard with admin credentials, the two-section job document, and the two roles that keep the image readable by the service without making the service assumable by an operator.

Admin Platform

Node Scalability — SQS-backed lambdas and the runtime mode flip.
Limits and Quotas — the AWS service limits this deployment operates against, and what each means at ESP RainMaker Neo scale.

Voice assistants

Alexa Smart Home — the Alexa Smart Home integration.
Google Voice Assistant — the Google Voice Assistant integration.
Samsung SmartThings — the SmartThings integration.

AI assistants

MCP Server — the MCP server surface.

Contributing

Want to contribute? Start with CONTRIBUTING.md at the repository root — it is the single source of truth for setup, conventions, the CLA and what a pull request needs. (CONTRIBUTING.md, SECURITY.md and LICENSE live at the root because GitHub surfaces them from there; everything longer-form lives under docs/.)

These pages go deeper on individual topics:

Contributor Agreement — the CLA.
Style Guide — how these specs are written.
Code Documentation — documentation expectations for code.
Testing — what a change is expected to test.
Deployment — the two deployment flows (self-deploy vs. the published installer template) and the operator inputs each takes.
Data Population — populating a deployment with data.

API reference

The HTTP and MQTT surfaces are not part of this build. They are specified as OpenAPI and AsyncAPI documents under docs/api/ and published as here: https://api.docs.neo.rainmaker.espressif.com

That page links the HTTP, MQTT and event references, each serving the raw YAML alongside its rendering. The specs describe the API contract; every deployment serves that contract at its own API Gateway hostname.