ESP RAINMAKER

ESP RAINMAKER

  • Docs
  • API
  • Help
  • Blog
  • GitHub

›Develop Firmware

Get Started

  • Get Started

Develop Firmware

  • Basics
  • Standard Types

Specifications

  • Concepts
  • Node - Cloud communication
  • Client - Cloud communication
  • User - Node Mapping
  • Claiming
  • User Roles

Services

  • OTA FW Upgrades
  • Time Service
  • Scheduling
  • Local Control Service
  • Scenes

CLI

  • Setup
  • Usage

3rd Party Integrations

  • 3rd Party Integrations

Other Features

  • Node Sharing
  • Local Control
  • ESP Insights (Beta)

What's Next?

  • What's Next?

Standard Predefined Types

Creating a Device generally requires multiple calls. For example, creating a Lightbulb with name, power and brightness would need:

esp_rmaker_device_t *device = esp_rmaker_device_create("Light", NULL, NULL);

esp_rmaker_device_add_param(device, esp_rmaker_param_create("name", NULL, esp_rmaker_str("Light"),
            PROP_FLAG_READ | PROP_FLAG_WRITE | PROP_FLAG_PERSIST));

esp_rmaker_param_t *power_param = esp_rmaker_param_create("power", NULL, esp_rmaker_bool(true), PROP_FLAG_READ | PROP_FLAG_WRITE);
esp_rmaker_param_add_ui_type(power_param, ESP_RMAKER_UI_TOGGLE);
esp_rmaker_device_add_param(device, power_param);
esp_rmaker_device_assign_primary_param(device, power_param);

esp_rmaker_param_t *brightness_param = esp_rmaker_param_create("brightness", NULL, esp_rmaker_int(100), PROP_FLAG_READ | PROP_FLAG_WRITE);
esp_rmaker_param_add_ui_type(brightness_param, ESP_RMAKER_UI_SLIDER);
esp_rmaker_param_add_bounds(brightness_param, esp_rmaker_int(0), esp_rmaker_int(100), esp_rmaker_int(1));
esp_rmaker_device_add_param(device, brightness_param);

This flexibility is useful as it lets you define any type of device. However, to simplify some common use cases, we have defined some standard types and have added helper APIs for them. Using standard types, the above code will get reduced to this:

light_device = esp_rmaker_lightbulb_device_create("Light", NULL, true);
esp_rmaker_device_add_cb(light_device, write_cb, NULL);

esp_rmaker_device_add_param(light_device, esp_rmaker_brightness_param_create("brightness", 100));

These standard types are also useful for defining some special handling in phone apps or other third party applications like Alexa or Google Voice Assistants. Below is a list of standard devices, services, parameters and ui elements. This list will keep updating as we add new types.

Devices

Parameters in Bold are mandatory.
* indicates primary parameter.

C APIs to implement some of these can be found here. Others can be built using the raw APIs. They have been included here just to indicate that they have special handling in clients like the Alexa/GVA.

NameTypeParamsGVAAlexaImage
Switchesp.device.switchName, Power*SWITCHSWITCH
Lightbulbesp.device.lightbulbName, Power*, Brightness, Color Temperature, Hue, Saturation, IntensityLIGHTLIGHT
Lightesp.device.lightName, Power*, Brightness, Color Temperature, Hue, Saturation, IntensityLIGHTLIGHTX
Fanesp.device.fanName, Power*, Speed, DirectionFANFAN
Temperature Sensoresp.device.temperature-sensorName, Temperature*XTEMPERATURE
_SENSOR
Outletesp.device.outletName, PowerOUTLETSMARTPLUG
Plugesp.device.plugName, PowerOUTLETSMARTPLUGX
Socketesp.device.socketName, PowerOUTLETSMARTPLUGX
Lockesp.device.lockName, Lock StateLOCKSMARTLOCK
Internal Blindsesp.device.blinds-internalNameBLINDSINTERIOR_BLINDX
External Blindsesp.device.blinds-externaNameBLINDSEXTERIOR_BLINDX
Garage Dooresp.device.garage-doorNameGARAGEGARAGE_DOORX
Garage Lockesp.device.garage-door-lockNameGARAGESMARTLOCKX
Speakeresp.device.speakerNameSPEAKERSPEAKERX
Air Conditioneresp.device.air-conditionerNameAC_UNITAIR_CONDITIONERX
Thermostatesp.device.thermostatNameTHERMOSTATTHERMOSTAT
TVesp.device.tvNameTVTVX
Washeresp.device.washerNameWASHERWASHERX
Otheresp.device.otherXOTHER

