Skip to main content

Examples

The SDK ships a set of complete, buildable example projects under examples/. Each one is a single source tree that builds for both ESP-IDF and POSIX — same app_main.c, same drivers, with every OS difference hidden behind the shared components in examples/common/.

The READMEs live next to the code, so the easiest way to use any of them is to clone the SDK and open the directory.

tip
Start with light

It is the reference implementation: node bring-up, a bulk write callback, all the optional services, and OTA in about 200 lines. Every other example is a variation on it.

Device examples​

Five projects, each a different device shape. Pick the one closest to your product.

light — RGB lightbulb​

The canonical example: power, hue, saturation, brightness, CCT, and light mode. Cloud writes arrive together in a bulk callback that auto-switches between HSV and CCT modes and turns the light on for any colour change. The boot button toggles power on a short press and randomises colour on a long one.

fan — fan​

Power, swing, and speed, with an LED status animation.

switch — on/off switch​

The smallest useful example: one parameter, an LED indicator, a button.

temp_sensor — temperature sensor​

A read-only sensor with a simulated source, and the clearest illustration of a sensor-shaped data model.

multi_device — four devices on one node​

A light, a fan, a switch, and a read-only time-series temperature sensor on a single node, each with its own bulk callback. Copy this one if your product exposes several devices.

Advanced examples​

The projects under examples/advanced/ demonstrate SDK extension points rather than device shapes — start with a device example and come here once you need to hook into the SDK itself.

ota-custom — OTA extension points​

Custom-filetype handlers (mock, mock_no_ver) via custom_filetype_handler_lookup, plus a custom job callback via custom_job_cb. Logs every OTA lifecycle event and drives a status LED through the OTA states.

Shared components​

Everything under examples/common/ is example scaffolding, not SDK API. It is convenient to build on and free to change between SDK releases — copy what you use into your own repository for a product. See Start your own project.

  • app_entry — platform entry-point shim. Provides app_main() on ESP-IDF, and main() plus signal handling and teardown on POSIX, so examples implement only a portable app_run().
  • app_network — network provisioning and bring-up: collapses the whole provisioning sequence into one app_network_provision() call (Wi-Fi or Thread on ESP-IDF), and exposes provisioning lifecycle hooks for LED feedback. A no-op on POSIX.
  • app_event_loop — registers a default handler that logs every ESP RainMaker Neo, OTA, and network event. Useful during bring-up.
  • app_led — LED helper: LEDC or WS2812 on ESP-IDF, a no-op stub on POSIX.
  • app_button — boot-button helper with short- and long-press callbacks: GPIO on ESP-IDF, a no-op stub on POSIX. Registers the app_reset hold on the button for you.
  • app_reset — two-stage hold-to-reset: hold past one threshold for a network reset, keep holding past a second for a factory reset. See Troubleshooting.
  • ci-sdkconfig — the shared sdkconfig variants used by CI builds.

Simulated hardware sources live inside the examples that use them — for instance temp_sensor/main/temp_sim.c drives the temperature reading.

Building any example​

ESP-IDF:

cd examples/light
idf.py set-target esp32c3
idf.py build flash monitor

POSIX:

cd examples/light
cmake -B build
cmake --build build
cd build && ./light

Each example ships a committed sdkconfig.defaults, plus sdkconfig.defaults.<target> where a chip needs different settings and sdkconfig.defaults.psram* for PSRAM builds. Copy these when starting a new project rather than configuring from scratch.

Every example builds in CI against supported ESP-IDF releases across all supported targets, so if one does not build for you, suspect your environment before the example.

An example is not a product

Examples default to development-friendly settings — the serial console is on, logging is verbose, and some enable weaker security to keep bring-up simple. Before you ship, work through the pre-production checklist.