Custom & standard types

Types are predefined schemas that describe the nature of a device and its parameters, and the UI element a client should render for them.

With custom types you define every aspect yourself — name, parameters, data types, UI hints, bounds — giving full flexibility to model any device. With standard types you use helper APIs for common devices such as light bulbs, fans, and temperature sensors: these set up the mandatory parameters, assign standard UI elements, and get you working phone-app rendering and voice-assistant integration with minimal code.

This page is the type reference. For the concepts behind nodes, devices, and parameters, see Data model.

Example usage

Creating a custom device

Creating a device generally takes several calls. A lightbulb with name, power, and brightness:

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);

That flexibility lets you define any device. For common cases, standard types cut it down.

Creating a standard device

light_device = esp_rmaker_lightbulb_device_create("Light", NULL, true);
esp_rmaker_device_add_bulk_cb(light_device, bulk_write_cb, NULL);

esp_rmaker_device_add_param(light_device,
    esp_rmaker_brightness_param_create(ESP_RMAKER_DEF_BRIGHTNESS_ID, 100));

The helper creates the device, adds the mandatory Name and Power parameters, and assigns Power as the primary parameter. Standard types also drive special handling in phone apps and third-party integrations such as Alexa and Google Voice Assistant.

Standard types

Below are the standard devices, services, parameters, and UI elements declared in esp_rmaker_standard_types.h. This list grows as new types are added.

Devices

caution

Parameters in bold are added automatically by the helper API. * indicates the primary parameter. Rows with no helper API are type strings only — build them with esp_rmaker_device_create() and the raw parameter APIs; they are listed because clients give them special handling.

Name	Type	Helper API	Params	GVA	Alexa
Switch	esp.device.switch	esp_rmaker_switch_device_create	Name, Power*	SWITCH	SWITCH
Lightbulb	esp.device.lightbulb	esp_rmaker_lightbulb_device_create	Name, Power*, Brightness, CCT, Hue, Saturation, Intensity, Light Mode	LIGHT	LIGHT
Light	esp.device.light	—	Name, Power, Brightness, CCT, Hue, Saturation, Intensity, Light Mode	LIGHT	LIGHT
Fan	esp.device.fan	esp_rmaker_fan_device_create	Name, Power*, Speed, Direction	FAN	FAN
Temperature Sensor	esp.device.temperature-sensor	esp_rmaker_temp_sensor_device_create	Name, Temperature*	THERMOSTAT	TEMPERATURE_SENSOR
Outlet	esp.device.outlet	—	Name, Power	OUTLET	SMARTPLUG
Plug	esp.device.plug	—	Name, Power	OUTLET	SMARTPLUG
Socket	esp.device.socket	—	Name, Power	OUTLET	SMARTPLUG
Lock	esp.device.lock	—	Name, lock state	—	SMARTLOCK
Internal Blinds	esp.device.blinds-internal	—	Name, Blinds Position	—	INTERIOR_BLIND
External Blinds	esp.device.blinds-external	—	Name, Blinds Position	—	EXTERIOR_BLIND
Garage Door	esp.device.garage-door	—	Name, Garage Position	—	GARAGE_DOOR
Garage Door Lock	esp.device.garage-door-lock	—	Name, lock state	—	SMARTLOCK
Speaker	esp.device.speaker	—	Name, Power	—	SPEAKER
Air Conditioner	esp.device.air-conditioner	—	Name, Power, Temperature, Speed, AC Mode	—	AIR_CONDITIONER
Thermostat	esp.device.thermostat	—	Name, Temperature, AC Mode, Power	THERMOSTAT	THERMOSTAT
TV	esp.device.tv	—	Name, Power	—	TV
Washer	esp.device.washer	—	Name, Mode	—	WASHER
Zigbee Gateway	esp.device.zigbee_gateway	—	Name, Add Zigbee Device	—	—
Thread Border Router	esp.device.thread-br	—	Name	—	—
Other	esp.device.other	—	—	—	OTHER

GVA and Alexa columns are the categories the RainMaker Neo backend maps each type to (action.devices.types.* and AVS display categories respectively). A — in the GVA column means the type is not mapped and falls through to the SWITCH default.

