ESP Rainmaker Typescript Base SDK

The @espressif/rainmaker-base-sdk package provides a foundational SDK to help mobile app developers quickly integrate with the ESP Rainmaker ecosystem. It enables seamless provisioning, control, and management of devices.

Table of Contents

• Overview
• Key Features
• Requirements
• Installation
  • Package Manager
  • Local Installation
• Usage
• Resources
• License
• API Documentation

Overview

The @espressif/rainmaker-base-sdk package is designed to accelerate app development by providing a unified API for interacting with the ESP Rainmaker platform. With support for different communication transports, developers can seamlessly integrate features such as provisioning, device control, and discovery into their apps.

The SDK provides:

• Native module support with adapter interfaces for iOS and Android.
• Support for various transport modes (currently local and cloud).
• A modular design with separate modules for user management, device management, and group management.

Key Features

• [x] Provisioning and Discovery: Support for device provisioning and discovery via native modules with customizable adapter interfaces.
• [x] Local and Cloud Communication: Control devices locally, with automatic fallback to cloud communication for updates and retrieval of the latest parameters.
• [x] Cross-Platform Compatibility: Works with React Native and other cross-platform frameworks.
• [x] Extensible Modules: Provides modular APIs for user, device, and group management.
• [ ] Matter Protocol Support: Future-proof your app with Matter protocol support (planned).

Requirements

Before installing the @espressif/rainmaker-base-sdk package, ensure you meet the following prerequisites:

• Node.js: Version 20.17.0 or higher is recommended.
• Package Manager: Any one from npm, yarn, or pnpm installed.

Installation

Package Manager

To install the latest version of the @espressif/rainmaker-base-sdk package from the npm registry, you can use your preferred package manager:

Using npm:

npm install @espressif/rainmaker-base-sdk

Using Yarn:

yarn add @espressif/rainmaker-base-sdk

Using pnpm:

pnpm add @espressif/rainmaker-base-sdk

Local Installation

To build and install the package locally for development and testing:

1. Clone the repository

2. Check out the appropriate branch:

   git checkout main

3. Ensure you are using Node.js v20.17.0 or higher. If you have nvm installed, you can run:

   nvm use

   If you don’t have nvm, please install Node.js v20.17.0 or a higher version manually.

4. Install the required dependencies using Yarn:

   yarn install

5. Build the package:

   yarn run build

6. Create a tarball for testing locally:

   yarn pack

7. Add the tarball to your project:

   yarn add <PATH_TO_PACK_TARBALL_FILE>

After installation, you can import and configure the SDK in your project as shown in the usage examples below.

Usage

User Login Usage Example

Below is a step-by-step guide to logging in a user using the @espressif/rainmaker-base-sdk SDK:

1. Import the SDK

   Begin by importing the ESPRMBase class from the @espressif/rainmaker-base-sdk package.

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

2. Configure the SDK

   Use the configure method to initialize the SDK with the required base URL and API version.

   ESPRMBase.configure({
     baseUrl: "https://api.rainmaker.espressif.com",
     version: "v1",
   });

3. Get an Instance of the Authentication Module

   Obtain an instance of the authentication module by calling getAuthInstance() on the ESPRMBase class.

   const authInstance = ESPRMBase.getAuthInstance();

4. Attempt User Login

   Call the login method on the authentication instance, passing the username and password as arguments. Handle the response or any potential errors using a try-catch block.

   try {
     const resp = await authInstance.login("<USERNAME>", "<PASSWORD>");
     console.log(resp); // Log the response on successful login
   } catch (error) {
     console.log(error); // Handle and log any errors during login
   }

5. Review the Login Response

   The login method returns a promise. On successful resolution, it provides the user's instance. Ensure you properly log or handle the response in your application.

Resources

• Changelog

License

This project is licensed under the Apache 2.0 license - see the LICENSE file for details.