Getting Started
Bootstrap CDF in 3 steps: install the package, register an adaptor, and initialize. This page walks through a minimal custom adaptor example to show how everything fits together.
For detailed type information, interfaces, and API signatures, refer to the TypeScript API (TypeDoc). It documents every class, method, and type you'll use while building.
Quick install
npm install @espressif/rainmaker-base-cdf
CDF provides the store and registry infrastructure. You implement adaptors for your SDKs — or use existing ones from the ecosystem.
What you'll learn
This page covers:
- Install CDF — Add the package to your project
- Study reference adaptors — Learn from production RainMaker and Matter implementations
- Understand the pattern — Adaptor class → transformers → bootstrap
- Use CDF in your app — Initialize and call entity methods
Reference implementations
Most developers will use these existing adaptors or build adaptors following their patterns. Study these production implementations from the RainMaker Home app before writing your own.
RainMaker Base Adaptor
This is the primary adaptor for ESP RainMaker. It covers:
- All domain stores — UserStore, NodeStore, GroupStore, AutomationStore, SceneStore, ScheduleStore, SubscriptionStore
- Complete operations — Auth, device control, groups, scenes, schedules, automations
- Real transformers — Shows how to convert RainMaker SDK responses into stable CDF entities
- Bootstrap setup — How to initialize the adaptor and wire it into React context
Start here if you're building for RainMaker. Most of your code will follow this pattern.
Matter Adaptor
This is the adaptor for Matter devices. It demonstrates:
- Matter-specific operations — Device discovery, commissioning, attribute reading/writing
- Transformer patterns — Converting Matter clusters and attributes into CDF entity operations
- How to map SDKs — Adapting a different SDK (Matter vs. RainMaker) to the same CDF interface
- Handling async workflows — Long-running operations like commissioning
Study this if you need to add Matter support or are building an adaptor for a different SDK.
What happens after init
Once CDF initializes, you have access to the ESPCDF singleton with all stores:
| Store | Purpose |
|---|---|
| userStore | Login, user info, orchestration |
| nodeStore | Devices, params, transports |
| groupStore | Homes, membership, sharing |
| automationStore | Rules and automations |
| sceneStore | Scene definitions |
| scheduleStore | Time-based schedules |
| subscriptionStore | Real-time push events |
Your UI can read any store and call methods on entities. CDF handles everything else automatically.
Build a custom adaptor
If neither RainMaker nor Matter fits your use case, implement ESPSDKAdaptor following the same pattern. The structure is always:
- Adaptor class — Handles SDK initialization and auth entry points
- Transformers — Convert SDK data into CDF entities with operations
- Bootstrap — Register the adaptor and initialize CDF
Refer to the RainMaker or Matter adaptor in the repo for the complete, production-ready pattern. The TypeDoc API reference documents every interface method you need to implement.
Next steps
Dive into Adaptor Registry to understand the full interface contract and transformer deep-dives.
Resources
- CDF Overview — core concepts
- Adaptor Registry — adaptor patterns and transformers
- Entities — entity API and event handling
- Domain Stores — store APIs and patterns
- esp-rainmaker-app-cdf-ts — source repository with full examples
@espressif/rainmaker-base-cdfon npm- TypeScript API (TypeDoc) — complete API reference