The backend accepts more device types than the SDK declares

The cloud's voice-assistant converters also recognise esp.device.set-top, esp.device.remote, esp.device.contact-sensor, esp.device.motion-sensor, esp.device.doorbell, esp.device.security-panel, and esp.device.water-heater. There is no macro for these in esp_rmaker_standard_types.h — pass the string literal to esp_rmaker_device_create() if you need one.

Services

Services are created with esp_rmaker_service_create(). The SDK creates these three itself when you enable the corresponding feature; you do not build them by hand.

Name	Type	Service ID	Params	Enabled by
Time	esp.service.time	Time	TZ, TZ-POSIX	esp_rmaker_timezone_service_enable()
System	esp.service.system	System	Reboot, Network-Reset, Factory-Reset — whichever flags you set	esp_rmaker_system_service_enable()
Local Control	esp.service.local_control	Local Control	Type, POP, Username	esp_rmaker_local_ctrl_service_enable()

Two further service types are declared but not implemented as data-model services in RainMaker Neo:

Type	Status
esp.service.schedule	Schedules are real and always on, but they are exchanged through the details-maintenance mechanism (getSchedDetails), not as a service with a Schedules parameter. See Schedules and automations.
esp.service.ota	OTA runs on AWS IoT Jobs, not on service parameters. There is no OTA service and no esp.param.ota_* parameters in use. See OTA firmware updates.

Parameters

Rows with a helper API are created fully configured — data type, UI type, properties, and bounds exactly as listed. Rows without one are type strings you apply yourself with esp_rmaker_param_create().

Name	Type	Helper API	Data Type	UI Type	Properties	Min, Max, Step
Name	esp.param.name	esp_rmaker_name_param_create	String	—	Read, Write, Persist	N/A
Power	esp.param.power	esp_rmaker_power_param_create	Bool	esp.ui.toggle	Read, Write	N/A
Brightness	esp.param.brightness	esp_rmaker_brightness_param_create	Int	esp.ui.slider	Read, Write	0, 100, 1
Hue	esp.param.hue	esp_rmaker_hue_param_create	Int	esp.ui.hue-slider	Read, Write	0, 360, 1
Saturation	esp.param.saturation	esp_rmaker_saturation_param_create	Int	esp.ui.slider	Read, Write	0, 100, 1
Intensity	esp.param.intensity	esp_rmaker_intensity_param_create	Int	esp.ui.slider	Read, Write	0, 100, 1
CCT	esp.param.cct	esp_rmaker_cct_param_create	Int	esp.ui.slider	Read, Write	2700, 6500, 100
Light Mode	esp.param.light-mode	esp_rmaker_light_mode_param_create	Int	esp.ui.dropdown or esp.ui.hidden	Read, Write	1, 2, 1 1: HSV 2: CCT
Speed	esp.param.speed	esp_rmaker_speed_param_create	Int	esp.ui.slider	Read, Write	0, 5, 1
Direction	esp.param.direction	esp_rmaker_direction_param_create	Int	esp.ui.dropdown	Read, Write	0, 1, 1
Temperature	esp.param.temperature	esp_rmaker_temperature_param_create	Float	esp.ui.text	Read, Time series	N/A
Timezone	esp.param.tz	— (Time service)	String	—	Read, Write	N/A
Timezone POSIX	esp.param.tz_posix	— (Time service)	String	—	Read, Write	N/A
Reboot	esp.param.reboot	— (System service)	Bool	—	Read, Write	N/A
Network-Reset	esp.param.network-reset	— (System service)	Bool	—	Read, Write	N/A
Factory-Reset	esp.param.factory-reset	— (System service)	Bool	—	Read, Write	N/A
Local Control POP	esp.param.local_control_pop	— (Local Control service)	String	—	Read	N/A
Local Control Type	esp.param.local_control_type	— (Local Control service)	Int	—	Read	N/A
Local Control Username	esp.param.local_control_username	— (Local Control service)	String	—	Read	N/A
Toggle Controller	esp.param.toggle	—	Bool	any applicable	Read, Write	N/A
Range Controller	esp.param.range	—	Int / Float	any applicable	Read, Write	app specific
Mode Controller	esp.param.mode	—	String	esp.ui.dropdown	Read, Write	N/A
AC Mode	esp.param.ac-mode	—	String	esp.ui.dropdown	Read, Write	N/A
Blinds Position	esp.param.blinds-position	—	Int	esp.ui.slider	Read, Write	0, 100, 1
Garage Position	esp.param.garage-position	—	Int	esp.ui.slider	Read, Write	0, 100, 1
Add Zigbee Device	esp.param.add_zigbee_device	—	String	esp.ui.qr-scan	Read, Write	N/A
OTA Status	esp.param.ota_status	—	String	—	Read	Declared, unused — see Services
OTA Info	esp.param.ota_info	—	String	—	Read	Declared, unused
OTA URL	esp.param.ota_url	—	String	—	Write	Declared, unused
Schedules	esp.param.schedules	—	Array	—	Read, Write, Persist	Declared, unused
Scenes	esp.param.scenes	—	Array	—	Read, Write, Persist	Declared, unused — scenes are not implemented

