Adapters

Connect the RainMaker SDK to your platform—React Native, web, Electron—by implementing small adapter interfaces for storage, BLE, notifications, and more.

What This Module Does ?

Adapters bridge TypeScript SDK logic and platform-native capabilities (AsyncStorage, BLE modules, FCM, localStorage). The SDK stays platform-agnostic; your app supplies implementations at configure time.

Use adapters when you integrate @espressif/rainmaker-base-sdk on any platform that is not already wired for you (e.g. custom React Native, Vue, Angular, Electron).

Storage is always required. Other adapters depend on which features you enable — see table below.

Expected outcome: ESPRMBase.configure() receives working adapters and SDK features (provisioning, local control, push) function on your platform.

Configure Adapter as per need

You only pass adapters for features your app uses.

Adapter	Required?	Enables
Storage	Yes	Sessions, tokens, SDK cache
Provisioning	If onboarding devices	BLE/SoftAP provision flow
Local discovery	If local discovery	mDNS / Bonjour scan
Local control	If LAN control	Direct parameter updates on LAN
Notification	If push updates	Remote node update events
OAuth	If social login	Third-party auth code flow
App utility	Optional	BLE/location permission checks

Common Workflows

Implement a storage adapter (web)

import type { ESPRMStorageAdapterInterface } from "@espressif/rainmaker-base-sdk";

class WebStorageAdapter implements ESPRMStorageAdapterInterface {
  async setItem(name: string, value: string): Promise<void> {
    localStorage.setItem(name, value);
  }
  async getItem(name: string): Promise<string | null> {
    return localStorage.getItem(name);
  }
  async removeItem(name: string): Promise<void> {
    localStorage.removeItem(name);
  }
  async clear(): Promise<void> {
    localStorage.clear();
  }
}

export default new WebStorageAdapter();

Implement storage (React Native)

import AsyncStorage from "@react-native-async-storage/async-storage";
import type { ESPRMStorageAdapterInterface } from "@espressif/rainmaker-base-sdk";

const asyncStorageAdapter: ESPRMStorageAdapterInterface = {
  setItem: (name, value) => AsyncStorage.setItem(name, value),
  getItem: (name) => AsyncStorage.getItem(name),
  removeItem: (name) => AsyncStorage.removeItem(name),
  clear: () => AsyncStorage.clear(),
};

export default asyncStorageAdapter;

Register adapters with the SDK

import { ESPRMBase } from "@espressif/rainmaker-base-sdk";
import storageAdapter from "./adapters/storage";
import provisionAdapter from "./adapters/provision";

ESPRMBase.configure({
  baseUrl: "https://api.rainmaker.espressif.com",
  version: "v1",
  customStorageAdapter: storageAdapter,
  provisionAdapter, // omit if not provisioning
});

See Getting Started for full config options.

Use the React Native reference implementation

Please see complete implementations for adapters at esp-rainmaker-home/native-adaptors

Error Handling

Missing storage adapter

// Fails — storage is required
ESPRMBase.configure({ baseUrl: "https://api.rainmaker.espressif.com" });

// Correct
ESPRMBase.configure({
  baseUrl: "https://api.rainmaker.espressif.com",
  customStorageAdapter: storageAdapter,
});

Interface mismatch

Implement every method on the interface with async methods returning Promise. TypeScript implements ESPRMStorageAdapterInterface (etc.) catches missing methods at compile time.

async setItem(name: string, value: string): Promise<void> {
  try {
    await AsyncStorage.setItem(name, value);
  } catch (error) {
    console.error("Storage setItem failed:", error);
    throw error;
  }
}

Advanced Concepts

Why adapters exist

React Native needs native modules for BLE; browsers use localStorage and limited Web Bluetooth; Electron may use the filesystem. Adapters let one SDK target all of them with the same TypeScript API.

Adapter responsibilities (summary)

Adapter	Responsibility
Storage	setItem, getItem, removeItem, clear
Provisioning	Device search, connect, Wi-Fi scan, provision, disconnect
Local discovery	startDiscovery / stopDiscovery with mDNS params
Local control	LAN connect, sendData for local param paths
Notification	addNotificationListener for push payloads
OAuth	getCode from OAuth redirect URL
App utility	Permission checks before BLE/location features

Best Practices

1. Implement implements Interface for compile-time safety
2. Throw or log errors inside adapters — do not swallow native failures
3. Provide only adapters you need — smaller surface, easier testing
4. Fork RN reference adapters instead of writing provisioning from scratch
5. Test permission flows with appUtilityAdapter before BLE onboarding UI

Related Resource

• API Reference:
  • ESPRMStorageAdapterInterface
  • ESPProvisionAdapterInterface
  • ESPLocalDiscoveryAdapterInterface
  • ESPLocalControlAdapterInterface
  • ESPNotificationAdapterInterface
  • ESPOauthAdapterInterface
  • ESPAppUtilityAdapterInterface