DOCSEARCHbyAlgolia
Submit Docs

ESP RainMaker Documentation

repository·master·Indexed 20 days ago

https://github.com/espressif/esp-rainmaker

An end-to-end IoT solution for ESP32 series SoCs providing remote monitoring and control with zero cloud configuration. It integrates device firmware, a cloud backend, and mobile applications. The ecosystem includes the esp_rainmaker firmware agent and the rmaker_camera component for WebRTC functionality, supporting both Standalone and Split Mode architectures for camera streaming on hardware such as ESP32-P4, ESP32-S3, and ESP32-C6.

Tokens
30.1K
Snippets
78
Records
147
Agent score
69%

What's inside ESP RainMaker

  1. Overview of ESP RainMaker

    master

    ESP RainMaker is an end-to-end solution from Espressif designed for remote control and monitoring of ESP32 series SoCs (including ESP32, ESP32-S2, ESP32-C3, ESP32-C6, ESP32-C2, etc.). It eliminates the need for manual Cloud configuration by providing a complete ecosystem that includes:

    • Device SDK: A C API for developing device firmware.
    • Self-adapting Phone Apps: Available for Android and iOS.
    • Transparent Cloud Middleware: Handles connectivity and data orchestration.
    • Host Utilities: A Python API for managing host-side tools.

  2. Overview of the ESP RainMaker Agent Component

    master
    The esp_rainmaker component serves as the primary firmware agent for the ESP RainMaker ecosystem. It acts as a central entry point that pulls in all other necessary sub-components required to implement ESP RainMaker functionality on ESP32 devices. For comprehensive implementation details, device provisioning, and cloud integration guides, refer to the official ESP RainMaker documentation.

  3. Overview of the ESP RainMaker Zigbee Gateway Example

    master

    The Zigbee Gateway example demonstrates a RainMaker-based device that acts as a bridge between Zigbee and the RainMaker cloud. The gateway is provisioned via the standard RainMaker provisioning flow. Once active, any Zigbee device joined to the gateway is automatically mapped as a RainMaker device, allowing it to be controlled via the RainMaker App and cloud services.

    Supported Zigbee device mappings:

    • ESP_ZB_HA_ON_OFF_LIGHT_DEVICE_ID (0x0100)
    • ESP_ZB_HA_IAS_ZONE_ID (0x0402, Zone type: Door/Window handle)

  4. Overview of ESP RainMaker test coverage

    master

    The unit tests in test_app cover several functional areas of the ESP RainMaker component. The test execution order is fixed: Core (node/device) runs first, followed by OTA, Groups, Scenes, and Schedule (which depend on the node), and finally Node Cleanup runs last.

    Tested Functionalities:

    • Core RainMaker Features: Node and device creation/management, parameter operations, node attributes, and node cleanup.
    • MQTT Operations: Initialization, subscription, publishing, data handling, and validation of NULL/invalid inputs.
    • OTA: Enabling OTA with parameters, reporting status, and state checks (mark valid/invalid).
    • Auth Service: Token status updates, token/URL retrieval, and enable/disable lifecycle.
    • Groups: Enabling the Groups service with a node.
    • Scenes: Enabling the Scenes service with a node.
    • Schedule: Enabling the Schedule service with a node.

  5. What is ESP RainMaker

    master

    ESP RainMaker is an end-to-end solution from Espressif for remote control and monitoring of ESP32 series SoCs (including ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-C5). It allows developers to define custom devices and parameters directly in the firmware without requiring manual Cloud configuration. The phone applications dynamically render the user interface based on the device information provided by the firmware.

    The solution consists of four primary components:

    1. Claiming Service: Provides Cloud connectivity credentials.
    2. RainMaker Agent: The firmware component (this repository) used for device development.
    3. RainMaker Cloud: The backend service providing remote connectivity.
    4. RainMaker Phone App/CLI: Client utilities for remote access and control.

  6. Understand the Matter + RainMaker Switch Example

    master

    This example demonstrates a hybrid device that uses both Matter and ESP RainMaker protocols:

    • Matter: Used for commissioning (Wi-Fi provisioning) and local control.
    • RainMaker: Used for remote control (over the internet) and Over-the-Air (OTA) upgrades.

    Hardware Interaction:

    • Commissioning: Scan the QR Code generated by the mfg_tool script using the ESP RainMaker app.
    • Physical Control: Pressing the BOOT button on the ESP32-C3-DevKitC board toggles the switch power state. This action sends an on/off command to the remote device and updates the state in the phone app.
    • App Control: Toggling the switch in the phone app toggles the RGB LED on the board.
    • Remote Testing: To verify remote control functionality, change the mobile device's network connection (e.g., switch from Wi-Fi to cellular) to ensure it works outside the local network.

  7. Use the RainMaker App Network Component

    master

    The rmaker_app_network component is a connectivity helper for ESP RainMaker applications. It provides a unified API to manage both WiFi and Thread networking, simplifying the implementation of network connectivity in mesh or standard WiFi applications.

    Key Features

    • WiFi Management: Simplified WiFi connection and configuration.
    • Thread Support: Connectivity for Thread-based mesh applications.
    • Unified API: A single interface to handle different network protocols.
    • RainMaker Integration: Designed to work seamlessly with the ESP RainMaker framework.

  8. Understand the Switch Example behavior

    master

    The Switch Example demonstrates a bidirectional switch using a physical button and an RGB LED on boards like the ESP32-S2-Saola-1 or ESP32-C3-DevKitC.

    • Physical Interaction: Pressing the BOOT button toggles the switch state. This state change is reflected in the LED color and the mobile phone app.
    • App Interaction: Toggling the switch in the phone app toggles the physical LED on the board.
    • Feedback: When the switch is toggled via the app, the ESP32 monitor will print a confirmation message, for example: I (16073) app_main: Received value = true for Switch - power

  9. Understand the Temperature Sensor example behavior

    master

    This example demonstrates a temperature sensor using an esp timer and an RGB LED on supported boards like ESP32-S2-Saola-1 or ESP32-C3-DevKitC.

    Behavioral Logic:

    • Temperature Cycling: The temperature starts at 25.0 and increases by 0.5 every minute until it reaches 99.5. It then decreases by 0.5 every minute until it reaches 0.5, repeating this cycle indefinitely.
    • LED Feedback: The RGB LED hue changes based on the temperature. The hue shifts from 200 (bluish) at low temperatures to 0 (reddish) as the temperature increases toward 99.5.
    • App Integration: Temperature changes are visible in the ESP RainMaker phone app.

  10. Understand Matter + RainMaker LED Light Example

    master

    This example demonstrates a hybrid device that uses Matter for commissioning (Wi-Fi provisioning) and local control, and ESP RainMaker for remote control and OTA upgrades.

    Key Features:

    • Hardware: Uses the BOOT button and RGB LED on an ESP32-C3-DevKitC. The LED simulates a lightbulb with hue, saturation, and brightness.
    • Local Control: Pressing the BOOT button toggles the light state, which is reflected in the phone app. Toggling via the app controls the physical LED.
    • Remote Control: Changing the network connection on the mobile device allows testing of RainMaker's remote capabilities.

    Optimization Notes: To save DRAM, this example:

    • Disables the chip shell (CONFIG_ENABLE_CHIP_SHELL=n).
    • Sets the dynamic endpoint count to 2 (CONFIG_ESP_MATTER_MAX_ENDPOINT_COUNT=2).

  11. Understand the Multi Device Example behavior

    master

    This example demonstrates how to host multiple virtual devices on a single ESP32 board. The firmware implements 4 distinct devices:

    1. Switch: Uses the physical BOOT button and the onboard RGB LED (green color) to demonstrate state synchronization. Pressing the BOOT button toggles the switch state in the phone app. Toggling the switch in the app toggles the LED and prints a message to the monitor.
    2. Temperature Sensor: Uses an ESP timer to simulate temperature changes. The value starts at 25.0, increases by 0.5 every minute until it reaches 99.5, then decreases by 0.5 until it reaches 0.5, repeating the cycle. Changes are visible in the phone app.
    3. Lightbulb: A dummy device. Changing its value in the phone app prints status messages to the ESP32 monitor.
    4. Fan: A dummy device. Changing its value in the phone app prints status messages to the ESP32 monitor.
    I (16073) app_main: Received value = true for Switch - power

  12. Use the rmaker_camera component for WebRTC functionality

    master
    The rmaker_camera component is a shared ESP RainMaker component designed for camera examples. It provides WebRTC camera functionality, handles device creation within the RainMaker ecosystem, manages AWS credentials, and initializes the WebRTC stack using KVS signaling. It supports both Standalone mode (complete WebRTC with media streaming on a single device) and Split Mode (signaling-only for split architecture deployments).