自定义类型与标准类型

about

自定义类型与标准预定义类型

在 ESP RainMaker 固件开发中，“类型”指用于描述设备及其属性（如参数或 UI 元素）在手机应用中呈现方式的预定义模式。

使用自定义类型时，你需要手动定义设备的每个方面（如名称、电源、亮度等参数），包括它们的数据类型、UI 提示、取值范围等，从而灵活地建模任何设备。

而标准类型（如 esp_rmaker_lightbulb_device_create）则是针对常见设备（如灯泡、风扇或温度传感器等）提供的简化辅助 API。这些 API 会自动处理参数设置、分配标准 UI 元素，并提升与 RainMaker 手机应用及第三方服务（如 Alexa 或谷歌助手）的兼容性。标准类型适用于常见场景，能够以最少的代码实现高效集成。

---

示例用法

创建自定义设备

创建一个设备通常需要多次调用。例如，创建一个带有名称、电源和亮度的灯泡：

---

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

---

这种灵活性可以让你定义任何类型的设备。但为简化常见场景，我们也定义了标准类型并提供了辅助 API。

创建标准设备

使用标准类型，上述代码可简化为：

---

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

---

标准类型还便于在手机应用或 Alexa、谷歌语音助手等第三方应用中定义某些特殊的处理逻辑。

---

标准类型

以下是标准设备、服务、参数和 UI 元素列表。随着新类型的加入，该列表会持续更新。

设备

警告

加粗参数为必选。* 表示主参数。

部分设备的 C API 可查阅此处。其他设备可通过原始 API 构建。此处列出仅为说明这些设备在 Alexa/GVA 等客户端中有特殊处理。

名称	类型	参数	GVA	Alexa	图片
开关	esp.device.switch	名称，电源*	SWITCH	SWITCH
调光器	esp.device.dimmer	名称，电源*	SWITCH	SWITCH
灯泡	esp.device.lightbulb	名称，电源*，亮度，色温，色调，饱和度，强度，灯光模式	LIGHT	LIGHT
灯	esp.device.light	名称，电源*，亮度，色温，色调，饱和度，强度，灯光模式	LIGHT	LIGHT
风扇	esp.device.fan	名称，电源*，速度，方向	FAN	FAN
温度传感器	esp.device.temperature-sensor	名称，温度*	X	TEMPERATURE _SENSOR
插座	esp.device.outlet	名称，电源*	OUTLET	SMARTPLUG
插头	esp.device.plug	名称，电源*	OUTLET	SMARTPLUG
插孔	esp.device.socket	名称，电源*	OUTLET	SMARTPLUG
门锁	esp.device.lock	名称， 锁状态*	LOCK	SMARTLOCK
内部窗帘	esp.device.blinds-internal	名称， 窗帘位置*	BLINDS	INTERIOR_BLIND
外部窗帘	esp.device.blinds-external	名称， 窗帘位置*	BLINDS	EXTERIOR_BLIND
车库门	esp.device.garage-door	名称， 车库位置*，锁状态	GARAGE	GARAGE_DOOR
扬声器	esp.device.speaker	名称，电源*，媒体状态，媒体控制，音量，静音	SPEAKER	SPEAKER
空调	esp.device.air-conditioner	名称，电源*，设定温度，温度，风速，空调模式	AC_UNIT	AIR_CONDITIONER
温控器	esp.device.thermostat	名称，设定温度*，温度，空调模式，电源	THERMOSTAT	THERMOSTAT
电视	esp.device.tv	名称，电源*，媒体状态，媒体控制 应用选择器，输入选择器，音量，静音，Channel, Channel Relative	TV	TV
洗衣机	esp.device.washer	名称，Running State*, Paused State*, Mode, Run Cycle	WASHER	WASHER
门磁传感器	esp.device.contact-sensor	名称, 接触检测状态*	SENSOR	CONTACT_SENSOR
人体传感器	esp.device.motion-sensor	名称， 运动检测状态*	X	MOTION_SENSOR
门铃	esp.device.doorbell	名称， Bell Pressed State*	X	DOORBELL
安防面板	esp.device.security-panel	名称，布防状态*， 火警状态， 水警状态， 一氧化碳警报状态， 入侵警报状态	X	SECURITY_PANEL
热水器	esp.device.water-heater	名称，温度	WATERHEATER	WATER_HEATER	X
机顶盒	esp.device.set-top	名称，电源，媒体状态，媒体控制，应用选择器，输入选择器，音量，静音	SETTOP	OTHER	X
遥控器	esp.device.remote	名称，电源，媒体状态，媒体控制，应用选择器，输入选择器，音量，静音	REMOTE	OTHER	X
冰箱	esp.device.refrigerator	名称，电源，设定温度（摄氏度）	REFRIGERATOR	OTHER	X
其他	esp.device.other		X	OTHER

