Skip to main content

Core Concepts

The Aqara Spec data model uses a layered architecture, from top to bottom: Device(Device) → Endpoint(Endpoint) → Device Type(Device Type) → Function(Function) → Trait(Trait) / Command(Command).

A device has two special endpoints: Root Endpoint (Endpoint 0) and Public Endpoint (usually Endpoint 1). The Root Endpoint carries root device information; the Public Endpoint carries device-level common Functions shared by the whole device, so they are not duplicated on each business Endpoint.

The following example shows the structure of a multi-Endpoint occupancy sensor device, including Root Endpoint, Public Endpoint, and multiple business Endpoints:

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 (Business 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 (Business Endpoint)
│    └── Illuminance Sensor (Device Type)
│         └── Illuminance (Function)
│              └── CurrentIlluminance (Trait)
├── Endpoint 4 (Business Endpoint, sub-zone)
│    └── 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 (Business Endpoint, sub-zone)
     └── 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​

A Device is a physical smart device, such as a hub, light bulb, door lock, or sensor. A Device consists of one or more Endpoints.

Endpoint​

An Endpoint is a logical functional node within a device. Each Endpoint has an Endpoint ID (Uint16, range 0–65535) and is associated with one or more Device Types.

Aqara Spec defines three kinds of Endpoints:

  • Root Endpoint (Endpoint 0): the device root node, associated with the Root Device Type. It must implement Basic Information and Descriptor.
  • Public Endpoint (usually Endpoint 1): the device public endpoint, associated with the Public Device Type. It carries device-level common Functions such as Identify, diagnostics, OTA, and ecosystem coordination, shared by the whole device.
  • Business Endpoint (Endpoint 2 and above): carries concrete business capabilities and is associated with the corresponding business Device Type (for example, Occupancy Sensor or Illuminance Sensor). The same Device Type may appear on multiple Endpoints (in the example above, Endpoints 4 and 5 are sub-zones of Endpoint 2). A front-end-visible business Endpoint must implement Label and Endpoint Icon; otherwise it cannot be displayed in the UI.

Device Type​

Device Type describes the device type of an Endpoint. Each Device Type is identified by a unique Device Type ID (Uint16). Each Device Type defines the set of Functions that devices of that type must (M) or may optionally (O) implement. Duplicate Functions are not allowed under a single Endpoint.

In addition to business Device Types, Aqara Spec defines two Device Types that map to special Endpoints:

  • Root: used only for the Root Endpoint; must implement Basic Information and Descriptor.
  • Public: used only for the Public Endpoint; must implement Identify, and may optionally implement common Functions such as diagnostics, network commissioning, OTA, and ecosystem coordination.

For example, business Endpoint 2 above is associated with the Occupancy Sensor Device Type and implements Functions such as Occupancy Sensing and Radar Sensing Union. Device-level common capabilities (such as Identify and Matter Commissioning) are provided by the Public Endpoint (Endpoint 1) and are not duplicated on each business Endpoint.

See the full Device Type list in Device Types.

Function​

A Function describes a complete functional unit of a device and consists of Traits and Commands.

See the full Function list in Function Codes.

Trait​

A Trait describes an attribute or state within a Function and supports operations such as Read, Write, and Report.

See the full Trait list in Trait Codes.

Command​

A Command describes an executable operation within a Function and is sent from a client to the device.

See the full Command list in Command Codes.

Parameter​

A Parameter is a data field inside a Trait.