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 these can be found here.
Name | Type | Params | Primary | Image |
---|---|---|---|---|
Switch | esp.device.switch | Name, Power* | Power | ![]() |
Lightbulb | esp.device.lightbulb | Name, Power*, Brightness, Color Temperature, Hue, Saturation, Intensity | Power | ![]() |
Fan | esp.device.fan | Name, Power*, Speed, Direction | Power | ![]() |
Temperature Sensor | esp.device.temperature-sensor | Name, Temperature* | Temperature | ![]() |
Services
Parameters in Bold are mandatory.
C APIs to implement these can be found here.
Name | Type | Params |
---|---|---|
OTA | esp.service.ota | OTA URL, OTA Status, OTA Info |
Parameters
C APIs to implement these can be found here.
Name | Type | Data Type | UI Type | Prop- erties | Min, Max, Step |
---|---|---|---|---|---|
Name | esp.param.name | String | Read, Write | 1, 32, - | |
Power | esp.param.power | Bool | esp.ui.toggle | Read, Write | |
Brightness | esp.param.brightness | Int | esp.ui.slider | Read, Write | 0, 100, 1 |
Color Temperature | esp.param.cct | Int | esp.ui.slider | Read, Write | 2700, 6500, 100 |
Hue | esp.param.hue | Int | esp.ui.slider | Read, Write | 0, 360, 1 |
Saturation | esp.param.saturation | Int | esp.ui.slider | Read, Write | 0, 100, 1 |
Intensity | esp.param.intensity | Int | esp.ui.slider | Read, Write | 0, 100, 1 |
Speed | esp.param.speed | Int | esp.ui.slider | Read, Write | 0, 5, 1 |
Direction | esp.param.direction | Int | esp.ui.dropdown | Read, Write | 0, 1, 1 |
Temperature | esp.param.temperature | Float | Read | ||
OTA URL | esp.param.ota_url | String | Write | ||
OTA Status | esp.param.ota_status | String | Read | ||
OTA Info | esp.param.ota_info | String | Read |
UI Elements
These define how the parameters should be rendered in the Phone apps.
Name | Type | Data Types | Requirements | Sample |
---|---|---|---|---|
Text (Default) | esp.ui.text | All | N/A | ![]() |
Toggle Switch | esp.ui.toggle | Bool | N/A | ![]() |
Slider | esp.ui.slider | Int, Float | Bounds (min, max) | ![]() |