Getting Started

Get CDF into your app: know what it is and why it belongs in the stack, then install, bootstrap, and use stores the way a real home app does.

NPM Package: @espressif/rainmaker-base-cdf

For a fuller product-level picture, see the CDF Overview.

What is CDF?

CDF (Central Data Framework) is the app data layer between your UI and IoT SDKs (RainMaker, Matter, and others).

Your screens read stores and call entity methods. CDF keeps that data in sync and routes work to the active SDK through an adaptor — so feature code does not talk to raw SDK APIs.

App UI  →  CDF (stores + entities)  →  SDK adaptor  →  RainMaker / Matter / …

Why do you need it?

The RainMaker Base SDK gives you cloud and device APIs. On its own, your app still has to manage state, UI refresh, and (if needed) more than one backend.

CDF helps you avoid that boilerplate. You use one stable surface for users, devices, homes, scenes, schedules, and automations.

Without CDF	With CDF
Call SDK APIs from screens	Call CDF entity methods
Maintain lists and cache yourself	Read ready-made stores
Wire push / refresh by hand	Stores update; UI can re-render
UI locked to one SDK	Same UI API across adaptors

Use the SDK alone only if you already own state management and want full control of every call.

What can it help with?

Store	What your app can do
userStore	Sign in / out, profile
nodeStore	List devices, set parameters
groupStore	Homes, rooms, sharing
sceneStore	Create and activate scenes
scheduleStore	Time-based actions
automationStore	Event-driven rules
subscriptionStore	Live push updates into stores

What apps can use it?

App type	Fit
React Native smart-home / IoT apps	Primary path (RainMaker Home)
React web apps	Same CDF APIs via context
Other TypeScript apps	Consume stores/entities directly

You still configure the Base SDK (and its platform adapters such as storage) underneath the RainMaker CDF adaptor — see Base SDK Getting Started.

What will you achieve?

By the end of this page you will:

Know why CDF sits in your app stack
Install and initialize CDF with an existing RainMaker adaptor
Read and update data from a screen through stores

Writing custom adaptors is optional and covered later in Adaptor Registry.

1. Install

npm install @espressif/rainmaker-base-cdf

2. Bootstrap CDF (typical app path)

Most apps reuse an existing adaptor. Production examples from RainMaker Home:

Minimal shape:

import { AdaptorRegistry, initCDF } from "@espressif/rainmaker-base-cdf";
import { ESPRMBaseSDKAdaptor, ESPRMBaseAdaptorIdentifier } from "@sdk-adaptors/ESPRMBase";

const registry = AdaptorRegistry.getInstance();

registry.register(
  new ESPRMBaseSDKAdaptor({
    baseUrl: "https://api.rainmaker.espressif.com",
    region: "us-east-1",
    // Add other SDK config as needed
  })
);

registry.setActiveAdaptor(ESPRMBaseAdaptorIdentifier);

const cdf = await initCDF({ sdkAdaptorRegistry: registry });

In React / React Native, expose cdf through context (the home app uses useCDF()). Feature screens then import CDF only — not the raw SDK.

3. Use CDF in a screen

List devices

import { observer } from "mobx-react-lite";

const DeviceList = observer(function DeviceList({ cdf }) {
  const nodes = cdf.nodeStore.nodesList;

  return (
    <>
      {nodes.map((node) => (
        <Text key={node.id}>{node.id}</Text>
      ))}
    </>
  );
});

Wrap store-reading components with MobX observer so they re-render when CDF updates.

Control a device parameter

await node.setParam("Power", true);
// Store updates; observer components refresh

Typical feature flow

Sign in → userStore
Load homes / rooms → groupStore
Show devices → nodeStore
Toggle a light, run a scene, or edit a schedule → entity methods on the matching store

More examples: Room management · Entities · Domain stores · RainMaker Home

4. What to learn next

Goal	Go here
Deeper what / why / stack picture	Overview
Feature workflows	Entities, Domain stores
Layers in detail	Architecture
Custom or multi-SDK adaptors	Adaptor Registry (advanced)
Pitfalls	Best practices

What is CDF?​

Why do you need it?​

What can it help with?​

What apps can use it?​

What will you achieve?​

1. Install​

2. Bootstrap CDF (typical app path)​

3. Use CDF in a screen​

List devices​

Control a device parameter​

Typical feature flow​

4. What to learn next​

Resources​