核心概念

Aqara Spec 物模型采用分层架构，从上到下依次为：Device(设备) → Endpoint(端点) → Device Type(设备类型) → Function(功能) → Trait(功能点) / Command(命令)。

设备内存在两类特殊 Endpoint：Root Endpoint（Endpoint 0）和 Public Endpoint（通常为 Endpoint 1）。Root Endpoint 承载设备根信息；Public Endpoint 承载设备级通用 Function，供整个设备共享，不在各业务 Endpoint 上重复实现。

以下以一台多 Endpoint 人体存在传感器设备为例，展示 Root Endpoint、Public Endpoint 与多个业务 Endpoint 的实际结构：

Device: "<Device ID>"
├── Endpoint 0 (Root Endpoint)
│    └── Root (Device Type)
│         └── Basic Information (Function)
│              ├── DebugInfo (Trait)
│              ├── BLEVersion (Trait)
│              ├── MCUVersion (Trait)
│              ├── FirmwareRevision (Trait)
│              ├── SerialNumber (Trait)
│              ├── VendorName (Trait)
│              ├── VendorID (Trait)
│              ├── ProductName (Trait)
│              ├── Reachable (Trait)
│              ├── FirmwareRevisionString (Trait)
│              └── ProductID (Trait)
├── Endpoint 1 (Public Endpoint)
│    └── Public (Device Type)
│         ├── Identify (Function)
│         │    ├── IdentifyTime (Trait)
│         │    ├── IdentifyType (Trait)
│         │    └── Identify (Command)
│         ├── Matter Commissioning (Function)
│         │    ├── MatterFabricsOperationState (Trait)
│         │    ├── ConnectedMatterFabrics (Trait)
│         │    ├── MatterCommissioningWindowStatus (Trait)
│         │    ├── MatterNodeID (Trait)
│         │    ├── OpenMatterCommissioningWindow (Command)
│         │    └── RemoveMatterFabric (Command)
│         ├── General Diagnostics (Function)
│         │    ├── UpTime (Trait)
│         │    ├── NetworkInterfaces (Trait)
│         │    ├── ActiveHardwareFaults (Trait)
│         │    ├── RebootCount (Trait)
│         │    └── RebootReason (Trait)
│         ├── Matter Node Information (Function)
│         │    └── MatterNodeFirstEndpointID (Trait)
│         └── Thread Network Diagnostics (Function)
│              ├── OverrunCount (Trait)
│              ├── PartitionID (Trait)
│              ├── TxTotalCount (Trait)
│              ├── TxUnicastCount (Trait)
│              ├── TxBroadcastCount (Trait)
│              ├── RxTotalCount (Trait)
│              ├── RxUnicastCount (Trait)
│              ├── RxBroadcastCount (Trait)
│              ├── NetworkFaultChange (Trait)
│              ├── Channel (Trait)
│              ├── PanID (Trait)
│              ├── ExtendedPanID (Trait)
│              ├── NetworkName (Trait)
│              ├── RouteTable (Trait)
│              ├── RoutingRole (Trait)
│              ├── NeighborTable (Trait)
│              └── MeshLocalPrefix (Trait)
├── Endpoint 2 (业务 Endpoint)
│    └── Occupancy Sensor (Device Type)
│         ├── Occupancy Sensing (Function)
│         │    ├── HoldTime (Trait)
│         │    ├── Occupancy (Trait)
│         │    └── OccupancySensorType (Trait)
│         ├── General Configuration (Function)
│         │    └── CurrentSensitivityLevel (Trait)
│         ├── Ambient Sensing Configuration (Function)
│         │    ├── InstallMode (Trait)
│         │    ├── SideInstall (Trait)
│         │    ├── InstallHeightSetting (Trait)
│         │    ├── InstallStatus (Trait)
│         │    ├── InstallAngle (Trait)
│         │    ├── MaxDetectionZones (Trait)
│         │    ├── Zones (Trait)
│         │    ├── EntryExitRegionBitmask (Trait)
│         │    ├── InterferenceRegionBitmask (Trait)
│         │    ├── EdgeRegionBitmask (Trait)
│         │    ├── EnableHumanCountDetection (Trait)
│         │    ├── EnableAIHighPrecisionRecognition (Trait)
│         │    ├── EnableAIEntryExitRegionRecognition (Trait)
│         │    ├── EnableAIInterferenceSourceRecognition (Trait)
│         │    ├── EnableAIAdaptiveSensitivity (Trait)
│         │    ├── CoordinateReverseSetting (Trait)
│         │    ├── DetectionDirectionSetting (Trait)
│         │    ├── AutoInterferenceSourceRecognition (Trait)
│         │    ├── AutoEdgeRecognition (Trait)
│         │    ├── AIEntryExitRegionRecognition (Trait)
│         │    ├── ProximityDistanceLevel (Trait)
│         │    ├── InterferenceSourceRecognitionReportingTimeout (Trait)
│         │    ├── AISpaceBackgroundLearningReportingTimeout (Trait)
│         │    ├── AISpaceBackgroundLearningComplete (Trait)
│         │    ├── SubscribeAutoInterferenceSourceRecognitionData (Command)
│         │    ├── SubscribeAutoEdgeRecognitionData (Command)
│         │    ├── SubscribeAIEntryExitRegionRecognitionData (Command)
│         │    ├── EnableAISpaceBackgroundLearning (Command)
│         │    ├── CreateZone (Command)
│         │    ├── UpdateZone (Command)
│         │    ├── RemoveZone (Command)
│         │    └── SetZones (Command)
│         ├── Radar Sensing Union (Function)
│         │    ├── ChildEndpointList (Trait)
│         │    ├── CurrentHumanCount (Trait)
│         │    └── MotionState (Trait)
│         └── Occupant Location (Function)
│              ├── MaxDetectionTargets (Trait)
│              ├── LocationInfo (Trait)
│              ├── SubscribeLocationData (Command)
│              └── SubscribeRemoveDetectionTarget (Command)
├── Endpoint 3 (业务 Endpoint)
│    └── Illuminance Sensor (Device Type)
│         └── Illuminance (Function)
│              └── CurrentIlluminance (Trait)
├── Endpoint 4 (业务 Endpoint, 子区域)
│    └── Occupancy Sensor (Device Type)
│         ├── Occupancy Sensing (Function)
│         │    ├── HoldTime (Trait)
│         │    ├── Occupancy (Trait)
│         │    └── OccupancySensorType (Trait)
│         ├── Radar Sensing Union (Function)
│         │    ├── ZoneID (Trait)
│         │    └── MotionState (Trait)
│         └── Occupant Location (Function)
│              └── LocationInfo (Trait)
└── Endpoint 5 (业务 Endpoint, 子区域)
     └── Occupancy Sensor (Device Type)
          ├── Occupancy Sensing (Function)
          │    ├── HoldTime (Trait)
          │    ├── Occupancy (Trait)
          │    └── OccupancySensorType (Trait)
          ├── Radar Sensing Union (Function)
          │    ├── ZoneID (Trait)
          │    └── MotionState (Trait)
          └── Occupant Location (Function)
               └── LocationInfo (Trait)

