Skip to main content

Overview

The @espressif/rainmaker-base-sdk is a TypeScript-based SDK that provides core functionality for integrating ESP RainMaker features into mobile applications. This SDK serves as the foundation for building applications that can interact with ESP RainMaker devices, manage users, control devices, and organize them into groups.

npmGitHub

Architecture​

The SDK follows a modular architecture designed for flexibility and extensibility:

Core Components​

  • Core SDK Functionality - Main SDK classes and methods for RainMaker operations
  • Adapter Interfaces - Platform-agnostic interfaces for platform-specific implementations
  • TypeScript Support - Full TypeScript types and interfaces for better development experience
  • Promise-based API - All operations use async/await patterns for clean asynchronous code

Main Classes​

  • ESPRMBase - Main SDK class for initialization and configuration
  • ESPRMAuth - Authentication and user management
  • ESPRMUser - User instance for user-level operations
  • ESPRMNode - Device/node instance for device operations
  • ESPRMGroup - Group instance for group operations

SDK Architecture Flow​

Key Features​

1. User Management​

Comprehensive user account and authentication management:

  • Authentication - User signup, login (password/OTP), and OAuth integration
  • Password Management - Password recovery, change password, and account security
  • User Profile - Manage user information, phone numbers, and timezone settings
  • Custom Data - Store and manage custom user data with fine-grained permissions
  • Tags Management - Categorize users and manage feature access through tags
  • Security - Multi-factor authentication (MFA) and account management
  • Session Management - Handle user sessions, tokens, and logout operations
  • Push Notifications - Register and manage push notification endpoints for mobile apps

For detailed information, see User Management.

2. Device Management​

Complete device lifecycle and control management:

  • Device Provisioning - Add new RainMaker devices to your account
  • Node Management - Retrieve, manage, and delete provisioned devices (nodes)
  • Device Control - Control device parameters and update device states
  • Service Control - Manage service parameters and configurations
  • Time Series Data - Retrieve historical data from device parameters
  • Automation - Create and manage automation triggers
  • Node Sharing - Share devices with other users
  • OTA Updates - Over-the-air firmware updates
  • Timezone Management - Set and update node timezones
  • Node Metadata & Tags - Manage node tags and metadata
  • Transport Order - Configure communication transport modes
  • Batch Operations - Update multiple nodes efficiently

For detailed information, see Device Management.

3. Group Management​

Organize and manage devices in groups:

  • Get Groups - Retrieve and query node groups with pagination support
  • Manage Groups - Create, update, delete groups, and manage nodes within groups
  • Share Groups - Share groups with other users and manage sharing requests
  • Group Metadata - Manage group metadata and custom data
  • Subgroups - Create and manage subgroups within parent groups

For detailed information, see Group Management.

4. Adapter Architecture​

The SDK provides a flexible adapter system for platform-specific implementations:

  • Storage Adapter: For persistent data storage
  • Provisioning Adapter: For device provisioning operations
  • Local Discovery Adapter: For finding devices on local network
  • Local Control Adapter: For direct device communication
  • Notification Adapter: For push notification handling
  • OAuth Adapter: For third-party authentication
  • App Utility Adapter: For platform-specific utilities

The adapter pattern allows the SDK to work across different JavaScript frameworks (React Native, Vue, Angular, Electron, etc.) by providing platform-specific implementations. Reference implementations for React Native are available at esp-rainmaker-home/adaptors.

For detailed information on implementing adapters for your platform, see the SDK Adapters Guide

Integration Options​

Direct SDK Usage​

Use the SDK directly in your application with full control:

  • Full Control - Direct access to all SDK methods and features
  • Custom Implementation - Implement required adapters for your platform
  • State Management - Handle state management yourself using your preferred approach
  • Flexibility - Complete control over how you integrate SDK features

This approach is ideal for developers who want maximum flexibility and control over their implementation.

CDF Integration​

Use with Central Data Framework (CDF) for enhanced capabilities:

  • Built-in State Management - Automatic state synchronization and management
  • Data Synchronization - Real-time data updates across your application
  • Simplified Integration - Higher-level abstractions for common operations
  • Reactive Updates - Automatic UI updates when data changes

This approach is ideal for developers who want a more opinionated, framework-like experience with built-in state management.

For more details about CDF integration, see the CDF Documentation.

Integration Comparison​

Additional Resources​

On this page