chore: 提交高层 xiaomi 封装库及示例

- 新增 xiaomi/examples/ 下 8 个示例程序（用户/家庭查询、设备列表、开关/灯光/空调控制、属性订阅、高级过滤分类、SPEC 解析） - miot_client_sub.go: 重构 SubProp/SubEvent，使用 buildPropTopic/buildEventTopic 支持通配符订阅（siid/piid=0 → +），并修复锁顺序问题（将 RequestRefreshProp 移到 Lock 外） - spec_parser.go: 新增 downloadSpecFile 方法，本地 SPEC 文件缺失时自动从 miot-spec.org 下载 - ARCH_PLAN.md: 架构设计从 Proposed 更新为 Accepted（v1.0→v1.1），补充设备分类/工厂/SPEC 映射等模块设计 - xiaomi/: 新增 miot 上层强类型封装模块，包含 Client 主入口、用户/家庭/设备 API、属性读写、动作调用、订阅通知，以及 devices/ 设备控制抽象（Switch/Light/AirConditioner/Fan/Cover/Humidifier/Vacuum/WaterHeater/Thermostat）和 specs/ SPEC 查询辅助 - 更多 xiaomi 示例（风扇/窗帘/传感器控制）
2026-06-29 08:51:21 +08:00
parent 35efed7d15
commit a3d94c4b9f
93 changed files with 7582 additions and 157 deletions
@@ -0,0 +1,212 @@
+package devices
+
+import (
+	"context"
+	"xiaomihome/xiaomi"
+)
+
+// Light 灯光统一控制接口
+type Light interface {
+	Device
+	TurnOn(ctx context.Context) error
+	TurnOff(ctx context.Context) error
+	Toggle(ctx context.Context) error
+
+	// 能力查询
+	HasBrightness() bool
+	HasColorTemp() bool
+	HasColor() bool
+
+	// 亮度 (1-100)
+	SetBrightness(ctx context.Context, pct int) error
+	GetBrightness(ctx context.Context) (int, error)
+
+	// 色温 (2700-6500K)
+	SetColorTemp(ctx context.Context, kelvin int) error
+	GetColorTemp(ctx context.Context) (int, error)
+
+	// 颜色 (0-255)
+	SetColor(ctx context.Context, r, g, b int) error
+	GetColor(ctx context.Context) (r, g, b int, err error)
+
+	OnStateChanged(handler func(state LightState)) (string, error)
+}
+
+// LightState 灯光完整状态
+type LightState struct {
+	Power      bool   `json:"power"`
+	Brightness int    `json:"brightness"`
+	ColorTemp  int    `json:"color_temp"`
+	ColorRGB   [3]int `json:"color_rgb"`
+}
+
+type lightDevice struct {
+	BaseDevice
+	propOn         siidPiid // "on"
+	propBrightness siidPiid // "brightness"
+	propColorTemp  siidPiid // "color-temperature"
+	propColor      siidPiid // "color"
+}
+
+// NewLight creates a Light control for the given device.
+func NewLight(client *xiaomi.Client, info *xiaomi.DeviceInfo) (Light, error) {
+	d := &lightDevice{
+		BaseDevice: NewBaseDevice(client, info),
+	}
+
+	resolver := d.getSpecResolver()
+	if resolver == nil {
+		return nil, xiaomi.ErrNoSPEC
+	}
+
+	// "on" is required
+	siid, piid, ok := resolver.find("on")
+	if !ok {
+		return nil, xiaomi.ErrNotSupported
+	}
+	d.propOn = siidPiid{siid, piid, true}
+
+	// Optional properties
+	if s, p, ok := resolver.find("brightness"); ok {
+		d.propBrightness = siidPiid{s, p, true}
+	}
+	if s, p, ok := resolver.find("color-temperature"); ok {
+		d.propColorTemp = siidPiid{s, p, true}
+	}
+	if s, p, ok := resolver.find("color"); ok {
+		d.propColor = siidPiid{s, p, true}
+	}
+
+	return d, nil
+}
+
+func (d *lightDevice) TurnOn(ctx context.Context) error {
+	if !d.propOn.valid {
+		return xiaomi.ErrNotSupported
+	}
+	return d.SetProp(ctx, d.propOn.siid, d.propOn.piid, true)
+}
+
+func (d *lightDevice) TurnOff(ctx context.Context) error {
+	if !d.propOn.valid {
+		return xiaomi.ErrNotSupported
+	}
+	return d.SetProp(ctx, d.propOn.siid, d.propOn.piid, false)
+}
+
+func (d *lightDevice) Toggle(ctx context.Context) error {
+	on, err := d.isOn(ctx)
+	if err != nil {
+		return err
+	}
+	if on {
+		return d.TurnOff(ctx)
+	}
+	return d.TurnOn(ctx)
+}
+
+func (d *lightDevice) isOn(ctx context.Context) (bool, error) {
+	prop, err := d.GetProp(ctx, d.propOn.siid, d.propOn.piid)
+	if err != nil {
+		return false, err
+	}
+	if b, ok := prop.Value.(bool); ok {
+		return b, nil
+	}
+	return false, nil
+}
+
+func (d *lightDevice) HasBrightness() bool { return d.propBrightness.valid }
+func (d *lightDevice) HasColorTemp() bool  { return d.propColorTemp.valid }
+func (d *lightDevice) HasColor() bool      { return d.propColor.valid }
+
+func (d *lightDevice) SetBrightness(ctx context.Context, pct int) error {
+	if !d.propBrightness.valid {
+		return xiaomi.ErrNotSupported
+	}
+	return d.SetProp(ctx, d.propBrightness.siid, d.propBrightness.piid, pct)
+}
+
+func (d *lightDevice) GetBrightness(ctx context.Context) (int, error) {
+	if !d.propBrightness.valid {
+		return 0, xiaomi.ErrNotSupported
+	}
+	prop, err := d.GetProp(ctx, d.propBrightness.siid, d.propBrightness.piid)
+	if err != nil {
+		return 0, err
+	}
+	return toInt(prop.Value), nil
+}
+
+func (d *lightDevice) SetColorTemp(ctx context.Context, kelvin int) error {
+	if !d.propColorTemp.valid {
+		return xiaomi.ErrNotSupported
+	}
+	return d.SetProp(ctx, d.propColorTemp.siid, d.propColorTemp.piid, kelvin)
+}
+
+func (d *lightDevice) GetColorTemp(ctx context.Context) (int, error) {
+	if !d.propColorTemp.valid {
+		return 0, xiaomi.ErrNotSupported
+	}
+	prop, err := d.GetProp(ctx, d.propColorTemp.siid, d.propColorTemp.piid)
+	if err != nil {
+		return 0, err
+	}
+	return toInt(prop.Value), nil
+}
+
+func (d *lightDevice) SetColor(ctx context.Context, r, g, b int) error {
+	if !d.propColor.valid {
+		return xiaomi.ErrNotSupported
+	}
+	colorVal := (r << 16) | (g << 8) | b
+	return d.SetProp(ctx, d.propColor.siid, d.propColor.piid, colorVal)
+}
+
+func (d *lightDevice) GetColor(ctx context.Context) (r, g, b int, err error) {
+	if !d.propColor.valid {
+		return 0, 0, 0, xiaomi.ErrNotSupported
+	}
+	prop, err := d.GetProp(ctx, d.propColor.siid, d.propColor.piid)
+	if err != nil {
+		return 0, 0, 0, err
+	}
+	val := toInt(prop.Value)
+	r = (val >> 16) & 0xFF
+	g = (val >> 8) & 0xFF
+	b = val & 0xFF
+	return r, g, b, nil
+}
+
+func (d *lightDevice) OnStateChanged(handler func(state LightState)) (string, error) {
+	if !d.propOn.valid {
+		return "", xiaomi.ErrNotSupported
+	}
+	return d.SubProp(d.propOn.siid, d.propOn.piid, func(did string, prop *xiaomi.PropertyValue) {
+		state := LightState{}
+		if b, ok := prop.Value.(bool); ok {
+			state.Power = b
+		}
+		handler(state)
+	})
+}
+
+// toInt converts an interface{} value to int.
+func toInt(v interface{}) int {
+	switch n := v.(type) {
+	case float64:
+		return int(n)
+	case int:
+		return n
+	case int64:
+		return int(n)
+	case uint8:
+		return int(n)
+	case uint16:
+		return int(n)
+	case uint32:
+		return int(n)
+	}
+	return 0
+}