Device（设备）

Device 是一个物理智能设备，如网关、灯泡、门锁、传感器等。一个 Device 由一个或多个 Endpoint 组成。

Endpoint（端点）

Endpoint 是设备中的一个逻辑功能节点。每个 Endpoint 拥有一个 Endpoint ID（Uint16，取值 0 ~ 65535），并关联一个或多个 Device Type。

Aqara Spec 定义了三类 Endpoint：

Root Endpoint（Endpoint 0）：设备根节点，关联 Root Device Type，必须实现 Basic Information 和 Descriptor 功能。
Public Endpoint（通常为 Endpoint 1）：设备公共端点，关联 Public Device Type，承载 Identify、诊断、OTA 及各类生态协同等设备级通用 Function，供整个设备共享。
业务 Endpoint（Endpoint 2 及以上）：承载具体业务功能，关联对应的业务 Device Type（如 Occupancy Sensor、Illuminance Sensor）。同一 Device Type 可出现在多个 Endpoint 上（如上例 Endpoint 4、5 为 Endpoint 2 的子区域）。前端可见的业务 Endpoint 必须实现 Label、Endpoint Icon 功能，否则无法前端展示。

Device Type（设备类型）

Device Type 用于描述 Endpoint 的设备类型。每个 Device Type 由唯一的 Device Type ID（Uint16）标识。每个 Device Type 定义了该类型设备必须（M）或可选（O）实现的 Function 集合。一个 Endpoint 下不允许添加重复的 Function。

除业务 Device Type 外，Aqara Spec 定义了两个与特殊 Endpoint 对应的 Device Type：

Root：仅用于 Root Endpoint，必须实现 Basic Information 和 Descriptor。
Public：仅用于 Public Endpoint，必须实现 Identify，可选实现诊断、网络配网、OTA 及各类生态协同等通用 Function。

例如上例中业务 Endpoint 2 关联 Occupancy Sensor Device Type，实现 Occupancy Sensing、Radar Sensing Union 等 Function；设备级通用能力（如 Identify、Matter Commissioning）由 Public Endpoint（Endpoint 1）统一提供，不在各业务 Endpoint 重复实现。

完整的 Device Type 列表见设备类型。

Function（功能）

Function 描述设备的一个完整功能单元，由若干 Traits 和 Commands 组成。

完整的 Function 列表见功能代码。

Trait（功能点）

Trait 描述 Function 中的一个属性或状态，支持 Read、Write、Report 等操作。

完整的 Trait 列表见功能点代码。

Command（命令）

Command 描述 Function 中可执行的操作，由客户端向设备发送。

完整的 Command 列表见命令代码。

Parameter（参数）

Parameter 是 Trait 内部的数据字段。

Device（设备）​

Endpoint（端点）​

Device Type（设备类型）​

Function（功能）​

Trait（功能点）​

Command（命令）​

Parameter（参数）​