Overview
What is CDF?
The Central Data Framework (CDF) is the app data layer for RainMaker-style home and IoT apps. It is published as @espressif/rainmaker-base-cdf.
In plain terms: your screens talk to CDF. CDF talks to the SDKs (RainMaker, Matter, and others) through adaptors. You build features against one stable API instead of each SDK’s own types and calls.
Why do you need it?
The RainMaker Base SDK already exposes auth, devices, groups, and more. Without CDF, every screen still has to:
- Keep device lists, rooms, scenes, and user data up to date after each API call
- Refresh the UI when a parameter changes or a push event arrives
- Learn a different API if you also support Matter or another backend
CDF is the layer that owns that work so feature code stays simple: read a store, call an entity method, and let the UI update.
| Without CDF | With CDF |
|---|---|
| Call SDK APIs from screens | Call methods on CDF entities |
| Manage lists and cache yourself | Read ready-made stores |
| Wire refresh / push updates by hand | Stores update; UI re-renders |
| UI tied to one SDK | Same UI API across adaptors |
Prefer the Base SDK alone when you already have your own state layer and want full control of every call.
What can CDF help with?
CDF gives your app ready-made product areas as stores. Each store is where your UI reads data and triggers actions:
| Area | Store | What you can build |
|---|---|---|
| Users & auth | userStore | Sign in / out, profile |
| Devices | nodeStore | List nodes, read and set parameters |
| Homes & rooms | groupStore | Homes, rooms, membership, sharing |
| Scenes | sceneStore | Define and activate multi-device scenes |
| Schedules | scheduleStore | Time-based actions |
| Automations | automationStore | Event-driven rules |
| Live updates | subscriptionStore | Push events feed into the other stores |
You do not need to understand adaptors, transformers, or registry internals to use these features. That material is for Architecture and Adaptor Registry later.
What apps can use CDF?
CDF is a TypeScript package. It fits apps that need a shared data layer for IoT / smart-home features.
| Good fit | Notes |
|---|---|
| React Native home / IoT apps | Primary path; used by ESP RainMaker Home |
| React (web) apps | Same stores and entities; wire CDF through React context |
| Other TypeScript apps | Possible if you consume stores/entities without MobX UI helpers |
Under CDF you still use ecosystem SDKs (for example @espressif/rainmaker-base-sdk) and, for that SDK, platform adapters (storage, BLE, push) so the SDK works on your platform.
What will you achieve?
After you adopt CDF, you should be able to:
- Ship screens faster — login, device list, room control, scenes, schedules without custom sync logic
- Keep UI consistent — one model for devices and homes even if backends differ
- Stay reactive — when a device or push event changes data, stores update and the UI can re-render
- Grow the app — add Matter or another SDK via an adaptor without rewriting feature screens
Reference implementation: esp-rainmaker-home
How CDF fits with the SDK and adaptors
Two related ideas often get mixed up:
| Piece | Job |
|---|---|
| RainMaker Base SDK | RainMaker APIs (auth, nodes, groups, …) |
| SDK platform adapters | Bridge the Base SDK to the device (storage, BLE, notifications) |
| CDF | App-facing stores and entities your UI uses |
| CDF SDK adaptors | Plug RainMaker / Matter / custom SDKs into CDF |
Most app developers use an existing CDF adaptor and build UI against stores. Writing adaptors is an advanced step — see Adaptor Registry.
Learning path
| Step | Page | So you can... |
|---|---|---|
| 1 | Getting started | Install CDF and use stores in a screen |
| 2 | Entities | Build feature workflows (devices, groups, scenes, …) |
| 3 | Domain stores | Lists, pagination, filtering, reactive queries |
| 4 | Architecture | Layers in more detail (intermediate) |
| 5 | Adaptor registry | Multiple SDKs or a custom adaptor (advanced) |
| 6 | Best practices / Errors | Pitfalls and debugging |
Resources
- Getting Started — install and first screen
- CDF Architecture — layered breakdown
- Adaptor Registry — register adaptors and write custom ones
- ESP RainMaker Home — reference app
- TypeScript API (TypeDoc) — API reference