Device Resource Management (Trait)

For Aqara devices, endpoint, function, and trait are the three core hierarchical levels used to describe and operate smart device features.

• Endpoint: Represents a physical or logical port of the device. Each endpoint identifies a sub-unit of the device (such as an individual socket hole in an outlet) and is uniquely marked by endpointId.
• Function: Each endpoint can contain one or more functions, such as "switch control", "status information," etc. Each function is distinguished by the functionCode.
• Trait: Each function is further composed of multiple traits. A trait is the smallest operable unit that can be read, written, or subscribed to and corresponds to a specific property or operation (for example: "switch status", "current power value," etc.). Each trait is identified by the traitCode.

The following is an example using a double rocker switch "A" to illustrate these relationships:

Double Rocker Switch A
  ├─ Root (endpointId: 0)
  │    └─ Basic Information (functionCode: BasicInformation)
  │    │      └─ Firmware Version (traitCode: FirmwareRevision)
  │    │      └─ ...
  │    └─ ...
  ├─ Public (endpointId: 1)
  │    └─ Energy Control (functionCode: EnergyManagement)
  │    │      └─ Voltage Value (traitCode: CurrentVoltage)
  │    │      └─ ...
  │    └─ ...
  ├─ Switch (endpointId: 2)
  │    └─ Switch Function (functionCode: Output)
  │    │      └─ Switch State (traitCode: OnOff)
  └─ Switch (endpointId: 3)
       └─ Switch Function (functionCode: Output)
       │      └─ Switch State (traitCode: OnOff)

In actual development, you will frequently encounter fields such as type and trait in interface parameters and responses. For device types and trait codes corresponding to these fields, refer to the following documentation:

• Supported Device Types
• Supported Traits

Query Trait Values Of Matter Device By ID

• API intent: spec.query.specdevice.config
• Description: This API queries trait values of a matter device by its ID. A Matter device here refers to a device whose model prefix is aqara.matter.

Request Parameter Description

Request Example

{ 
    "intent" : "spec.query.specdevice.config", 
    "data":{ 
        "dids": ["matt.2990fb3413ed87c9b7370000", "matt.2990fb3413ed884726370000"] 
    }
}

Response Data Description

result.data is an array of objects. The table below details the data structure of each object in result.data, with all fields being subfields of result.data:

Response Example

{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": {
        "data": [
            {
                "types": [
                    "ContactSensor"
                ],
                "endpoints": [
                    {
                        "functions": [
                            {
                                "functionId": 128,
                                "traits": [
                                    {
                                        "traitId": 32901,
                                        "attribute": {
                                            "readable": true,
                                            "format": "Bool",
                                            "type": "BOOLEAN",
                                            "subscribable": true,
                                            "writable": false
                                        },
                                        "time": 1762399511357,
                                        "value": "1",
                                        "traitCode": "Reachable"
                                    }
                                ],
                                "functionCode": "BasicInformation"
                            },
                            {
                                ...
                            }
                        ],
                        "endpointId": 0,
                        "endpointTypes": [
                            "Root"
                        ]
                    },
                    {
                        ...
                    },
                ],
                "model": "aqara.matter.4447_8194",
                "deviceId": "matt.2990fb3413ed87c9b7370000"
            }
        ]
    }
}

Query Trait Values Of Non-Matter Devices By Models

• API intent: spec.query.qlinkmodel.config
• Description: This API queries the trait value by the model of a non-Matter device.

Request Parameter Description

Request Example

{
    "intent" : "spec.query.qlinkmodel.config",
    "data":{
        "models": ["lumi.motion.agl001","lumi.switch.aus002"]
    }  
}

Response Data Description

result.data is a Map<String, Object>, where the device model is used as the key, and the value is the configuration object for that device. The table below details the data structure of result.data, with all fields being subfields under result.data:

Response Example

{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": {
        "data": {
            "lumi.switch.aus002": {
                "types": [
                    "Switch",
                    "Button",
                    "OccupancySensor"
                ],
                "endpoints": [
                    {
                        "functions": [
                            {
                                "functionId": 128,
                                "traits": [
                                    {
                                        "traitId": 32901,
                                        "attribute": {
                                            "readable": true,
                                            "enums": [
                                                {
                                                    "value": "0",
                                                    "key": "Offline"
                                                }
                                            ],
                                            "format": "Bool",
                                            "type": "BOOLEAN",
                                            "subscribable": true,
                                            "writable": false
                                        },
                                        "traitCode": "Reachable"
                                    }
                                ],
                                "functionCode": "BasicInformation" 
                            },
                            {
                                ...
                            }
                        ],
                        "endpointId": 0,
                        "endpointTypes": [
                            "Root"
                        ]
                    },
                    {
                        ...
                    }
                ],
                "model": "lumi.switch.aus002"
            }
        }
    }        
}

Get Device Trait Values

• API intent: spec.query.trait
• Description: This API supports querying the current values of multiple traits in batch. A maximum of 50 traits can be queried per request; if more than 50 traits are provided, only the latest values of the first 50 traits will be returned.

Request Parameter Description

Request Example

{
    "intent": "spec.query.trait",
    "data": {
        "traits": [
            {
                "deviceId": "lumi1.54ef448a0b73",
                "endpointId": 0,
                "functionCode": "BasicInformation",
                "traitCode": "Reachable"
            },
            {
                "deviceId": "lumi1.54ef448a0b73",
                "endpointId": 0,
                "functionCode": "Descriptor",
                "traitCode": "EndpointArrayDynamic"
            },
            {
                ...
            }
        ]
    }
}

Response Data Description

result.data is an array of Objects. The following table details the data structure of each object in result.data, with all fields being subfields of result.data:

Response Example

{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": {
        "data": [
            {
                "functionCode": "BasicInformation",
                "endpointId": 0,
                "time": null,
                "deviceId": "lumi1.54ef448a0b73",
                "value": "1",
                "traitCode": "Reachable"
            },
            {
                "functionCode": "Descriptor",
                "endpointId": 0,
                "time": 1762417659743,
                "deviceId": "lumi1.54ef448a0b73",
                "value": "[0,1,2,3]",
                "traitCode": "EndpointArrayDynamic"
            },
            {
                ...
            }
        ]
    }
}

Control Devices

• API intent: spec.write.trait
• Description: This API is used to batch control devices by specifying a list of traits. A maximum of 10 devices can be controlled in a single request, and any number of traits can be issued to each device simultaneously. If the device count exceeds 10, only the first 50 trait control requests will be processed, and the excess will be ignored.

Request Parameter Description

Request Example

{
    "intent": "spec.write.trait",
    "data": {
        "traits": [
            {
                "deviceId": "lumi1.54ef448a0b73",
                "endpointId": 3,
                "functionCode": "Output",
                "traitCode": "OnOff",
                "value": "0"
            }
        ]
    }
}

Response Data Description

Response Example

result.data is an array of objects. The table below details the data structure of each object in result.data, with all fields being subfields of result.data:

{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": {
        "data": [
            {
                "functionCode": "Output",
                "endpointId": 3,
                "deviceId": "lumi1.54ef448a0b73",
                "value": "0",
                "traitCode": "OnOff",
                // 0 indicates a successful API call, while non-zero indicates a failed API call (this only reflects the API request itself, not whether the device was actually controlled)
                "code": 0
            }
        ]
    }
}

Subscribe and Unsubscribe to Trait Value Push

To subscribe or unsubscribe to device trait value updates, please refer to the relevant sections in the Message Push Interface (Trait) documentation:

• Subscribe to Trait Value
• Unsubscribe from Trait Value