服务

警告

加粗参数为必选。

相关 C API 可在这里查阅。

名称	类型	参数
OTA	esp.service.ota	OTA URL，OTA 状态，OTA 信息
日程	esp.service.schedules	Schedules
时间	esp.service.time	TZ，TZ-POSIX
系统	esp.service.system	重启，恢复出厂设置，Wi-Fi 重置

参数

部分参数的 C API 可在这里查阅。其他参数可通过原始 API 构建。此处列出仅为说明这些参数在 Alexa/GVA 等客户端有特殊处理。

名称	类型	数据类型	UI 类型	属性	最小值，最大值，步长	Description
名称	esp.param.name	字符串		读，写	1，32，-	Name of the device
电源	esp.param.power	布尔	esp.ui.toggle	读，写	N/A	Used to turn on/off the device
亮度	esp.param.brightness	整型	esp.ui.slider	读，写	0，100，1	Brightness level of the device
Dim	esp.param.dim	Int	esp.ui.slider	Read/Write	0, 100, 1	Alias to Brightness
色温	esp.param.cct	整型	esp.ui.slider	读，写	2700，6500，100	Color correlated temperature
色调	esp.param.hue	整型	esp.ui.slider	读，写	0，360，1	Hue of the light
饱和度	esp.param.saturation	整型	esp.ui.slider	读，写	0，100，1	Saturation of the light
强度	esp.param.intensity	整型	esp.ui.slider	读，写	0，100，1	Intensity of the light
速度	esp.param.speed	整型	esp.ui.slider	读，写	0，5，1	Speed of the fan
方向	esp.param.direction	整型	esp.ui.dropdown	读，写	0，1，1	Direction of the fan (0: Forward, 1: Reverse)
环境温度	esp.param.temperature	浮点		读	N/A	Current ambient temperature
目标温度	esp.param.setpoint-temperature	整型/浮点	esp.ui.slider	读/写	N/A	single target temperature
Lower Bound Target temperature	esp.param.setpoint-low-temperature	Int/Float	esp.ui.slider	Read/Write	N/A	Used in conjunction with Upper Bound Target temperature. Lower bound of the temperature range.
Upper Bound Target temperature	esp.param.setpoint-high-temperature	Int/Float	esp.ui.slider	Read/Write	N/A	Used in conjunction with Lower Bound Target temperature. Upper bound of the temperature range.
环境湿度	esp.param.humidity	浮点		读	N/A	Current ambient humidity
切换控制器	esp.param.toggle	布尔	任何适用类型	读，写	N/A	Generic toggle parameter
范围控制器	esp.param.range	整型/浮点	任何适用类型	读，写	应用自定义	Generic range parameter
模式控制器	esp.param.mode	字符串	esp.ui.dropdown	读，写	N/A	The valid strings for this can be different, depending on device type
锁状态	esp.param.lockstate	整型	esp.ui.toggle	读，写	0，2，1 0：未锁定 1：已锁定 2：卡死	Used for Lock device
窗帘位置	esp.param.blinds-position	整型	esp.ui.slider	读/写	0，100，1	Used for Blinds device, indicates the open percentage
车库位置	esp.param.garage-position	整型	esp.ui.slider	读/写	0，100，1	Used for Garage door device, indicates the open percentage
灯光模式	esp.param.light-mode	整型	esp.ui.dropdown/ esp.ui.hidden	读/写	0，2，1 0:Default(both HSV, CCT) 1：HSV 2：CCT	Used to set the light mode to HSV/CCT
空调模式	esp.paran.ac-mode	字符串	esp.ui.dropdown	读/写	N/A	Current operating mode of the AC unit
媒体状态	esp.param.media-activity-state	字符串	esp.ui.dropdown	读/写	N/A	Indicates whether Entertainment device is active
Playback State	esp.param.media-playback-state	String	esp.ui.dropdown	Read/Write	N/A	Indicate the current state when playing media.
媒体控制	esp.param.media-activity-control	字符串	esp.ui.dropdown	读/写	N/A	Controls media playback (e.g., play, pause, stop)
音量	esp.param.volume	浮点	esp.ui.slider	读/写	0，20，1	Current volume level
静音	esp.param.mute	布尔	esp.ui.toggle	读/写	N/A	Mute state of the device
应用选择器	esp.param.app-selector	字符串	esp.ui.dropdown	读/写	N/A	Used to select the app on entertainment device
输入选择器	esp.param.input-selector	字符串	esp.ui.dropdown	读/写	N/A	Used to select the input on entertainment device
接触检测状态	esp.param.contact-detection-state	布尔	esp.ui.toggle	读	N/A	Indicates if contact is detected
运动检测状态	esp.param.motion-detection-state	布尔	esp.ui.toggle	读	N/A	Indicates if motion is detected
布防状态	esp.param.arm-state	布尔	esp.ui.toggle	读/写	N/A	Current arm state of the security panel
火警状态	esp.param.fire-alarm	布尔	esp.ui.toggle	读	N/A	Indicates if fire alarm is triggered
水警状态	esp.param.water-alarm	布尔	esp.ui.toggle	读	N/A	Indicates if water alarm is triggered
一氧化碳检测状态	esp.param.carbon-monoxide-alarm	布尔	esp.ui.toggle	读	N/A	Indicates if carbon monoxide alarm is triggered
入侵警报状态	esp.param.burglary-alarm	布尔	esp.ui.toggle	读	N/A	Indicates if burglary alarm is triggered
Bell Pressed State	esp.param.bell-pressed	bool	esp.ui.trigger	Write	N/A	Used to trigger bell press event
Run Cycle	esp.param.run-cycle	string	esp.ui.dropdown	Read	N/A	Indicates current run cycle of the device
Running State	esp.param.running-state	bool	esp.ui.toggle	Read/Write	N/A	Device can be started and stopped with this parameter
Paused state	esp.param.paused-state	bool	esp.ui.toggle	Read/Write	N/A	Device can be paused and unpaused with this parameter
Channel	esp.param.channel	string	esp.ui.text	Read/Write	N/A	Used to set channel by channel code on entertainment device
Channel Relative	esp.param.channel-relative	string	esp.ui.text	Read/Write	N/A	Used to change channel on entertainment device
Media Playback State	esp.param.media-playback-state	string	esp.ui.text	Read/Write	N/A	Indicates the current state when playing media.
OTA URL	esp.param.ota_url	String	N/A	Write	N/A
OTA 状态	esp.param.ota_status	String	N/A	Read	N/A
OTA 信息	esp.param.ota_info	String	N/A	Read	N/A
时区	esp.param.tz	String	N/A	读，写	N/A
时区 POSIX	esp.param.tz_posix	String	N/A	读，写	N/A
日程	esp.param.schedules	Array	N/A	读，写，重启后仍保留	N/A
重启	esp.param.reboot	Bool	N/A	读，写	N/A
恢复出厂设置	esp.param.factory-reset	Bool	N/A	读，写	N/A
Wi-Fi 重置	esp.param.wifi-reset	Bool	N/A	读，写	N/A

UI 元素

这些定义了参数在手机应用中的呈现方式。

名称	类型	数据类型	要求	示例
文本（默认）	esp.ui.text	所有	N/A
切换开关	esp.ui.toggle	布尔	N/A
滑块	esp.ui.slider	整型，浮点	边界（最小值、最大值）
亮度滑块	esp.ui.slider	整型	参数类型 = esp.param.brightness
色温滑块	esp.ui.slider	整型	参数类型 = esp.param.cct
饱和度滑块	esp.ui.slider	整型	参数类型 = esp.param.saturation
色调滑块	esp.ui.hue-slider	整型	参数类型 = esp.param.hue
色调圆环	esp.ui.hue-circle	整型	参数类型 = esp.param.hue
大按钮	esp.ui.push-btn-big	布尔	N/A
下拉框	esp.ui.dropdown	整型/字符串	整型需边界（最小/最大） 字符串需有效值
触发器 (仅安卓)	esp.ui.trigger	布尔	N/A
隐藏 (仅安卓)	esp.ui.hidden	布尔	N/A	参数将被隐藏