Custom & Standard Types

about

Custom vs Standard Pre-defined Types

In ESP RainMaker firmware development, types refer to predefined schemas that describe the nature of a device and its attributes like paramter, or UI element (Displayed in the phone app).

When you use custom types, you manually define every aspect of the device—such as name, parameters like power and brightness, their data types, UI hints, and bounds, etc—giving you full flexibility to model any device.

On the other hand, standard types (like esp_rmaker_lightbulb_device_create) are simplified helper APIs provided for common devices like light bulbs, fans, or temperature sensors, etc. These automatically handle parameter setup, assign standard UI elements, and enable better compatibility with RainMaker phone apps and third-party services like Alexa or Google Assistant. Standard types are ideal for common use cases and enable smoother integrations with minimal code.

---

Example Usage

Creating a custom device

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.

---

Creating a standard device

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.

---

Standard Types

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.

Name	Type	Params	GVA	Alexa	Image
Switch	esp.device.switch	Name, Power*	SWITCH	SWITCH
Dimmer	esp.device.dimmer	Name, Power*	SWITCH	SWITCH
Lightbulb	esp.device.lightbulb	Name, Power*, Brightness, Color Temperature, Hue, Saturation, Intensity, Light Mode	LIGHT	LIGHT
Light	esp.device.light	Name, Power*, Brightness, Color Temperature, Hue, Saturation, Intensity, Light Mode	LIGHT	LIGHT
Fan	esp.device.fan	Name, Power*, Speed, Direction	FAN	FAN
Temperature Sensor	esp.device.temperature-sensor	Name, Temperature*	X	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*	LOCK	SMARTLOCK
Internal Blinds	esp.device.blinds-internal	Name, Blinds Position*	BLINDS	INTERIOR_BLIND
External Blinds	esp.device.blinds-external	Name, Blinds Position*	BLINDS	EXTERIOR_BLIND
Garage Door	esp.device.garage-door	Name, Garage Position*, Lock State	GARAGE	GARAGE_DOOR
Speaker	esp.device.speaker	Name, Power*, Media State, Media Control, Volume, Mute	SPEAKER	SPEAKER
Air Conditioner	esp.device.air-conditioner	Name, Power*, Setpoint Temperature, Temperature, Fan Speed, AC Mode	AC_UNIT	AIR_CONDITIONER
Thermostat	esp.device.thermostat	Name, Setpoint Temperature*, Temperature, AC Mode, Power	THERMOSTAT	THERMOSTAT
TV	esp.device.tv	Name, Power*, Media State, Media Control App Selector, Input Selector, Volume, Mute	TV	TV
Washer	esp.device.washer	Name, Mode	WASHER	WASHER
Contact Sensor	esp.device.contact-sensor	Name, Contact Detection State*	SENSOR	CONTACT_SENSOR
Motion Sensor	esp.device.motion-sensor	Name, Motion Detection State*	X	MOTION_SENSOR
Door Bell	esp.device.doorbell	Name, Pressed State*	X	DOORBELL
Security Panel	esp.device.security-panel	Name, Arm State*, Fire Alarm State, Water Alarm State, CO Alarm State, Burglary Alarm State	X	SECURITY_PANEL
Water Heater	esp.device.water-heater	Name, Temperature	WATERHEATER	WATER_HEATER	X
Set Top Box	esp.device.set-top	Name, Power, Media State, Media Control, App Selector, Input Selector, Volume, Mute	SETTOP	OTHER	X
Remote	esp.device.remote	Name, Power, Media State, Media Control, App Selector, Input Selector, Volume, Mute	REMOTE	OTHER	X
Refrigerator	esp.device.refrigerator	Name, Power, SetPointTempCelsius	REFRIGERATOR	OTHER	X
Other	esp.device.other		X	OTHER

---

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
Schedule	esp.service.schedules	Schedules
Time	esp.service.time	TZ, TZ-POSIX
System	esp.service.system	Reboot, 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.

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	N/A
Brightness	esp.param.brightness	Int	esp.ui.slider	Read, Write	0, 100, 1
CCT	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
Ambient Temperature	esp.param.temperature	Float		Read	N/A
Target temperature	esp.param.setpoint-temperature	Int/Float	esp.ui.slider	Read/Write	N/A
Ambient Humidity	esp.param.humidity	Float		Read	N/A
OTA URL	esp.param.ota_url	String	N/A	Write	N/A
OTA Status	esp.param.ota_status	String	N/A	Read	N/A
OTA Info	esp.param.ota_info	String	N/A	Read	N/A
Timezone	esp.param.tz	String	N/A	Read, Write	N/A
Timezone POSIX	esp.param.tz_posix	String	N/A	Read, Write	N/A
Schedules	esp.param.schedules	Array	N/A	Read, Write, Persist	N/A
Reboot	esp.param.reboot	Bool	N/A	Read, Write	N/A
Factory-Reset	esp.param.factory-reset	Bool	N/A	Read, Write	N/A
Wi-Fi-Reset	esp.param.wifi-reset	Bool	N/A	Read, Write	N/A
Toggle Controller	esp.param.toggle	Bool	Any type applicable	Read, Write	N/A
Range Controller	esp.param.range	Int/Float	Any type applicable	Read, Write	App specific
Mode Controller	esp.param.mode	String	esp.ui.dropdown	Read, Write	N/A
Lock State	esp.param.lockstate	Int	esp.ui.toggle	Read, Write	0, 2, 1 0:Unlocked 1:Locked 2:Jammed
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
Light Mode	esp.param.light-mode	Int	esp.ui.dropdown/ esp.ui.hidden	Read/Write	0, 2, 1 0:invalid 1:HSV 2:CCT
AC Mode	esp.paran.ac-mode	String	esp.ui.dropdown	Read/Write	N/A
Media State	esp.param.media-activity-state	String	esp.ui.dropdown	Read/Write	N/A
Media Control	esp.param.media-activity-control	String	esp.ui.dropdown	Read/Write	N/A
Volume	esp.param.volume	Float	esp.ui.slider	Read/Write	0, 20, 1
Mute	esp.param.mute	Bool	esp.ui.toggle	Read/Write	N/A
App Selector	esp.param.app-selector	String	esp.ui.dropdown	Read/Write	N/A
Input Selector	esp.param.input-selector	String	esp.ui.dropdown	Read/Write	N/A
Contact Detection State	esp.param.contact-detection-state	bool	esp.ui.toggle	Read	N/A
Motion Detection State	esp.param.motion-detection-state	bool	esp.ui.toggle	Read	N/A
Arm State	esp.param.arm-state	bool	esp.ui.toggle	Read/Write	N/A
Fire Alarm State	esp.param.fire-alarm	bool	esp.ui.toggle	Read	N/A
Water Alarm State	esp.param.water-alarm	bool	esp.ui.toggle	Read	N/A
CO Detection State	esp.param.carbon-monoxide-alarm	bool	esp.ui.toggle	Read	N/A
Burglary Alarm State	esp.param.burglary-alarm	bool	esp.ui.toggle	Read	N/A

---

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)
Brightness Slider	esp.ui.slider	Int	Param type = esp.param.brightness
CCT Slider	esp.ui.slider	Int	Param type = esp.param.cct
Saturation Slider	esp.ui.slider	Int	Param type = esp.param.saturation
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 strs for String
Trigger (Android only)	esp.ui.trigger	Bool	N/A
Hidden (Android only)	esp.ui.hidden	Bool	N/A	Param will be hidden