标准预定义类型

创建设备时通常需要在代码中进行多次调用。例如，要创建一个新设备，类型为灯泡 (Lightbulb)，参数包括名称 (Name)、功率 (Power) 和亮度 (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);

上述代码灵活性较高，允许用户定义任何类型的设备。然而，为了对常见用例进行简化，RainMaker 已经定义了一些标准类型，并为其添加了 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));

标准类型也有助于在 RainMaker 手机应用或第三方应用（如 Alexa 或谷歌语音助手）中定义一些特殊的处理程序。下文表格列出了目前支持的标准设备类型、服务、参数和 UI 元素，表格内容会随着新类型的添加而不断更新。

设备

加粗参数为必要参数。
* 符号表示该参数为主要参数。

实现其中部分功能的 C 语言 API 可参考此处。其余功能可通过原始 API 来构建，列在表中是为了表明它们在 Alexa 或谷歌语音助手 (GVA) 等客户端中有特殊处理程序。

名称	类型	参数	GVA	Alexa	标志
Switch	esp.device.switch	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	X
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	X
Socket	esp.device.socket	Name, Power*	OUTLET	SMARTPLUG	X
Lock	esp.device.lock	Name, Lock State*	LOCK	SMARTLOCK
Internal Blinds	esp.device.blinds-internal	Name, Blinds Position*	BLINDS	INTERIOR_BLIND	X
External Blinds	esp.device.blinds-external	Name, Blinds Position*	BLINDS	EXTERIOR_BLIND	X
Garage Door	esp.device.garage-door	Name, Garage Position*, Lock State	GARAGE	GARAGE_DOOR	X
Speaker	esp.device.speaker	Name, Power, Media State, Media Control, Volume*, Mute	SPEAKER	SPEAKER	X
Air Conditioner	esp.device.air-conditioner	Name, Power, Setpoint Temperature, Fan Speed, AC Mode*	AC_UNIT	AIR_CONDITIONER	X
Thermostat	esp.device.thermostat	Name, Setpoint Temperature, AC Mode*, Power	THERMOSTAT	THERMOSTAT
TV	esp.device.tv	Name, Power, Media State, Media Control* App Selector, Input Selector, Volume, Mute	TV	TV	X
Washer	esp.device.washer	Name, Mode	WASHER	WASHER	X
Contact Sensor	esp.device.contact-sensor	Name, Contact Detection State*	X	CONTACT_SENSOR	X
Motion Sensor	esp.device.motion-sensor	Name, Motion Detection State*	X	MOTION_SENSOR	X
Door Bell	esp.device.doorbell	Name, Pressed State*	X	DOORBELL	X
Security Panel	esp.device.security-panel	Name, Arm State*, Fire Alarm State, Water Alarm State, CO Alarm State, Burglary Alarm State	X	SECURITY_PANEL	X
Other	esp.device.other		X	OTHER

服务

加粗参数为必要参数。

实现这些功能的 C 语言 API 可参考此处。

名称	类型	参数
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

参数

名称	类型	数据类型	UI 类型	特性	最小值、最大值、步长
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
Temperature	esp.param.temperature	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	任意类型	Read, Write	N/A
Range Controller	esp.param.range	Int/Float	任意类型	Read, Write	视具体应用而定
Mode Controller	esp.param.mode	String	esp.ui.dropdown	Read, Write	N/A
Setpoint Temperature	esp.param.setpoint-temperature	Int/Float	任意类型	Read/Write	N/A
Lock State	esp.param.lockstate	Int	任意类型	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 元素

下方表格定义了相关参数在手机应用中的呈现方式。

名称	类型	数据类型	要求	示例
Text（默认）	esp.ui.text	所有	N/A
Toggle Switch	esp.ui.toggle	Bool	N/A
Slider	esp.ui.slider	Int, Float	设定边界 (min/max)
Brightness Slider	esp.ui.slider	Int	参数类型 = esp.param.brightness
CCT Slider	esp.ui.slider	Int	参数类型 = esp.param.cct
Saturation Slider	esp.ui.slider	Int	参数类型 = esp.param.saturation
Hue Slider	esp.ui.hue-slider	Int	参数类型 = esp.param.hue
Hue Circle	esp.ui.hue-circle	Int	参数类型 = esp.param.hue
Push button (Big)	esp.ui.push-btn-big	Bool	N/A
Dropdown	esp.ui.dropdown	Int/String	Int：设定边界 (min/max) String：有效字符串
Trigger （仅安卓）	esp.ui.trigger	Bool	N/A
Hidden （仅安卓）	esp.ui.hidden	Bool	N/A	参数隐藏

标准预定义类型

设备​

服务​

参数​

UI 元素​

设备

服务

参数

UI 元素