Subscription Store

SubscriptionStore is the real-time event gateway for CDF. It bridges the RainMaker SDK's push events (cloud updates, local discovery) to observable node state inside your app.

What it does

When a device update arrives from the cloud or a local transport is discovered, SubscriptionStore receives it via two entry points:

• nodeUpdates.listen(event) — handles parameter changes, connectivity updates, user-node operations
• transport.listen(config) — registers new local transports (WiFi, BLE, Thread, etc.)

These listeners route events to nodeEventHandlers, which update NodeStore observables. Your UI components watch those observables with observer() and re-render automatically.

Don't call the SDK directly for updates. Adaptors own the subscription lifecycle and wire SDK callbacks to these listeners. This separation ensures one source of truth and makes it easy to trace event flow.

Event flow

Step by step:

1. Cloud Push — RainMaker backend sends a device update
2. Subscribe — Adaptor registers callback with ESPCDFUser.subscribeToNodeUpdates()
3. Listen — Callback forwards event to subscriptionStore.nodeUpdates.listen()
4. Handle — Event handler processes the payload (parameter, connectivity, user-node change)
5. Get Node — Handler looks up the node in NodeStore
6. Update — Handler applies @action updates to observable properties
7. UI Updates — Components using observer() re-render automatically

API reference

nodeUpdates.listen(event)

Receives node update events from the SDK and routes them to event handlers.

espCDF.subscriptionStore.nodeUpdates.listen({
  nodeId: "abc123",
  event_type: "params_updated",
  params: { power: "on", brightness: 80 }
});

transport.listen({ nodeId, transportDetails })

Registers a newly discovered local transport (WiFi, BLE, Thread, etc.) for a node.

espCDF.subscriptionStore.transport.listen({
  nodeId: "abc123",
  transportDetails: { type: "local", host: "192.168.1.10", port: 80 }
});

Note: This store does not manage subscription lifecycle (startNodeUpdates, stopNodeUpdates). That belongs to the adaptor and ESPCDFUser.

How to use it

Wire node updates (adaptor setup)

After user login, the adaptor should register an SDK callback and forward events to the store:

// Inside your adaptor / user transformer — not in UI code
const onNodeUpdate = (event: unknown) => {
  espCDF.subscriptionStore.nodeUpdates.listen(event);
};

await user.subscribeToNodeUpdates({ onNodeUpdate });

The adaptor owns the subscription. On logout, call user.unsubscribeFromNodeUpdates() to tear down the SDK subscription and clear state.

Register local transports

When the SDK discovers a local transport (BLE, WiFi, Thread, etc.), register it with the store:

espCDF.subscriptionStore.transport.listen({
  nodeId: "device-abc123",
  transportDetails: { type: "local", host: "192.168.1.10", port: 80 },
});

The store updates the node’s availableTransports and syncs _raw via property-change events.

Read node state in your UI

Listen to node observables, not raw SDK callbacks. Use observer() to react to changes:

import { observer } from "mobx-react-lite";
import type { ESPCDF } from "@espressif/rainmaker-base-cdf";

const IsConnected = observer(function IsConnected({
  espCDF,
  nodeId,
}: {
  espCDF: ESPCDF;
  nodeId: string;
}) {
  const node = espCDF.nodeStore.getNodeById(nodeId);
  return <StatusDot connected={node?.connectivityStatus?.connected ?? false} />;
});

Event handlers

Behind the scenes, the store calls event handlers (from services/nodeEventHandlers) to apply updates to node state:

Handler	Purpose
handleNodeUpdateEvent	Routes param changes, connectivity, and user-node operations
handleNodeTransportUpdate	Adds/updates local transports in availableTransports
handleNodeParamsChanged	Updates parameter values on the node
handleNodeConnected / handleNodeDisconnected	Tracks online/offline status

All handlers are MobX actions that resolve the node from NodeStore, update observables, and sync _raw via property-change events.

See also

Core concepts

• Node store — stores the observable nodes that subscriptions update
• ESPCDFUser — owns the subscription lifecycle (subscribeToNodeUpdates, unsubscribeFromNodeUpdates)

Source code

• SubscriptionStore implementation
• Node event handlers

API Reference

• Typescript API (TypeDoc)