Services

Parameters in Bold are mandatory.

C APIs to implement these can be found here.

NameTypeParams
OTAesp.service.otaOTA URL, OTA Status, OTA Info
Scheduleesp.service.schedulesSchedules
Timeesp.service.timeTZ, TZ-POSIX
Systemesp.service.systemReboot, Factory-Reset, Wi-Fi-Reset

Parameters

C APIs to implement some of these can be found here. Others can be built using the raw APIs. They have been included here just to indicate that they have special handling in clients like the Alexa/GVA.

NameTypeData TypeUI TypeProp-
erties
Min, Max, Step
Nameesp.param.nameStringRead, Write1, 32, -
Poweresp.param.powerBoolesp.ui.toggleRead, WriteN/A
Brightnessesp.param.brightnessIntesp.ui.sliderRead, Write0, 100, 1
CCTesp.param.cctIntesp.ui.sliderRead, Write2700, 6500, 100
Hueesp.param.hueIntesp.ui.sliderRead, Write0, 360, 1
Saturationesp.param.saturationIntesp.ui.sliderRead, Write0, 100, 1
Intensityesp.param.intensityIntesp.ui.sliderRead, Write0, 100, 1
Speedesp.param.speedIntesp.ui.sliderRead, Write0, 5, 1
Directionesp.param.directionIntesp.ui.dropdownRead, Write0, 1, 1
Temperatureesp.param.temperatureFloatReadN/A
OTA URLesp.param.ota_urlStringN/AWriteN/A
OTA Statusesp.param.ota_statusStringN/AReadN/A
OTA Infoesp.param.ota_infoStringN/AReadN/A
Timezoneesp.param.tzStringN/ARead, WriteN/A
Timezone POSIXesp.param.tz_posixStringN/ARead, WriteN/A
Schedulesesp.param.schedulesArrayN/ARead, Write, PersistN/A
Rebootesp.param.rebootBoolN/ARead, WriteN/A
Factory-Resetesp.param.factory-resetBoolN/ARead, WriteN/A
Wi-Fi-Resetesp.param.wifi-resetBoolN/ARead, WriteN/A
Toggle Controlleresp.param.toggleBoolAny type
applicable
Read, WriteN/A
Range Controlleresp.param.rangeInt/FloatAny type
applicable
Read, WriteApp specific
Mode Controlleresp.param.modeStringesp.ui.dropdownRead, WriteN/A
Setpoint Temperatureesp.param.setpoint-temperatureInt/FloatAny type
applicable
Read/WriteN/A
Lock Stateesp.param.lockstateBoolAny type
applicable
Read/WriteN/A
Blinds Positionesp.param.blinds-positionIntesp.ui.sliderRead/Write0, 100, 1
Garage Positionesp.param.garage-positionIntesp.ui.sliderRead/Write0, 100, 1
Light Modeesp.param.light-modeIntesp.ui.dropdown/
esp.ui.hidden
Read/Write0, 2, 1
0:invalid
1:HSV
2:CCT
AC Modeesp.paran.ac-modeStringesp.ui.dropdownRead/WriteN/A

UI Elements

These define how the parameters should be rendered in the Phone apps.

NameTypeData TypesRequirementsSample
Text (Default)esp.ui.textAllN/A
Toggle Switchesp.ui.toggleBoolN/A
Slideresp.ui.sliderInt, FloatBounds (min, max)
Brightness Slideresp.ui.sliderIntParam type =
esp.param.brightness
CCT Slideresp.ui.sliderIntParam type = esp.param.cct
Saturation Slideresp.ui.sliderIntParam type =
esp.param.saturation
Hue Slideresp.ui.hue-sliderIntParam type =
esp.param.hue
Hue Circleesp.ui.hue-circleIntParam type =
esp.param.hue
Push button (Big)esp.ui.push-btn-bigBoolN/A
Dropdownesp.ui.dropdownInt/StringBounds (min/max) for Int
Valid strs for String
Trigger
(Android only)
esp.ui.triggerBoolN/A
Hidden
(Android only)
esp.ui.hiddenBoolN/AParam will be hidden
← BasicsConcepts →
  • Devices
  • Services
  • Parameters
  • UI Elements
Copyright © 2022 Espressif SystemsPrivacy PolicyTerms of UseCookie Policy