xiaomihome/xiaomi/types.go

// Package xiaomi provides a high-level, strongly-typed wrapper over the miot package.
// It converts map[string]interface{} APIs into typed structs and offers device
// control abstractions that hide siid/piid details behind semantic interfaces.
package xiaomi

// ========== 基础信息 ==========

// UserInfo 用户信息（字段对齐 Xiaomi open.account.xiaomi.com/user/profile API）
type UserInfo struct {
	UID       string `json:"userId"`
	NickName  string `json:"miliaoNick"`
	AvatarURL string `json:"miliaoIcon"`
}

// HomeInfo 家庭信息
type HomeInfo struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	UID        string     `json:"uid"`
	GroupID    string     `json:"group_id"`
	Rooms      []RoomInfo `json:"rooms"`
	DidList    []string   `json:"did_list"`
	ShareState bool       `json:"share_state"`
	CityID     string     `json:"city_id"`
	Longitude  float64    `json:"longitude"`
	Latitude   float64    `json:"latitude"`
	Address    string     `json:"address"`
}

// RoomInfo 房间信息
type RoomInfo struct {
	ID      string   `json:"id"`
	Name    string   `json:"name"`
	HomeID  string   `json:"home_id"`
	DidList []string `json:"did_list"` // 房间内设备 DID
}

// DeviceInfo 设备信息（替代 map[string]interface{}）
type DeviceInfo struct {
	DID          string `json:"did"`
	Name         string `json:"name"`
	Model        string `json:"model"`
	Manufacturer string `json:"manufacturer"`
	FWVersion    string `json:"fw_version"`
	Icon         string `json:"icon"`
	URN          string `json:"urn"` // 设备 SPEC 类型
	Token        string `json:"token"`
	IP           string `json:"local_ip"`
	RSSI         int    `json:"rssi"`
	SSID         string `json:"ssid"`
	BSSID        string `json:"bssid"`
	Online       bool   `json:"is_online"`
	HomeID       string `json:"home_id"`
	HomeName     string `json:"home_name"`
	RoomID       string `json:"room_id"`
	RoomName     string `json:"room_name"`
	OwnerID      string `json:"owner_id"`
	ParentID     string `json:"parent_id"`
	ParentModel  string `json:"parent_model"`
	GroupID      string `json:"group_id"`
	ConnectType  int    `json:"connect_type"` // 0=WiFi, 1=BLE, 2=ZigBee, ...
}

// ========== 属性/事件 ==========

// PropertyValue 属性值（强类型）。
// Type 字段仅在主动 GetProp 场景可用（可从 SPEC 推断 format），SubProp 回调中 miot 不提供 type 信息。
type PropertyValue struct {
	DID   string      `json:"did"`
	SIID  int         `json:"siid"`
	PIID  int         `json:"piid"`
	Code  int         `json:"code"`
	Value interface{} `json:"value"`
	Type  string      `json:"type"` // SPEC format ("bool"/"uint8"/"float"/"string"); 仅 GetProp 时可用
}

// PropertiesChanged 属性变化事件
type PropertiesChanged struct {
	DID        string          `json:"did"`
	Properties []PropertyValue `json:"properties"`
}

// EventOccurred 事件发生通知
type EventOccurred struct {
	DID       string                 `json:"did"`
	SIID      int                    `json:"siid"`
	EIID      int                    `json:"eiid"`
	Arguments map[string]interface{} `json:"arguments"`
	Timestamp int64                  `json:"timestamp"`
}

// DeviceState 设备在线状态
type DeviceState string

const (
	StateOnline  DeviceState = "online"
	StateOffline DeviceState = "offline"
)

// ========== Action ==========

// ActionResult Action 执行结果
type ActionResult struct {
	DID  string                   `json:"did"`
	SIID int                      `json:"siid"`
	AIID int                      `json:"aiid"`
	Code int                      `json:"code"`
	Out  []map[string]interface{} `json:"out"`
}

// ========== 属性读写辅助类型 ==========

// PropKey 属性键对
type PropKey struct {
	DID  string
	SIID int
	PIID int
}

// PropKeyValue 属性键值对
type PropKeyValue struct {
	PropKey
	Value interface{}
}

// PropResult 写入结果
type PropResult struct {
	PropKey
	Code int
}

// ========== 回调定义 ==========

// PropHandler 属性变化回调（强类型，替代 miot 的 map handler）
type PropHandler func(did string, prop *PropertyValue)

// EventHandler 事件回调（强类型）
type EventHandler func(did string, event *EventOccurred)

// DeviceStateHandler 设备在线状态变化回调
type DeviceStateHandler func(did string, state DeviceState)

// ========== 设备分类 ==========

// Kind 设备大类
type Kind string

const (
	KindAirConditioner Kind = "air_conditioner"
	KindLight          Kind = "light"
	KindSwitch         Kind = "switch"
	KindFan            Kind = "fan"
	KindCover          Kind = "cover"
	KindHumidifier     Kind = "humidifier"
	KindVacuum         Kind = "vacuum"
	KindWaterHeater    Kind = "water_heater"
	KindThermostat     Kind = "thermostat"
	KindSensor         Kind = "sensor"
	KindUnknown        Kind = "unknown"
)

// DeviceKind 从 URN 快速判断设备种类（不依赖 SPEC 加载）
func (d *DeviceInfo) DeviceKind() Kind {
	return Classify(d)
}