Skip to main content

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.

AdapterRequired?Enables
StorageYesSessions, tokens, SDK cache
ProvisioningIf onboarding devicesBLE/SoftAP provision flow
Local discoveryIf local discoverymDNS / Bonjour scan
Local controlIf LAN controlDirect parameter updates on LAN
NotificationIf push updatesRemote node update events
OAuthIf social loginThird-party auth code flow
App utilityOptionalBLE/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)​

AdapterResponsibility
StoragesetItem, getItem, removeItem, clear
ProvisioningDevice search, connect, Wi-Fi scan, provision, disconnect
Local discoverystartDiscovery / stopDiscovery with mDNS params
Local controlLAN connect, sendData for local param paths
NotificationaddNotificationListener for push payloads
OAuthgetCode from OAuth redirect URL
App utilityPermission 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

On this page