Overview

What is CDF?

The Central Data Framework (CDF) is an SDK-agnostic, state management layer for the RainMaker home app. Published as @espressif/rainmaker-base-cdf, it decouples your UI from underlying SDKs by providing a single, stable surface. Multiple SDK implementations plug in through adaptors, letting you switch ecosystems without touching UI code.

How it works

CDF is a data and operation pipeline between your UI and the SDKs. Here's the flow:

1. Your UI reads from stores — Observable data containers that hold the current state
2. Your UI calls entity methods — Operations that send commands to devices or the backend
3. CDF routes through the registry — The AdaptorRegistry sends all calls to the active SDK adaptor
4. The adaptor handles the SDK — Makes API calls, handles responses, translates back to CDF types
5. Stores update automatically — Results flow back into stores; your UI re-renders

---

The key principle: Your UI depends only on CDF. All SDK details are hidden behind adaptors. This means you can swap SDKs (RainMaker, Matter, custom APIs) without changing any UI code.

---

Core concepts and terminology

The foundation: ESPCDF and registry

ESPCDF is your entry point — a singleton holding all stores and the AdaptorRegistry. The registry routes calls to the active SDK adaptor, so you can switch SDKs at runtime.

const cdf = await initCDF({ sdkAdaptorRegistry: registry });
const nodes = cdf.nodeStore.nodesList; // Read stores
await cdf.nodeStore.nodes[0].setParam(...); // Routes through adaptor

The bridge: Adaptors and entities

Component	Role
ESPSDKAdaptor	Translates SDK data into CDF shapes
CDF entity	App-facing object (ESPCDFNode, ESPCDFGroup, ESPCDFUser)
operations	Methods that call SDKs (created by adaptors)
_raw	Original SDK object, kept in sync internally

// Adaptor transforms raw SDK data
const cdfNode = transformToMyCDFNode(sdkDevice);

// UI calls methods on the CDF entity
const result = await cdfNode.setParam("brightness", 100);
// Under the hood: adaptor calls SDK, gets response, updates the store

Automatic sync: Stores update on their own

Call an entity method → CDF updates the store → Your UI re-renders automatically.

await node.setParam("power", true); // You call this
// NodeStore updates, observer() components re-render

No manual subscriptions. No callbacks. Stores handle it behind the scenes.

---

Domain stores

CDF organizes data into domain stores — one per entity type. Each store is observable: when an operation completes, the store updates automatically and your UI re-renders. Stores also handle pagination, filtering, and querying so you don't manage that logic in screens.

Store	Entity	What you can do
UserStore	ESPCDFUser	Login, logout, manage user profile; triggers other stores
NodeStore	ESPCDFNode	Query devices, set params, manage services and transports
GroupStore	ESPCDFGroup	Create/delete homes, manage membership and sharing
AutomationStore	ESPCDFAutomation	Create automations triggered by nodes, weather, or daylight
SceneStore	ESPCDFScene	Define scenes (groups of param values) and activate them
ScheduleStore	ESPCDFSchedule	Create time-based schedules to run across devices
SubscriptionStore	—	Receives real-time push events and feeds them into stores

---

Learning path

Build your understanding layer by layer. Start by getting code working, then learn how to extend it, then understand the data flow, then optimize and troubleshoot.

Step	Page	So you can...
1	Getting started	Install CDF, wire it up in React, and see your first working screen
2	Adaptor registry	Register SDK adaptors and write custom ones for your backend
3	Entities	Understand how entity methods work and emit events
4	Domain stores	Use store APIs for pagination, filtering, and reactive queries
5	Errors	Handle and debug config and registry errors
6	Best practices	Avoid common pitfalls and troubleshoot issues

---

Resources

• Getting Started — install and bootstrap
• CDF Architecture — layered architecture breakdown
• Adaptor Registry — register adaptors and write custom ones
• ESP RainMaker Home — reference implementation
• TypeScript API (TypeDoc) — complete API reference