设备功能接口（trait）

对于 Aqara 设备，endpoint（端点）、function（功能） 和 trait（功能点）是描述和操作智能设备功能的三个核心层级。

• 端点：代表设备的物理或逻辑端口，每个端点标识设备的一个子单元（如插座的某一个孔），用 endpointId 唯一标识。
• 功能：每个端点可包含一个或多个功能，例如“开关控制”、“状态信息”等。功能以 functionCode 区分。
• 功能点：每个功能进一步由多个功能点组成。功能点是可读、可写、可订阅的最小操作单元，对应具体的某个属性和操作，如“开关状态”、“当前功率值”等。功能点以 traitCode 区分。

以双键开关 A 为例，示意上述关系：

双键开关 A
  ├─ Root (endpointId: 0)
  │    └─ 基本信息 (functionCode: BasicInformation)
  │    │      └─ 固件版本（traitCode：FirmwareRevision）
  │    │      └─ ...
  │    └─ ...
  ├─ Public (endpointId: 1)
  │    └─ 电量控制 (functionCode: EnergyManagement)
  │    │      └─ 电压值（traitCode：CurrentVoltage）
  │    │      └─ ...
  │    └─ ...
  ├─ Switch (endpointId: 2)
  │    └─ 开关功能 (functionCode: Output)
  │    │      └─ 开关状态（traitCode：OnOff）
  └─ Switch (endpointId: 3)
       └─ 开关功能 (functionCode: Output)
       │      └─ 开关状态（traitCode：OnOff）

在实际业务开发时，您会经常在接口参数和返回中遇到 deviceType、trait 等字段。关于这些字段涉及的设备类型和功能点编码，可参考以下文档：

• 支持的设备类型
• 支持的功能点

根据 ID 查询 Matter 设备的功能

• 接口intent：spec.query.specdevice.config
• 接口描述：该接口通过 Matter 设备的 ID 查询其功能。Matter 设备，是指 model 前缀为 aqara.matter. 的设备。

请求参数说明

请求参数示例

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

响应参数说明

result.data 是一个 Object 数组。下表为 result.data 的数据结构详情，表中的各字段均为 result.data 的子结构：

功能点属性类型

响应数据示例

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

根据 model 查询非 Matter 设备的功能

• 接口intent：spec.query.qlinkmodel.config
• 接口描述：该接口通过非 Matter 设备的 model 查询其所有功能。

请求参数说明

请求参数示例

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

响应数据说明

result.data 是一个 Map<String, Object>，以设备的 model 作为 key，其 value 为该设备的配置对象。下表为 result.data 的数据结构详情，表中的各字段均为 result.data 的子结构：

响应数据示例

{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": {
        "data": {
            "lumi.switch.aus002": {
                "deviceTypesList": [
                    "Switch",
                    "Button",
                    "OccupancySensor"
                ],
                "endpoints": [
                    {
                        "functions": [
                            {
                                "functionId": 128,
                                "traits": [
                                    {
                                        "traitId": 32901,
                                        "parameter": {
                                            "readable": true,
                                            "type": "Bool",
                                            "subscribable": true,
                                            "writable": false
                                        },
                                        "traitCode": "Reachable"
                                    }
                                ],
                                "functionCode": "BasicInformation" 
                            },
                            {
                                ...
                            }
                        ],
                        "endpointId": 0,
                        "deviceType": "Root"
                    },
                    {
                        ...
                    }
                ],
                "model": "lumi.switch.aus002"
            }
        }
    }        
}

获取最新功能点值

• 接口intent：spec.query.trait
• 接口描述：本接口支持批量查询 trait 的当前值，单次最多支持 50 个 trait。如果传入的 trait 数量超过 50，仅返回前 50 个 trait 的最新值。

请求参数说明

请求参数示例

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

响应参数说明

result.data 是一个 Object 数组，下表为 result.data 的数据结构详情，表中的各字段均为 result.data 的子结构：

响应数据示例

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

控制设备

• 接口intent：spec.write.trait
• 接口描述：本接口用于通过指定功能点列表批量控制设备。单次最多可控制 10 台设备，对每台设备可同时下发任意数量的功能点。当设备数量超过 10 台时，仅处理前 50 个功能点的控制请求，超出部分将被忽略。

请求参数说明

请求参数示例

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

响应参数说明

响应数据示例

result.data 是一个 Object 数组，下表为 result.data 的数据结构详情，表中的各字段均为 result.data 的子结构：

{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": {
        "data": [
            {
                "functionCode": "Output",
                "endpointId": 3,
                "deviceId": "lumi1.54ef448a0b73",
                "value": false,
                "traitCode": "OnOff",
                //设备调用是否成功，0：成功，非0：不成功，这只代表接口调用成功，不代表设备控制成功
                "code": 0
            }
        ]
    }
}

订阅和取订设备功能值

如需订阅或取消订阅设备功能点值的推送，请参考消息推送接口（trait）文档中的相关说明：

• 订阅设备功能值
• 取消订阅设备功能值