自定义类型与标准类型

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	名称，电源*，媒体状态，媒体控制 应用选择器，输入选择器，音量，静音	TV	TV
洗衣机	esp.device.washer	名称，模式	WASHER	WASHER
门磁传感器	esp.device.contact-sensor	名称, 接触检测状态*	SENSOR	CONTACT_SENSOR
人体传感器	esp.device.motion-sensor	名称， 运动检测状态*	X	MOTION_SENSOR
门铃	esp.device.doorbell	名称， 按下状态*	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 类型	属性	最小值，最大值，步长
名称	esp.param.name	字符串		读，写	1，32，-
电源	esp.param.power	布尔	esp.ui.toggle	读，写	N/A
亮度	esp.param.brightness	整型	esp.ui.slider	读，写	0，100，1
色温	esp.param.cct	整型	esp.ui.slider	读，写	2700，6500，100
色调	esp.param.hue	整型	esp.ui.slider	读，写	0，360，1
饱和度	esp.param.saturation	整型	esp.ui.slider	读，写	0，100，1
强度	esp.param.intensity	整型	esp.ui.slider	读，写	0，100，1
速度	esp.param.speed	整型	esp.ui.slider	读，写	0，5，1
方向	esp.param.direction	整型	esp.ui.dropdown	读，写	0，1，1
环境温度	esp.param.temperature	浮点		读	N/A
目标温度	esp.param.setpoint-temperature	整型/浮点	esp.ui.slider	读/写	N/A
环境湿度	esp.param.humidity	浮点		读	N/A
OTA URL	esp.param.ota_url	字符串	N/A	写	N/A
OTA 状态	esp.param.ota_status	字符串	N/A	读	N/A
OTA 信息	esp.param.ota_info	字符串	N/A	读	N/A
时区	esp.param.tz	字符串	N/A	读，写	N/A
时区 POSIX	esp.param.tz_posix	字符串	N/A	读，写	N/A
日程	esp.param.schedules	数组	N/A	读，写，重启后仍保留	N/A
重启	esp.param.reboot	布尔	N/A	读，写	N/A
恢复出厂设置	esp.param.factory-reset	布尔	N/A	读，写	N/A
Wi-Fi 重置	esp.param.wifi-reset	布尔	N/A	读，写	N/A
切换控制器	esp.param.toggle	布尔	任何适用类型	读，写	N/A
范围控制器	esp.param.range	整型/浮点	任何适用类型	读，写	应用自定义
模式控制器	esp.param.mode	字符串	esp.ui.dropdown	读，写	N/A
锁状态	esp.param.lockstate	整型	esp.ui.toggle	读，写	0，2，1 0：未锁定 1：已锁定 2：卡死
窗帘位置	esp.param.blinds-position	整型	esp.ui.slider	读/写	0，100，1
车库位置	esp.param.garage-position	整型	esp.ui.slider	读/写	0，100，1
灯光模式	esp.param.light-mode	整型	esp.ui.dropdown/ esp.ui.hidden	读/写	0，2，1 0：无效 1：HSV 2：CCT
空调模式	esp.paran.ac-mode	字符串	esp.ui.dropdown	读/写	N/A
媒体状态	esp.param.media-activity-state	字符串	esp.ui.dropdown	读/写	N/A
媒体控制	esp.param.media-activity-control	字符串	esp.ui.dropdown	读/写	N/A
音量	esp.param.volume	浮点	esp.ui.slider	读/写	0，20，1
静音	esp.param.mute	布尔	esp.ui.toggle	读/写	N/A
应用选择器	esp.param.app-selector	字符串	esp.ui.dropdown	读/写	N/A
输入选择器	esp.param.input-selector	字符串	esp.ui.dropdown	读/写	N/A
接触检测状态	esp.param.contact-detection-state	布尔	esp.ui.toggle	读	N/A
运动检测状态	esp.param.motion-detection-state	布尔	esp.ui.toggle	读	N/A
布防状态	esp.param.arm-state	布尔	esp.ui.toggle	读/写	N/A
火警状态	esp.param.fire-alarm	布尔	esp.ui.toggle	读	N/A
水警状态	esp.param.water-alarm	布尔	esp.ui.toggle	读	N/A
一氧化碳检测状态	esp.param.carbon-monoxide-alarm	布尔	esp.ui.toggle	读	N/A
入侵警报状态	esp.param.burglary-alarm	布尔	esp.ui.toggle	读	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	参数将被隐藏