Default parameter IDs. The helpers use ESP_RMAKER_DEF_*_ID macros: "Name", "Power", "Brightness", "Hue", "Saturation", "Intensity", "CCT", "Light Mode", "Direction", "Speed", "Temperature". Reuse them so your parameter IDs match what other RainMaker devices report.

GVA traits. The backend maps parameter types to Google traits: Power → OnOff, Brightness → Brightness, Hue / Saturation / CCT → ColorSetting, Speed → FanSpeed, Temperature → TemperatureSetting, Light Mode / Mode → Modes. Name is metadata and maps to no trait.

UI elements

These tell the phone apps how to render a parameter.

Name	Type	Data Types	Requirements
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)
Hue Slider	esp.ui.hue-slider	Int	Param type = esp.param.hue
Hue Circle	esp.ui.hue-circle	Int	Param type = esp.param.hue
Push Button (big)	esp.ui.push-btn-big	Bool	N/A
Dropdown	esp.ui.dropdown	Int, String	Bounds (min, max) for Int; valid strings for String
Trigger	esp.ui.trigger	Bool	N/A
Hidden	esp.ui.hidden	All	Parameter is not shown
QR Scan	esp.ui.qr-scan	String	N/A

A slider on esp.param.brightness, esp.param.cct, or esp.param.saturation is rendered as the corresponding specialised control by the apps — you still set esp.ui.slider; the param type drives the difference.

Type changes to watch for

If you are porting an existing application, or working from the ESP RainMaker type reference, these are the values to check:

	Previously	ESP RainMaker Neo
System reset parameter	esp.param.wifi-reset ("Wi-Fi-Reset")	esp.param.network-reset ("Network-Reset")
Hue UI type	esp.ui.slider	esp.ui.hue-slider
Temperature properties	Read	Read + Time series, with esp.ui.text
Schedules	esp.service.schedules service with a Schedules parameter	Details-maintenance mechanism; type string declared but unused
OTA	esp.service.ota with ota_url / ota_status / ota_info	AWS IoT Jobs; type strings declared but unused
Scenes	Supported	Not implemented; type strings reserved
Device helpers	switch, lightbulb, fan, temp sensor, and more	switch, lightbulb, fan, temp sensor only
Added types	—	esp.device.zigbee_gateway, esp.device.thread-br, esp.device.garage-door-lock, esp.param.add_zigbee_device, esp.ui.qr-scan
Dropped types	esp.device.dimmer, esp.param.humidity, esp.param.setpoint-temperature, esp.param.lockstate, esp.param.media-*, esp.param.volume, esp.param.mute, esp.param.app-selector, esp.param.input-selector, the alarm-state params	No macros declared — use string literals if you need them

Related

• Data model — nodes, devices, parameters, property flags, attributes and tags
• Callbacks and events — dispatching on parameter type
• Firmware specifications → Node Configuration — the published JSON schema