This appendix defines the Function, Trait, and Command in the Aqara Spec data model tag system. These definitions serve as the business semantic layer, where Function and Trait map to Object/Property of the Aqara data model, and Command maps to the Service of the Aqara data model business interaction protocol.
Aqara Spec defines the data model tag system for Aqara smart devices, used to describe what the device "can do". In this tag system, Function and Trait map to Object/Property of the Aqara data model, and Command maps to the Service of the Aqara data model business interaction protocol: Aqara Spec describes business semantics, while the data model and interaction protocol describe data structures and access methods respectively.
Data Model Architecture
The Aqara Spec data model adopts a layered architecture, from top to bottom: Device -> Endpoint -> Device Type -> Function -> Trait / Command.
There are two special types of Endpoint in a device: Root Endpoint (Endpoint 0) and Public Endpoint (usually Endpoint 1). The Root Endpoint carries device root information; the Public Endpoint carries device-level common Functions shared by the entire device, which are not implemented repeatedly on each business Endpoint.
The following uses a multi-Endpoint human presence sensor as an example to show the actual structure of the Root Endpoint, Public Endpoint, and multiple business Endpoints:
Device: "<Device ID>"
├── Endpoint 0 (Root Endpoint)
│ └── Device Type: Root (ID: 0x0000)
│ └── Basic Information (Function ID: 0x0080)
│ ├── DebugInfo (Trait ID: 0x4E29)
│ ├── BLEVersion (Trait ID: 0x4EE9)
│ ├── MCUVersion (Trait ID: 0x4EEB)
│ ├── FirmwareRevision (Trait ID: 0x8080)
│ ├── SerialNumber (Trait ID: 0x8081)
│ ├── VendorName (Trait ID: 0x8082)
│ ├── VendorID (Trait ID: 0x8083)
│ ├── ProductName (Trait ID: 0x8084)
│ ├── Reachable (Trait ID: 0x8085)
│ ├── FirmwareRevisionString (Trait ID: 0x8117)
│ └── ProductID (Trait ID: 0x8118)
├── Endpoint 1 (Public Endpoint)
│ └── Device Type: Public (ID: 0x0001)
│ ├── Identify (Function ID: 0x0083)
│ │ ├── IdentifyTime (Trait ID: 0x8094)
│ │ ├── IdentifyType (Trait ID: 0x8095)
│ │ └── Identify (Command ID: 0x8096)
│ ├── Matter Commissioning (Function ID: 0x00AD)
│ │ ├── MatterFabricsOperationState (Trait ID: 0x4FA0)
│ │ ├── ConnectedMatterFabrics (Trait ID: 0x8123)
│ │ ├── MatterCommissioningWindowStatus (Trait ID: 0x8124)
│ │ ├── MatterNodeID (Trait ID: 0x8142)
│ │ ├── OpenMatterCommissioningWindow (Command ID: 0x88B9)
│ │ └── RemoveMatterFabric (Command ID: 0x88BC)
│ ├── General Diagnostics (Function ID: 0x00B0)
│ │ ├── UpTime (Trait ID: 0x4E23)
│ │ ├── NetworkInterfaces (Trait ID: 0x4E2A)
│ │ ├── ActiveHardwareFaults (Trait ID: 0x813D)
│ │ ├── RebootCount (Trait ID: 0x8148)
│ │ └── RebootReason (Trait ID: 0x8149)
│ ├── Matter Node Information (Function ID: 0x00B3)
│ │ └── MatterNodeFirstEndpointID (Trait ID: 0x8143)
│ └── Thread Network Diagnostics (Function ID: 0x00B5)
│ ├── OverrunCount (Trait ID: 0x4E2C)
│ ├── PartitionID (Trait ID: 0x4E2D)
│ ├── TxTotalCount (Trait ID: 0x4E2E)
│ ├── TxUnicastCount (Trait ID: 0x4E2F)
│ ├── TxBroadcastCount (Trait ID: 0x4E30)
│ ├── RxTotalCount (Trait ID: 0x4E31)
│ ├── RxUnicastCount (Trait ID: 0x4E32)
│ ├── RxBroadcastCount (Trait ID: 0x4E33)
│ ├── NetworkFaultChange (Trait ID: 0x4E34)
│ ├── Channel (Trait ID: 0x814A)
│ ├── PanID (Trait ID: 0x814B)
│ ├── ExtendedPanID (Trait ID: 0x814C)
│ ├── NetworkName (Trait ID: 0x814D)
│ ├── RouteTable (Trait ID: 0x814E)
│ ├── RoutingRole (Trait ID: 0x814F)
│ ├── NeighborTable (Trait ID: 0x8150)
│ └── MeshLocalPrefix (Trait ID: 0x8151)
├── Endpoint 2 (Business Endpoint)
│ └── Device Type: Occupancy Sensor (ID: 0x0027)
│ ├── Occupancy Sensing (Function ID: 0x00A0)
│ │ ├── HoldTime (Trait ID: 0x4E72)
│ │ ├── Occupancy (Trait ID: 0x80E8)
│ │ └── OccupancySensorType (Trait ID: 0x80E9)
│ ├── General Configuration (Function ID: 0x00AF)
│ │ └── CurrentSensitivityLevel (Trait ID: 0x813B)
│ ├── Ambient Sensing Configuration (Function ID: 0x00E3)
│ │ ├── InstallMode (Trait ID: 0x4F13)
│ │ ├── SideInstall (Trait ID: 0x4F14)
│ │ ├── InstallHeightSetting (Trait ID: 0x4F15)
│ │ ├── InstallStatus (Trait ID: 0x4F16)
│ │ ├── InstallAngle (Trait ID: 0x4F17)
│ │ ├── MaxDetectionZones (Trait ID: 0x4F18)
│ │ ├── Zones (Trait ID: 0x4F19)
│ │ ├── EntryExitRegionBitmask (Trait ID: 0x4F1B)
│ │ ├── InterferenceRegionBitmask (Trait ID: 0x4F1C)
│ │ ├── EdgeRegionBitmask (Trait ID: 0x4F1D)
│ │ ├── EnableHumanCountDetection (Trait ID: 0x4F1F)
│ │ ├── EnableAIHighPrecisionRecognition (Trait ID: 0x4F23)
│ │ ├── EnableAIInterferenceSourceRecognition (Trait ID: 0x4F27)
│ │ ├── EnableAIAdaptiveSensitivity (Trait ID: 0x4F28)
│ │ ├── CoordinateReverseSetting (Trait ID: 0x4F29)
│ │ ├── DetectionDirectionSetting (Trait ID: 0x4F2A)
│ │ ├── AutoInterferenceSourceRecognition (Trait ID: 0x4F30)
│ │ ├── AutoEdgeRecognition (Trait ID: 0x4F31)
│ │ ├── AIEntryExitRegionRecognition (Trait ID: 0x4F32)
│ │ ├── ProximityDistanceLevel (Trait ID: 0x4F5A)
│ │ ├── InterferenceSourceRecognitionReportingTimeout (Trait ID: 0x4FA8)
│ │ ├── AISpaceBackgroundLearningReportingTimeout (Trait ID: 0x4FA9)
│ │ ├── AISpaceBackgroundLearningComplete (Trait ID: 0x4FAA)
│ │ ├── SubscribeAutoInterferenceSourceRecognitionData (Command ID: 0x9C78)
│ │ ├── SubscribeAutoEdgeRecognitionData (Command ID: 0x9C79)
│ │ ├── SubscribeAIEntryExitRegionRecognitionData (Command ID: 0x9C7A)
│ │ ├── EnableAISpaceBackgroundLearning (Command ID: 0x9C7B)
│ │ ├── CreateZone (Command ID: 0x9C7C)
│ │ ├── UpdateZone (Command ID: 0x9C7D)
│ │ ├── RemoveZone (Command ID: 0x9C7E)
│ │ └── SetZones (Command ID: 0x9D36)
│ ├── Radar Sensing Union (Function ID: 0x00E4)
│ │ ├── ChildEndpointList (Trait ID: 0x4F33)
│ │ ├── CurrentHumanCount (Trait ID: 0x4F35)
│ │ └── MotionState (Trait ID: 0x80EA)
│ └── Occupant Location (Function ID: 0x00E5)
│ ├── MaxDetectionTargets (Trait ID: 0x4F3E)
│ ├── LocationInfo (Trait ID: 0x4F46)
│ ├── SubscribeLocationData (Command ID: 0x9C7F)
│ └── SubscribeRemoveDetectionTarget (Command ID: 0x9C80)
├── Endpoint 3 (Business Endpoint)
│ └── Device Type: Illuminance Sensor (ID: 0x001A)
│ └── Illuminance (Function ID: 0x009A)
│ └── CurrentIlluminance (Trait ID: 0x80DD)
├── Endpoint 4 (Business Endpoint, Sub-area)
│ └── Device Type: Occupancy Sensor (ID: 0x0027)
│ ├── Occupancy Sensing (Function ID: 0x00A0)
│ │ ├── HoldTime (Trait ID: 0x4E72)
│ │ ├── Occupancy (Trait ID: 0x80E8)
│ │ └── OccupancySensorType (Trait ID: 0x80E9)
│ ├── Radar Sensing Union (Function ID: 0x00E4)
│ │ ├── ZoneID (Trait ID: 0x4F34)
│ │ └── MotionState (Trait ID: 0x80EA)
│ └── Occupant Location (Function ID: 0x00E5)
│ └── LocationInfo (Trait ID: 0x4F46)
└── Endpoint 5 (Business Endpoint, Sub-area)
└── Device Type: Occupancy Sensor (ID: 0x0027)
├── Occupancy Sensing (Function ID: 0x00A0)
│ ├── HoldTime (Trait ID: 0x4E72)
│ ├── Occupancy (Trait ID: 0x80E8)
│ └── OccupancySensorType (Trait ID: 0x80E9)
├── Radar Sensing Union (Function ID: 0x00E4)
│ ├── ZoneID (Trait ID: 0x4F34)
│ └── MotionState (Trait ID: 0x80EA)
└── Occupant Location (Function ID: 0x00E5)
└── LocationInfo (Trait ID: 0x4F46)
Core Concepts
Device
A Device is a physical smart device, such as a gateway, light bulb, door lock, sensor, etc. A Device consists of one or more Endpoints.
Endpoint
An Endpoint is a logical functional node in a device. Each Endpoint has an Endpoint ID (Uint16, ranging from 0 to 65535) and is associated with one or more Device Types.
Aqara Spec defines three types of Endpoint:
- Root Endpoint (Endpoint 0): device root node, associated with the Root Device Type, and must implement Basic Information and Descriptor functions.
- Public Endpoint (usually Endpoint 1): device public endpoint, associated with the Public Device Type, carrying device-level common Functions such as Identify, diagnostics, OTA, and various ecosystem collaboration, shared by the entire device.
- Business Endpoint (Endpoint 2 and above): carries specific business functions and is associated with the corresponding business Device Type (such as Occupancy Sensor, Illuminance Sensor). The same Device Type can appear on multiple Endpoints (e.g., Endpoints 4 and 5 in the above example are sub-areas of Endpoint 2). Front-end visible business Endpoints must implement the Label and Endpoint Icon functions, otherwise they cannot be displayed on the front end.
Device Type
A 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 this type must (M) or may (O) implement. Duplicate Functions are not allowed under one Endpoint.
The new allocation range for business Aqara standard Device Type IDs is 1 ~ 10000. The Root Device Type ID 0 is a special reserved value and is not part of the new allocation range for business Device Types.
In addition to business Device Types, Aqara Spec defines two Device Types corresponding to special Endpoints:
- Root (ID: 0x0000): used only for the Root Endpoint, must implement Basic Information and Descriptor.
- Public (ID: 0x0001): used only for the Public Endpoint, must implement Identify, and may optionally implement common Functions such as diagnostics, network provisioning, OTA, and various ecosystem collaboration.
For example, in the above example, business Endpoint 2 is associated with the Occupancy Sensor (ID: 0x0027) Device Type, implementing Functions such as Occupancy Sensing and Radar Sensing Union; device-level common capabilities (such as Identify and Matter Commissioning) are uniformly provided by the Public Endpoint (Endpoint 1) and are not implemented repeatedly on each business Endpoint.
For the complete Device Type ID encoding and Function requirements, see Device Type definitions.
Function
A Function describes a complete functional unit of a device, consisting of several Traits and Commands. Each Function is identified by a unique Function ID (Uint16).
The new allocation range for Aqara standard Function IDs is 0 ~ 19999; the private Function ID range reserved for user customization is 64001 ~ 65534.
Trait
A Trait describes an attribute or state in a Function, supporting operations such as Read, Write, and Report. Each Trait is identified by a unique Trait ID (Uint16).
The new allocation range for Aqara standard Trait IDs is 1 ~ 30000; the private Trait ID range reserved for user customization is 60000 ~ 64000.
Command
A Command describes an executable operation in a Function, sent from the client to the device. Each Command is identified by a unique Command ID (Uint16).
The new allocation range for Aqara standard Command IDs is 40001 ~ 50000; the private Command ID range reserved for user customization is 64001 ~ 65534.
Parameter
A Parameter is a data field inside a Trait, identified by a Parameter ID (Uint16).
ID Numbering System
ID Allocation Range Overview
| Category | Standard Range | Private Range | Format |
|---|
| Device Type ID | 1 ~ 10000 (business types; 0 is the Root special reserved value) | 64001 ~ 65534 | Uint16 |
| Function ID | 0 ~ 19999 | 64001 ~ 65534 | Uint16 |
| Trait ID | 1 ~ 30000 | 60000 ~ 64000 | Uint16 |
| Command ID | 40001 ~ 50000 | 64001 ~ 65534 | Uint16 |
| Parameter ID | 0x0000 ~ 0xFFFF | - | Uint16 |
The standard and private ranges above constrain new ID allocation so that user-defined IDs do not collide with Aqara standard ID ranges. Values outside these ranges are not part of the corresponding category's standard or private new-allocation ranges. Updating the rules does not change IDs that are already defined or already in use: existing IDs SHOULD be kept as-is, and MUST NOT be renumbered or revalidated solely to fit the new ranges even if they fall outside the current new-allocation ranges. Except for the Root special reserved Device Type ID value 0, newly allocated Device Type IDs SHOULD use the business standard range or the private range above.
Trait Parameter Field Description
Parameter ID uses a 16-bit integer identifier, with a valid range of 0x0001 ~ 0xFFFE (1 ~ 65534). 0x0000 and 0xFFFF are reserved and unavailable.
Standard Trait Parameter ID
| Parameter ID | Name | BACnet Property | Default Access | Description |
|---|
| 0x0001 | Present Value | PROP_PRESENT_VALUE | - | Current value, indicating the real-time state of the Trait; the data type is defined by the Trait, and may be an integer, float, boolean, enumeration, string, or composite data type. For numeric values, Minimum Value <= Present Value <= Maximum Value MUST hold, and step and other constraints MUST be satisfied. |
| 0x0002 | Maximum Value | PROP_MAX_PRES_VALUE | RV | Maximum allowed/representable value of Present Value; the data type is consistent with the numeric Present Value, supporting integers and float, and MUST NOT be less than Minimum Value. Together with Minimum Value it describes the numeric range, not an alarm threshold. |
| 0x0003 | Minimum Value | PROP_MIN_PRES_VALUE | RV | Minimum allowed/representable value of Present Value; the data type is consistent with the numeric Present Value, supporting integers and float, and MUST NOT be greater than Maximum Value. Together with Maximum Value it describes the numeric range, not an alarm threshold. |
| 0x0004 | Unit | PROP_UNITS | RV | Engineering unit; the data type and the valid unit codes are specified by the unit definition of the corresponding Trait. Numeric values and related thresholds SHOULD use compatible units. |
| 0x0005 | Step Value | PROP_STEP_VALUE | RV | Numeric step value; the data type is consistent with Present Value, supporting integers and float, and MUST be greater than 0. It describes the step granularity of valid numeric values. |
| 0x0006 | Supported Value | PROP_SUPPORTED_VALUES | RV | Supported value list (Array/List); the element data type MUST be consistent with Present Value, and each element SHOULD satisfy the valid-value constraints of the Trait. |
| 0x0007 | Default Value | PROP_RELINQUISH_DEFAULT | RV | Default value (relinquish default); readable and reportable by default, not writable (Access is RV). The data type is consistent with Present Value, supporting integers, float, and other data types defined by the Trait; it MUST satisfy the range, step, supported-value list, and other applicable constraints of Present Value. The specific timing of adoption is defined by the Trait. |
| 0x0008 | High Limit | PROP_HIGH_LIMIT | RVW | High-side monitoring threshold; the data type is consistent with the numeric Present Value, supporting integers and float. Minimum Value <= High Limit <= Maximum Value and High Limit > Low Limit are required. It does not define the Present Value span. |
| 0x0009 | Low Limit | PROP_LOW_LIMIT | RVW | Low-side monitoring threshold; the data type is consistent with the numeric Present Value, supporting integers and float. Minimum Value <= Low Limit <= Maximum Value and Low Limit < High Limit are required. It does not define the Present Value span. |
| 0x000A | COV Increment | PROP_COV_INCREMENT | RVW | Change-reporting threshold, applicable to Traits whose Present Value is float; the data type is float, MUST be greater than 0, and the unit is consistent with Present Value. When the absolute difference between the current value and the baseline value of the last COV notification reaches or exceeds this threshold, a notification is triggered, suppressing frequent reports caused by minor fluctuations. |
| 0x000B | Maximum Actual Value | PROP_MAX_ACTUAL_VALUE | RVW | Upper endpoint calibration value of the actual quantity corresponding to Present Value; readable, writable, and reportable (Access is RVW); the data type is float, and integer data types are not supported. Minimum Value <= Maximum Actual Value <= Maximum Value and Maximum Actual Value > Minimum Actual Value are required; the mapping is defined by the Trait. |
| 0x000C | Minimum Actual Value | PROP_MIN_ACTUAL_VALUE | RVW | Lower endpoint calibration value of the actual quantity corresponding to Present Value; readable, writable, and reportable (Access is RVW); the data type is float, and integer data types are not supported. Minimum Value <= Minimum Actual Value <= Maximum Value and Minimum Actual Value < Maximum Actual Value are required; the mapping is defined by the Trait. |
| 0x000D | Is Null | PROP_IS_NULL | RV | Boolean with values true/false; true indicates that Present Value currently has no valid data or is uninitialized, and its current payload SHOULD NOT be used as a valid business value. |
| 0x000E | Extended Supported Values | PROP_EXTENDED_SUPPORTED_VALUES | RV | Extended supported value list (List[Struct]); the structure fields, element constraints, and list length are defined by the corresponding Trait. |
| 0x000F | Max Item Num | - | RV | Maximum number of elements allowed when Present Value is Array/List; the data type is uint32, ranging from 0 to 4294967295. The number of list elements MUST NOT exceed this value. |
| 0x0010 | Counter Generation | - | RV | Optional read-only, reportable Parameter of the Trait; the data type is uint32, ranging from 0 to 4294967295, used to identify the generation of a cumulative counter. MUST be provided when the implementation cannot guarantee continuous logical cumulative values and requires accurate difference calculation. |
The default read/write access in this table uses full Access flags: RV means readable and reportable, and RVW means readable, writable, and reportable. All readable Parameters support reporting, so the default access does not use standalone R or RW flags. Parameters marked only R or RW in specific Trait parameter tables also follow this reporting-support rule; reportable means the capability to report exists, and does not mean a notification MUST be sent on every read or when the value is unchanged. The specific reporting timing follows the corresponding Trait and interaction protocol definitions.
Present Value has no default read/write access; it follows the Access definition in the specific Trait parameter table. When it is readable, it is also reportable. Data types, read/write access, and constraints explicitly defined by a specific Trait take precedence over the generic default conventions; this table neither automatically extends the write access of existing Traits nor requires all Traits to implement every Parameter.
Frontends determine the read, write, and reporting capabilities of Parameters based on the access descriptions in this table by default. If the actual access of a device Parameter differs from the default access in this table, the device SHALL report the difference, or clearly record it in a pre-configurable data table accessible to the frontend. The difference information SHALL be able to locate the applicable device and its Function, Trait, and Parameter, and SHALL clearly state the actual Access of that Parameter so that the frontend can identify and apply it.
Frontends SHALL prefer explicit difference information applicable to the target device and the target Parameter; when no applicable difference information is provided, the default access in this table applies. Present Value access is still determined by the actual definition of the specific Trait and is not derived from the default access in this table. The above access information is used for frontend capability display and interaction control, and does not replace the device-side validation of actual access permissions.
The range constraints in this table use Minimum Value <= parameter value <= Maximum Value, including both boundary values. When boundary parameters are not explicitly provided, the valid range and data type boundaries declared by the corresponding Trait apply. The magnitude relationship between a pair of upper and lower limit parameters is validated only when both are implemented together. For writable Parameters, the written value and parameter combinations MUST still satisfy the applicable constraints, and MUST NOT invalidate the upper/lower limit relationship by writing.
Numeric Boundary Parameters
Minimum Value and Maximum Value
Minimum Value (PROP_MIN_PRES_VALUE) and Maximum Value (PROP_MAX_PRES_VALUE) describe the lower and upper bounds of the numeric range of Present Value. Reading these two parameters reveals the valid numeric range declared by the Trait. When writing Present Value, clients SHOULD constrain the target value to this range while also obeying the Trait's own data type, step value, enumeration values, and other constraints. Devices SHOULD also handle out-of-range inputs according to their Trait definitions, and MUST NOT treat these two boundaries as alarm thresholds.
For example, if a temperature Trait has Minimum Value of -50, Maximum Value of 100, and Unit of degrees Celsius, it declares a numeric range of -50°C to 100°C. Clients may use this range to validate user input or to display the adjustable range. If the value is a read-only sensor reading, these boundaries describe the Trait's range and do not imply that clients can write the value.
These two parameters describe the protocol-level numeric range of Present Value; they are not necessarily identical to the sensor's physical measurement capability, the device's alarm range, or the controller's safety range. Whether they exist, whether they are readable, and their concrete constraints are defined by the corresponding Trait parameter table; do not assume every Trait defines both parameters.
Step Value and Default Value
Step Value uses the same data type as the numeric Present Value, supporting both integer steps (for example, 1) and float steps (for example, 0.1). The step value MUST be greater than 0; when the Trait uses Minimum Value as the step start, valid values are determined by Minimum Value + n × Step Value, where n is a non-negative integer, and the result MUST NOT exceed Maximum Value. Floating-point comparisons SHOULD consider the representation precision of the data type and MUST NOT rely on a floating-point remainder being exactly zero to judge step validity.
Default Value uses the same data type as Present Value and obeys the same valid-value constraints. Its data type is not limited to integers, and it does not mean the value can be silently returned when the current value cannot be read. Whether the default value is adopted when restoring default settings, releasing control, or in other circumstances SHOULD be defined by the corresponding Trait.
COV Increment Parameters
COV Increment references the change-notification semantics of BACnet COV_Increment and is used for change-reporting filtering of float-type Present Value. Let Vref be the baseline value at the last notification and V the current valid value; when abs(V - Vref) >= COV Increment, the COV notification condition for the current value change is satisfied. After a notification is triggered, the baseline is updated to the value of this notification. The comparison baseline is not the previous sample value, so accumulated offsets from multiple small changes may still trigger a notification.
For example, with COV Increment = 0.5 and a baseline of 20.0, a current value of 20.2 does not trigger a change notification, while continuing to change to 20.5 or 19.5 satisfies the notification condition. This Parameter is not a sampling period, a periodic reporting interval, or an alarm deadband, and it does not change the read precision or numeric range of Present Value.
This specification requires COV Increment to be a finite floating-point number greater than 0. The initial notification on first subscription, subscription validity, other state changes, and periodic notifications are still handled according to the corresponding interaction protocol and Trait definitions and MUST NOT be blocked by this change threshold. Defining this Parameter alone does not mean a subscription is established or a notification will necessarily be sent; this section only borrows the increment semantics of BACnet and does not directly introduce its full subscription mechanism.
Monitoring Threshold Parameters
Low Limit and High Limit
Low Limit (PROP_LOW_LIMIT) and High Limit (PROP_HIGH_LIMIT) represent the low-side and high-side monitoring thresholds, for scenarios where the object defines corresponding monitoring or alarm semantics. They answer "at what operating value should a low-side or high-side anomaly be considered", not "what numeric values this Trait can represent". Thresholds are often configurable for site operating requirements, but whether they can actually be configured depends on the parameter's access permissions and the corresponding Trait definition.
For example, chilled-water temperature monitoring may set Low Limit to 5°C and High Limit to 35°C: when the current value is below the low limit it may be judged as a low-side limit violation, and when above the high limit as a high-side limit violation. Exact comparison rules (for example, whether equality to the threshold counts as a violation) SHOULD be defined by the corresponding object or alarm mechanism.
Merely defining or reading Low Limit and High Limit does not automatically mean that the device will generate alarms or events, or proactively report them. To implement complete alarm behavior, the object must also support the relevant mechanisms and handle factors such as enabling conditions, duration/delay, deadband, event state, and notification methods according to their definitions. Clients MUST NOT infer that alarms are enabled or that alarm notifications will necessarily be sent solely from the presence of threshold parameters. Thresholds MUST use the same data type as the monitored Present Value and compatible units, and their values MUST satisfy Minimum Value <= Low Limit < High Limit <= Maximum Value. Thresholds may lie outside the normal operating range for the application, but MUST NOT exceed the declared numeric range or be used as substitutes for Minimum Value or Maximum Value.
Actual Quantity Calibration Parameters
Minimum Actual Value and Maximum Actual Value
Minimum Actual Value (PROP_MIN_ACTUAL_VALUE) and Maximum Actual Value (PROP_MAX_ACTUAL_VALUE) describe the actual-quantity endpoints corresponding to the two ends of the Present Value range, and may be used to interpret or convert between device numeric values and actual physical quantities. Together with Unit, they help clients understand the meaning of the actual quantity; for example, the actual quantity's unit may be lumens, volts, or another engineering unit. Which actual quantity is represented, which Present Value the endpoints correspond to, whether the mapping is linear, and whether it is used for output mapping MUST be stated by the corresponding Trait or object definition and MUST NOT be inferred from parameter names alone.
For example, a dimming object's Present Value may represent a dimming control interval of 0% to 100%, while the brightness the device can actually reach is 20% to 80% of rated brightness; the object defines a linear mapping between these interval endpoints. In that case Minimum Actual Value is 20% brightness and Maximum Actual Value is 80% brightness: control value 0% maps to actual brightness 20%, control value 100% maps to actual brightness 80%, and control value 50% maps to 20% + (80% - 20%) × 50% = 50% brightness. Here the two Actual Value percentages are actual output relative to rated brightness, while the control-value percentage is the position of Present Value in the control interval; they have different meanings. For a general linear endpoint mapping, use proportional interpolation between the Present Value endpoints defined by the object; if the object specifies a nonlinear mapping, or Present Value is not a percentage, follow that object's mapping rules and do not apply this example directly.
This parameter pair explains the correspondence between numeric endpoints and actual quantities. It is not the protocol-allowed range of Present Value (described by Minimum Value / Maximum Value), nor the operating alarm thresholds (described by Low Limit / High Limit). For example, a dimmable luminaire's Present Value control range may be 0% to 100%, while the corresponding actual brightness range is 20% to 80% of rated brightness.
Both Actual Value parameters use the float data type; integer data types are not supported, and their data type is not required to match that of Present Value. Their values MUST satisfy Minimum Value <= Minimum Actual Value < Maximum Actual Value <= Maximum Value. The corresponding Trait MUST still explicitly define the unit and mapping of the actual quantity and ensure that the endpoint values can be represented within the declared range.
Distinguishing the Three Parameter Groups
- Minimum Value / Maximum Value: validate or understand the protocol-level numeric bounds of
Present Value—"how far is this value allowed/representable?"
- Low Limit / High Limit: judge whether an operating value has reached a monitoring threshold—"at what operating level is a low-side/high-side limit violation?"
- Minimum Actual Value / Maximum Actual Value: where the object definition supports it, explain the correspondence between
Present Value and actual physical-quantity endpoints—"how much actual quantity does this numeric endpoint correspond to?"
The three groups are not interchangeable, and a Trait is not guaranteed to define all of them. Implementations and clients SHOULD first consult the specific Trait's parameter table, data types, units, access permissions, and constraints, then interpret and use them according to that Trait definition; linear interpolation for actual-quantity conversion is appropriate only when the object explicitly defines a linear mapping.
Permission Flags
Permission Types
| Flag | Description |
|---|
| Read | Client can read this parameter |
| Write | Client can write this parameter |
| Report | Actively report this parameter when the device changes |
| Configured | Device reports during configuration phase |
Mandatory Flags
- M (Mandatory): device must implement
- O (Optional): device may implement optionally
Function List Overview
The following summarizes all Function definitions covered in this appendix. See the corresponding sections for the Trait, Command, and data types of each Function.
Function Index
This section summarizes all Function definitions in Aqara Spec. See the corresponding sections for the Trait, Command, and data types of each Function.
| Function ID | Code | Description |
|---|
| 0x0001 | Binding | Indicates the persistent binding relationship between an endpoint and one or more other local or remote Endpoints. |
| 0x0009 | CO | Provides carbon monoxide concentration monitoring and alarm capabilities, used to detect carbon monoxide leaks in the environment and alert in time. |
| 0x000A | WaterFreezeDetector | Used to detect the risk of freezing in pipes or the environment, and report water freezing related events when the threshold is reached. |
| 0x000B | RainSensor | Used to detect rainfall status, reporting whether it is raining and related rainfall information. |
| 0x000C | OnOffSensor | Used to detect binary switch input status, reporting discrete states such as on/off or triggered/not triggered. |
| 0x0080 | BasicInformation | Provides basic device information, including vendor, product model, firmware version, serial number, online status and other basic attributes. |
| 0x0081 | Descriptor | Describes the device endpoint composition and capability structure, including endpoint list, device types, Server/Client clusters, etc. |
| 0x0082 | EndpointLabel | Manages endpoint visibility and display information, such as name, room, icon, tags, etc., for front-end display and organization. |
| 0x0083 | Identify | Provides device identification capability, helping users locate physical devices through LED blinking, sound and other methods. |
| 0x0084 | Output | Provides switch output control capability, supporting reading and controlling the on/off state of the load. |
| 0x0085 | LevelControl | Provides brightness or level adjustment capability, supporting setting, reading current brightness/level, and gradual control. |
| 0x0086 | ColorControl | Provides color control capability, including adjusting light color through color temperature, HSV, XY color space and other methods. |
| 0x0087 | Button | Describes event reporting of button-type input devices, including single click, long press, multi-click and other action recognition. |
| 0x0088 | Camera | Manages camera basic capabilities, including device status, mode switching, image encryption and cloud-related capabilities. |
| 0x0089 | WindowCovering | Provides lift, tilt, position control and status feedback for shading devices such as curtains and blinds. |
| 0x008A | Lifter | Provides stroke control for lifting devices, supporting setting target position, stopping and status query. |
| 0x008B | IRControl | Provides infrared emission control capability, used to control traditional infrared appliances such as air conditioners and TVs. |
| 0x008C | EnergyManagement | Manages device battery level and energy information, including battery percentage, power consumption statistics and low battery alarm. |
| 0x008D | HeaterCooler | Provides cooling/heating control capability, including target temperature, operation mode, fan speed and other HVAC parameters. |
| 0x008E | FanControl | Provides fan speed and mode control, supporting gear adjustment and operation status reading. |
| 0x008F | Temperature | Measures and reports ambient temperature, providing attributes such as current temperature value and valid range. |
| 0x0090 | RelativeHumidity | Measures and reports ambient relative humidity, providing attributes such as current humidity value and valid range. |
| 0x0091 | MediaPlayback | Provides media playback control capability, including play, pause, track switching, volume and playback state management. |
| 0x0092 | Speaker | Describes device speaker output capability, including text-to-speech broadcast, volume control, mute and other audio output functions. |
| 0x0093 | PowerSource | Describes device power source and battery status, including battery level, charging status, battery type and other information. |
| 0x0094 | DoorLock | Provides smart door lock core capabilities, including lock status, user/credential management, lock/unlock and alarm events. |
| 0x0095 | Sweeper | Provides basic sweeping robot control, including starting cleaning, pausing, returning to dock and status feedback. |
| 0x0096 | AirQuality | Monitors and reports air quality indicators, such as AQI or comprehensive air quality level. |
| 0x0097 | Pressure | Measures and reports atmospheric pressure or system pressure value. |
| 0x0098 | ParticulateMatter | Monitors and reports particulate matter concentration (such as PM2.5, PM10). |
| 0x0099 | CO2 | Measures and reports carbon dioxide concentration in the environment. |
| 0x009A | Illuminance | Measures and reports ambient illuminance (lux). |
| 0x009B | Contact | Detects binary states such as contact/door magnetic, reporting open or closed state and optional angle information. |
| 0x009C | Smoke | Detects smoke and reports alarm events, supporting related configurations such as sensitivity, self-test and mute. |
| 0x009D | Gas | Detects combustible gas or harmful gas leaks and reports alarm events. |
| 0x009E | Sleep | Monitors sleep-related states, reporting indicators such as sleep stage, duration or quality. |
| 0x009F | WaterLeak | Detects water immersion events and reports alarm in time when water leakage is detected. |
| 0x00A0 | OccupancySensing | Detects whether people are present in the space, reporting occupancy/idle state and parameters such as hold time. |
| 0x00A1 | Location | Provides location information reporting and query capability for devices or targets. |
| 0x00A2 | Knob | Describes rotation angle, press and combined action events of knob-type input devices. |
| 0x00A3 | Cube | Describes gesture recognition of the cube controller, including actions such as flip, rotate, shake and face recognition. |
| 0x00A4 | Vibration | Detects vibration or motion changes, reporting events such as movement, tilt and fall. |
| 0x00A5 | Modes | Provides device multi-mode management capability, supporting switching and reading the current operation mode. |
| 0x00A6 | PetFeeder | Provides pet feeding control capability, including food amount, feeding schedule and remaining quantity status. |
| 0x00A7 | BridgeConfiguration | Manages gateway bridging configuration, describing sub-device access, bridging capability and network topology related information. |
| 0x00A8 | AttitudeDetection | Detects device posture or tilt angle changes, reporting abnormal posture or angle information. |
| 0x00A9 | Group | Manages device group configuration, maintaining node list within the group and group-level control capabilities. |
| 0x00AA | Doorbell | Provides doorbell related capabilities, including call event reporting and linkage with indoor chimes/relays. |
| 0x00AB | NetworkCommissioning | Provides network provisioning capability, supporting scanning, connecting and configuring networks such as Wi-Fi and Thread. |
| 0x00AC | EcosystemInformation | Describes ecosystem platform information that the device is connected to, such as binding status of HomeKit, Matter Fabric, etc. |
| 0x00AD | MatterCommissioning | Provides Matter onboarding and Fabric management capability, including provisioning window, Fabric list and node identification. |
| 0x00AE | IndicationLight | Manages device indicator light behavior, including status indication, brightness, color and blinking modes. |
| 0x00AF | GeneralConfiguration | Provides common device configuration items, such as sensitivity, delay, default parameters and other device-level settings. |
| 0x00B0 | GeneralDiagnostics | Provides common diagnostic information, including running time, restart count, network interfaces and hardware faults. |
| 0x00B1 | PanTilt | Provides Pan/Tilt/Zoom control capability, including presets, calibration and relative/absolute movement. |
| 0x00B2 | BridgedConfiguration | Describes configuration information of bridged sub-devices, used in Matter/Zigbee bridging scenarios. |
| 0x00B3 | MatterNodeInformation | Provides Matter node related information, such as the first Endpoint ID and node topology auxiliary information. |
| 0x00B5 | ThreadNetworkDiagnostics | Provides Thread network diagnostic metrics, including channel, PAN ID, neighbor table, routing role and transmission/reception statistics. |
| 0x00B6 | GarageDoorOpener | Provides garage door control and status feedback, including open/close/stop and position status. |
| 0x00B7 | MatterBridgeCommissioning | Manages the capability of the Matter Bridge to share bridged devices with third-party Matter ecosystems. |
| 0x00B8 | MARSConfiguration | Provides smart load (MARS) related configuration, used for load identification and smart power distribution management. |
| 0x00B9 | CustomizedConfiguration | Provides read/write capability for vendor or user custom extension configuration items. |
| 0x00BA | FreshAirControl | Provides fresh air system control capability, supporting introducing outdoor air and adjusting air volume, modes, etc. |
| 0x00BB | ScreenDisplay | Manages screen display related hardware properties, such as resolution, brightness, backlight and display status. |
| 0x00BC | ValveControl | Provides automatic or manual valve control capability, used to precisely adjust water/gas flow. |
| 0x00BD | FilterMonitoring | Continuously monitors the usage status and remaining life of various filter elements (such as HEPA, activated carbon). |
| 0x00BE | OperationalState | Describes the current running state of the device, such as idle, running, paused, fault, etc. |
| 0x00BF | Flow | Measures and reports the flow rate of liquid or gas. |
| 0x00C0 | Mode | Provides device characteristic mode interface, supporting switching between multiple predefined modes. |
| 0x00C1 | VacuumOperationalState | Describes the current running state of the sweeping robot, such as cleaning, returning to dock, charging, etc. |
| 0x00C2 | RefrigeratorState | Describes refrigerator running state, including idle, cooling, defrosting, fault, etc. |
| 0x00C3 | EVSE | Provides electric vehicle supply equipment (EVSE) control capability, including charging start/stop, current limit and charging status. |
| 0x00C4 | VacuumRunMode | Controls sweeping robot operation modes, such as auto, edge, spot, etc. |
| 0x00C5 | VacuumCleanMode | Controls sweeping robot cleaning modes, such as standard, strong, quiet, etc. |
| 0x00C6 | TemperatureControl | Provides temperature setting and adjustment capability, used for target temperature control of thermostat devices. |
| 0x00C7 | MediaInput | Describes media input source management and switching, supporting selecting the current playback source and input list. |
| 0x00C8 | HEPAFilterMonitoring | Monitors HEPA filter usage, remaining life and replacement reminders. |
| 0x00C9 | ActivatedCarbonFilterMonitoring | Monitors activated carbon filter usage, remaining life and replacement reminders. |
| 0x00CA | ThreadBorderRouter | Manages Thread border routers and the operation and configuration of the Thread networks they host. |
| 0x00CB | ThemePack | Manages device theme package resources, including theme download, switching and version information. |
| 0x00CC | WiFiNetworkDiagnostics | Provides standardized Wi-Fi network diagnostic metrics, assisting in troubleshooting connection quality and link status. |
| 0x00CD | ZigbeeNetworkDiagnostics | Provides Zigbee network diagnostic capability, including channel, PAN, neighbors and routing information. |
| 0x0125 | ZigbeeSubscribe | Provides Zigbee subscription capability, used to record subscribable device resources, capability scope and subscription record management. |
| 0x00CE | AnalogInputObject | Collects continuously changing analog input in a read-only manner (such as voltage and temperature analog signals). |
| 0x00CF | AnalogOutputObject | Provides writable continuous analog output control signals. |
| 0x00D0 | BinaryInputObject | Collects binary state inputs, such as door magnetic, switch and other true/false or active/inactive quantities. |
| 0x00D1 | BinaryOutputObject | Drives binary actuator outputs, such as relays, contactors, solenoid valves or alarms. |
| 0x00D2 | MultiStateInputObject | Collects multi-state discrete inputs, representing one of N states. |
| 0x00D3 | MultiStateOutputObject | Outputs multi-state discrete control commands, such as HVAC mode or light scene switching. |
| 0x00D4 | CharacterStringValueObject | Defines data objects represented in string form and their externally visible characteristics. |
| 0x00D5 | ScreenUserInterface | Manages panel-side user interface configuration, including page layout, cards, themes and display data. |
| 0x00D6 | DeviceAnomalyMonitoring | Continuously monitors key safety indicators such as device temperature, load, current and voltage, and reports alarms to support protection strategies when anomalies such as over-temperature, overload, overcurrent or undervoltage occur. |
| 0x00D7 | OTA | Manages the device firmware upgrade process, including download, installation scheduling and upgrade progress and result reporting. |
| 0x00D8 | HumanRecognition | Uses algorithms such as vision to detect human-shaped targets in the image in real time, distinguishing humans from other objects and reporting events. |
| 0x00D9 | SoundDetection | Collects ambient sounds through microphones, recognizes specific sound types (such as glass breaking, baby crying) and raises alarms. |
| 0x00DA | PetRecognition | Identifies pet individuals such as cats and dogs in the image, reporting pet appearance or related recognition events. |
| 0x00DB | FaceRecognition | Collects facial features and compares them with the local library, reporting face recognition results and matching information. |
| 0x00DC | GestureRecognition | Analyzes gesture actions in real time and converts predefined gestures into control commands. |
| 0x00DD | VehicleDetection | Detects vehicle appearance in the monitored area, reporting vehicle presence events for security or automation use. |
| 0x00DE | FlameDetection | Detects visible flames through image or sensor algorithms, reporting fire events immediately for early warning. |
| 0x00DF | PackageRecognition | Automatically recognizes packages in the image, sending reminders and recording events upon delivery or pickup. |
| 0x00E0 | HumanPresence | Detects human presence in the space, supporting advanced perception capabilities such as people counting, trajectory and identity association. |
| 0x00E1 | HeartMonitoring | Uses sensors to continuously or periodically measure the user's heart rate, recording and analyzing heart health related data. |
| 0x00E2 | BreathingMonitoring | Uses sensors to continuously or periodically measure the user's respiratory rate and patterns, supporting health monitoring. |
| 0x00E3 | AmbientSensingConfiguration | Provides environmental sensing configuration capability, including area management, installation mode, detection switch and AI area recognition. |
| 0x00E4 | RadarSensingUnion | Aggregates radar sensing capabilities, including joint data such as sub-endpoint list, people counting and motion status. |
| 0x00E5 | OccupantLocation | Provides location, activity state and posture information of presence targets, supporting location data subscription and target management. |
| 0x00E6 | MatterCoordination | Centrally manages Matter protocol related collaboration operations, including onboarding, binding, data synchronization and certificate management. |
| 0x00E7 | OTACoordination | Manages OTA firmware upgrade collaboration process, including task issuance, progress reporting, result feedback and version query. |
| 0x00E8 | StudioCoordination | Manages the integration of gateway with the Aqara Studio development environment, including account authentication, project backup and device synchronization. |
| 0x00E9 | CameraCoordination | Handles complex camera business logic, including WebRTC calls, pan/tilt control, recognition data synchronization and extended events. |
| 0x00EA | SecurityGuardCoordination | Manages home space security alert capability, including alert arm/disarm, alarm confirmation and local/cloud configuration synchronization. |
| 0x00EB | SceneCoordination | Manages the lifecycle of smart scenes (automation rules), including synchronization, deletion, trigger execution and consistency verification. |
| 0x00EC | HubCoordination | Serves as the gateway core collaboration module, managing sub-device onboarding, configuration, heartbeat, tokens and various proxy services. |
| 0x00ED | LightBoxCoordination | Manages configuration issuance of smart light box devices, controlling displayed content and effects. |
| 0x00EE | IRCoordination | Manages gateway infrared learning and emission, including code library synchronization, virtual remote creation and button control. |
| 0x00EF | CommLinkCoordination | Monitors the communication link quality between gateway and cloud, performing latency probing and reporting results. |
| 0x00F0 | RingtoneCoordination | Manages gateway local ringtone/music files, including download, deletion and consistency verification with the cloud library. |
| 0x00F1 | ScreenCoordination | Manages smart scene panel interaction, including configuration issuance, status query and cloud/panel bidirectional transparent transmission. |
| 0x00F2 | ConfigurationCoordination | Manages common function configuration, resource subscription and location information synchronization through multicast or batch methods. |
| 0x00F3 | LockCoordination | Handles smart door lock extended business, including dedicated transparent transmission channel, encryption/decryption assistance and extended event reporting. |
| 0x00F4 | WakeupCoordination | Obtains wake-up service address or token for low-power devices supporting remote wake-up. |
| 0x00F5 | CloudStorageCoordination | Manages cloud recording/cloud storage business resource configuration, obtaining information such as storage quota and upload credentials. |
| 0x00F6 | CentralHubCoordination | Manages hub gateway advanced capabilities, including hub enabling, Broker information and data transparent transmission channel. |
| 0x00F7 | IftttCoordination | Serves as the automation rule collaboration center, managing the synchronization, subscription and execution of IFTTT/local automation rules. |
| 0x00F8 | NetworkManagement | Serves as the core control module for device network connection and access policies, managing remote proxies and access addresses. |
| 0x00F9 | ToiletCore | Integrates the most basic physical state sensing and component control of smart toilets, including sitting detection, lid opening, flushing, seat heating and night light. |
| 0x00FA | ToiletDiagnostic | Monitors the health status of key hardware subsystems of smart toilets, proactively reporting fault information such as temperature, flow and fan. |
| 0x00FB | ToiletHygiene | Maintains device self-cleaning hygiene, including nozzle cleaning, foam shield, plasma sterilization and pipeline cleaning. |
| 0x00FC | ToiletWashDry | Defines the complete washing and drying process of smart toilets, covering wash modes, water temperature/water pressure, drying wind speed and duration settings. |
| 0x00FD | ToiletSettings | Allows users to personalize default parameters and automation scenarios, such as automatic lid opening, automatic flushing, foam shield and prolonged sitting reminders. |
| 0x00FE | Lighting | Provides Aqara dimming and scene control capability, including built-in/custom scenes, music rhythm and light strip segment control. |
| 0x00FF | ScreenUIConfig | Provides unified panel UI configuration, including page layout, themes, card count and multi-page information management. |
| 0x0100 | Ringtone | Provides ringtone and music playback control, supporting track selection, volume/duration adjustment and playback status monitoring. |
| 0x0101 | FenceDetection | Defines virtual fence areas in camera images, detecting people entering or leaving and supporting linkage policies such as recording and push notifications. |
| 0x0102 | Security | Manages device security policies and access permissions, including user passwords, lost mode and related verification mechanisms. |
| 0x0103 | Storage | Manages local SD card recording, formatting, recording modes and storage status monitoring and maintenance. |
| 0x0104 | ImageMediaManagement | Manages canvas layout and image resources, supporting image download, storage, deletion, status reporting and ID list maintenance. |
| 0x0105 | VoiceAssistant | Manages device voice interaction capabilities, including wake word, voice control switch, voice timbre, continuous conversation, voice control language, near-field wake-up and space area configuration. |
| TBD | VoiceIntercom | Manages device voice intercom related capabilities, including the list of online devices available for intercom. |
| 0x0106 | SpaceSecurity | Manages device security capabilities in a specific space, including alarm ringtone, volume, arm/disarm status and alarm duration. |
| 0x0107 | Massage | Manages electric bed comfort and posture adjustment, including back/leg lifting, massage mode/intensity/timer, child lock and emergency stop. |
| 0x0108 | TowelRackDry | Manages towel rack drying process, controlling target temperature and drying duration, and feeding back remaining time and fault status. |
| 0x0109 | Live | Controls real-time video streaming, supporting enhanced capabilities such as time-lapse photography, zoom, sleep/wake and associated event recording. |
| 0x010A | Playback | Manages recording playback and history, including cloud short video type recognition and local recording download capability. |
| 0x010B | CloudRecording | Controls the cloud recording master switch, deciding whether to upload video content to cloud storage. |
| 0x010C | CameraSettings | Provides camera extended configuration, such as scheduled image upload, RTSP streaming and advanced function switches. |
| 0x010D | AIDetection | Performs AI-driven image and audio analysis, implementing event detection, content recognition and intelligent alerts. |
| 0x010E | VideoSettings | Manages image processing and display, including image quality, watermark, privacy masking, night vision and fill light linkage. |
| 0x010F | CameraWorkMode | Defines camera power consumption strategy and working modes, adapting to different power types and usage scenarios. |
| 0x0110 | AudioSettings | Controls audio capture and output, adjusting parameters such as recording mute and system prompt volume. |
| 0x0111 | CameraPrivacySecurity | Focuses on camera privacy policies, including low-power security privacy protection capabilities such as scheduled sleep. |
| 0x0112 | CameraNotifications | Manages event notification policies, supporting notification type, scheduled time period, filter rules and importance level settings. |
| 0x0113 | NASStorage | Integrates with network attached storage (NAS), providing binding, policy configuration, transmission interval and status management. |
| 0x0114 | Repeater | Manages Wi-Fi relay capability, including keep-alive, relay link information, network diagnostics and connection status with the gateway. |
| 0x0115 | TamperProtection | Provides physical security protection, detecting and responding to tampering behaviors such as illegal disassembly and forced removal, supporting alarm and recording linkage. |
| 0x0116 | SmileDetection | Recognizes smiling faces in the image and reports events, supporting enabling/disabling control of smile recognition capability. |
| 0x0128 | SO2 | Represents the monitoring functional domain for sulfur dioxide in the air, including but not limited to SO2 concentration measurement, SO2 detection status, over-limit alarm, sensor status and other capabilities. |
| 0x0129 | NO2 | Represents the monitoring functional domain for nitrogen dioxide in the air, including but not limited to NO2 concentration measurement, NO2 detection status, over-limit alarm, sensor status and other capabilities. |
| 0x012A | O3 | Represents the monitoring functional domain for ozone in the air, including but not limited to O3 concentration measurement, O3 detection status, over-limit alarm, sensor status and other capabilities. |
| 0x012B | Formaldehyde | Represents the monitoring functional domain for formaldehyde in the air, including but not limited to HCHO concentration measurement, formaldehyde detection status, over-limit alarm, sensor status and other capabilities. |
| 0x012C | O2 | Represents the monitoring functional domain for oxygen in the environment, including but not limited to O2 concentration measurement, hypoxia/hyperoxia determination, sensor status and other capabilities. |
| 0x012D | Chlorine | Represents the monitoring functional domain for chlorine gas in the air, including but not limited to Cl2 concentration measurement, chlorine detection status, over-limit alarm, sensor status and other capabilities. |
| 0x012E | HydrochloricAcid | Represents the monitoring functional domain for hydrogen chloride gas in the air, including but not limited to HCl concentration measurement, hydrogen chloride detection status, over-limit alarm, sensor status and other capabilities. |
| 0x012F | HydrogenSulfide | Represents the monitoring functional domain for hydrogen sulfide in the air, including but not limited to H2S concentration measurement, hydrogen sulfide detection status, over-limit alarm, sensor status and other capabilities. |
| 0x0130 | Ammonia | Represents the monitoring functional domain for ammonia gas in the air, including but not limited to NH3 concentration measurement, ammonia detection status, over-limit alarm, sensor status and other capabilities. |
| 0x0131 | WaterQuality | Represents the monitoring functional domain for water quality, covering but not limited to the measurement and state determination of parameters such as water hardness, turbidity, pH, TDS, residual chlorine and dissolved oxygen. |
| 0x0132 | NitrogenOxides | Represents the monitoring functional domain for nitrogen oxides in the air, including but not limited to NOx concentration measurement, nitrogen oxide detection status, over-limit alarm, sensor status and other capabilities. |
| 0x0133 | LiquidLevel | Represents the monitoring functional domain for liquid level in containers or pipelines, including but not limited to liquid level height measurement, stored liquid volume determination, replenishment/drainage demand analysis, and high/low liquid level risk warning. |
| 0x0134 | Noise | Represents the monitoring functional domain for environmental noise, including but not limited to noise level measurement, noise over-limit determination, peak noise, average noise and other capabilities. |
| 0x0135 | HeatMeter | Represents the comprehensive management of heating/cooling metering functions in heating/cooling supply systems, covering the measurement and reporting of parameters such as instantaneous heat flow, instantaneous cooling flow, cumulative heat value, cumulative cooling value and their fractional parts. |
| 0x0136 | Boiler | Represents the monitoring and control functional domain for boiler equipment operation status, covering the measurement, setting and reporting of parameters such as exhaust gas temperature, flame regulation, load output, combustion timing and ignition count. |
| 0x0137 | ControlCabinet | Represents the monitoring and control functional domain for control cabinet equipment, covering the measurement, setting and reporting of parameters such as frequency feedback, cooling water temperature actual value and setpoint, temperature difference setting and manual frequency reference. |
| 0x0138 | Compressor | Represents the monitoring and control functional domain for compressor equipment operation status, covering the measurement, setting and reporting of parameters such as temperature, pressure, current, voltage, power, humidity, speed, opening, running time and cooling capacity. |
| 0x0139 | CoolingPump | Represents the monitoring and control functional domain for cooling pump equipment, covering the measurement, setting and reporting of parameters such as frequency feedback, manual frequency reference, frequency upper/lower limits and running time. |
| 0x013A | Buzzer | Represents the control functional domain for device buzzers, used to play or stop buzzer sounds, supporting setting playback volume and duration, applicable to scenarios such as doorbell prompts, alarm reminders and operation feedback. |
| 0x013B | GasMetering | Provides gas metering related capabilities, including gas calorific value and the conversion coefficient from working-condition volume to standard volume, used for energy conversion and standardized conversion of gas consumption. |
| 0x013C | EnergyStorage | Manages energy storage battery SOC, rated/available capacity, cumulative charge/discharge energy and charge/discharge power measured at the battery boundary, as well as battery health status. |
| 0x013D | ElectricityMetering | Provides energy meter and grid connection point metering capabilities, including power direction, demand, and imported/exported energy accumulated separately by tariff registers. |
| 0x013E | PowerGeneration | Describes the rated power and operation status of power generation equipment, as well as energy, power and heat recovery data related to gas cogeneration. |
Device Type Definitions
A Device Type describes the device type of an Endpoint. A Device can consist of one or more Endpoints. Each Endpoint can consist of one or more Device Types. Duplicate Functions are not allowed under one Endpoint.
Each Device Type is identified by a unique Device Type ID (Uint16). The following table lists the ID encoding of each Device Type and its mandatory (M) or optional (O) Function set, grouped by category.
Special types: Root, Public. They correspond to the Root Endpoint and Public Endpoint respectively.
- Root (ID: 0x0000): used for the Root Endpoint (Endpoint 0), must implement Basic Information and Descriptor functions.
- Public (ID: 0x0001): used for the Public Endpoint (usually Endpoint 1), carrying device-level common Functions, including Identify and various optional collaboration/diagnostic functions.
Device Type List
System Types
System Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0000 | Root (Root Node) | BasicInformation | M | |
| 0x0000 | Root (Root Node) | Descriptor | M | |
| 0x0000 | Root (Root Node) | EndpointLabel | O | |
| 0x0001 | Public (Public Node) | Identify | M | |
| 0x0001 | Public (Public Node) | WindowCovering | O | |
| 0x0001 | Public (Public Node) | EnergyManagement | O | |
| 0x0001 | Public (Public Node) | PowerSource | O | |
| 0x0001 | Public (Public Node) | NetworkCommissioning | O | |
| 0x0001 | Public (Public Node) | EcosystemInformation | O | |
| 0x0001 | Public (Public Node) | IndicationLight | O | |
| 0x0001 | Public (Public Node) | GeneralConfiguration | O | |
| 0x0001 | Public (Public Node) | GeneralDiagnostics | O | |
| 0x0001 | Public (Public Node) | ThreadNetworkDiagnostics | O | |
| 0x0001 | Public (Public Node) | ZigbeeNetworkDiagnostics | O | |
| 0x0001 | Public (Public Node) | DeviceAnomalyMonitoring | O | |
| 0x0001 | Public (Public Node) | MatterCoordination | O | |
| 0x0001 | Public (Public Node) | OTACoordination | O | |
| 0x0001 | Public (Public Node) | StudioCoordination | O | |
| 0x0001 | Public (Public Node) | CameraCoordination | O | |
| 0x0001 | Public (Public Node) | SecurityGuardCoordination | O | |
| 0x0001 | Public (Public Node) | SceneCoordination | O | |
| 0x0001 | Public (Public Node) | HubCoordination | O | |
| 0x0001 | Public (Public Node) | LightBoxCoordination | O | |
| 0x0001 | Public (Public Node) | IRCoordination | O | |
| 0x0001 | Public (Public Node) | CommLinkCoordination | O | |
| 0x0001 | Public (Public Node) | RingtoneCoordination | O | |
| 0x0001 | Public (Public Node) | ScreenCoordination | O | |
| 0x0001 | Public (Public Node) | ConfigurationCoordination | O | |
| 0x0001 | Public (Public Node) | LockCoordination | O | |
| 0x0001 | Public (Public Node) | WakeupCoordination | O | |
| 0x0001 | Public (Public Node) | CloudStorageCoordination | O | |
| 0x0001 | Public (Public Node) | CentralHubCoordination | O | |
| 0x0001 | Public (Public Node) | IftttCoordination | O | |
| 0x0001 | Public (Public Node) | NetworkManagement | O | |
| 0x0001 | Public (Public Node) | Security | O | |
| 0x0001 | Public (Public Node) | OTA | O | |
Gateway/Bridge Types
Gateway/Bridge Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0003 | Hub (Gateway) | BridgeConfiguration | M | |
| 0x0003 | Hub (Gateway) | Speaker | O | |
| 0x0003 | Hub (Gateway) | MatterBridgeCommissioning | O | |
| 0x0003 | Hub (Gateway) | ZigbeeNetworkDiagnostics | O | |
| 0x0003 | Hub (Gateway) | Ringtone | O | |
| 0x0003 | Hub (Gateway) | ThreadNetworkDiagnostics | O | |
| 0x0004 | BridgedNode (Bridged Device) | BridgedConfiguration | M | Describes bridged devices |
Lighting Types
Lighting Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x000A | Light (Light) | Output | M | |
| 0x000A | Light (Light) | LevelControl | O | |
| 0x000A | Light (Light) | ColorControl | O | |
| 0x000A | Light (Light) | DeviceAnomalyMonitoring | O | |
| 0x000A | Light (Light) | Lighting | O | |
| 0x000A | Light (Light) | ImageMediaManagement | O | |
Electrical Types
Electrical Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x000B | Outlet (Socket) | Output | M | |
| 0x000B | Outlet (Socket) | EnergyManagement | O | |
| 0x000B | Outlet (Socket) | DeviceAnomalyMonitoring | O | |
| 0x000C | Switch (Switch) | Output | M | |
| 0x000C | Switch (Switch) | EnergyManagement | O | |
| 0x000C | Switch (Switch) | MARSConfiguration | O | |
| 0x000C | Switch (Switch) | CustomizedConfiguration | O | |
| 0x000C | Switch (Switch) | ScreenUserInterface | O | |
| 0x000C | Switch (Switch) | DeviceAnomalyMonitoring | O | |
| 0x004A | GeneralValve (Valve) | Identify | M | This defines conformance to the Water Valve device type. |
| 0x004A | GeneralValve (Valve) | ValveControl | M | |
| 0x003E | Valve (Valve) | Output | M | |
| 0x0042 | ElectricalSensor (Electrical Parameter Sensor) | EnergyManagement | O | General electrical parameter sensor; does not indicate the imported/exported, demand or time-of-use metering capabilities of a grid connection point meter. |
| 0x0043 | Pump (Pump) | Output | M | A Pump device in a smart home system is designed to control and manage the flow of liquids, such as water or other fluids. |
HVAC Types
HVAC Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x000D | AirConditioner (Air Conditioner, dual setpoint) | Output | M | Supports automatic cool/heat switching and maintains separate cooling and heating target temperatures. |
| 0x000D | AirConditioner (Air Conditioner, dual setpoint) | HeaterCooler | M | Must implement CoolingTemperature, HeatingTemperature, and MinHeatCoolDeadBand; HeaterCoolerMode must support Auto and report Supported Value. See below for dual-setpoint and Auto mode requirements. |
| 0x000D | AirConditioner (Air Conditioner, dual setpoint) | FanControl | O | |
| 0x000D | AirConditioner (Air Conditioner, dual setpoint) | FreshAirControl | O | |
| 0x000D | AirConditioner (Air Conditioner, dual setpoint) | Temperature | O | Outdoor temperature uses OutdoorTemperature; indoor temperature reuses HeaterCooler's CurrentTemperature. |
| 0x0087 | SingleSetpointAC (Single-setpoint Air Conditioner) | Output | M | The user first selects cool or heat mode, then sets the single target temperature for that mode. |
| 0x0087 | SingleSetpointAC (Single-setpoint Air Conditioner) | HeaterCooler | M | Must implement SetTemperature; HeaterCoolerMode must report Supported Value and support at least one of Cool or Heat. See below for single-setpoint control requirements. |
| 0x0087 | SingleSetpointAC (Single-setpoint Air Conditioner) | FanControl | O | |
| 0x0087 | SingleSetpointAC (Single-setpoint Air Conditioner) | FreshAirControl | O | |
| 0x0087 | SingleSetpointAC (Single-setpoint Air Conditioner) | Temperature | O | Outdoor temperature uses OutdoorTemperature; indoor temperature reuses HeaterCooler's CurrentTemperature. |
| 0x0062 | AirConditionerController (Air Conditioner Controller) | Binding | M | This device type represents a controller that can be bound to one or more target air conditioners. |
| 0x000E | WindowCovering (Curtain) | WindowCovering | M | |
| 0x002D | Thermostat (Thermostat) | HeaterCooler | M | |
| 0x002D | Thermostat (Thermostat) | FanControl | O | |
| 0x0061 | ThermostatController (Thermostat Controller) | Binding | M | This device type represents a thermostat controller that can be bound to one or more target thermostats. |
| 0x0030 | FloorHeating (Floor Heating) | Output | M | |
| 0x0030 | FloorHeating (Floor Heating) | HeaterCooler | M | |
| 0x0031 | Ventilation (Fresh Air) | Output | M | |
| 0x0031 | Ventilation (Fresh Air) | FanControl | M | |
| 0x0031 | Ventilation (Fresh Air) | FreshAirControl | O | |
| 0x0038 | BathroomHeater (Bathroom Heater) | Output | M | |
| 0x0038 | BathroomHeater (Bathroom Heater) | HeaterCooler | O | |
| 0x0038 | BathroomHeater (Bathroom Heater) | FanControl | O | |
| 0x005E | TemperatureControlledCabinet (Temperature Controlled Cabinet) | TemperatureControl | M | |
| 0x005E | TemperatureControlledCabinet (Temperature Controlled Cabinet) | Temperature | O | |
| 0x0048 | Fan (Fan) | FanControl | M | A Fan is a smart home device designed to circulate air in order to provide cooling, ventilation, or air circulation within a roo |
| 0x0048 | Fan (Fan) | Output | O | |
| 0x0059 | HeatPump (Heat Pump) | HeaterCooler | M | A Heat Pump Device is an energy-efficient heating and cooling system that transfers heat between indoor and outdoor environments |
| 0x0059 | HeatPump (Heat Pump) | PowerSource | M | |
| 0x0059 | HeatPump (Heat Pump) | EnergyManagement | M | |
AirConditioner and SingleSetpointAC both implement Output and HeaterCooler; they differ in target-temperature and mode-control models:
AirConditioner (Device Type ID 0x000D, decimal 13) is a dual-setpoint air conditioner for devices that can maintain cooling and heating targets at the same time and automatically switch between cooling and heating based on room temperature. Its CoolingTemperature and HeatingTemperature are two independent targets that are both effective concurrently; SetTemperature MUST NOT be used as an alias or substitute for these two targets. The difference between the two targets MUST be no less than the Present Value of MinHeatCoolDeadBand. The device MUST support and report Auto in HeaterCoolerMode/Supported Value. In Auto mode, cool when room temperature is above the cooling target, and heat when below the heating target; while in the deadband between the two targets, do not simultaneously request both cooling and heating because of this automatic temperature-control logic. In Auto mode, clients SHOULD display and allow independent adjustment of both targets; when switching to Cool or Heat, use the corresponding cooling or heating target, while the other target remains independently effective. The device SHOULD validate the relationship whenever either target or the minimum deadband is updated; writes that violate the minimum deadband MUST be rejected, and MUST NOT be applied partially.SingleSetpointAC (Device Type ID 0x0087, decimal 135) is a single-setpoint air conditioner for devices where the user first selects cool or heat mode and then sets one target temperature, including cool-only or heat-only devices. Its SetTemperature is the only effective air-conditioner target temperature in the current mode; the device MUST NOT use CoolingTemperature and HeatingTemperature together to represent the current air-conditioner control target. For this Device Type, HeaterCoolerMode/Supported Value MUST list the modes the device actually supports and MUST include at least one of Cool or Heat; after the user switches Cool/Heat mode, SetTemperature still means the single target for the current mode and does not represent separately stored cooling and heating targets.HeaterCoolerMode/Supported Value is the basis for modes available to the client; clients MUST NOT present modes the device has not declared support for based only on the global enumeration definition. Auto mode on AirConditioner works from the two targets and the deadband; the client flow for SingleSetpointAC SHOULD first present the Cool/Heat modes the device supports (only that one mode if only one is supported), then edit SetTemperature.MinHeatCoolDeadBand constrains dual-setpoint automatic control and represents the minimum temperature difference that MUST be kept between the cooling and heating targets; it does not apply to SingleSetpointAC controlled with SetTemperature. When a current-temperature Trait is used for status display, implement it according to its own Conformance; the device may use an internal sensor for Auto control and need not fabricate an external temperature measurement solely because of that internal sensor.
Audio/Video Types
Audio/Video Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x000F | Camera (Camera) | Camera | M | |
| 0x000F | Camera (Camera) | Speaker | O | |
| 0x000F | Camera (Camera) | PanTilt | O | |
| 0x000F | Camera (Camera) | Storage | O | |
| 0x000F | Camera (Camera) | NASStorage | O | |
| 0x000F | Camera (Camera) | CameraNotifications | O | |
| 0x000F | Camera (Camera) | CameraPrivacySecurity | O | |
| 0x000F | Camera (Camera) | AudioSettings | O | |
| 0x000F | Camera (Camera) | CameraWorkMode | O | |
| 0x000F | Camera (Camera) | VideoSettings | O | |
| 0x000F | Camera (Camera) | AIDetection | O | |
| 0x000F | Camera (Camera) | CameraSettings | O | |
| 0x000F | Camera (Camera) | CloudRecording | O | |
| 0x000F | Camera (Camera) | Playback | O | |
| 0x000F | Camera (Camera) | Live | O | |
| 0x0011 | Speaker (Speaker) | Speaker | M | |
| 0x0011 | Speaker (Speaker) | MediaPlayback | O | |
| 0x0012 | TV (TV) | Output | M | |
| 0x0012 | TV (TV) | MediaPlayback | O | |
| 0x0012 | TV (TV) | Speaker | O | |
| 0x005A | BasicVideoPlayer (Basic Video Player) | Output | M | |
| 0x005A | BasicVideoPlayer (Basic Video Player) | MediaPlayback | M | |
| 0x005A | BasicVideoPlayer (Basic Video Player) | MediaInput | O | |
| 0x005B | CastingVideoPlayer (Casting Video Player) | Output | M | |
| 0x005B | CastingVideoPlayer (Casting Video Player) | MediaPlayback | M | |
| 0x005B | CastingVideoPlayer (Casting Video Player) | MediaInput | O | |
| 0x005C | VideoRemoteControl (Video Remote Control) | Output | M | |
| 0x005C | VideoRemoteControl (Video Remote Control) | MediaPlayback | M | |
| 0x005C | VideoRemoteControl (Video Remote Control) | MediaInput | O | |
| 0x003F | Projector (Projector) | Output | O | |
| 0x0039 | Panel (Panel) | Speaker | O | |
| 0x0039 | Panel (Panel) | ScreenDisplay | O | |
| 0x003A | VideoDoorbell (Video Doorbell) | Camera | M | |
| 0x003A | VideoDoorbell (Video Doorbell) | Speaker | O | |
IR/Remote Control Types
IR/Remote Control Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0013 | IRDevice (IR Device) | IRControl | M | |
| 0x0013 | IRDevice (IR Device) | Output | O | |
| 0x0013 | IRDevice (IR Device) | HeaterCooler | O | |
| 0x006C | GestureSensor (Gesture Sensor) | GestureRecognition | M | |
Clothes Drying Rack Types
Clothes Drying Rack Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0014 | ClotheDryingMachine (Clothes Drying Machine) | Lifter | M | |
Sensor Types
Sensor Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0015 | ContactSensor (Contact Sensor) | Contact | M | |
| 0x0016 | DoorLock (Door Lock) | DoorLock | M | |
| 0x0017 | TemperatureSensor (Temperature Sensor) | Temperature | M | |
| 0x0018 | HumiditySensor (Humidity Sensor) | RelativeHumidity | M | |
| 0x0019 | AtmosphericPressureSensor (Atmospheric Pressure) | Pressure | M | |
| 0x005D | PressureSensor (Pressure Sensor) | Pressure | M | Pressure Sensor is a general-purpose pressure detection device capable of measuring air pressure, water pressure, and hydraulic |
| 0x001A | IlluminanceSensor (Illuminance Sensor) | Illuminance | M | |
| 0x001B | CO2Sensor (CO2 Sensor) | CO2 | M | |
| 0x001C | TVOCSensor (TVOC Sensor) | AirQuality | M | |
| 0x0049 | AirQualitySensor (Air Quality Sensor) | AirQuality | M | An Air Quality Sensor is a smart device designed to monitor the quality of the air within a home or other indoor environments. |
| 0x007C | WaterQualitySensor (Water Quality Sensor) | WaterQuality | M | |
| 0x001D | NaturalGasAlarm (Natural Gas Alarm) | Gas | M | |
| 0x001E | SmokeAlarm (Smoke Alarm) | Smoke | M | |
| 0x001E | SmokeAlarm (Smoke Alarm) | CO | O | |
| 0x001E | SmokeAlarm (Smoke Alarm) | PowerSource | O | |
| 0x0047 | COAlarm (Carbon Monoxide Alarm) | CO | M | A CO Alarm is a critical safety device designed to detect the presence of carbon monoxide (CO) gas in the air. |
| 0x0047 | COAlarm (Carbon Monoxide Alarm) | PowerSource | O | |
| 0x003D | LPGAlarm (Liquefied Petroleum Gas Alarm) | Gas | M | |
| 0x001F | ParticulateMatterSensor (Particulate Matter Sensor) | ParticulateMatter | M | |
| 0x0020 | WaterLeakSensor (Water Leak Sensor) | WaterLeak | M | |
| 0x0021 | SleepMonitor (Sleep Monitor) | Sleep | M | |
| 0x0022 | MotionSensor (Motion Sensor) | OccupancySensing | M | |
| 0x0027 | OccupancySensor (Occupancy Sensor) | OccupancySensing | M | |
| 0x0027 | OccupancySensor (Occupancy Sensor) | OccupantLocation | O | |
| 0x0027 | OccupancySensor (Occupancy Sensor) | RadarSensingUnion | O | |
| 0x0027 | OccupancySensor (Occupancy Sensor) | AmbientSensingConfiguration | O | |
| 0x0023 | Knob (Knob Switch) | Knob | M | |
| 0x0023 | Knob (Knob Switch) | Button | O | |
| 0x0024 | Button (Wireless Switch) | Button | M | |
| 0x0025 | Cube (Cube) | Cube | M | |
| 0x0026 | VibrationSensor (Vibration Sensor) | Vibration | M | |
| 0x0029 | LocationSensor (Location Sensor) | Location | M | |
| 0x0028 | WaterHeater (Water Heater) | Output | M | |
| 0x0044 | OnOffSensor (On/Off Sensor) | OnOffSensor | O | An On/Off Sensor is a smart home device designed to detect and report the status of electrical appliances or systems-whether the |
| 0x0046 | RainSensor (Rain Sensor) | RainSensor | O | A Rain Sensor is a smart device designed to detect rainfall and provide real-time information about weather conditions. |
| 0x0045 | WaterFreezeDetector (Water Freeze Detector) | WaterFreezeDetector | M | A Water Freeze Detector is a smart device designed to monitor the temperature of water systems in the home. |
| 0x004C | FlowSensor (Flow Sensor) | Flow | M | A Flow Sensor device measures and reports the flow rate of a fluid. |
| 0x007D | HeatMeter (Heat Meter) | HeatMeter | M | Used for heat/cooling metering and statistics in heating/cooling supply systems. |
| 0x007E | Compressor (Compressor) | Compressor | M | Used for operation monitoring and control of the compression stage in refrigeration systems. |
| 0x007F | ControlCabinet (Control Cabinet) | ControlCabinet | M | Used for centralized monitoring and frequency regulation control in scenarios such as cooling water systems. |
| 0x0080 | CoolingPump (Cooling Pump) | CoolingPump | M | Used for pump operation monitoring and frequency regulation in cooling water circulation systems. |
| 0x0081 | Boiler (Boiler) | Boiler | M | Used for boiler operation parameter monitoring, flame regulation and combustion control. |
| 0x0082 | LiquidLevelSensor (Liquid Level Sensor) | LiquidLevel | M | Used to monitor liquid level height and liquid level risks in containers or pipelines. |
| 0x0084 | WaterMeter (Water Meter) | Flow | M | Used to measure and report water flow rate and cumulative water consumption. |
| 0x0084 | WaterMeter (Water Meter) | Temperature | O | Applicable to water meters that support water temperature measurement. |
| 0x0084 | WaterMeter (Water Meter) | ValveControl | O | Applicable to water meters with integrated shut-off valves. |
| 0x0085 | GasMeter (Gas Meter) | Flow | M | Used to measure and report gas flow rate and cumulative gas consumption. |
| 0x0085 | GasMeter (Gas Meter) | ValveControl | O | Applicable to gas meters with integrated shut-off valves. |
| 0x0085 | GasMeter (Gas Meter) | GasMetering | O | Provides gas metering parameters such as gas calorific value and gas volume conversion coefficient. |
| 0x003C | AttitudeDetector (Attitude Detection) | AttitudeDetection | M | |
| 0x005F | ModeSelector (Mode Selector) | Mode | M | |
Security/AI Detection Types
Security/AI Detection Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0071 | HumanDetector (Human Detector) | HumanRecognition | O | |
| 0x0071 | HumanDetector (Human Detector) | HumanPresence | O | |
| 0x002F | FireAlarm (Fire Alarm) | FlameDetection | M | |
| 0x0070 | PackageDetector (Package Detector) | PackageRecognition | M | |
| 0x006F | SoundSensor (Sound Sensor) | SoundDetection | M | |
| 0x006E | PetMonitor (Pet Monitor) | PetRecognition | M | |
| 0x006D | FaceScanner (Face Scanner) | FaceRecognition | M | |
| 0x006B | VehicleDetector (Vehicle Detector) | VehicleDetection | M | |
| 0x0072 | Doorbell (Doorbell) | Doorbell | M | A doorbell that is not a video doorbell |
Health Monitoring Types
Health Monitoring Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0073 | BreathingMonitor (Breathing Monitor) | BreathingMonitoring | M | |
| 0x0074 | HeartMonitor (Heart Monitor) | HeartMonitoring | M | |
| 0x0075 | VirtualFence (Virtual Fence) | FenceDetection | O | |
Cleaning/Appliance Types
Cleaning/Appliance Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0010 | SweepingRobot (Sweeping Robot) | Sweeper | M | |
| 0x004D | RoboticVacuumCleaner (Robotic Vacuum Cleaner) | VacuumOperationalState | M | This defines conformance for the Robotic Vacuum Cleaner device type. |
| 0x004D | RoboticVacuumCleaner (Robotic Vacuum Cleaner) | Mode | M | |
| 0x004B | AirPurifier (Air Purifier) | Identify | M | An Air Purifier is a standalone device that is designed to clean the air in a room. |
| 0x004B | AirPurifier (Air Purifier) | Output | M | |
| 0x004B | AirPurifier (Air Purifier) | FanControl | M | |
| 0x004B | AirPurifier (Air Purifier) | ActivatedCarbonFilterMonitoring | O | |
| 0x004B | AirPurifier (Air Purifier) | HEPAFilterMonitoring | O | |
| 0x002A | SmartToilet (Toilet) | ToiletCore | M | |
| 0x002A | SmartToilet (Toilet) | ToiletDiagnostic | O | |
| 0x002A | SmartToilet (Toilet) | ToiletHygiene | O | |
| 0x002A | SmartToilet (Toilet) | ToiletWashDry | O | |
| 0x002A | SmartToilet (Toilet) | ToiletSettings | O | |
| 0x002B | TVBox (TV Box) | BasicInformation | | |
| 0x002C | SmartBed (Bed) | Lifter | O | Represent a motorized bed system that allows for independent or synchronized adjustment of the backrest and legrest positions, and may incorporate multi-mode massage functions, timer-based operations, and safety mechanisms such as child locks to enhance user comfort and safety. |
| 0x002C | SmartBed (Bed) | Massage | O | |
| 0x002E | Pusher (Window Pusher) | BasicInformation | | |
| 0x0035 | TowelRack (Towel Rack) | TowelRackDry | M | Represent an intelligent bathroom heating appliance designed to dry and warm towels through controlled heating cycles, providing real-time monitoring of surface temperature, remaining drying duration, and operational status while ensuring system safety through fault detection. |
| 0x0036 | PetFeeder (Pet Feeder) | PetFeeder | M | |
| 0x0037 | PetWaterer (Pet Waterer) | BasicInformation | | |
| 0x0034 | ElectricCooker (Electric Cooker) | BasicInformation | | |
| 0x0033 | Oven (Steamer/Oven) | OperationalState | M | An Oven is a household or commercial appliance used for cooking, baking, roasting, or heating food. |
| 0x0032 | Hearth (Stove) | BasicInformation | | |
| 0x004F | Refrigerator (Refrigerator) | Mode | M | A Refrigerator is an appliance that keeps food and beverages cold to preserve freshness. |
| 0x004F | Refrigerator (Refrigerator) | RefrigeratorState | M | |
| 0x004E | LaundryWasher (Washing Machine) | OperationalState | M | A Laundry Washer is an appliance that cleans clothes and textiles by agitating them in water with detergent to remove dirt, stai |
| 0x0051 | LaundryDryer (Clothes Dryer) | OperationalState | M | A Laundry Dryer is an appliance designed to dry clothes, towels, and other textiles by removing moisture through heat |
| 0x0050 | Dishwasher (Dishwasher) | OperationalState | M | A Dishwasher is an appliance designed to automatically clean dishes, utensils, and cookware by spraying hot water mixed with det |
| 0x0052 | Cooktop (Cooktop) | Output | M | A Cooktop is a kitchen appliance designed for cooking food by providing heat through burners, induction coils, or other heating |
| 0x0053 | CookSurface (Cooking Surface) | Output | M | A Cook Surface refers to the flat cooking area of a stove or cooktop, where heat is applied to cookware for cooking food. |
| 0x0054 | ExtractorHood (Range Hood) | FanControl | M | An Extractor Hood is an appliance installed above the cooktop or stove to ventilate and remove smoke, steam, odors |
| 0x0055 | MicrowaveOven (Microwave Oven) | Output | M | A Microwave Oven is an appliance that uses electromagnetic waves (microwaves) to rapidly heat or cook food. |
| 0x003B | AccessController (Access Controller) | BasicInformation | | |
Energy Types
Energy Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0056 | ElectricVehicleSupplyEquipment (EV Charging Pile) | EVSE | M | Electric Vehicle Supply Equipment (EVSE) refers to the hardware used to deliver electrical energy from a power source |
| 0x0056 | ElectricVehicleSupplyEquipment (EV Charging Pile) | Mode | M | |
| 0x0056 | ElectricVehicleSupplyEquipment (EV Charging Pile) | EnergyStorage | O | Only implemented when the device can provide vehicle battery-side data; must not be confused with EVSE's own backup battery. |
| 0x0057 | SolarPower (Solar Power) | PowerSource | M | Solar Power is the energy harnessed from the sun using photovoltaic (PV) cells, which convert sunlight into electricity. |
| 0x0057 | SolarPower (Solar Power) | EnergyManagement | M | The SolarPower implementation must provide CumulativeGeneratedActiveEnergy and GeneratedActivePower, whose metering boundary is the AC output side of the inverter. |
| 0x0057 | SolarPower (Solar Power) | PowerGeneration | O | Rated generation power and cumulative sold energy are implemented according to device capabilities; grid connection status is provided by EnergyManagement. |
| 0x0058 | BatteryStorage (Battery Storage) | PowerSource | M | PowerSource describes the device power source; BatPercentRemaining does not replace the storage SOC. |
| 0x0058 | BatteryStorage (Battery Storage) | EnergyManagement | M | |
| 0x0058 | BatteryStorage (Battery Storage) | EnergyStorage | M | Provides battery-side data of the storage system, such as SOC, capacity, charge/discharge and health status. |
| 0x0086 | ElectricityMeter (Energy Meter) | EnergyManagement | M | Provides general electrical parameters and cumulative imported/exported active energy. |
| 0x0086 | ElectricityMeter (Energy Meter) | ElectricityMetering | M | The MeteringPointType of the grid connection point meter must be GridConnectionPoint; demand and time-of-use energy are optionally implemented according to device capabilities. |
BACnet Object Types
BACnet Object Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0063 | AnalogInputDevice (Analog Input Device) | AnalogInputObject | M | |
| 0x0064 | AnalogOutputDevice (Analog Output Device) | AnalogOutputObject | M | |
| 0x0065 | BinaryInputDevice (Binary Input Device) | BinaryInputObject | M | |
| 0x0066 | BinaryOutputDevice (Binary Output Device) | BinaryOutputObject | M | |
| 0x0067 | MultiStateInputDevice (Multi-state Input Device) | MultiStateInputObject | M | |
| 0x0068 | MultiStateOutputDevice (Multi-state Output Device) | MultiStateOutputObject | M | |
| 0x0069 | CharStringValueDevice (Character String Device) | CharacterStringValueObject | M | |
Vehicle-mounted Types
Vehicle-mounted Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x0041 | MultiActionDetector (Multi-action Detector) | Cube | O | Multi-action detector supporting multiple types of action detection, such as double tap, rotation, vibration, etc. |
| 0x0041 | MultiActionDetector (Multi-action Detector) | Vibration | O | |
| 0x0041 | MultiActionDetector (Multi-action Detector) | Knob | O | |
| 0x0040 | GarageDoor (Garage Door) | GarageDoorOpener | M | |
Other Types
Other Types
| ID | Device Type | Required Functions | Mandatory | Remarks |
|---|
| 0x006A | Scene (Scene) | BasicInformation | | |
| 0x0077 | NAS (Network Attached Storage) | BasicInformation | | |
| 0x0076 | WiFiRepeater (WiFi Repeater) | BasicInformation | | |
| 0x0083 | VoiceAssistant (Voice Assistant) | VoiceAssistant | M | Voice assistant device type. |
Function names in the table are consistent with the Aqara Spec Function definition sections.
Device Type ID Index
The following table lists all Device Types in ascending ID order for easy lookup by code. See the previous section list for Function requirements.
Device Type ID Index Table
| ID | Code | Name | Category |
|---|
| [[devtype_0000]]0x0000 | Root | Root node | Other |
| [[devtype_0001]]0x0001 | Public | Public node | Other |
| [[devtype_0003]]0x0003 | Hub | Gateway | Other |
| [[devtype_0004]]0x0004 | BridgedNode | Bridged device | Other |
| [[devtype_000a]]0x000A | Light | Light | Lighting |
| [[devtype_000b]]0x000B | Outlet | Socket | Outlet |
| [[devtype_000c]]0x000C | Switch | Switch | Switch |
| [[devtype_000d]]0x000D | AirConditioner | Dual-setpoint Air Conditioner | HeaterCooler |
| [[devtype_000e]]0x000E | WindowCovering | Curtain | Shading |
| [[devtype_000f]]0x000F | Camera | Camera | Security |
| [[devtype_0010]]0x0010 | SweepingRobot | Sweeping robot | Other |
| [[devtype_0011]]0x0011 | Speaker | Speaker | Other |
| [[devtype_0012]]0x0012 | TV | TV | Other |
| [[devtype_0013]]0x0013 | IRDevice | IR device | IRDevice |
| [[devtype_0014]]0x0014 | ClotheDryingMachine | Clothes drying machine | Other |
| [[devtype_0015]]0x0015 | ContactSensor | Contact sensor | Security |
| [[devtype_0016]]0x0016 | DoorLock | Door lock | Security |
| [[devtype_0017]]0x0017 | TemperatureSensor | Temperature sensor | Environment |
| [[devtype_0018]]0x0018 | HumiditySensor | Humidity sensor | Environment |
| [[devtype_0019]]0x0019 | AtmosphericPressureSensor | Atmospheric pressure | Environment |
| [[devtype_001a]]0x001A | IlluminanceSensor | Illuminance sensor | Environment |
| [[devtype_001b]]0x001B | CO2Sensor | CO2 sensor | Environment |
| [[devtype_001c]]0x001C | TVOCSensor | TVOC sensor | Environment |
| [[devtype_001d]]0x001D | NaturalGasAlarm | Natural gas alarm | Security |
| [[devtype_001e]]0x001E | SmokeAlarm | Smoke alarm | Security |
| [[devtype_001f]]0x001F | ParticulateMatterSensor | Particulate matter sensor | Environment |
| [[devtype_0020]]0x0020 | WaterLeakSensor | Water leak sensor | Security |
| [[devtype_0021]]0x0021 | SleepMonitor | Sleep monitor | Other |
| [[devtype_0022]]0x0022 | MotionSensor | Motion sensor | Security |
| [[devtype_0023]]0x0023 | Knob | Knob switch | Remote |
| [[devtype_0024]]0x0024 | Button | Wireless switch | Remote |
| [[devtype_0025]]0x0025 | Cube | Cube | Remote |
| [[devtype_0026]]0x0026 | VibrationSensor | Vibration sensor | Security |
| [[devtype_0027]]0x0027 | OccupancySensor | Occupancy sensor | Security |
| [[devtype_0028]]0x0028 | WaterHeater | Water heater | Other |
| [[devtype_0029]]0x0029 | LocationSensor | Location sensor | Other |
| [[devtype_002a]]0x002A | SmartToilet | Toilet | Other |
| [[devtype_002b]]0x002B | TVBox | TV box | Other |
| [[devtype_002c]]0x002C | SmartBed | Bed | Other |
| [[devtype_002d]]0x002D | Thermostat | Thermostat | HeaterCooler |
| [[devtype_002e]]0x002E | Pusher | Window pusher | Other |
| [[devtype_002f]]0x002F | FireAlarm | Fire alarm | Security |
| [[devtype_0030]]0x0030 | FloorHeating | Floor heating | HeaterCooler |
| [[devtype_0031]]0x0031 | Ventilation | Fresh air | HeaterCooler |
| [[devtype_0032]]0x0032 | Hearth | Stove | Other |
| [[devtype_0033]]0x0033 | Oven | Steamer/Oven | Other |
| [[devtype_0034]]0x0034 | ElectricCooker | Electric cooker | Other |
| [[devtype_0035]]0x0035 | TowelRack | Towel rack | Other |
| [[devtype_0036]]0x0036 | PetFeeder | Pet feeder | Other |
| [[devtype_0037]]0x0037 | PetWaterer | Pet waterer | Other |
| [[devtype_0038]]0x0038 | BathroomHeater | Bathroom heater | HeaterCooler |
| [[devtype_0039]]0x0039 | Panel | Panel | Other |
| [[devtype_003a]]0x003A | VideoDoorbell | Video doorbell | Security |
| [[devtype_003b]]0x003B | AccessController | Access controller | Other |
| [[devtype_003c]]0x003C | AttitudeDetector | Attitude detection | Other |
| [[devtype_003d]]0x003D | LPGAlarm | LPG alarm | Security |
| [[devtype_003e]]0x003E | Valve | Valve | Other |
| [[devtype_003f]]0x003F | Projector | Projector | Other |
| [[devtype_0040]]0x0040 | GarageDoor | Garage door | Other |
| [[devtype_0041]]0x0041 | MultiActionDetector | Multi-action detector | Remote |
| [[devtype_0042]]0x0042 | ElectricalSensor | Electrical parameter sensor | Outlet |
| [[devtype_0043]]0x0043 | Pump | Pump | Other |
| [[devtype_0044]]0x0044 | OnOffSensor | On/off sensor | Environment |
| [[devtype_0045]]0x0045 | WaterFreezeDetector | Water freeze detector | Environment |
| [[devtype_0046]]0x0046 | RainSensor | Rain sensor | Environment |
| [[devtype_0047]]0x0047 | COAlarm | Carbon monoxide alarm | Environment |
| [[devtype_0048]]0x0048 | Fan | Fan | Other |
| [[devtype_0049]]0x0049 | AirQualitySensor | Air quality sensor | Environment |
| [[devtype_004a]]0x004A | GeneralValve | Valve | Outlet |
| [[devtype_004b]]0x004B | AirPurifier | Air purifier | Environment |
| [[devtype_004c]]0x004C | FlowSensor | Flow sensor | Environment |
| [[devtype_004d]]0x004D | RoboticVacuumCleaner | Sweeping robot | Other |
| [[devtype_004e]]0x004E | LaundryWasher | Washing machine | Other |
| [[devtype_004f]]0x004F | Refrigerator | Refrigerator | Other |
| [[devtype_0050]]0x0050 | Dishwasher | Dishwasher | Other |
| [[devtype_0051]]0x0051 | LaundryDryer | Clothes dryer | Other |
| [[devtype_0052]]0x0052 | Cooktop | Cooktop | Other |
| [[devtype_0053]]0x0053 | CookSurface | Cooking surface | Other |
| [[devtype_0054]]0x0054 | ExtractorHood | Range hood | Other |
| [[devtype_0055]]0x0055 | MicrowaveOven | Microwave oven | Other |
| [[devtype_0056]]0x0056 | ElectricVehicleSupplyEquipment | EV charging pile | Other |
| [[devtype_0057]]0x0057 | SolarPower | Solar power | Other |
| [[devtype_0058]]0x0058 | BatteryStorage | Battery storage | Other |
| [[devtype_0059]]0x0059 | HeatPump | Heat pump | Other |
| [[devtype_005a]]0x005A | BasicVideoPlayer | Basic video player | Other |
| [[devtype_005b]]0x005B | CastingVideoPlayer | Casting video player | Other |
| [[devtype_005c]]0x005C | VideoRemoteControl | Video remote control | Other |
| [[devtype_005d]]0x005D | PressureSensor | Pressure sensor | Environment |
| [[devtype_005e]]0x005E | TemperatureControlledCabinet | Temperature controlled cabinet | HeaterCooler |
| [[devtype_005f]]0x005F | ModeSelector | Mode selector | Other |
| [[devtype_0061]]0x0061 | ThermostatController | Thermostat controller | HeaterCooler |
| [[devtype_0062]]0x0062 | AirConditionerController | Air conditioner controller | HeaterCooler |
| [[devtype_0063]]0x0063 | AnalogInputDevice | Analog input device | Other |
| [[devtype_0064]]0x0064 | AnalogOutputDevice | Analog output device | Other |
| [[devtype_0065]]0x0065 | BinaryInputDevice | Binary input device | Other |
| [[devtype_0066]]0x0066 | BinaryOutputDevice | Binary output device | Other |
| [[devtype_0067]]0x0067 | MultiStateInputDevice | Multi-state input device | Other |
| [[devtype_0068]]0x0068 | MultiStateOutputDevice | Multi-state output device | Other |
| [[devtype_0069]]0x0069 | CharStringValueDevice | Character string device | Other |
| [[devtype_006a]]0x006A | Scene | Scene | Other |
| [[devtype_006b]]0x006B | VehicleDetector | Vehicle detector | Security |
| [[devtype_006c]]0x006C | GestureSensor | Gesture sensor | Remote |
| [[devtype_006d]]0x006D | FaceScanner | Face scanner | Security |
| [[devtype_006e]]0x006E | PetMonitor | Pet monitor | Security |
| [[devtype_006f]]0x006F | SoundSensor | Sound sensor | Security |
| [[devtype_0070]]0x0070 | PackageDetector | Package detector | Security |
| [[devtype_0071]]0x0071 | HumanDetector | Human detector | Security |
| [[devtype_0072]]0x0072 | Doorbell | Doorbell | Other |
| [[devtype_0073]]0x0073 | BreathingMonitor | Breathing monitor | Other |
| [[devtype_0074]]0x0074 | HeartMonitor | Heart monitor | Other |
| [[devtype_0075]]0x0075 | VirtualFence | Virtual fence | Other |
| [[devtype_0076]]0x0076 | WiFiRepeater | WiFi repeater | Other |
| [[devtype_0077]]0x0077 | NAS | Network attached storage | Other |
| [[devtype_007c]]0x007C | WaterQualitySensor | Water quality sensor | Environment |
| [[devtype_007d]]0x007D | HeatMeter | Heat meter | Environment |
| [[devtype_007e]]0x007E | Compressor | Compressor | HeaterCooler |
| [[devtype_007f]]0x007F | ControlCabinet | Control cabinet | HeaterCooler |
| [[devtype_0080]]0x0080 | CoolingPump | Cooling pump | HeaterCooler |
| [[devtype_0081]]0x0081 | Boiler | Boiler | HeaterCooler |
| [[devtype_0082]]0x0082 | LiquidLevelSensor | Liquid level sensor | Environment |
| [[devtype_0083]]0x0083 | VoiceAssistant | Voice assistant | Other |
| [[devtype_0084]]0x0084 | WaterMeter | Water meter | Environment |
| [[devtype_0085]]0x0085 | GasMeter | Gas meter | Environment |
| [[devtype_0086]]0x0086 | ElectricityMeter | Energy meter | Other |
| [[devtype_0087]]0x0087 | SingleSetpointAC | Single-setpoint Air Conditioner | HeaterCooler |
Function names in the table are consistent with the Aqara Spec Function definition sections.
Matter / Zigbee Device Type to Aqara Spec Device Type Mapping
This appendix defines the correspondence between Matter Device Types, Zigbee Device Types and Aqara Spec Device Types.
Matter Device Type Mapping
| No. | Matter Device Type | Matter Device Type ID | Aqara Spec Device Type | Aqara Spec Device Type ID |
|---|
| 1 | Dimmable Plug-In Unit | 0x010B | Light | 0x000A |
| 2 | Mounted On/Off Control | 0x010F | Switch | 0x000C |
| 3 | Mounted Dimmable Load Control | 0x0110 | Light | 0x000A |
| 4 | Pump | 0x0303 | Pump | 0x0043 |
| 5 | Pressure Sensor | 0x0305 | PressureSensor | 0x005D |
| 6 | On/Off Sensor | 0x0850 | OnOffSensor | 0x0044 |
| 7 | Smoke & CO Alarm | 0x0076 | SmokeAlarm | 0x001E |
| Smoke & CO Alarm | 0x0076 | COAlarm | 0x0047 |
| 8 | Air Quality Sensor | 0x002C | AirQualitySensor | 0x0049 |
| 9 | Water Leak Detector | 0x0043 | WaterLeakDetector | 0x0020 |
| 10 | Water Freeze Detector | 0x0041 | WaterFreezeDetector | 0x0045 |
| 11 | Rain Sensor | 0x0044 | RainSensor | 0x0046 |
| 12 | Window Covering | 0x0202 | WindowCovering | 0x000E |
| 13 | Fan | 0x002B | Fan | 0x0048 |
| 14 | Water Valve | 0x0042 | GeneralValve | 0x004A |
| 15 | Flow Sensor | 0x0306 | FlowSensor | 0x004C |
| 16 | Air Purifier | 0x002D | AirPurifier | 0x004B |
| 17 | Laundry Washer | 0x0073 | LaundryWasher | 0x004E |
| 18 | Refrigerator | 0x0070 | Refrigerator | 0x004F |
| 19 | Room Air Conditioner | 0x0072 | AirConditioner | 0x000D |
| 20 | Dishwasher | 0x0075 | Dishwasher | 0x0050 |
| 21 | Laundry Dryer | 0x007C | LaundryDryer | 0x0051 |
| 22 | Oven (Range) | 0x007B | Oven | 0x0033 |
| 23 | Cooktop | 0x0078 | Cooktop | 0x0052 |
| 24 | Cook Surface | 0x0077 | CookSurface | 0x0053 |
| 25 | Extractor Hood | 0x007A | ExtractorHood | 0x0054 |
| 26 | Microwave Oven | 0x0079 | MicrowaveOven | 0x0055 |
| 27 | Robotic Vacuum Cleaner | 0x0074 | RoboticVacuumCleaner | 0x004D |
| 28 | Electric Vehicle Supply Equipment | 0x050C | ElectricVehicleSupplyEquipment | 0x0056 |
| 29 | Water Heater | 0x050F | WaterHeater | 0x0028 |
| 30 | Solar Power | 0x0017 | SolarPower | 0x0057 |
| 31 | Battery Storage | 0x0011 | BatteryStorage | 0x0058 |
| 32 | Heat Pump | 0x0309 | HeatPump | 0x0059 |
| 33 | Electrical Sensor | 0x0510 | ElectricalSensor | 0x0042 |
| 34 | Basic Video Player | 0x0028 | BasicVideoPlayer | 0x005A |
| 35 | Casting Video Player | 0x0023 | CastingVideoPlayer | 0x005B |
| 36 | Video Remote Control | 0x002A | VideoRemoteControl | 0x005C |
| 37 | Speaker | 0x0022 | Speaker | 0x0011 |
| 38 | Door Lock | 0x000A | DoorLock | 0x0016 |
| 39 | On/Off Light | 0x0100 | Switch | 0x000C |
| 40 | Dimmable Light | 0x0101 | Light | 0x000A |
| 41 | Color Temperature Light | 0x010C | Light | 0x000A |
| 42 | Extended Color Light | 0x010D | Light | 0x000A |
| 43 | On/Off Plug-in Unit | 0x010A | Outlet | 0x000B |
| 44 | Thermostat | 0x0301 | Thermostat | 0x002D |
| 45 | Occupancy Sensor | 0x0107 | OccupancySensor | 0x0027 |
| Occupancy Sensor | 0x0107 | MotionSensor | 0x0022 |
| 46 | Light Sensor | 0x0106 | IlluminanceSensor | 0x001A |
| 47 | Contact Sensor | 0x0015 | ContactSensor | 0x0015 |
| 48 | Temperature Sensor | 0x0302 | TemperatureSensor | 0x0017 |
| 49 | Humidity Sensor | 0x0307 | HumiditySensor | 0x0018 |
| 50 | Generic Switch | 0x000F | Button | 0x0024 |
| 51 | Bridge | 0x000E | BridgeNode | 0x0004 |
| 52 | Temperature Controlled Cabinet | 0x0071 | TemperatureControlledCabinet | 0x005E |
Zigbee Device Type Mapping
| No. | Zigbee Device Type | Zigbee Device Type ID | Aqara Spec Device Type | Aqara Spec Device Type ID |
|---|
| 1 | Aqara Root Node | 0x0016 | Public | 0x0001 |
| 2 | On/Off Switch | 0x0000 | Switch | 0x000C |
| 3 | Door Lock | 0x000A | DoorLock | 0x0016 |
| 4 | Smart Plug | 0x0051 | Outlet | 0x000B |
| 5 | On/Off Light | 0x0100 | Switch | 0x000C |
| 6 | Dimmable Light | 0x0101 | Light | 0x000A |
| 7 | Color Dimmable Light | 0x0102 | Light | 0x000A |
| 8 | Light Sensor | 0x0106 | IlluminanceSensor | 0x001A |
| 9 | Occupancy Sensor | 0x0107 | OccupancySensor | 0x0027 |
| 10 | Window Covering Device | 0x0202 | WindowCovering | 0x000E |
| 11 | Window Covering Controller | 0x0203 | WindowCovering | 0x000E |
| 12 | Thermostat | 0x0301 | Thermostat | 0x002D |
| 13 | Temperature Sensor | 0x0302 | TemperatureSensor | 0x0017 |
| 14 | Pump | 0x0303 | Pump | 0x0043 |
| 15 | Pressure Sensor | 0x0305 | AtmosphericPressureSensor | 0x0019 |
| 16 | Flow Sensor | 0x0306 | FlowSensor | 0x004C |
| 17 | Mini Split AC | 0x0307 | AirConditioner | 0x000D |
Binding
Introduction
Indicates the persistent binding relationship between an endpoint and one or more other local or remote Endpoints.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0001 | Binding | Binding |
Trait
Command
This Function does not contain Commands.
Data Types
BindingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the Binding Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DeviceID | characterString | M | Device ID of the target device. Maximum length 32 bytes. |
| 1 | ParentID | characterString | O | Device ID of the parent device to which the target device belongs. Not required if it is under the same preferred Matter controller as the binding party. Maximum length 32 bytes. |
| 2 | GroupID | uint32 | O | SHALL be set when the binding target is a device group (Conformance: GROUP). |
| 3 | ModelValue | characterString | O | For non-Matter devices, the target model value SHALL be set (Conformance: !MATTER). Maximum length 32 bytes. |
| 4 | EndPointID | uint32 | M | Endpoint ID of the target device. |
| 5 | DeviceTypeID | uint32 | M | Aqara Device Type ID of the target device. |
Trait Definitions
Binding Trait
Binding indicates the persistent relationship between an endpoint and one or more other local or remote Endpoints.
| Trait ID | Code |
|---|
| 0x0002 | Binding |
Parameters
SupportedBindingDeviceTypes Trait
Indicates the list of device types that can be bound by this controller endpoint.
| Trait ID | Code |
|---|
| 0x4E76 | SupportedBindingDeviceTypes |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
SupportedBindingFunctions Trait
Indicates the list of Function capabilities that this controller endpoint can bind and control.
| Trait ID | Code |
|---|
| 0x4E75 | SupportedBindingFunctions |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
Command Definitions
This Function does not contain Commands.
CO (Carbon Monoxide)
Introduction
Provides carbon monoxide concentration monitoring and alarm capabilities, used to detect carbon monoxide leaks in the environment and alert in time.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0009 | CO | Carbon monoxide |
Trait
Command
Data Types
ExpressedStateEnum8 Type
This enumeration defines the valid values of the Present Value of the ExpressedState Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | SmokeAlarm | Smoke leak |
| 0x02 | COAlarm | CO leak |
| 0x03 | BatteryAlert | Battery warning |
| 0x04 | Testing | Testing |
| 0x05 | HardwareFault | Hardware error |
| 0x06 | EndOfService | Service end |
| 0x07 | InterconnectSmoke | Interconnected smoke alarm |
| 0x08 | InterconnectCO | Interconnected CO alarm |
Trait Definitions
CODetected Trait
Indicates whether a carbon monoxide leak has been detected.
| Trait ID | Code |
|---|
| 0x0004 | CODetected |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ExpressedState Trait
ExpressedState defines the status of the alarm.
| Trait ID | Code |
|---|
| 0x0005 | ExpressedState |
Parameters
CODensity Trait
Indicates the carbon monoxide concentration in the air, used to monitor toxic gas risks and assist with ventilation linkage and safety alarms. Unit: mg/m^3.
| Trait ID | Code |
|---|
| 0x51A2 | CODensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 1000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
SelfTestRequest Command
SelfTestRequest indicates alarm self-test.
This Command has no parameters.
WaterFreezeDetector
Introduction
Used to detect the risk of freezing in pipes or the environment, and report water freezing related events when the threshold is reached.
Function Identification
| Function ID | Code | Name |
|---|
| 0x000A | WaterFreezeDetector | Water freeze detector |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BooleanState Trait
BooleanState describes how boolean values are used to represent statistics in the context of the device (possibly in a smart home system).
| Trait ID | Code |
|---|
| 0x000A | BooleanState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
RainSensor
Introduction
Used to detect rainfall status, reporting whether it is raining and related rainfall information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x000B | RainSensor | Rain sensor |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BooleanState Trait
BooleanState describes how boolean values are used to represent statistics in the context of the device (possibly in a smart home system).
| Trait ID | Code |
|---|
| 0x000A | BooleanState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Rainfall Trait
Indicates the rainfall intensity per unit time, which can be used to determine weather changes, on-site precipitation levels, and linkage conditions related to the outdoor environment. Unit: mm/min.
| Trait ID | Code |
|---|
| 0x51AE | Rainfall |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
OnOffSensor
Introduction
Used to detect binary switch input status, reporting discrete states such as on/off or triggered/not triggered.
Function Identification
| Function ID | Code | Name |
|---|
| 0x000C | OnOffSensor | On/off sensor |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BooleanState Trait
BooleanState describes how boolean values are used to represent statistics in the context of the device (possibly in a smart home system).
| Trait ID | Code |
|---|
| 0x000A | BooleanState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Introduction
Provides basic device information, including vendor, product model, firmware version, serial number, online status and other basic attributes.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0080 | BasicInformation | Basic device information |
Trait
Command
This Function does not contain Commands.
Data Types
ConfigurationVersionTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ConfigurationVersion Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ConfigurationVersion | uint32 | M | Device configuration version number. |
| 1 | ThingModelMd5 | characterString | M | Data model MD5 checksum. |
HubConnectionStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the HubConnectionStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Disconnected | Disconnected |
| 0x01 | Connected | Connected |
Trait Definitions
HardwareVersionString Trait
Specifies the version number of the node hardware. The value meaning and version numbering rules are defined by the vendor. This attribute provides a value that is easier for users to understand than the HardwareVersion attribute.
| Trait ID | Code |
|---|
| 0x8116 | HardwareVersionString |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
FirmwareRevisionString Trait
This Trait is used for access to and reporting of "firmware revision string" data.
| Trait ID | Code |
|---|
| 0x8117 | FirmwareRevisionString |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
ConfigurationVersion Trait
Used to store the device ConfigurationVersion and data model MD5. Each time the App directly connects to the device and builds a new data model, it compares this Trait with the cloud data model, then decides whether to update the data model or report the new Trait value.
| Trait ID | Code |
|---|
| 0x4F8E | ConfigurationVersion |
Parameters
DeviceID Trait
Indicates the unique identifier of the device.
| Trait ID | Code |
|---|
| 0x8089 | DeviceID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
Reachable Trait
Indicates whether the device is reachable. 0: Offline, 1: Online.
| Trait ID | Code |
|---|
| 0x8085 | Reachable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RV | M |
ProductName Trait
Specifies the readable (displayable) name of the node model, such as the model number (or other identifier) assigned by the vendor.
| Trait ID | Code |
|---|
| 0x8084 | ProductName |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
NodeLabel Trait
Indicates the custom name set by the user for the Matter node, with a string length of at most 32 bytes. When a Matter device is connected to Aqara, the device name preferentially uses a non-empty NodeLabel; when NodeLabel is empty, it falls back to displaying ProductName. After the user modifies the device name in Aqara Home, the gateway or App should write the custom name to the device's NodeLabel, which is saved by the device and synchronized through this Trait.
| Trait ID | Code |
|---|
| 0x5241 | NodeLabel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | string32 | Maximum 32 bytes | | RVW | O |
VendorID Trait
This Trait is used for access to and reporting of "vendor ID" data.
| Trait ID | Code |
|---|
| 0x8083 | VendorID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
VendorName Trait
This Trait is used for access to and reporting of "vendor name" data.
| Trait ID | Code |
|---|
| 0x8082 | VendorName |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
HubConnectionStatus Trait
Indicates the connection status between the device and the central Hub, used to determine whether the device is currently connected to the central Hub.
| Trait ID | Code |
|---|
| 0x4F52 | HubConnectionStatus |
Parameters
BLVersion Trait
Specifies the Bootloader version. UTF-8 characters with a maximum length of 64 bytes.
| Trait ID | Code |
|---|
| 0x4EE9 | BLVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
MCUVersion Trait
Specifies the MCU version. (Current value: String(64), default null)
| Trait ID | Code |
|---|
| 0x4EEB | MCUVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
RadarVersion Trait
Specifies the radar module version. (Current value: String(64), default null)
| Trait ID | Code |
|---|
| 0x4EEA | RadarVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ChipTemperature Trait
Indicates the current temperature measured by the device. Unit: deg C.
| Trait ID | Code |
|---|
| 0x4E7F | ChipTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 1000.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
ManufacturerChipID Trait
Identifies the manufacturer chip ID.
| Trait ID | Code |
|---|
| 0x4EA4 | ManufacturerChipID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
DeviceXCode Trait
Indicates the device type X code of the device.
Valid X code range is 1 to 65534. 0 and 65535 are invalid X code values, both indicating that the device has no X code; the default value is 65535.
| Trait ID | Code |
|---|
| 0x4E9E | DeviceXCode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | 1 to 65534; 65535 is the default no-X-code marker | 65535 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65534 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ModelValue Trait
AIOT model value, e.g., lumi.gateway.cn01.
| Trait ID | Code |
|---|
| 0x8175 | ModelValue |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ConfigurationFlag Trait
Indicates the configuration status. When the flag is set to 1, the device must be configured before normal use.
| Trait ID | Code |
|---|
| 0x816F | ConfigurationFlag |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
MatterSpecificationVersion Trait
This Trait is used for access to and reporting of "Matter specification version" data.
| Trait ID | Code |
|---|
| 0x8147 | MatterSpecificationVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
PartNumber Trait
This Trait is used for access to and reporting of "part number" data.
| Trait ID | Code |
|---|
| 0x8146 | PartNumber |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
SupportedMatterRoles Trait
Indicates the Matter roles supported by the device, such as Thread Border Router, Matter Controller, Matter Commissioner, and Matter Bridge. Each bit represents one role.
| Trait ID | Code |
|---|
| 0x8120 | SupportedMatterRoles |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ProductID Trait
Specifies the numeric ID assigned by the vendor to uniquely identify the specific product of this node.
| Trait ID | Code |
|---|
| 0x8118 | ProductID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Mac Trait
Specifies the IEEE 802 link MAC (Wi-Fi or Ethernet) of the device. The BLE address and Magic Pair Unique ID are not values of this Trait; the Unique ID can be found in ref_MagicPairOnboardingPayload.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
Location Trait
This Trait is used for access to and reporting of "location" data.
| Trait ID | Code |
|---|
| 0x8087 | Location |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
HardwareVersion Trait
Specifies the version number of the node hardware. The value meaning and version numbering rules are defined by the vendor.
| Trait ID | Code |
|---|
| 0x8086 | HardwareVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | 0 | RV | O |
| 0x0002 | Maximum Value | characterString | | 4294967295 | R | O |
| 0x0003 | Minimum Value | characterString | | 0 | R | O |
SerialNumber Trait
This Trait is used for access to and reporting of "serial number" data.
| Trait ID | Code |
|---|
| 0x8081 | SerialNumber |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
FirmwareRevision Trait
Contains the current version number of the software running on this node.
| Trait ID | Code |
|---|
| 0x8080 | FirmwareRevision |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | 0 | RV | O |
| 0x0002 | Maximum Value | characterString | | 4294967295 | R | O |
| 0x0003 | Minimum Value | characterString | | 0 | R | O |
AIModelVersion Trait
Version string of the current AI algorithm model.
| Trait ID | Code |
|---|
| 0x4FC4 | AIModelVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
LogicBlockVersion Trait
Logic Block Firmware Version. Indicates the firmware version of the Aqara Studio logic block, used to identify the specific version of the logic block firmware for OTA upgrades, compatibility determination and troubleshooting.
| Trait ID | Code |
|---|
| 0x5146 | LogicBlockVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ThermostatBaseSN Trait
Thermostat base serial number (SN), used to uniquely identify the hardware identity information of the thermostat base. It is typically used for device registration, after-sales tracking and production traceability.
| Trait ID | Code |
|---|
| 0x5155 | ThermostatBaseSN |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ThermostatBaseFWVersion Trait
Indicates the firmware version of the thermostat base. The version number consists of five parts separated by dots: integrator.Air conditioner brand.Fresh air brand.Floor heating brand.Version number. This version number is used to identify the base firmware version for OTA upgrades, compatibility checks and troubleshooting.
| Trait ID | Code |
|---|
| 0x515E | ThermostatBaseFWVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
Command Definitions
This Function does not contain Commands.
Descriptor
Introduction
Describes the device endpoint composition and capability structure, including endpoint list, device types, Server/Client clusters and other information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0081 | Descriptor | Device capability description |
Trait
Command
This Function does not contain Commands.
Data Types
EndpointStructureNodeStructure Type
This structure defines the nested child node field layout of EndpointStructure.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EndpointId | uint16 | M | Endpoint ID. |
| 1 | ChildEndpoints | list[EndpointStructureNodeStructure] | O | List of child Endpoint nodes, used to express the nested hierarchy. |
EndpointStructureTraitPresentValueStructure Type
This structure defines the Present Value field layout of the EndpointStructure Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EndpointId | uint16 | M | Root Endpoint ID. |
| 1 | ChildEndpoints | list[EndpointStructureNodeStructure] | O | Child Endpoint hierarchy structure. |
Trait Definitions
EndpointCount Trait
Indicates the number of Endpoints contained in the current Device.
| Trait ID | Code |
|---|
| 0x808C | EndpointCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 3 | RV | M |
| 0x0002 | Maximum Value | int32 | | 65279 | R | O |
| 0x0003 | Minimum Value | int32 | | 2 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
EndpointDeviceTypes Trait
Describes the Device Type of each Endpoint in all configuration instances of the current Device, used together with EndpointArray or EndpointArrayDynamic.
| Trait ID | Code |
|---|
| 0x808E | EndpointDeviceTypes |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | M |
SupportedEndpointDynamic Trait
Indicates whether the current Device instance supports dynamic configuration.
| Trait ID | Code |
|---|
| 0x808A | SupportedEndpointDynamic |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
EndpointArray Trait
Describes all possible combinations of Endpoints contained in the current Device. Used together with SupportedEndpointDynamic, EndpointDynamicCount and SelectedEndpointDynamic.
| Trait ID | Code |
|---|
| 0x808D | EndpointArray |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
EndpointFunctions Trait
This Trait is used for access to and reporting of "endpoint functions" data.
| Trait ID | Code |
|---|
| 0x808F | EndpointFunctions |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
EndpointArrayDynamic Trait
Describes the Endpoint combination used by the current Device instance. Mutually exclusive with EndpointArray (only one is valid at a time).
| Trait ID | Code |
|---|
| 0x80F5 | EndpointArrayDynamic |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
EndpointDynamicCount Trait
Indicates the number of dynamic Endpoint configuration instances supported by the current Device. Default value is 1.
| Trait ID | Code |
|---|
| 0x808B | EndpointDynamicCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RV | O |
| 0x0002 | Maximum Value | int32 | | 65279 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
SelectedEndpointDynamic Trait
Indicates the array index of EndpointArray, identifying the currently selected Device Endpoint configuration instance.
| Trait ID | Code |
|---|
| 0x8090 | SelectedEndpointDynamic |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | int32 | | 65279 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | int32 | | 0 | RW | O |
EndpointStructure Trait
Describes the Endpoint hierarchy (nested relationship) in the configuration instance used by the current Device.
| Trait ID | Code |
|---|
| 0x8156 | EndpointStructure |
Parameters
Command Definitions
This Function does not contain Commands.
EndpointLabel
Introduction
Manages endpoint visibility and display information, such as name, room, icon, tags, etc., for front-end display and organization.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0082 | EndpointLabel | Endpoint label |
Trait
Command
This Function does not contain Commands.
Data Types
EndpointApplianceTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the EndpointApplianceType Trait.
| Value | Name | Description |
|---|
| Light | Light fixture | Used to represent an endpoint for light fixtures or lighting control functions. |
| Switch | Switch | Used to represent an endpoint that controls the on/off state of a circuit or device. |
| Outlet | Socket | Used to represent an endpoint for a controlled power outlet or power output. |
| Fan | Fan | Used to represent an endpoint for fan-type devices. |
| Ventilation | Fresh air device | Used to represent an endpoint for fresh air or ventilation devices. |
| AirConditioner | Air conditioner | Used to represent an endpoint for air conditioner devices. |
| AirPurifier | Air purifier | Used to represent an endpoint for air purification devices. |
| Humidifier | Humidifier | Used to represent an endpoint for devices that increase ambient humidity. |
| Dehumidifier | Dehumidifier | Used to represent an endpoint for devices that decrease ambient humidity. |
| TV | TV | Used to represent an endpoint for TV devices. |
| Refrigerator | Refrigerator | Used to represent an endpoint for refrigerators or cold storage devices. |
| Computer | Computer | Used to represent an endpoint for computer devices. |
| WaterHeater | Water heater | Used to represent an endpoint for devices that prepare or supply hot water. |
| Kettle | Electric kettle | Used to represent an endpoint for kettle-type devices. |
| MicrowaveOven | Microwave oven | Used to represent an endpoint for microwave heating or cooking devices. |
| Hub | Gateway | Used to represent an endpoint for gateway or hub devices. |
| ContactSensor | Contact sensor | Used to represent a sensor endpoint that detects the opening/closing or contact state of objects such as doors and windows. |
| Door | Door | Used to represent an endpoint for door bodies or door-type devices. |
| Window | Window | Used to represent an endpoint for window bodies or window-type devices. |
| Cabinet | Cabinet | Used to represent an endpoint for cabinets or cabinet-type devices. |
| Other | Other | Used to represent an endpoint for appliances or devices not classified into the above categories. |
Trait Definitions
EndpointVisibility Trait
Describes the visibility of all Endpoints contained in the current Device. 0: Invisible, 1: Visible.
| Trait ID | Code |
|---|
| 0x8093 | EndpointVisibility |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RV | M |
EndpointName Trait
Describes the Endpoint name, in string format, maximum length 32.
| Trait ID | Code |
|---|
| 0x8091 | EndpointName |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
EndpointRoom Trait
Describes the ID of the room where the Endpoint is located, in string format, maximum length 32 bytes.
| Trait ID | Code |
|---|
| 0x8092 | EndpointRoom |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
EndpointRoomName Trait
Describes the name of the room where the Endpoint is located, in string format, maximum length 128 bytes.
| Trait ID | Code |
|---|
| 0x80F8 | EndpointRoomName |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
EndpointIcon Trait
Describes the current icon ID. The selectable icon list varies by Device Type and cannot be customized by the vendor.
| Trait ID | Code |
|---|
| 0x8097 | EndpointIcon |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
EndpointApplianceType Trait
Describes the current appliance type (e.g., Light, Fan, Air Conditioner, etc.). The selectable type list varies by Device Type.
| Trait ID | Code |
|---|
| 0x80A1 | EndpointApplianceType |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
| 0x0006 | Supported Value | list[characterString] | | | R | O |
EndpointStatistics Trait
Describes whether the device can be included in statistics functions.
| Trait ID | Code |
|---|
| 0x80F4 | EndpointStatistics |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EndpointTag Trait
The current value of this attribute should be the ID of a semantic tag within the namespace. 0 indicates the "aggregation" capability, and N (N > 0) specifies the capability of the Nth channel.
| Trait ID | Code |
|---|
| 0x8154 | EndpointTag |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain Commands.
Identify
Introduction
Provides device identification capability, helping users locate a physical device through indicator blinking, sounds, etc.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0083 | Identify | Identify |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x8096 | Identify | Identify | M |
Data Types
IdentifyTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the IdentifyType Trait.
| Value | Name | Description |
|---|
| 0x00 | None | None |
| 0x01 | Light | Light |
| 0x02 | LEDIndicator | LEDIndicator |
| 0x03 | AudibleBeep | AudibleBeep |
| 0x04 | Display | Display |
| 0x05 | Actuator | Actuator |
Identify Command Structure Type
Parameter structure of the Identify Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | IdentifyTime | uint16 | M | Remaining time in seconds for the device to continue self-identifying. When the value is 0, the device MAY use the default identification duration. |
Trait Definitions
IdentifyTime Trait
Indicates the remaining duration (in seconds) during which the device will continue self-identifying. Value range is 0 to 10, step 0.1, unit seconds (s). When the value is 0, the default remaining duration is used.
| Trait ID | Code |
|---|
| 0x8094 | IdentifyTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
IdentifyType Trait
Specifies the way identification is presented to the user. Values: 0 = None, 1 = Light, 2 = LED indicator, 3 = Sound, 4 = Display (visible on screen), 5 = Actuator (e.g., curtain or relay action), 6-255 = Reserved.
| Trait ID | Code |
|---|
| 0x8095 | IdentifyType |
Parameters
ReverseIdentify Trait
When triggered (through a local operation on the device, such as button press or touch screen interaction), the device sends a signal to all connected client tools (e.g., mobile App, Web application, or desktop software) to locate and identify the corresponding device in that tool. The user can physically operate the device to quickly find it in the tool.
| Trait ID | Code |
|---|
| 0x8136 | ReverseIdentify |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | V | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
| Command ID | Name | Conformance |
|---|
| 0x8096 | Identify | M |
Identify Command
When written, starts or stops device self-identification.
Parameters
Identify Command Structure
Output
Introduction
Provides switch output control capability, supporting reading and controlling the on/off state of the load.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0084 | Output | Output |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x811A | Off | Off | O |
| 0x8119 | On | On | O |
| 0x809A | Toggle | Toggle | O |
Data Types
StartUpOnOffEnum8 Type
This enumeration defines the valid values of the Present Value of the StartUpOnOff Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off at power-on |
| 0x01 | On | On at power-on |
| 0x02 | Toggle | Invert at power-on |
| 0x03 | Hold | Memory at power-on |
OutputSwitchingTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the OutputSwitchingType Trait.
| Value | Name | Description |
|---|
| 0x01 | NonResettableSwitch | Non-rebound switch |
| 0x02 | MomentaryPushSwitch | Rebound switch |
| 0x03 | ActiveLowCloseRelay | Low-level closed relay |
| 0x04 | InsertCardOnMode | Card insertion power-on mode |
| 0x05 | InsertCardOffMode | Card insertion power-off mode |
OutputNodeModeEnum32 Type
This enumeration defines the valid values of the Present Value of the OutputNodeMode Trait.
| Value | Name | Description |
|---|
| 0x00 | WetMode | Wet node mode |
| 0x01 | DryPulseNormallyClosed | Dry node pulse normally closed mode |
| 0x02 | DryPulseNormallyOpen | Dry node pulse normally open mode |
| 0x03 | DryToggleMode | Dry node on/off mode |
Trait Definitions
OnOff Trait
When written, turns the device on or off, i.e. controls the device switch state. Reading indicates the current switch state. Values: false = Off, true = On.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | | RVW | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
StartUpOnOff Trait
Defines the startup behavior of a set of custom configuration parameters when the device powers on (e.g., restoring user-customized configurations). It may override the default OnOff behavior.
| Trait ID | Code |
|---|
| 0x8099 | StartUpOnOff |
Parameters
OutputSwitchingType Trait
Defines the type of external switch connected to the device.
| Trait ID | Code |
|---|
| 0x4E87 | OutputSwitchingType |
Parameters
OutputNodeMode Trait
Defines the working mode of the output node.
| Trait ID | Code |
|---|
| 0x4E86 | OutputNodeMode |
Parameters
OutputInterlockFlag Trait
When the values of two attributes are the same, the states corresponding to these two attributes are in an interlock relationship.
| Trait ID | Code |
|---|
| 0x4E85 | OutputInterlockFlag |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
Command Definitions
| Command ID | Name | Conformance |
|---|
| 0x811A | Off | O |
| 0x8119 | On | O |
| 0x809A | Toggle | O |
Off Command
This Command is used to perform the "Off" operation.
This Command has no parameters.
On Command
This Command is used to perform the "On" operation.
This Command has no parameters.
Toggle Command
This Command is used to perform the "Toggle" operation.
This Command has no parameters.
LevelControl
Introduction
Provides brightness level adjustment capability, supporting setting/reading the current brightness, step dimming, and dimming control linked or decoupled with the switch.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0085 | LevelControl | Level control |
Trait
Command
Data Types
StepBrightnessWithOnOff Command Structure Type
Parameter structure of the StepBrightnessWithOnOff Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Size | float | M | Brightness step value, range -100 ~ 100; positive means increase, negative means decrease, unit %. |
| 1 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
SetBrightnessWithOnOff Command Structure Type
Parameter structure of the SetBrightnessWithOnOff Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Level | float | M | Target brightness value, range 1 ~ 100, unit %; default value 50. |
| 1 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
SetBrightness Command Structure Type
Parameter structure of the SetBrightness Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Level | float | M | Target brightness value, range 1 ~ 100, unit %; default value 50. |
| 1 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 2 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of the CurrentLevel Trait. |
StepBrightness Command Structure Type
Parameter structure of the StepBrightness Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Size | float | M | Brightness step value, range -100 ~ 100; positive means increase, negative means decrease, unit %. |
| 1 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 2 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of the CurrentLevel Trait. |
Trait Definitions
CurrentLevel Trait
This Trait indicates the current brightness level and is the core state value of Level Control.
On the Matter side (light-type devices), a level range of 1-254 is commonly used; the Aqara side uses percentage semantics, with mapping examples of 1%=1, 50%=127, 100%~=254.
| Trait ID | Code |
|---|
| 0x809B | CurrentLevel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
| 0x000B | Maximum Actual Value | float | | | RVW | O |
| 0x000C | Minimum Actual Value | float | | | RVW | O |
DimmingCurvature Trait
This Trait is used to indicate the power value of the dimming algorithm curve, which controls the change speed and dwell time of brightness in the low-brightness region (near the minimum brightness range).
The value range is 0.1 to 10.0. The device should apply curve mapping within this range and adjust the subjective visual rhythm of the brightness transition accordingly.
- When the value is
1.0, it indicates a linear dimming curve, where brightness changes at an approximately uniform rate over time.
- When the value is greater than
1.0, the low-brightness region changes more slowly and dwells longer, making the overall visual effect closer to "slow start, then accelerating at the end".
- When the value is less than
1.0, the low-brightness region passes through faster, brightness enters the medium-high region earlier, and the visual start-up is more direct.
The larger the value, the higher the proportion of transition time occupied by the low-brightness region; the smaller the value, the lower the proportion. This parameter only affects the shape of the transition curve and does not change the target brightness range of the command.
| Trait ID | Code |
|---|
| 0x4EAC | DimmingCurvature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1.5 | RVW | O |
| 0x0002 | Maximum Value | float | | 10.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.1 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 1.5 | RW | O |
StartUpBrightness Trait
This Trait indicates the start-up brightness used by the device after power-on (when the light is turned on). Unit: %.
| Trait ID | Code |
|---|
| 0x4E8A | StartUpBrightness |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
OffTransitionTime Trait
This Trait is used to indicate the brightness transition duration when the On/Off Cluster of the same endpoint receives the Off command.
Its semantics are: the device should gradually transition CurrentLevel from the maximum brightness to the minimum brightness allowed by the device (usually corresponding to the off state) within this duration.
The unit of this value is ms. For example, a value of 1000 means 1000 ms, i.e., a 1 s off transition duration.
When this Trait is not implemented, or the Present Value is null, the device should fall back to the configuration of OnOffTransitionTime.
| Trait ID | Code |
|---|
| 0x8166 | OffTransitionTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | int32 | | 10000 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 500 | R | O |
| 0x0007 | Default Value | int32 | | 0 | RW | O |
OnTransitionTime Trait
This Trait is used to indicate the brightness transition duration when the On/Off Cluster of the same endpoint receives the On command.
Its semantics are: the device should gradually transition CurrentLevel from the minimum brightness allowed by the device to the maximum brightness within this duration.
The unit of this value is ms. For example, a value of 1000 means 1000 ms, i.e., a 1 s on transition duration.
When this Trait is not implemented, or the Present Value is null, the device should fall back to the configuration of OnOffTransitionTime.
| Trait ID | Code |
|---|
| 0x8165 | OnTransitionTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | int32 | | 10000 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 500 | R | O |
| 0x0007 | Default Value | int32 | | 0 | RW | O |
InitialBrightness Trait
This Trait indicates the starting brightness when the device begins the brightness transition after power-on or reset.
If a target brightness is configured, the device should start from this initial brightness and gradually transition to the target brightness. Unit: %.
| Trait ID | Code |
|---|
| 0x4F8B | InitialBrightness |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 50 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
Command Definitions
StepBrightnessWithOnOff Command
This command is used to perform brightness step adjustment with switch linkage.
When the brightness drops near the minimum level, the device may synchronously update the switch state according to the linkage semantics.
Effect on Receipt
After receiving this command, the device should first perform the brightness step according to the semantics of StepBrightness:
- When
Size = 0, the command has no effect and should return INVALID_COMMAND.
- When
Size ≠ 0, update CurrentLevel according to the step direction and step size; if the minimum/maximum boundary allowed by the device is reached, stop at the boundary and shorten the actual transition duration proportionally.
On top of the above behavior, this command should also perform switch linkage:
- If the command effect would make CurrentLevel higher than the device minimum level, the OnOff of the same endpoint should be set to
TRUE (On).
- If the command effect would make CurrentLevel reach the device minimum level, the OnOff of the same endpoint should be set to
FALSE (Off).
Parameters
StepBrightnessWithOnOff Command Structure
SetBrightnessWithOnOff Command
This command is used to perform target brightness setting with switch linkage.
Compared with SetBrightness, this command supports affecting the switch state while setting the brightness.
Effect on Receipt
After receiving this command, the device should first, according to the semantics of SetBrightness, continuously transition from the current brightness to the target brightness.
- The transition duration preferentially uses the
Time in the command.
- When
Time is empty, the device transition duration configuration should be used; if no configuration is available, the transition should be completed as fast as the device can achieve.
On top of the above behavior, this command should also perform switch linkage:
- If the command effect would make CurrentLevel higher than the device minimum level, the OnOff of the same endpoint should be set to
TRUE (On).
- If the command effect would make CurrentLevel reach the device minimum level, the OnOff of the same endpoint should be set to
FALSE (Off).
Parameters
SetBrightnessWithOnOff Command Structure
SetBrightness Command
This command is used to set the target brightness without changing the on/off state of the light.
Effect on Receipt
After receiving this command, the device should continuously transition from the current brightness to the target value specified by Level.
- The transition duration preferentially uses the
Time in the command.
- When
Time is empty, the device transition duration configuration should be used; if no configuration is available, the transition should be completed as fast as the device can achieve.
If the device does not support variable-rate transition, the transition duration field may be ignored.
Parameters
SetBrightness Command Structure
StepBrightness Command
This command is used to perform brightness step adjustment without changing the on/off state of the light.
Effect on Receipt
When Size = 0, the command has no effect and should return INVALID_COMMAND.
When Size ≠ 0, the device should perform the brightness change according to the step direction:
Up: increase CurrentLevel by Size, or stop when the device maximum level is reached; if the boundary is reached early, the transition duration should be shortened proportionally.Down: decrease CurrentLevel by Size, or stop when the device minimum level is reached; if the boundary is reached early, the transition duration should be shortened proportionally.
Parameters
StepBrightness Command Structure
ColorControl
Introduction
Provides color control capability, supporting adjustment of light color through HSV, XY and color temperature modes, and supporting combined delivery with brightness commands.
This Function provides the light color adjustment interface. Color definition follows the CIE 1931 color space, with the core control method being x, y chromaticity coordinates (corresponding to ColorXY / CurrentX / CurrentY).
In addition, color can optionally be controlled through ColorTemperature or Hue + Saturation; Hue and Saturation are recommended to be interpreted according to the HSV (HSB) model. RGB/W primary point capabilities can be used to extend the color expression range.
This Function does not handle brightness control; brightness is provided by the LevelControl Function. During linkage control, the brightness value in LevelControl should be interpreted as "the ratio of the maximum light intensity achievable at the current color".
Function Identification
| Function ID | Code | Name |
|---|
| 0x0086 | ColorControl | Color control |
Trait
Command
Data Types
ColorModeEnum8 Type
This enumeration defines the valid values of the Present Value of the ColorMode Trait.
| Value | Name | Description |
|---|
| 0x00 | HSV | Current color determined by Hue and Saturation |
| 0x01 | XY | Current color determined by CurrentX and CurrentY |
| 0x02 | ColorTemperature | Current color determined by the color temperature value |
ColorPointRGBXYPresentValueStructure Type
This structure defines the Present Value field layout of ColorPointRGBXY.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ColorPointRX | uint16 | M | This parameter represents the normalized chromaticity value x of the device's current red primary point defined in the CIE xyY color space. x and the ColorPointRX attribute satisfy: x = ColorPointRX / 65536 (ColorPointRX value range is 0 to 65279, inclusive). |
| 1 | ColorPointRY | uint16 | M | This parameter represents the normalized chromaticity value y of the device's current red primary point defined in the CIE xyY color space. y and the ColorPointRY attribute satisfy: y = ColorPointRY / 65536 (ColorPointRY value range is 0 to 65279, inclusive). |
| 2 | ColorPointGX | uint16 | M | This parameter represents the normalized chromaticity value x of the device's current green primary point defined in the CIE xyY color space. x and the ColorPointGX attribute satisfy: x = ColorPointGX / 65536 (ColorPointGX value range is 0 to 65279, inclusive). |
| 3 | ColorPointGY | uint16 | M | This parameter represents the normalized chromaticity value y of the device's current green primary point defined in the CIE xyY color space. y and the ColorPointGY attribute satisfy: y = ColorPointGY / 65536 (ColorPointGY value range is 0 to 65279, inclusive). |
| 4 | ColorPointBX | uint16 | M | This parameter represents the normalized chromaticity value x of the device's current blue primary point defined in the CIE xyY color space. x and the ColorPointBX attribute satisfy: x = ColorPointBX / 65536 (ColorPointBX value range is 0 to 65279, inclusive). |
| 5 | ColorPointBY | uint16 | M | This parameter represents the normalized chromaticity value y of the device's current blue primary point defined in the CIE xyY color space. y and the ColorPointBY attribute satisfy: y = ColorPointBY / 65536 (ColorPointBY value range is 0 to 65279, inclusive). |
WhitePointXYPresentValueStructure Type
This structure defines the Present Value field layout of WhitePointXY.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | WhitePointX | uint16 | M | This parameter represents the normalized chromaticity value x of the device's current white point defined in the CIE xyY color space. x and the WhitePointX attribute satisfy: x = WhitePointX / 65536 (WhitePointX value range is 0 to 65279, inclusive). |
| 1 | WhitePointY | uint16 | M | This parameter represents the normalized chromaticity value y of the device's current white point defined in the CIE xyY color space. y and the WhitePointY attribute satisfy: y = WhitePointY / 65536 (WhitePointY value range is 0 to 65279, inclusive). |
LEDICProtocolEnum8 Type
This enumeration defines the valid values of the Present Value of the LEDICProtocol Trait.
| Value | Name | Description |
|---|
| 0x01 | SID | Single-wire zero code |
LEDTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the LEDType Trait.
| Value | Name | Description |
|---|
| 0x00 | RGBW | RGBW light-color LED bead |
LightingMusicSyncModeEnum8 Type
This enumeration defines the valid values of the Present Value of the LightingMusicSyncMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Random | Random |
| 0x01 | Breath | Breathing |
| 0x02 | Rainbow | Rainbow |
| 0x03 | WaterFlow | Flowing |
LightingDynamicSceneModeEnum8 Type
This enumeration defines the valid values of the Present Value of the LightingDynamicSceneMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Breath | Breathing |
| 0x01 | ForwardRainbow | Forward rainbow |
| 0x02 | WaterFlow | Flowing |
| 0x03 | Flicker | Blinking |
| 0x04 | Jump | Jumping |
| 0x05 | ReverseRainbow | Reverse rainbow |
| 0x06 | Floating | Floating |
| 0x07 | Running | Running |
OtaDynamicColorSequenceResultEnum8 Type
This enumeration defines the valid values of the Present Value of the OtaDynamicColorSequenceResult Trait.
| Value | Name | Description |
|---|
| 0x00 | Delivering | Transmitting |
| 0x01 | Success | Success |
| 0x02 | Uninitialized | Not initialized |
| 0x03 | Idle | Idle |
| 0x04 | SameVersion | No upgrade needed, same version |
| 0x05 | OtaInProgress | OTA in progress |
| 0x06 | DeviceError | Failed_device returned |
| 0x07 | Timeout | Failed_timeout |
| 0x08 | OtaBusy | Failed_OTA in progress |
| 0x09 | FileFetchFailed | Failed_file not obtained |
| 0x0A | NoMemory | Failed_memory allocation unsuccessful |
| 0x0B | InvalidCommandParameter | Invalid command parameter |
| 0x11 | DongleUpgrading | dongle upgrading |
| 0x12 | DongleChipInfoFailed | dongle upgrade failed to obtain chip information |
| 0x13 | DongleChipInfoParseFailed | dongle upgrade failed to parse chip information |
| 0x14 | DongleVersionIncompatible | dongle upgrade version incompatible |
| 0x15 | DongleFlashWriteFailed | dongle upgrade failed to write flash |
IsInDynamicColorSequenceEnum8 Type
This enumeration defines the valid values of the Present Value of the IsInDynamicColorSequence Trait.
| Value | Name | Description |
|---|
| 0x00 | NotInSequence | Not in dynamic sequence mode |
| 0x01 | InSequence | In dynamic sequence mode |
DynamicSequenceModeEnum8 Type
This enumeration defines the valid values of the Mode field in the dynamic sequence configuration.
| Value | Name | Description |
|---|
| 0x00 | Level | Level mode |
| 0x01 | LevelColorTemperature | Level + color temperature mode |
| 0x02 | LevelXY | Level + XY mode |
| 0x03 | SegmentedLevelXYStatic | Level + XY segmented mode (static) |
| 0x04 | SegmentedLevelXYDynamic | Level + XY segmented mode (dynamic) |
| 0x05 | PureId | Pure ID mode |
DynamicSequenceOperationFunctionCodeEnum8 Type
This enumeration defines the valid values of the FunctionCode field in DynamicSequenceOperation.
| Value | Name | Description |
|---|
| 0x00 | FunctionSendPreview | Send custom sequence data (preview, not persisted) |
| 0x01 | FunctionSave | Send custom sequence data (persisted, requires later startup) |
| 0x02 | FunctionStart | Start sequence mode (using SequenceID) |
| 0x03 | FunctionDelete | Delete custom sequence mode (using SequenceID) |
| 0x04 | FunctionStop | Stop the current sequence mode (ignoring SequenceID) |
| 0x80 | StatusSuccess | Operation successful |
| 0x81 | StatusIncomplete | Request received but operation not completed |
| 0x82 | StatusInternalError | Internal error (e.g., insufficient storage, data corruption) |
| 0x83 | StatusInvalidAttribute | Illegal attribute value (e.g., ID does not exist, wrong step count) |
| 0x84 | StatusOtaReady | The device has exited the previous OTA and can perform the next OTA |
SequenceStepStructure Type
Parameter structure of a single step of a dynamic sequence.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Duration | uint32 | M | Hold time of this step, in milliseconds (ms). |
| 1 | LightLevel | uint8 | M | Brightness value, range 0-255 (0 means off). |
| 2 | TransitionTime | uint32 | M | Time to transition to this step, in milliseconds (ms). |
| 3 | XY | uint32 | O | Color value (XY encoded). |
| 4 | ColorTemp | uint16 | O | Color temperature value (micro reciprocal degree, 1000000 / K). |
SequenceStructDataStructure Type
Main structure of a dynamic sequence.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Channel | uint8 | M | Channel number of the light strip (0 indicates the main channel or monochrome light). |
| 1 | Cycles | uint16 | M | Number of loop executions (0 means infinite loop). |
| 2 | EndAction | characterString | M | End action: 0x00 turns off the light, 0x02 keeps the last sequence state. |
| 3 | Mode | DynamicSequenceModeEnum8 | M | Sequence mode. |
| 4 | Queues | list[SequenceStepStructure] | M | Step list. |
DynamicColorSequenceInfoStructure Type
Complete information structure of a dynamic sequence.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SequenceID | uint32 | M | Sequence ID. |
| 1 | SequenceStructData | SequenceStructDataStructure | M | Sequence content. |
| 2 | SequenceName | characterString | M | Sequence name. |
| 3 | IconID | characterString | M | Icon ID. |
| 4 | UpdateTime | uint32 | O | Update time. |
| 5 | Source | uint8 | O | Source (e.g., 1 indicates AI). |
| 6 | Type | characterString | M | Type: inner (built-in) or self (custom). |
| 7 | State | uint32 | M | Status (1 indicates success). |
DynamicSequenceOperationTraitPresentValueStructure Type
Parameter structure of the DynamicSequenceOperation Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SequenceID | uint32 | M | ID of the dynamic/static sequence mode. Recommended range: 0x00-0x3F (custom dynamic), 0x40-0x7F (preset dynamic), 0x80-0x9F (preset static), 0xA0-0xBF (custom static), 0xFF (not specified). |
| 1 | FunctionCode | DynamicSequenceOperationFunctionCodeEnum8 | M | Function code when sent by the client; status code when reported by the device. |
| 2 | ChannelMask | uint32 | M | Channel mask of a multi-channel device. Bit0-Bit3 correspond to channels 1-4, Bit4-Bit7 are reserved and should be 0. Only valid when stopping (0x04) or sending data (0x00/0x01); otherwise set to 0. |
SaveDynamicColorSequence Command Structure Type
Parameter structure of the SaveDynamicColorSequence Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SequenceID | uint32 | O | May be left empty when adding; the server assigns a new sequence ID. |
| 1 | SequenceStructData | SequenceStructDataStructure | M | Main structure of the sequence. |
| 2 | SequenceName | characterString | M | Sequence name. |
| 3 | IconID | characterString | M | Icon ID; not reported by the device, maintained on the server side. |
| 4 | UpdateTime | uint32 | O | Not reported by the device, maintained on the server side. |
| 5 | Source | uint8 | O | Not reported by the device, maintained on the server side. |
PreviewDynamicColorSequence Command Structure Type
Parameter structure of the PreviewDynamicColorSequence Command.
RemoveDynamicColorSequence Command Structure Type
Parameter structure of the RemoveDynamicColorSequence Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SequenceID | uint32 | M | Sequence ID to be deleted. |
GetDynamicColorSequenceData Command Structure Type
Request parameter structure of the GetDynamicColorSequenceData Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SequenceID | uint32 | M | Sequence ID to be queried. |
StartDynamicColorSequence Command Structure Type
Parameter structure of the StartDynamicColorSequence Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SequenceID | uint32 | M | Sequence ID to be executed. |
MoveToXYColorBrightness Command Structure Type
Parameter structure of the MoveToXYColorBrightness Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ColorX | uint16 | M | Target color X value, range 0 ~ 0xFEFF. |
| 1 | ColorY | uint16 | M | Target color Y value, range 0 ~ 0xFEFF. |
| 2 | Level | float | M | Target brightness value, range 1 ~ 100, unit %; default value 50. |
| 3 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 4 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
MoveToColorTemperatureBrightness Command Structure Type
Parameter structure of the MoveToColorTemperatureBrightness Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ColorTemperature | uint32 | M | Target color temperature value (micro reciprocal degree). |
| 1 | Level | float | M | Target brightness value, range 1 ~ 100, unit %; default value 50. |
| 2 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 3 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
MoveToHueSaturationBrightness Command Structure Type
Parameter structure of the MoveToHueSaturationBrightness Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Hue | float | M | Hue value, range 0 ~ 360. |
| 1 | Saturation | float | M | Saturation value. |
| 2 | Level | float | M | Target brightness value, range 1 ~ 100, unit %; default value 50. |
| 3 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 4 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
MoveToXYColor Command Structure Type
Parameter structure of the MoveToXYColor Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ColorX | uint16 | M | Target color X value, range 0 ~ 0xFEFF. |
| 1 | ColorY | uint16 | M | Target color Y value, range 0 ~ 0xFEFF. |
| 2 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 3 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
MoveToHueAndSaturation Command Structure Type
Parameter structure of the MoveToHueAndSaturation Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Hue | float | M | Hue value, range 0 ~ 360. |
| 1 | Saturation | float | M | Saturation value. |
| 2 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 3 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
MoveToColorTemperature Command Structure Type
Parameter structure of the MoveToColorTemperature Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ColorTemperature | uint32 | M | Target color temperature value (micro reciprocal degree). |
| 1 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 2 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
StepColorTemperature Command Structure Type
Parameter structure of the StepColorTemperature Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Size | int32 | M | Color temperature step value, range -370 ~ 370; positive means increase, negative means decrease. |
| 1 | Time | int32 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 2 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
MoveToHue Command Structure Type
Parameter structure of the MoveToHue Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Hue | float | M | Hue value, range 0 ~ 360. |
| 1 | Direction | uint8 | O | Hue change direction: 0 shortest path, 1 longest path, 2 up, 3 down. |
| 2 | Time | uint16 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 3 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
MoveToSaturation Command Structure Type
Parameter structure of the MoveToSaturation Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Saturation | float | M | Saturation value. |
| 1 | Time | uint16 | O | Transition time, unit ms; value range 0 ~ 1000000, step uniformly 500 ms. |
| 2 | ExecuteIfOff | boolean | O | Whether to execute the command when the light is off: 0 means not executed when the Present Value of the OnOff Trait is FALSE; 1 means executed even when OnOff is FALSE, and may change the Present Value of related Traits. |
Trait Definitions
ColorMode Trait
The ColorMode trait is used to indicate the color space in which the lighting device currently operates, i.e., the color encoding format or coordinate system used by the device to receive and report color data. It supports reading and reporting but not writing. Its values are four types: Hue color, XY color, color temperature, and RGB color. Hue color represents a color description method based on hue, usually used together with saturation and lightness, suitable for intuitive color selection; XY color represents a precise color description method based on CIE 1931 chromaticity coordinates, which is device-independent and suitable for professional color management scenarios; color temperature represents white light color based on the color temperature value (micro reciprocal degree, value 1000000 / Kelvin color temperature), used to adjust the warmth/coolness of white light; RGB color represents colored light described by the three primary components red, green and blue, and is the most common full-color control method. It should be noted that ColorMode and LightingModeSetting are two traits at different levels: LightingModeSetting determines the set of functions supported by the device (e.g., whether color temperature, whether color is supported), affecting the exposure of data model points, while ColorMode only determines the specific encoding format of the current color data; the two are independent of each other but together affect the color control behavior of the device. In particular, when the light device is a sub-device bridged under a gateway, the gateway will automatically identify the color space actually supported by the sub-device and update the data model data of the sub-device. Therefore, when an external system (such as an App or AI control) wants to control the color of the light, it should determine which specific color control commands can be sent based on the traits and commands contained in the device's data model (e.g., whether color temperature control, RGB control or XY control commands are included), and the gateway will automatically handle color space adaptation and ultimately control the sub-device.
| Trait ID | Code |
|---|
| 0x809C | ColorMode |
Parameters
ColorPointRGBXY Trait
Defines the coordinate points of the RGB three primary colors in the CIE 1931 chromaticity space (R/G/B each contains X and Y), used to describe the device color gamut boundary.
| Trait ID | Code |
|---|
| 0x4F9F | ColorPointRGBXY |
Parameters
WhitePointXY Trait
Defines the X and Y coordinates of the white point in the CIE 1931 chromaticity space, used to describe the device white point reference.
| Trait ID | Code |
|---|
| 0x4F9E | WhitePointXY |
Parameters
ColorXY Trait
ColorXY is used to represent x and y in the CIE 1931 color space.
The two high bytes of ColorXY correspond to CurrentX, and the two low bytes correspond to CurrentY; the conversion relationship between CurrentX/CurrentY and x/y in the CIE 1931 color space is as follows: x = CurrentX / 65535, y = CurrentY / 65535.
| Trait ID | Code |
|---|
| 0x4EE0 | ColorXY |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 0 | RW | O |
LEDICQuantity Trait
Indicates the number of dimming driver ICs.
| Trait ID | Code |
|---|
| 0x4F00 | LEDICQuantity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 100 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
LEDICProtocol Trait
Indicates the IC protocol of the LED.
| Trait ID | Code |
|---|
| 0x4EFF | LEDICProtocol |
Parameters
LEDType Trait
Indicates the type of LED beads.
| Trait ID | Code |
|---|
| 0x4EFE | LEDType |
Parameters
LightingMusicSyncMode Trait
Determines how the light responds to music after enabling (e.g., random effects, breathing transitions, rainbow flowing or water ripple, etc.).
| Trait ID | Code |
|---|
| 0x4EEE | LightingMusicSyncMode |
Parameters
LightingMusicSyncEnable Trait
Makes the light color and brightness change synchronously with the music rhythm to achieve a dynamic audio-visual effect.
| Trait ID | Code |
|---|
| 0x4EED | LightingMusicSyncEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | O | 0 | RVW | O |
| 0x0007 | Default Value | boolean | O | 0 | RW | O |
LightingDynamicSceneMode Trait
Supports dynamic lighting effects (such as rainbow flowing, breathing gradients, blinking, etc.) and provides preset scenes such as "forward rainbow" or "waterfall", delivering a rich visual experience.
| Trait ID | Code |
|---|
| 0x4EEC | LightingDynamicSceneMode |
Parameters
StartUpXYColor Trait
ColorXY represents the x and y values in the CIE xyY color space, containing the ColorX and ColorY elements, where x = ColorX/65535 and y = ColorY/65535.
| Trait ID | Code |
|---|
| 0x4E8C | StartUpXYColor |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 0 | RW | O |
ColorRGB Trait
ColorRGB represents a 24-bit color value in the RGB color space, packed as 0xRRGGBB, without an Alpha channel.
| Trait ID | Code |
|---|
| 0x4EDF | ColorRGB |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 16777215 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 0 | RW | O |
ColorTemperature Trait
This Trait is used for access to and reporting of color temperature values.
In implementation, Kelvin and Mired are often converted: Mired = 1000000 / Kelvin.
| Trait ID | Code |
|---|
| 0x809F | ColorTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 270 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 500 | R | O |
| 0x0003 | Minimum Value | uint32 | | 153 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 270 | RW | O |
StartUpColorTemperature Trait
Sets the default color temperature applied when the device powers on and the light is turned on. Unit: mired.
| Trait ID | Code |
|---|
| 0x4E8B | StartUpColorTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 270 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 370 | R | O |
| 0x0003 | Minimum Value | uint32 | | 153 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 270 | RW | O |
Saturation Trait
Contains the current saturation of the light source.
The conversion relationship with Matter CurrentSaturation is: Saturation(0~1) = CurrentSaturation / 254, and it can be displayed as 0-100% in the Aqara percentage view.
| Trait ID | Code |
|---|
| 0x813F | Saturation |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | O | 50 | RW | O |
Hue Trait
Contains the current hue value of the light source, in degrees (0-360).
The conversion relationship with Matter CurrentHue is: Hue(deg) = CurrentHue * 360 / 254. Unit: deg.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 360.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CurrentB Trait
This Trait is used for access to and reporting of "blue value" data.
| Trait ID | Code |
|---|
| 0x80F3 | CurrentB |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | int32 | | 255 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | int32 | | 0 | RW | O |
CurrentG Trait
This Trait is used for access to and reporting of "green value" data.
| Trait ID | Code |
|---|
| 0x80F2 | CurrentG |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | int32 | | 255 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | int32 | | 0 | RW | O |
CurrentR Trait
This Trait is used for access to and reporting of "red value" data.
| Trait ID | Code |
|---|
| 0x80F1 | CurrentR |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | int32 | | 255 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | int32 | | 0 | RW | O |
CurrentY Trait
This Trait represents the y component of the CIE 1931 chromaticity coordinate.
The relationship is: y = CurrentY / 65536, and the valid range of CurrentY is 0-65279.
| Trait ID | Code |
|---|
| 0x809E | CurrentY |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65279 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
CurrentX Trait
This Trait represents the x component of the CIE 1931 chromaticity coordinate.
The relationship is: x = CurrentX / 65536, and the valid range of CurrentX is 0-65279.
| Trait ID | Code |
|---|
| 0x809D | CurrentX |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65279 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
LightStripSegmentCount Trait
Indicates the total number of segments (addressable sections) of the light strip connected to the control module.
| Trait ID | Code |
|---|
| 0x4FEB | LightStripSegmentCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 10 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 50 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 10 | RW | O |
DynamicColorSequenceSetting Trait
This Trait is used for access to and reporting of "dynamic sequence scene settings" data.
| Trait ID | Code |
|---|
| 0x506B | DynamicColorSequenceSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
DynamicSequenceOperation Trait
This Trait is used to represent the related operation configuration for writing a dynamic sequence.
| Trait ID | Code |
|---|
| 0x506C | DynamicSequenceOperation |
Parameters
OtaDynamicColorSequenceResult Trait
This Trait is used to represent the reporting of dynamic sequence transmission results.
| Trait ID | Code |
|---|
| 0x506A | OtaDynamicColorSequenceResult |
Parameters
IsInDynamicColorSequence Trait
This Trait is used to indicate whether the device is in dynamic scene mode.
| Trait ID | Code |
|---|
| 0x506D | IsInDynamicColorSequence |
Parameters
DynamicColorSequences Trait
This Trait is used to report all dynamic sequence data information.
| Trait ID | Code |
|---|
| 0x5107 | DynamicColorSequences |
Parameters
Command Definitions
General Usage Notes
When the device receives any color control command in this section, the implementation should, within the hardware capability range of the device, choose a target color as close as possible to the requested color. The definition of the "actual presentation" of color is outside the scope of this specification; however, as long as the color data fields in the received command are within the range allowed by this specification and there is no error condition, the returned status code should be Success.
Taking the MoveToColorTemperature command as an example: if the target color temperature exceeds the hardware reachable range, the device should clamp at the physical minimum or maximum value (depending on the color temperature transition direction); this arrival time may be earlier than the end of the requested transition time.
If the color loop is active (ColorLoopActive = 1), the loop can only be stopped by sending the ColorLoopSet command that explicitly requests "disable color loop"; it should not be stopped by other commands with "stop semantics" (e.g., EnhancedMoveToHue with MoveMode = Stop, or StopMoveStep). In addition, while the color loop is active, the vendor may choose to ignore input color commands that would change Hue.
ColorMode Switching Notes
When the device receives any color command in this section, the first processing action should be to switch ColorMode to the mode corresponding to that command (see each command definition).
When switching from one color mode to another (e.g., from CurrentX/CurrentY to CurrentHue/CurrentSaturation), the command start color should be converted from the old mode attribute values to the new mode attribute values, and then executed as the starting point in the new mode.
When switching from a mode with a wider gamut to a mode with a more restricted gamut (e.g., CurrentX/CurrentY to CurrentHue/CurrentSaturation, or CurrentHue/CurrentSaturation to ColorTemperatureMireds), the current color may not have an equivalent value in the new mode. The behavior in such scenarios is vendor-defined, and it is recommended to avoid such mode switching during use.
MoveToXYColorBrightness Command
This command is used to set XY color and brightness simultaneously.
It is usually equivalent to sending MoveToColor and MoveToLevelWithOnOff in combination.
Effect on Receipt
After receiving this command, the device should first set the target XY color according to the semantics of MoveToXYColor (switching ColorMode to XY), and continuously transition to the target color according to the transition time; meanwhile, set the target brightness according to the semantics of MoveToLevelWithOnOff and handle switch linkage.
The color transition path is not mandated; the shortest path in the CIE xyY space is recommended.
Parameters
MoveToXYColorBrightness Command Structure
MoveToColorTemperatureBrightness Command
This command is used to set color temperature and brightness simultaneously.
It is usually equivalent to sending MoveToColorTemperature and MoveToLevelWithOnOff in combination.
Effect on Receipt
After receiving this command, the device should first perform the color temperature transition according to the semantics of MoveToColorTemperature (switching ColorMode to ColorTemperature), and perform brightness and switch linkage according to the semantics of MoveToLevelWithOnOff.
If the target color temperature exceeds the device's physical capability range, it should be clamped to the device's reachable minimum/maximum color temperature.
Parameters
MoveToColorTemperatureBrightness Command Structure
MoveToHueSaturationBrightness Command
This command is used to set Hue/Saturation and brightness simultaneously.
It is usually equivalent to sending MoveToHueAndSaturation and MoveToLevelWithOnOff in combination.
Effect on Receipt
After receiving this command, the device should first switch ColorMode to HSV, and transition continuously from the current Hue/Saturation to the target values; meanwhile, perform brightness and switch linkage according to the semantics of MoveToLevelWithOnOff.
Parameters
MoveToHueSaturationBrightness Command Structure
MoveToXYColor Command
This command is used to set the XY color.
After execution, the device should switch ColorMode to XY mode.
Effect on Receipt
After receiving this command, the device should set ColorMode (if implemented) to XY mode and transition continuously from the current color to the target color specified by ColorX/ColorY.
The transition duration should be consistent with the Time field. The color space transition path is not mandated; the shortest path in the CIE xyY space (which can be regarded as a "straight line" path) is recommended.
Parameters
MoveToXYColor Command Structure
MoveToHueAndSaturation Command
This command is used to set Hue and Saturation.
After execution, the device should switch ColorMode to HSV mode.
Effect on Receipt
After receiving this command, the device should switch ColorMode to HSV mode and transition continuously from the current Hue/Saturation to the target Hue/Saturation.
The transition duration should be consistent with the Time field. The transition path is not mandated; the shortest path in the color space is recommended.
Parameters
MoveToHueAndSaturation Command Structure
MoveToColorTemperature Command
This command is used to set the color temperature.
After execution, the device should switch ColorMode to ColorTemperature mode.
Effect on Receipt
After receiving this command, the device should set ColorMode (if implemented) to ColorTemperature mode and transition continuously from the current color temperature to the target color temperature.
The transition duration should be consistent with the Time field. According to this mode definition, the color temperature transition path changes along the Black Body Line.
If the target value is less than the device's physical minimum color temperature (Mired) or greater than the device's physical maximum color temperature (Mired), it should be clamped to the physical minimum/maximum value respectively as the final target.
Parameters
MoveToColorTemperature Command Structure
StepColorTemperature Command
This command is used to perform color temperature step adjustment.
Effect on Receipt
When StepSize = 0, the command has no effect and should return INVALID_COMMAND.
When StepSize > 0, the device should set ColorMode (and the corresponding enhanced mode, if implemented) to ColorTemperature mode and perform one step of color temperature change in the direction specified by StepMode:
Up: increase Mired (i.e., decrease Kelvin color temperature).Down: decrease Mired (i.e., increase Kelvin color temperature).
When the device-allowed boundary (configured boundary or physical boundary) is reached, the step operation should stop.
Parameters
StepColorTemperature Command Structure
MoveToHue Command
This command is used to set the target Hue (optionally with direction and time).
Effect on Receipt
After receiving this command, the device should switch ColorMode to HSV mode and transition continuously from the current Hue to the target Hue.
The transition duration should be consistent with the Time field; the direction is determined by the Direction field:
- Shortest path: move along the shortest direction of the hue ring.
- Longest path: move along the longest direction of the hue ring (commonly used for rainbow effects).
- When the two directions are equal in distance, the Up direction should be used.
Parameters
MoveToHue Command Structure
MoveToSaturation Command
This command is used to set the target Saturation (optionally with time).
Effect on Receipt
After receiving this command, the device should switch ColorMode to HSV mode and transition continuously from the current Saturation to the target Saturation.
The transition duration should be consistent with the Time field.
Parameters
MoveToSaturation Command Structure
SaveDynamicColorSequence Command
This command is used to add or update a dynamic sequence.
Parameters
SaveDynamicColorSequence Command Structure
PreviewDynamicColorSequence Command
This command is used to preview the dynamic sequence content.
Parameters
PreviewDynamicColorSequence Command Structure
RemoveDynamicColorSequence Command
This command is used to delete the specified dynamic sequence.
Parameters
RemoveDynamicColorSequence Command Structure
GetDynamicColorSequenceData Command
This command is used to get the details of the specified dynamic sequence.
Parameters
GetDynamicColorSequenceData Command Structure
StartDynamicColorSequence Command
This command is used to start the specified dynamic sequence.
Parameters
StartDynamicColorSequence Command Structure
StopDynamicColorSequence Command
This command is used to stop dynamic sequence execution.
This Command has no parameters.
Introduction
Describes event reporting of button-type input devices, including action recognition such as single click, long press, and multi-click.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0087 | Button | Button |
Trait
Command
This Function does not contain Commands.
Data Types
This enumeration defines the valid values of the Present Value of the ButtonEvent Trait.
| Value | Name | Description |
|---|
| 0x00 | SinglePress | Single click |
| 0x01 | DoublePress | Double click |
| 0x02 | LongPress | Long press |
| 0x03 | LongPressRelease | Long press release |
SpeedModeSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the SpeedModeSetting Trait.
| Value | Name | Description |
|---|
| 0x01 | FastClickMode | Fast click mode |
| 0x02 | MultiFuncMode | Multi-function mode |
Trait Definitions
This Trait is used for access to and reporting of "button event" data.
| Trait ID | Code |
|---|
| 0x80A0 | ButtonEvent |
Parameters
LocalControlDisabled Trait
Describes whether the button disables the associated local device control function (e.g., relay control). If disabled, pressing the button cannot turn on or off the local actuator.
| Trait ID | Code |
|---|
| 0x8155 | LocalControlDisabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SpeedModeSetting Trait
Defines the speed mode of key operations, e.g., Fast Click Mode and Multi-Function Mode.
| Trait ID | Code |
|---|
| 0x4E89 | SpeedModeSetting |
Parameters
Command Definitions
This Function does not contain Commands.
Camera
Introduction
Manages camera basic capabilities, including device status, mode switching, image encryption and cloud-related capabilities.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0088 | Camera | Camera |
Trait
Command
Data Types
CloudRecordingModeEnum8 Type
This enumeration defines the valid values of the Present Value of the CloudRecordingMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Event | Event recording |
| 0x01 | Continuous | Continuous recording |
CloudTimelapseInfoTraitPresentValueStructure Type
This structure defines the Present Value field layout of the CloudTimelapseInfo Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | task_num | characterString | M | Number of tasks. |
| 1 | task | array[Struct] | M | Cloud timelapse task array. Each Task contains id, active, repeat, start_date, end_date, start_time, end_time and interval. |
CloudClipRecordingTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the CloudClipRecordingType Trait.
| Value | Name | Description |
|---|
| 0x00 | Default | Default |
| 0x01 | Recording | Recording |
| 0x16 | AssociatedEvent | Associated event |
| 0x1B | SecurityAssociated | Security associated event |
LensObstructionTimePeriodTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LensObstructionTimePeriod Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, format HH:MM (24-hour). |
| 1 | endtime | characterString | M | End time, format HH:MM (24-hour). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, in the order Sunday to Saturday; 1 means active, 0 means inactive. |
This enumeration defines the valid values of the Present Value of the CloudAISupportedAlgorithm Trait.
| Value | Name | Description |
|---|
| 0x00 | HumanRecognition | Human detection |
| 0x01 | FaceRecognition | Face recognition |
| 0x02 | PetRecognition | Cat and dog recognition |
| 0x03 | VehicleDetection | Vehicle detection |
| 0x04 | PackageRecognition | Package recognition |
| 0x05 | FlameDetection | Flame detection |
EventLightingModeEnum8 Type
This enumeration defines the valid values of the Present Value of the EventLightingMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Steady | Always on |
| 0x01 | Blink | Blinking |
CamWorkModeEnum8 Type
This enumeration defines the valid values of the Present Value of the CamWorkMode Trait.
| Value | Name | Description |
|---|
| 0x00 | PowerSaving | Power saving mode |
| 0x01 | SuperPowerSaving | Super power saving mode |
| 0x02 | MainsPower | Always-on mode |
| 0x03 | AOV | Smart monitoring mode (AOV) |
RecordingModeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RecordingMode Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | mode | uint32 | M | Recording mode: 0=Off, 1=Continuous recording, 2=Event-triggered recording. |
| 1 | cover | uint32 | M | Storage overwrite policy; 1 means circular overwrite when storage is full. |
ImageFlipModeEnum8 Type
This enumeration defines the valid values of the Present Value of the ImageFlipMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | HorizontalFlip | Horizontal flip |
| 0x02 | VerticalFlip | Vertical flip |
| 0x03 | HorizontalVerticalFlip | Horizontal and vertical flip |
InfraredNightVisionSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the InfraredNightVisionSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | AlwaysOff | Always off |
| 0x01 | AlwaysOn | Always on |
| 0x02 | Auto | Auto switch |
| 0x03 | WarmColorFullColor | Warm light full color |
TimelapseTimePeriodTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimelapseTimePeriod Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, format HH:MM (24-hour). |
| 1 | endtime | characterString | M | End time, format HH:MM (24-hour). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, in the order Sunday to Saturday; 1 means active, 0 means inactive. |
ScheduledSleepTimePeriodTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ScheduledSleepTimePeriod Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, format HH:MM (24-hour). |
| 1 | endtime | characterString | M | End time, format HH:MM (24-hour). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, in the order Sunday to Saturday; 1 means active, 0 means inactive. |
PrivacyMaskRegionsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the PrivacyMaskRegions Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | visible | boolean | M | Whether to show the outline of mask regions in the live preview. |
| 1 | regions | array[Struct] | M | Privacy mask region array, up to 4 regions. Each Region contains color and rect. |
PowerFrequencyEnum8 Type
This enumeration defines the valid values of the Present Value of the PowerFrequency Trait.
| Value | Name | Description |
|---|
| 0x00 | 50Hz | 50Hz |
| 0x01 | 60Hz | 60Hz |
CameraNotificationSchedulePeriodsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the CameraNotificationSchedulePeriods Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, format HH:MM (24-hour). |
| 1 | endtime | characterString | M | End time, format HH:MM (24-hour). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, in the order Sunday to Saturday; 1 means active, 0 means inactive. |
CameraNotificationTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the CameraNotificationType Trait.
| Value | Name | Description |
|---|
| 0x01 | EventNotification | Event notification |
| 0x02 | AIVideoSummary | AI video summary notification |
LiveChannelEnum8 Type
This enumeration defines the valid values of the Present Value of the LiveChannel Trait.
| Value | Name | Description |
|---|
| 0x00 | Main | Main stream |
| 0x01 | Sub | Sub stream |
| 0x02 | Third | Third stream |
| 0x03 | Other | Other |
PlaybackChannelEnum8 Type
This enumeration defines the valid values of the Present Value of the PlaybackChannel Trait.
| Value | Name | Description |
|---|
| 0x00 | Main | Main stream |
| 0x01 | Sub | Sub stream |
| 0x02 | Third | Third stream |
| 0x03 | Other | Other |
AlexaDetectionEventsEnum8 Type
This enumeration defines the valid values of the array members of the AlexaDetectionEvents Trait.
| Value | Name | Description |
|---|
| 0x01 | HumanRecognition | Human detection |
| 0x02 | PackageRecognition | Package detection |
ThirdPartySnapshotTriggerSourceEnum8 Type
This enumeration defines the valid values of the source field of the ThirdPartySnapshotTrigger Command.
| Value | Name | Description |
|---|
| 0x01 | Alexa | Amazon Alexa |
LensObstructionSensitivityEnum8 Type
This enumeration defines the valid values of the Present Value of the LensObstructionSensitivity Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
SetDetectionModeEnum8 Type
This enumeration defines the valid values of the Present Value of the SetDetectionMode Trait.
| Value | Name | Description |
|---|
| 0x00 | FaceRecognition | Face recognition |
| 0x01 | HumanDetection | Human detection |
| 0x02 | PetDetection | Cat and dog recognition |
| 0x03 | PackageDetection | Package recognition |
| 0x04 | HumanLoitering | Person lingering |
| 0x05 | LensBlocking | Lens obstruction recognition |
LightingTimePeriodTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LightingTimePeriod Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, format HH:MM (24-hour). |
| 1 | endtime | characterString | M | End time, format HH:MM (24-hour). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, in the order Sunday to Saturday; 1 means active, 0 means inactive. |
WhiteLightToggle Command Structure Type
Parameter structure of the WhiteLightToggle Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
SnapshotUploadCommand Command Structure Type
Parameter structure of the SnapshotUploadCommand Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Type | enum8 | M | Command type. Values: 0:Default; 1:Capture. |
Parameter structure of the FormatSDCardCommand Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
CameraActiveToggle Command Structure Type
Parameter structure of the CameraActiveToggle Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
ThirdPartySnapshotTrigger Command Structure Type
Parameter structure of the ThirdPartySnapshotTrigger Command. This Command is invoked by third-party ecosystem platforms (such as Alexa) to trigger the device to perform a snapshot operation.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Source | ThirdPartySnapshotTriggerSourceEnum8 | M | Trigger source identifier. 0x01 = Alexa (Amazon Alexa), other values reserved for extension. |
Trait Definitions
CloudRecordingMode Trait
Indicates the cloud recording type. Value 0 means event-triggered recording (only when an event occurs), 1 means continuous recording (24/7).
| Trait ID | Code |
|---|
| 0x5001 | CloudRecordingMode |
Parameters
HdrEnable Trait
Enables or disables the HDR (High Dynamic Range) function. After enabling, the device improves image quality in backlit or high-contrast scenes, preserving details in highlights and shadows for a clearer, more natural picture.
| Trait ID | Code |
|---|
| 0x5000 | HdrEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CloudTimelapseInfo Trait
Provides cloud timelapse task information, including the number of tasks, task ID, active status, daily repeat flags, start/end dates, start/end times (absolute time or relative to sunrise/sunset) and capture interval.
| Trait ID | Code |
|---|
| 0x4FFF | CloudTimelapseInfo |
Parameters
P2PCaptureEnabled Trait
Indicates whether the camera enables the P2P (peer-to-peer) snapshot function.
| Trait ID | Code |
|---|
| 0x4E3E | P2PCaptureEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RV | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
P2PVideoEnable Trait
Enables or disables the P2P video transmission capability of the camera. After enabling, a video connection can be established through a peer-to-peer link.
| Trait ID | Code |
|---|
| 0x50D8 | P2PVideoEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraAdvancedEventNotificationSettings Trait
Configures the advanced event set for camera notifications. This value is a string composed of event type numbers separated by vertical bars (|), e.g., "39 | 40 | 111 | 108". Each number corresponds to a specific event type listed below. Only events whose numbers are included in the string will trigger notifications. Value Event Description
1 Motion detection
2 Human
3 Cat or dog present
4 Human wandering
5 Doorbell pressed
6 Tampering alarm
7 Family member recognized
8 Stranger recognized
9 Abnormal crying
10 Crying
11 Coughing
12 Alarm sound
13 Dog barking
14 Lens blocked
15 Package detected
16 Package disappeared
17 Vehicle present
32 Crib
33 Stroller
38 Toy car
39 Mask/face covering
40 Mouth and nose covered
46 Holding phone
48 Person fallen
50 Person climbing
53 Person smoking
56 Wearing hat
58 Dog
59 Cat
60 Drinking water
61 Eating
62 Using toilet
63 Animal
64 Pet
65 Bird
66 Bear
67 Brown bear
68 Squirrel
69 Rabbit
70 Deer
71 Reindeer
| Trait ID | Code |
|---|
| 0x4FC9 | CameraAdvancedEventNotificationSettings |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
CloudClipRecordingType Trait
Indicates the type of cloud short video (clip) recording triggered. Value 0 = Default (unspecified), 1 = Recording (general event), 22 = Associated event (triggered by other sensors/devices), 27 = Security associated event (e.g., home security alarm). This Trait can be read, written and actively reported by the device.
| Trait ID | Code |
|---|
| 0x4FE9 | CloudClipRecordingType |
Parameters
ZoomRatio Trait
Controls the zoom ratio of the camera. The larger the value, the closer the shooting subject appears.
| Trait ID | Code |
|---|
| 0x4FE8 | ZoomRatio |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RVW | O |
| 0x0002 | Maximum Value | float | | 9.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 1 | RW | O |
ImageEncryptionKey Trait
Provides the encryption key used to encrypt images (snapshots) before pushing them to the cloud or to clients.
| Trait ID | Code |
|---|
| 0x4FE6 | ImageEncryptionKey |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
LensObstructionPushEnable Trait
Enables or disables push notifications for lens obstruction events. When enabled, the user will receive an alert when the lens is obstructed.
| Trait ID | Code |
|---|
| 0x4FE0 | LensObstructionPushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
LensObstructionTimePeriod Trait
Defines the time period during which lens obstruction detection is active. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are "HH:MM" format strings (24-hour), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period is valid all day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of 7 unsigned 8-bit integers, indexed in the order Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. A value of 1 means active on that weekday, 0 means inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FDF | LensObstructionTimePeriod |
Parameters
LensObstructionEnable Trait
Enables or disables the lens obstruction detection function. When enabled, the camera monitors whether the lens is partially or fully obstructed, and can trigger events, recordings or notifications accordingly.
| Trait ID | Code |
|---|
| 0x4FDE | LensObstructionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
WhiteLightDuration Trait
Sets how long the white light (fill light) stays on after being triggered. A value of 0 means stays on continuously (always on). 1 to 1800 means the number of seconds it stays on before automatically turning off.
| Trait ID | Code |
|---|
| 0x4FDB | WhiteLightDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 1800 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 30 | RW | O |
CloudAISupportedAlgorithm Trait
Indicates the AI algorithm types supported by the cloud. The value is an enumeration representing the detection/recognition capabilities available through cloud processing.
| Trait ID | Code |
|---|
| 0x4FDD | CloudAISupportedAlgorithm |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array | | | RV | O |
| 0x0006 | Supported Value | list[array] | | | R | O |
EventLightingMode Trait
Defines the behavior of the indicator/lighting when the device detects an event. Steady: the light stays on continuously; Blink: the light blinks repeatedly.
| Trait ID | Code |
|---|
| 0x4FDA | EventLightingMode |
Parameters
ActiveWakeupInterval Trait
Configures the active wake-up interval of a battery-powered camera when operating in AOV (Always-On Video) smart monitoring mode. The device periodically wakes up at this interval (in seconds) to capture frames for event detection. For example, setting it to 3 means the camera wakes up every 3 seconds to check for motion or events.
| Trait ID | Code |
|---|
| 0x4FD9 | ActiveWakeupInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 3 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint32 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 3 | RW | O |
CameraMatterCapability Trait
Indicates Matter feature support using a bit mask. Bit0: the device supports native Matter camera (no gateway bridging required). Bit1: the gateway supports bridging the camera to Matter. Bit2: the camera (without a built-in gateway) can be bridged to Matter through a standalone gateway. Predefined combination values: 0 (bits 000), 2 (bits 010), 4 (bits 100), 5 (bits 101).
| Trait ID | Code |
|---|
| 0x4FD7 | CameraMatterCapability |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
CamWorkMode Trait
Defines the working mode of the camera in terms of power consumption and functionality. PowerSaving: reduces performance to extend battery life; SuperPowerSaving: maximum power saving with limited functions; MainsPower: full performance running under continuous power supply (AC/DC); AOV: Always-On Video low-power smart monitoring mode.
| Trait ID | Code |
|---|
| 0x4FD8 | CamWorkMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | CamWorkModeEnum8 | | 0 | RVW | O |
| 0x0006 | Supported Value | list[CamWorkModeEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
AOVRecordingEnable Trait
Enables or disables the AOV (Always-On Video) recording function. When enabled, the device records continuously to ensure critical moments are not missed.
| Trait ID | Code |
|---|
| 0x4FD6 | AOVRecordingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
RecordingMode Trait
Configures the recording behavior of the device. The structure contains two fields: mode (uint8, values: 0 = Off, 1 = Continuous recording, 2 = Event-triggered recording) and overwrite (uint8, value: 1 = circular overwrite when storage is full). Both fields are mandatory.
| Trait ID | Code |
|---|
| 0x4FD2 | RecordingMode |
Parameters
RangeTestMode Trait
Enables the ranging test mode for camera detection distance configuration. In this mode, the device gives a prompt when a target is detected (e.g., the white light flashes three times), indicating the effective range of the current distance setting.
| Trait ID | Code |
|---|
| 0x4FD3 | RangeTestMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
RecordingMuteEnable Trait
Determines whether audio is recorded simultaneously with video. When set to 1 (muted), the recording file does not save audio; when 0, audio is included.
| Trait ID | Code |
|---|
| 0x4FD1 | RecordingMuteEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
VideoCorrectionEnable Trait
Turns lens distortion correction on/off. When enabled, the device applies distortion correction to straighten the curved edges caused by wide-angle lenses (improving image geometry but possibly cropping the field of view).
| Trait ID | Code |
|---|
| 0x4FD0 | VideoCorrectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Specifies the format string for displaying date and time in the OSD watermark. Uses strftime-compatible format specifiers (e.g., %Y for year, %m for month, %d for day, %H for hour, %M for minute, %S for second).
| Trait ID | Code |
|---|
| 0x4FCE | OSDTimeFormatSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
ImageFlipMode Trait
Controls whether the video image is flipped vertically (180 deg rotation). When set to Flip (1), the image is upside down, suitable for ceiling or inverted mounting scenarios; when set to Normal (0), the image orientation is standard.
| Trait ID | Code |
|---|
| 0x4FCF | ImageFlipMode |
Parameters
OSDWatermarkEnable Trait
Controls whether to overlay a timestamp in the live preview and recordings. When enabled, the current date and time are displayed at the specified position of the video image, making it easy for viewers to accurately identify when an event occurred.
| Trait ID | Code |
|---|
| 0x4FCB | OSDWatermarkEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
InfraredNightVisionSetting Trait
Sets the night vision mode of the camera. AlwaysOff: IR cut and illuminator off; AlwaysOn: IR cut on (black and white) and IR LED on; Auto: switches according to ambient light; WarmColorFullColor: uses warm white light for full-color night vision.
| Trait ID | Code |
|---|
| 0x4FCA | InfraredNightVisionSetting |
Parameters
TimelapseTimePeriod Trait
Defines the scheduled period during which timelapse recording is active. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are "HH:MM" format (24-hour) strings, ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of 7 unsigned 8-bit integers, indexed in the order Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. A value of 1 means active on that weekday, 0 means inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FC8 | TimelapseTimePeriod |
Parameters
TimelapseEnable Trait
Enables or disables the timelapse function. When enabled, the device captures an image sequence at fixed intervals (configured separately) and composes them into a video.
| Trait ID | Code |
|---|
| 0x4FC7 | TimelapseEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DynamicCoverRefreshEnable Trait
Enables or disables dynamic refresh of the device cover image on the App home page.
| Trait ID | Code |
|---|
| 0x5027 | DynamicCoverRefreshEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
PeriodicSnapshotUploadEnable Trait
Enables or disables periodic snapshot upload to the cloud. When PeriodicSnapshotInterval is implemented, the capture interval is configured by that Trait; when it is not implemented, the behavior of uploading one frame every 10 minutes is maintained.
| Trait ID | Code |
|---|
| 0x5028 | PeriodicSnapshotUploadEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CloudRecordingEnable Trait
Enables or disables the master switch for event cloud recording.
| Trait ID | Code |
|---|
| 0x5026 | CloudRecordingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TheftModeNotificationEnable Trait
Enables or disables push notifications for anti-theft mode events.
| Trait ID | Code |
|---|
| 0x501D | TheftModeNotificationEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TheftModeEnable Trait
Enables or disables the anti-theft/lost mode.
| Trait ID | Code |
|---|
| 0x501C | TheftModeEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ScheduledSleepTimePeriod Trait
Defines the scheduled period during which the device should enter sleep mode. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are "HH:MM" format (24-hour) strings, ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of 7 unsigned 8-bit integers, indexed in the order Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. A value of 1 means active on that weekday, 0 means inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x501B | ScheduledSleepTimePeriod |
Parameters
AIDetectionBoxEnable Trait
Enables or disables drawing AI detection bounding boxes (e.g., people, pets) in the live preview.
| Trait ID | Code |
|---|
| 0x5019 | AIDetectionBoxEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ScheduledSleepEnable Trait
Enables or disables the scheduled sleep mode.
| Trait ID | Code |
|---|
| 0x501A | ScheduledSleepEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
PrivacyMaskRegions Trait
Defines mask regions in the video frame to protect privacy. Its value is a structure containing two fields: visible and regions. visible is a boolean or integer (0 or 1), indicating whether to show the outline of mask regions in the live preview (for debugging or confirmation, without affecting the actual masking effect). regions is an array of up to 4 mask objects. Each mask object contains color and rect. color is an integer (decimal), representing the RGB color of the mask block (e.g., the decimal form of 0xRRGGBB, with the high byte being red, the middle byte green, and the low byte blue). rect is an array of four integers specifying the bounding rectangle: left coordinate, top coordinate, width, height. The coordinate origin is at the top-left corner of the image, with the X axis increasing to the right and the Y axis increasing downward. This configuration applies to both live video and recording streams; masking is performed on the device side to ensure privacy-sensitive content cannot be restored.
| Trait ID | Code |
|---|
| 0x5018 | PrivacyMaskRegions |
Parameters
PowerFrequency Trait
Sets the power line frequency to avoid flicker (50Hz or 60Hz).
| Trait ID | Code |
|---|
| 0x5017 | PowerFrequency |
Parameters
WhiteLightOnOff Trait
Controls the master switch of the white fill light. Toggling can change the current state.
| Trait ID | Code |
|---|
| 0x5014 | WhiteLightOnOff |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
WhiteLightBrightness Trait
Sets the white light brightness level, ranging from 1% to 100%.
| Trait ID | Code |
|---|
| 0x5016 | WhiteLightBrightness |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 1 | RW | O |
CameraEventImportanceLevel Trait
Sets the minimum importance level for event notifications. Only events with level >= this value trigger notifications.
| Trait ID | Code |
|---|
| 0x5013 | CameraEventImportanceLevel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 2 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 5 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 2 | RW | O |
CameraAdvancedEventNotificationEnable Trait
Enables or disables advanced event notifications (e.g., detailed AI event alerts).
| Trait ID | Code |
|---|
| 0x5012 | CameraAdvancedEventNotificationEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraNotificationSchedulePeriods Trait
Defines the scheduled period during which notifications are allowed. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are "HH:MM" format (24-hour) strings, ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of 7 unsigned 8-bit integers, indexed in the order Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. A value of 1 means active on that weekday, 0 means inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x5010 | CameraNotificationSchedulePeriods |
Parameters
CameraFilterUnimportantNotifications Trait
Enables or disables unimportant notification filtering to reduce disturbance.
| Trait ID | Code |
|---|
| 0x5011 | CameraFilterUnimportantNotifications |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraNotificationScheduleEnable Trait
Enables or disables the notification schedule function.
| Trait ID | Code |
|---|
| 0x500F | CameraNotificationScheduleEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraNotificationType Trait
Specifies the type of notifications to receive: event notifications or AI video summary notifications.
| Trait ID | Code |
|---|
| 0x500E | CameraNotificationType |
Parameters
AlexaDetectionEvents Trait
Represents the list of detection event types that the device is required to support, as configured by the user through the Alexa platform.
| Trait ID | Code |
|---|
| 0x516D | AlexaDetectionEvents |
Parameters
LensObstructionRecordEnable Trait
Enables or disables local recording when lens obstruction is detected.
| Trait ID | Code |
|---|
| 0x4FFC | LensObstructionRecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
LensObstructionInterval Trait
The time interval (in seconds) between consecutive lens obstruction detection triggers.
| Trait ID | Code |
|---|
| 0x4FFD | LensObstructionInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
LensObstructionSensitivity Trait
This enumeration configures the sensitivity level for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity. Higher sensitivity makes the function more responsive to trigger conditions (e.g., more easily detecting weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FFB | LensObstructionSensitivity |
Parameters
AIModelSilenceOTAEnable Trait
Enables or disables silent OTA upgrades of AI models without user intervention. When enabled, AI models are updated automatically in the background.
| Trait ID | Code |
|---|
| 0x4FC5 | AIModelSilenceOTAEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SetDetectionMode Trait
Sets the primary detection mode of the camera. This mode determines the AI algorithm preferred for event generation and recording.
| Trait ID | Code |
|---|
| 0x4FC6 | SetDetectionMode |
Parameters
AIVideoSummaryEnable Trait
Enables or disables AI video summary generation. AI extracts key moments (events) and composes them into short video summaries.
| Trait ID | Code |
|---|
| 0x4FC3 | AIVideoSummaryEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AIVideoSearchEnable Trait
Enables or disables the AI video search function. When enabled, users can search recordings by object type (e.g., people, vehicles, packages).
| Trait ID | Code |
|---|
| 0x4FC2 | AIVideoSearchEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SupportLocalVideoDownload Trait
Indicates whether the device supports downloading local videos from the SD card through the App.
| Trait ID | Code |
|---|
| 0x4FC1 | SupportLocalVideoDownload |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LightingTimePeriod Trait
Defines the scheduled period during which the event-triggered lighting function is active. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are "HH:MM" format (24-hour) strings, ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of 7 unsigned 8-bit integers, indexed in the order Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. A value of 1 means active on that weekday, 0 means inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FBF | LightingTimePeriod |
Parameters
Enables or disables local recording when associated events (e.g., from other Zigbee/Thread sensors) occur. Allows recording to be triggered by external devices such as door/window sensors.
| Trait ID | Code |
|---|
| 0x4FC0 | RelatedEventRecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LightUpWhenEventDetected Trait
Turns on the white light for 20 seconds when an event (such as motion or human detection) is detected within the scheduled period. Used as a visual deterrent or for illumination.
| Trait ID | Code |
|---|
| 0x4FBE | LightUpWhenEventDetected |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LogoWatermarkEnable Trait
Enables or disables the brand Logo watermark overlay on videos. When enabled, the device embeds a fixed Logo image into video files.
| Trait ID | Code |
|---|
| 0x4FB0 | LogoWatermarkEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
CameraRTSPEnable Trait
Indicates the RTSP (Real Time Streaming Protocol) enable switch configuration of the camera. When enabled, the live video stream can be accessed via the RTSP protocol; when disabled, RTSP access is prohibited.
| Trait ID | Code |
|---|
| 0x4F91 | CameraRTSPEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraRTSPURL Trait
Indicates the RTSP (Real Time Streaming Protocol) URL of the camera, used to access the live video stream via the RTSP protocol. This attribute returns a JSON object whose keys are resolution identifiers (e.g., "360p", "720p", "1080p", "4mp") and whose values are the corresponding complete RTSP URL strings. Example format: {"360p": "rtsp://192.168.1.109:8554/360p","720p": "rtsp://192.168.1.109:8554/720p","1080p": "rtsp://192.168.1.109:8554/1080p","4mp": "rtsp://192.168.1.109:8554/4mp"}
| Trait ID | Code |
|---|
| 0x4F90 | CameraRTSPURL |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
LiveChannel Trait
Live video channel. Indicates the stream channel used for live video. 0 = Main stream, 1 = Sub stream, 2 = Third stream, 3 = Other.
| Trait ID | Code |
|---|
| 0x517C | LiveChannel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | LiveChannelEnum8 | | 0 | RVW | O |
| 0x0006 | Supported Value | list[LiveChannelEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
PlaybackChannel Trait
Playback video channel. Indicates the stream channel used for playback video. 0 = Main stream, 1 = Sub stream, 2 = Third stream, 3 = Other.
| Trait ID | Code |
|---|
| 0x517D | PlaybackChannel |
Parameters
P2PCaptureStatus Trait
P2P dynamic snapshot status switch
| Trait ID | Code |
|---|
| 0x4E44 | P2PCaptureStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Volume Trait
Indicates or sets the speaker volume of the camera device (e.g., two-way voice). The value is usually a percentage (0 to 100) or a device-defined numeric range.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
CameraActiveStatus Trait
This Trait is used for access to and reporting of "camera sleep status" data.
| Trait ID | Code |
|---|
| 0x80A2 | CameraActiveStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
Command Definitions
ThirdPartySnapshotTrigger Command
This Command is invoked by third-party ecosystem platforms (such as Alexa) to trigger the device to perform a snapshot operation. The command contains a trigger source parameter to identify the caller.
Parameters
ThirdPartySnapshotTrigger Command Structure
WhiteLightToggle Command
This Command is used to perform the "white light status toggle control" operation.
Parameters
WhiteLightToggle Command Structure
SnapshotUploadCommand Command
This Command is used to perform the "capture and upload" operation.
Parameters
SnapshotUploadCommand Command Structure
This Command is used to perform the "format SD card" operation.
Parameters
FormatSDCardCommand Command Structure
CameraActiveToggle Command
This Command is used to perform the "camera sleep toggle" operation.
Parameters
CameraActiveToggle Command Structure
WindowCovering
Introduction
This Function provides open/close control, tilt control, target position management and running status feedback for window covering devices such as curtains, roller blinds and venetian blinds.
In addition to standard open/close and tilt control, this Function also includes Aqara extended capabilities: scene management (startup, reading, preview, add/delete/modify of built-in/custom scenes), manual calibration, remote pairing, remote travel records, motor mapping exchange and enhanced mode status.
The client should determine the current controllability and operation stage of the device based on Traits such as TravelConfigured, MotorControllability, MotorOperationStatus and EnhanceMode, avoiding sending invalid commands when conditions are not met.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0089 | WindowCovering | Window covering |
Trait
Command
Data Types
LiftLimitRangeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LiftLimitRange Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Min | float | M | Minimum actual value of the open/close position, in %. |
| 1 | Max | float | M | Maximum actual value of the open/close position, in %. |
TiltLimitRangeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TiltLimitRange Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Min | float | M | Minimum actual value of the tilt/rotation position, in %. |
| 1 | Max | float | M | Maximum actual value of the tilt/rotation position, in %. |
WindowCoveringOpenOrientationEnum8 Type
This enumeration defines the valid values of the Present Value of the WindowCoveringOpenOrientation Trait.
| Value | Name | Description |
|---|
| 0x00 | LeftRight | Dual open left and right |
| 0x01 | LeftToRight | From left to right |
| 0x02 | RightToLeft | From right to left |
| 0x03 | Up | From bottom to top |
| 0x04 | Horizontal | Left and right open/close |
| 0x05 | Vertical | Top and bottom open/close |
TravelCalibrationReminderEnum8 Type
This enumeration defines the valid values of the Present Value of the TravelCalibrationReminder Trait.
| Value | Name | Description |
|---|
| 0x00 | TwoWeeks | Two weeks |
| 0x01 | OneMonth | One month |
| 0x02 | TwoMonths | Two months |
| 0x03 | ThreeMonths | Three months |
| 0x04 | SixMonths | Six months |
| 0x05 | Custom | Custom |
EffectInfoTraitPresentValueStructure Type
This structure defines the Present Value field layout of the EffectInfo Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID. |
| 1 | EffectData | characterString | M | Effect data. |
| 2 | EffectName | characterString | M | Effect name. |
EffectOperationStateEnum8 Type
This enumeration defines the valid values of the Present Value of the EffectOperationState Trait.
| Value | Name | Description |
|---|
| 0x00 | Idle | Idle |
| 0x01 | Executing | Executing |
| 0x02 | Previewing | Previewing |
AutoCalibrationEnum8 Type
This enumeration defines the valid values of the Present Value of the AutoCalibration Trait.
| Value | Name | Description |
|---|
| 0x00 | NormalMode | Normal mode |
| 0x01 | CalibrationMode | Calibration mode |
ManualPullStrengthEnum8 Type
This enumeration defines the valid values of the Present Value of the ManualPullStrength Trait.
| Value | Name | Description |
|---|
| 0x00 | Low | Low |
| 0x01 | Medium | Medium |
| 0x02 | High | High |
MotorStrengthEnum8 Type
This enumeration defines the valid values of the Present Value of the MotorStrength Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Strong | Strong |
LimitPointSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the LimitPointSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | ClearLimitPoints | Clear limit points |
| 0x01 | SetOpenLimit | Set open limit point |
| 0x02 | SetCloseLimit | Set close limit point |
UserDefinedEffectsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the UserDefinedEffects Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectID | uint8 | M | User defined effect ID. |
| 1 | EffectName | characterString | M | Effect name. |
BuiltInEffectsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the BuiltInEffects Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectID | uint8 | M | Built-in effect ID. |
| 1 | BuiltInEffectLabelID | enum8 | M | Built-in effect tag ID. |
ObstacleLimitSensitivityEnum8 Type
This enumeration defines the valid values of the Present Value of the ObstacleLimitSensitivity Trait.
| Value | Name | Description |
|---|
| 0x00 | Low | Low |
| 0x01 | MediumLow | Lower |
| 0x02 | Medium | Medium |
| 0x03 | MediumHigh | Higher |
| 0x04 | High | High |
MotorSpeedSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the MotorSpeedSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | LowSpeed | Low speed |
| 0x01 | MediumSpeed | Medium speed |
| 0x02 | HighSpeed | High speed |
MotorOperationStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the MotorOperationStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Closing | Closing |
| 0x01 | Opening | Opening |
| 0x02 | Stopped | Stopped |
| 0x03 | ObstacleStop | Stopped by obstacle |
| 0x04 | ObstacleLimitAutoRebound | Obstacle rebound |
ManualPullEventEnum32 Type
This enumeration defines the valid values of the Present Value of the ManualPullEvent Trait.
| Value | Name | Description |
|---|
| 0x01 | ManualOpen | Manual pull open |
| 0x02 | ManualClose | Manual pull close |
| 0x03 | ManualStop | Manual pull stop |
WindowCoveringTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the WindowCoveringType Trait.
| Value | Name | Description |
|---|
| 0x00 | RollerShade | Roller shade |
| 0x01 | VenetianBlind | Venetian blind |
| 0x02 | ShangrilaBlind | Shangri-La blind |
| 0x03 | ZebraBlind | Zebra blind |
| 0x04 | Curtain | Curtain |
| 0x05 | VerticalVenetianBlind | Dream curtain |
| 0x1F | RomanShade | Roman blind |
| 0x20 | BalloonShade | Balloon blind |
| 0x21 | WovenWood | Woven wood blind |
| 0x22 | PleatedShade | Pleated blind |
| 0x23 | CellularShade | Honeycomb blind |
| 0x24 | LayeredShade | Layered blind |
| 0x25 | LayeredShade2D | 2D layered blind |
| 0x26 | SheerShade | Translucent blind |
| 0x27 | TiltOnlyInteriorBlind | Tilt-only interior venetian blind |
| 0x28 | InteriorBlind | Interior venetian blind |
| 0x29 | VerticalBlindStripCurtain | Vertical blind slat curtain |
| 0x2A | InteriorVenetianBlind | Interior venetian blind (window) |
| 0x2B | ExteriorVenetianBlind | Exterior venetian blind |
| 0x2C | LateralLeftCurtain | Left sliding curtain |
| 0x2D | LateralRightCurtain | Right sliding curtain |
| 0x2E | CentralCurtain | Center curtain |
| 0x2F | RollerShutter | Rolling door |
| 0x30 | ExteriorVerticalScreen | Exterior vertical sun shade |
| 0x31 | AwningTerracePatio | Terrace awning |
| 0x32 | AwningVerticalScreen | Vertical awning |
| 0x33 | TiltOnlyPergola | Tilt-only gazebo |
| 0x34 | SwingingShutter | Swinging blind |
| 0x35 | SlidingShutter | Sliding blind |
| 0xFF | Unknown | Unknown |
WindowCoveringCategoryEnum8 Type
This enumeration defines the valid values of the Present Value of the WindowCoveringCategory Trait.
| Value | Name | Description |
|---|
| 0x00 | RollerShade | Roller shade |
| 0x01 | RollerShade2Motor | Double roller shade |
| 0x02 | RollerShadeExterior | Exterior roller shade |
| 0x03 | RollerShadeExterior2Motor | Double exterior roller shade |
| 0x04 | Drapery | Curtain |
| 0x05 | Awning | Awning |
| 0x06 | Shutter | Blind |
| 0x07 | TiltBlindTiltOnly | Tilt-only blind |
| 0x08 | TiltBlindLiftAndTilt | Tilt and lift blind |
| 0x09 | ProjectorScreen | Projection screen |
| 0xFF | Unknown | Unknown |
RemoveUserDefinedEffects Command Structure Type
Parameter structure of the RemoveUserDefinedEffects Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectIDs | list[Struct] | M | List of EffectIDs to be batch deleted. Each item should be an existing UserDefined effect ID; the list length must not exceed the Present Value of MaxUserDefinedEffects. |
EnterRemoteControlPairing Command Structure Type
Parameter structure of the EnterRemoteControlPairing Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PairingDuration | uint16 | M | Duration of remote pairing (seconds). After success, the device enters pairing mode and automatically exits after the timeout. |
ManualCalibrationOperation Command Structure Type
Parameter structure of the ManualCalibrationOperation Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Operation | enum8 | M | Calibration operation type (Open/Close/Stop). Only valid in manual calibration mode. |
EnterManualCalibration Command Structure Type
Parameter structure of the EnterManualCalibration Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CalibrationTimeout | uint16 | M | Idle timeout of the manual calibration session (seconds). After the timeout, the device should automatically exit calibration mode and discard temporary records. |
PreviewEffect Command Structure Type
Parameter structure of the PreviewEffect Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectData | characterString | M | Raw data of the effect to be previewed. The encoding format should be consistent with adding/updating user defined effects. |
RemoveUserDefinedEffect Command Structure Type
Parameter structure of the RemoveUserDefinedEffect Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID to be deleted. It should be an existing and removable UserDefined effect. |
UpdateUserDefinedEffect Command Structure Type
Parameter structure of the UpdateUserDefinedEffect Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID to be updated. It should be an existing UserDefined effect. |
| 1 | EffectData | characterString | M | Updated effect data, with an encoding format consistent with the EffectData specification. |
AddUserDefinedEffect Command Structure Type
Parameter structure of the AddUserDefinedEffect Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectName | characterString | M | Name of the new effect; the UTF-8 byte length must not exceed MaxEffectNameLength. |
| 1 | EffectData | characterString | M | Raw data of the new effect, with an encoding format consistent with the EffectData specification. |
GetEffectData Command Structure Type
Parameter structure of the GetEffectData Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID of the effect data to be read; it should exist in the BuiltIn or UserDefined list. |
StartEffect Command Structure Type
Parameter structure of the StartEffect Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectID | enum8 | M | Effect ID to be started; it should be a BuiltIn or UserDefined effect currently supported by the device. |
GoToPositionRotationPercentage Command Structure Type
Parameter structure of the GoToPositionRotationPercentage Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | RotationPercentage | float | M | Tilt rotation percentage. |
RotationControl Command Structure Type
Parameter structure of the RotationControl Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Direction | enum8 | M | Direction. |
StepPosition Command Structure Type
Parameter structure of the StepPosition Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Size | float | M | Step value. |
| 1 | Time | int32 | O | Time. |
GoToPositionPercentage Command Structure Type
Parameter structure of the GoToPositionPercentage Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PositionPercentage | float | M | Open/close ratio. |
| 1 | TransitionTime | uint32 | O | Time. |
Trait Definitions
WindowCoveringOpenOrientation Trait
Identifies the actual opening orientation of the window covering in automatic control.
| Trait ID | Code |
|---|
| 0x80A5 | WindowCoveringOpenOrientation |
Parameters
TravelCalibrationReminderEnable Trait
This Trait is used to enable or disable the travel calibration reminder.
When the Present Value is true, the device should trigger travel calibration reminders according to the periodic configuration of TravelCalibrationReminder and TravelCalibrationCustomDays; when false, the device does not trigger travel calibration reminders.
| Trait ID | Code |
|---|
| 0x5199 | TravelCalibrationReminderEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TravelCalibrationCustomDays Trait
This Trait is used to configure the custom period (in days) for travel calibration reminders.
When the value of TravelCalibrationReminder is Custom, the device should use the Present Value of this Trait as the reminder period.
| Trait ID | Code |
|---|
| 0x504E | TravelCalibrationCustomDays |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 999 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
TravelCalibrationReminder Trait
This Trait is used to configure the travel calibration reminder period.
The device can trigger reminders at fixed levels (two weeks/one month/two months/three months/six months) or custom days; when the value is Custom, it should be used together with TravelCalibrationCustomDays.
| Trait ID | Code |
|---|
| 0x504D | TravelCalibrationReminder |
Parameters
EffectInfo Trait
This Trait provides a list of effect information, each item containing EffectID, EffectData and EffectName, used for maintaining, displaying and synchronizing effect details.
The encoding of EffectData should be consistent with the effect write/preview commands, so that the client can directly display, back up or reuse it after reading.
| Trait ID | Code |
|---|
| 0x4F8A | EffectInfo |
Parameters
LastCalibrationDate Trait
Should indicate the date of the last calibration. Total = Year << 12 | Month << 8 | Day
| Trait ID | Code |
|---|
| 0x50C0 | LastCalibrationDate |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
EffectOperationState Trait
Indicates the current effect operation state of the window covering device (e.g., idle, executing, previewing).
| Trait ID | Code |
|---|
| 0x5062 | EffectOperationState |
Parameters
SafetyStatus Trait
This Trait is used to report the safety status bit set of the device (e.g., obstacle, overload or other protection states).
The client can use this to determine whether the device is in a restricted running state, and decide whether to prompt the user or limit further control.
| Trait ID | Code |
|---|
| 0x5051 | SafetyStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
ChildEndpointList Trait
This attribute should report the child endpoints currently allocated in the configured partitions of the window covering device.
| Trait ID | Code |
|---|
| 0x4F33 | ChildEndpointList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
AutoCalibration Trait
This Trait indicates the current auto calibration mode state of the device.
NormalMode indicates the normal control state; CalibrationMode indicates being in the calibration process. When in a calibration-related mode, some regular control behaviors may be restricted.
| Trait ID | Code |
|---|
| 0x504C | AutoCalibration |
Parameters
MotorMappingExchanged Trait
This Trait indicates whether the logical mapping of the primary/secondary motor has been exchanged.
When the value is true, the device should exchange the primary/secondary motor mapping, used to correct scenarios where the installation wiring direction is inconsistent, without rewiring.
| Trait ID | Code |
|---|
| 0x504A | MotorMappingExchanged |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
StepResolution Trait
This Trait defines the minimum resolution step accepted for position control.
When processing position targets or step requests, the device should align to this resolution (may round to the nearest supported value, or reject requests that do not meet the precision requirement according to device policy).
| Trait ID | Code |
|---|
| 0x5049 | StepResolution |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 100 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 10000 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 100 | RW | O |
ManualPullStrength Trait
This Trait is used to configure the manual pull trigger threshold strength.
The higher the threshold, the greater the external force usually required to trigger a manual pull action.
| Trait ID | Code |
|---|
| 0x5048 | ManualPullStrength |
Parameters
MotorStrength Trait
This Trait is used to configure the motor output strength mode.
Normal is suitable for regular operating conditions, Strong is suitable for load scenarios requiring greater driving force.
| Trait ID | Code |
|---|
| 0x5047 | MotorStrength |
Parameters
EnhanceMode Trait
This Trait represents the enhanced mode bitmap state of the device.
Under the manual calibration capability model, the key bits include: manual calibration mode (bit0), open/close calibration records configured (bit1/bit2); the remaining bits are reserved (bit3-bit7).
ManualCalibration and RemoteTravelRecord features are mutually exclusive; when the device implements one of them, it should keep the bitmap semantics consistent and not mix them.
The remote pairing state is not expressed through the EnhanceMode bitmap; the client should not use bit7 to infer the remote pairing state, but should rely on command responses and device pairing window behavior.
| Trait ID | Code |
|---|
| 0x5046 | EnhanceMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
LimitPointSetting Trait
Used to configure the curtain motor limit points, specifically setting the fully open or fully closed limit position.
| Trait ID | Code |
|---|
| 0x4EAD | LimitPointSetting |
Parameters
MaxEffectNameLength Trait
Indicates the maximum byte length allowed for the EffectName field in user defined effects of the window covering device. This value is fixed by the device, ranging from 1-32.
| Trait ID | Code |
|---|
| 0x4F9C | MaxEffectNameLength |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 32 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
UserDefinedEffects Trait
Contains a list of all user defined effects stored on the window covering device. Each entry includes EffectID (0x80-0xFE) and EffectName.
| Trait ID | Code |
|---|
| 0x4F9B | UserDefinedEffects |
Parameters
MaxUserDefinedEffects Trait
Indicates the maximum number of user defined effects that the window covering device can support.
| Trait ID | Code |
|---|
| 0x4F89 | MaxUserDefinedEffects |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 32 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
CurrentEffectID Trait
Indicates the EffectID of the currently active effect on the window covering device.
| Trait ID | Code |
|---|
| 0x4F88 | CurrentEffectID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x000D | Is Null | boolean | | False | RV | O |
BuiltInEffects Trait
Contains a list of all built-in effects supported by the window covering device. Each entry includes EffectID (0x00-0x7F) and BuiltInEffectLabelID.
| Trait ID | Code |
|---|
| 0x4F87 | BuiltInEffects |
Parameters
SupportedActionTypes Trait
This Trait indicates the set of action types supported by the device in EffectData.
Before sending AddUserDefinedEffect, UpdateUserDefinedEffect or PreviewEffect, the client should constrain the optional action modes based on this list.
| Trait ID | Code |
|---|
| 0x4FAB | SupportedActionTypes |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
TargetPositionRotationPercentage Trait
The current value of the TargetPositionRotationPercentage feature represents the target position that the window covering device tilt will reach or is moving toward, in percentage (unit 1%).
| Trait ID | Code |
|---|
| 0x4F05 | TargetPositionRotationPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CurrentPositionRotationPercentage Trait
The current value of the CurrentPositionRotationPercentage feature represents the actual tilt/rotation position, ranging from 0% to 100%, with a default step of 1%.
| Trait ID | Code |
|---|
| 0x4F04 | CurrentPositionRotationPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
TiltLimitRange Trait
This extended Trait is used to report the tilt/rotation limit range.
| Trait ID | Code |
|---|
| 0x51F0 | TiltLimitRange |
Parameters
CurrentRotationAngle Trait
The current value indicates the current rotation angle of the window covering device, ranging from -90 degrees to 90 degrees.
| Trait ID | Code |
|---|
| 0x8158 | CurrentRotationAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 90.0 | R | O |
| 0x0003 | Minimum Value | float | | -90.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
TargetPositionPercentage Trait
This Trait indicates the current or upcoming target open/close position percentage.
After receiving an open/close position control command, the device should write the target value to this Trait, and keep it consistent with CurrentPositionPercentage after movement completes or is interrupted.
| Trait ID | Code |
|---|
| 0x80A4 | TargetPositionPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
ObstacleLimitMarkingBlockTime Trait
The duration (in seconds) during which the obstacle limit marking function is disabled.
| Trait ID | Code |
|---|
| 0x4EDE | ObstacleLimitMarkingBlockTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 255 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 10 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 255 | RW | O |
LimitPointCount Trait
Represents the number of limit points (or travel limits) configured for curtain-type motors.
| Trait ID | Code |
|---|
| 0x4EDD | LimitPointCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 2 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
ObstacleLimitSensitivity Trait
Refers to the sensitivity setting of the curtain motor when encountering obstacles.
| Trait ID | Code |
|---|
| 0x4EDC | ObstacleLimitSensitivity |
Parameters
ObstacleLimitAutoReboundEnable Trait
When enabled, the curtain motor reverses direction when encountering an obstacle, preventing damage.
| Trait ID | Code |
|---|
| 0x4EDB | ObstacleLimitAutoReboundEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
ObstacleLimitMarkingEnable Trait
Enables or disables the function of marking limit points (open or close) when the motor encounters an obstacle.
| Trait ID | Code |
|---|
| 0x4EDA | ObstacleLimitMarkingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
MotorSpeedPercentage Trait
Defines the motor running speed percentage, ranging from 1 (lowest speed) to 100 (highest speed).
| Trait ID | Code |
|---|
| 0x4ED9 | MotorSpeedPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
MotorSpeedSetting Trait
Defines the motor running speed level, ranging from 1 (lowest speed) to 2 (highest speed).
| Trait ID | Code |
|---|
| 0x4ED8 | MotorSpeedSetting |
Parameters
ManualPullStartStopEnabled Trait
Enables the function that allows users to manually start and stop the curtain/window covering movement by pulling.
| Trait ID | Code |
|---|
| 0x4ED7 | ManualPullStartStopEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
ManualPullStartEnabled Trait
Enables the function that allows users to manually start the curtain/window covering movement by pulling.
| Trait ID | Code |
|---|
| 0x4EAE | ManualPullStartEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
ManualPullStopEnabled Trait
Enables the function that allows users to manually stop the curtain/window covering movement by pulling.
| Trait ID | Code |
|---|
| 0x4EAF | ManualPullStopEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
MotorOperationStatus Trait
Indicates the current running status of the motor.
| Trait ID | Code |
|---|
| 0x4E3F | MotorOperationStatus |
Parameters
WindowCoveringMotorsBinding Trait
Indicates whether multiple motors of a curtain-type device are logically bound for unified control. Values: false = independent control, true = unified master control.
| Trait ID | Code |
|---|
| 0x8157 | WindowCoveringMotorsBinding |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ManualPullEvent Trait
Tracks or emits events triggered by manual pull interactions with the window covering device.
| Trait ID | Code |
|---|
| 0x4EB1 | ManualPullEvent |
Parameters
ManualPullAdaptiveSpeedEnabled Trait
Allows adaptive speed adjustment during manual pull operations, providing pull-force-based variable speed response.
| Trait ID | Code |
|---|
| 0x4EB0 | ManualPullAdaptiveSpeedEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Used to indicate whether control is allowed when the curtain motor device has no travel configured.
| Trait ID | Code |
|---|
| 0x4E26 | UnconfiguredTravelControlPermission |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RV | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
MotorControllability Trait
Indicates whether the motor is currently controllable.
| Trait ID | Code |
|---|
| 0x4E43 | MotorControllability |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
WindowCoveringType Trait
Identifies the window covering product type (e.g., roller shade, venetian blind, curtain, etc.). The value is an enumeration defined in the supported value list (0 = Roller Shade, 1 = Venetian Blind, ... 255 = Unknown).
| Trait ID | Code |
|---|
| 0x80AE | WindowCoveringType |
Parameters
WindowCoveringCategory Trait
Reported by curtain-type devices to classify window covering devices into major categories.
| Trait ID | Code |
|---|
| 0x4E42 | WindowCoveringCategory |
Parameters
MotorDirectionReversed Trait
Specifies whether the motor running direction is reversed, affecting the open/close manner of the window covering device.
| Trait ID | Code |
|---|
| 0x4E41 | MotorDirectionReversed |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Indicates whether the curtain motor travel (movement range) has been configured.
| Trait ID | Code |
|---|
| 0x4E40 | TravelConfigured |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TargetRotationAngle Trait
The current value specifies the target rotation angle of the window covering device, ranging from -90 degrees to 90 degrees.
| Trait ID | Code |
|---|
| 0x8159 | TargetRotationAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 90.0 | R | O |
| 0x0003 | Minimum Value | float | | -90.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
TripTime Trait
Indicates the motor travel time, i.e., the time required from fully open to fully closed (or vice versa), in seconds. Value range 1 to 300 seconds, default 1 second.
| Trait ID | Code |
|---|
| 0x80F9 | TripTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RV | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
CurrentPositionPercentage Trait
Identifies the actual position as a percentage from 0% to 100%, with a default step of 1%.
| Trait ID | Code |
|---|
| 0x80A3 | CurrentPositionPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
LiftLimitRange Trait
This extended Trait is used to report the lift limit range.
| Trait ID | Code |
|---|
| 0x51EF | LiftLimitRange |
Parameters
Command Definitions
RemoveUserDefinedEffects Command
This command should request the device to batch remove user defined effects; only UserDefined type effects can be removed.
The device may return the processing result for each EffectID individually, or return a global error as defined by the implementation.
Effect on Receipt
After receiving the command, the device should validate each EffectID in turn:
- The length of the
EffectIDs list must not exceed the Present Value of the MaxUserDefinedEffects Trait.
- If the target ID does not exist, return a not-found semantic error.
- If the target ID corresponds to a BuiltIn effect, return a "cannot be deleted" semantic error.
- If the target ID corresponds to a UserDefined effect, delete it and return success.
The device may adopt the "per-item result return" or "overall failure return" strategy, but should ensure the final storage state is consistent with the returned semantics.
Parameters
RemoveUserDefinedEffects Command Structure
EnterRemoteControlPairing Command
This command should request the device to enter remote pairing mode and remain pairable for the duration specified by PairingDuration.
The state of this command does not depend on the EnhanceMode bitmap; the device should manage this process through the pairing window state.
Effect on Receipt
After receiving the command, the device should validate whether PairingDuration is within the supported range of the device.
- On validation success: the device should enter remote pairing mode and start the pairing timer.
- If already in remote pairing mode: the device may choose to reset the timer according to the implementation, or keep the existing timer policy.
- When the pairing duration expires: the device should automatically exit remote pairing mode.
Parameters
EnterRemoteControlPairing Command Structure
CommitManualCalibration Command
This command should request the device to commit the current manual calibration temporary records and exit manual calibration mode.
If the open/close key calibration records are incomplete, the command should fail and temporary records should not be persisted.
Effect on Receipt
The device should only process this command in manual calibration mode.
- If the device is not in manual calibration mode: return a "not in manual calibration mode" semantic error.
- If in manual calibration mode and the open/close temporary records are complete: the device should persist the calibration records, exit manual calibration mode, and update EnhanceMode (clear bit0, set bit1/bit2).
- If the temporary records are incomplete: the device should return a "missing calibration records" semantic error, and should not persist the temporary records; it should exit manual calibration mode and clear bit0 to ensure a predictable state.
This Command has no parameters.
ManualCalibrationOperation Command
This command should perform open/close/stop actions in manual calibration mode, used for position adjustment during calibration.
If the device is not in manual calibration mode, the command should return the corresponding error.
Effect on Receipt
The device should only process this command in manual calibration mode.
- When
Operation = Open: the device should move in the opening direction.
- When
Operation = Close: the device should move in the closing direction.
- When
Operation = Stop: the device should immediately stop the current movement.
After successful command execution, the device should reset the manual calibration idle timer; if the device is not in manual calibration mode, it should return the corresponding error.
Parameters
ManualCalibrationOperation Command Structure
EnterManualCalibration Command
This command should request the device to enter manual calibration mode and start the idle timeout timer according to CalibrationTimeout.
When the timeout expires and no valid calibration action is received, the device should automatically exit calibration mode and clean up temporary records.
Effect on Receipt
After receiving the command, the device should validate whether CalibrationTimeout satisfies the supported range of the device.
- On validation success: the device should enter manual calibration mode, set bit0 of EnhanceMode, and start the idle timer according to this parameter.
- When entering manual calibration mode: the device should not clear the saved open/close calibration records, and should not change bit1/bit2 of EnhanceMode.
- During the calibration session, after each successfully processed calibration action command, the device should reset the idle timer.
- After the timer expires: the device should exit manual calibration mode, clear bit0, and discard uncommitted temporary calibration records of this session; uncommitted records should not be persisted.
Parameters
EnterManualCalibration Command Structure
StopPreview Command
This command should request the device to stop the currently running effect preview and resume normal window covering operation.
Effect on Receipt
After receiving the command, the device should stop the current preview effect and restore to the regular control state.
- If a preview effect currently exists: terminate the preview and switch EffectOperationState back to idle or a stable state defined by the device.
- If no preview effect currently exists: the device may return a "no active preview" semantic status, or return success as a no-op according to the implementation.
This Command has no parameters.
PreviewEffect Command
This command should request the device to preview an effect using the provided EffectData without saving. Users can preview an effect before adding or updating a user defined effect.
Effect on Receipt
After receiving the command, the device should validate the EffectData encoding legality and action type support.
- On validation success: the device should enter preview state and execute the corresponding effect, without writing to persistent storage.
- On validation failure: the device SHALL return a parameter or data format error semantic status.
During preview, EffectOperationState SHALL reflect Previewing; after completion, it SHALL return to idle or an implementation-defined state.
Parameters
PreviewEffect Command Structure
RemoveUserDefinedEffect Command
This command should request the device to remove an existing user defined effect. Only UserDefined type effects can be removed; BuiltIn effects cannot be removed.
Effect on Receipt
After receiving the command, the device should validate whether EffectID exists and belongs to the UserDefined range.
- On validation success: the device should delete the effect record and update the UserDefinedEffects list.
- If
EffectID does not exist: return a "effect not found" semantic error.
- If the target is a BuiltIn effect: return a "non-user-defined effects cannot be deleted" semantic error.
Parameters
RemoveUserDefinedEffect Command Structure
UpdateUserDefinedEffect Command
This command should request the device to update an existing user defined effect. Only UserDefined type effects can be updated.
Effect on Receipt
After receiving the command, the device should first validate the legality of EffectID and the data content.
- On validation success: the device should update the corresponding effect data, keeping the effect ID unchanged.
- If
EffectID does not exist: return a "effect not found" semantic error.
- If the target is a BuiltIn effect: return a "non-user-defined effects cannot be updated" semantic error.
Parameters
UpdateUserDefinedEffect Command Structure
AddUserDefinedEffect Command
This command should request the device to add a new user defined effect. The new effect type is UserDefined.
Effect on Receipt
After receiving the command, the device should validate the EffectName length and the EffectData format.
- On validation success and capacity not full: the device should allocate a new UserDefined
EffectID, write the effect and update UserDefinedEffects.
- If the current count reaches MaxUserDefinedEffects: return a "effect count has reached the upper limit" semantic error.
- If the name or data is invalid: return a parameter error semantic status.
Parameters
AddUserDefinedEffect Command Structure
GetEffectData Command
This command should request the device to return the effect data of the specified EffectID. Clients can use it to read stored effect data (e.g., for display, backup or editing).
Effect on Receipt
After receiving the command, the device should validate whether EffectID exists in the BuiltIn or UserDefined list.
- On validation success: the device should return the corresponding
EffectData.
- On validation failure: SHALL return an "invalid scene ID" or "scene not found" semantic error.
Parameters
GetEffectData Command Structure
StartEffect Command
This command should request the device to start the specified window covering effect.
The target EffectID should exist in the BuiltInEffects or UserDefinedEffects list.
Effect on Receipt
After receiving the command, the device should validate the existence and executability of the target EffectID.
- On validation success: the device should start the corresponding effect, update CurrentEffectID to the target ID, and update EffectOperationState to executing.
- On validation failure: return a "effect not found" or "effect invalid" semantic error.
Parameters
StartEffect Command Structure
GoToPositionRotationPercentage Command
The GoToPositionRotationPercentage command is used to set the target tilt position of the window covering device to the percentage value specified in the command. TargetPositionRotationPercentage should be set to RotationPercentage; after completion, CurrentPositionRotationPercentage will be set to the percentage value specified in the command.
Effect on Receipt
After receiving the command, the device should constrain RotationPercentage within the supported range of the device and write it to TargetPositionRotationPercentage.
The device should drive the tilt movement; after reaching the target, it should update CurrentPositionRotationPercentage. If it cannot fully reach due to mechanical boundary constraints, it should stop at the reachable boundary and report the actual position.
Parameters
GoToPositionRotationPercentage Command Structure
RotationControl Command
This command should request the device to perform rotation control in the specified direction.
The device should perform rotation in combination with the current angle boundary, resolution and mechanical constraints, stopping at the boundary when necessary.
Parameters
RotationControl Command Structure
StepPosition Command
This command should request the device to perform a relative position step.
The step direction is determined by the sign of Size; the device should clip the target value within the controllable range and execute at the available resolution.
Effect on Receipt
After receiving the command, the device should calculate the relative target position according to Size.
- When
Size > 0: step in the opening direction.
- When
Size < 0: step in the closing direction.
- When
Size = 0: the device may return a no-action success according to the implementation, or return an invalid parameter semantic error.
If Time is provided, the device should perform the transition at that duration; otherwise, execute according to the device default policy. If the calculation result exceeds the boundary, it should be clipped to the minimum/maximum reachable position.
Parameters
StepPosition Command Structure
GoToPositionPercentage Command
This command should request the device to move to the specified open/close percentage position.
When TransitionTime is provided, the device should try to complete the transition at the specified duration; otherwise, execute according to the device default policy.
Effect on Receipt
After receiving the command, the device should validate and normalize PositionPercentage, and write it to TargetPositionPercentage.
The device should drive the position transition and update MotorOperationStatus during the movement; after reaching the target, it should update CurrentPositionPercentage.
When TransitionTime cannot be satisfied or the device does not support timed transitions, the device may adopt the nearest feasible policy according to implementation capability, but should not exceed the position boundary.
Parameters
GoToPositionPercentage Command Structure
AutoControl Command
This command should request the device to perform a product-defined automatic control action (e.g., switching between preset targets).
The specific policy is defined by the device implementation; the client can trigger it based on the current state and configuration.
This Command has no parameters.
StopMotion Command
This command should request the device to immediately stop the current movement.
After successful execution, the device should keep the current position and update the relevant running status.
This Command has no parameters.
GoToMinPositionPercentage Command
This command should request the device to move to the minimum open/close percentage position (usually corresponding to fully closed or the device-defined minimum endpoint).
This Command has no parameters.
GoToMaxPositionPercentage Command
This command should request the device to move to the maximum open/close percentage position (usually corresponding to fully open or the device-defined maximum endpoint).
This Command has no parameters.
Lifter
Introduction
Provides travel control for lifting-type devices, supporting target position setting, stop and status query.
Function Identification
| Function ID | Code | Name |
|---|
| 0x008A | Lifter | Lifter |
Trait
Command
Data Types
GoToPositionPercentage Command Structure Type
Parameter structure of the GoToPositionPercentage Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PositionPercentage | float | M | Open/close ratio. |
| 1 | TransitionTime | uint32 | O | Time. |
Trait Definitions
TargetPositionPercentage Trait
This Trait is used for access to and reporting of "target position percentage" data.
| Trait ID | Code |
|---|
| 0x80A4 | TargetPositionPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
CurrentPositionPercentage Trait
Identifies the actual position as a percentage from 0% to 100%, with a default step of 1%.
| Trait ID | Code |
|---|
| 0x80A3 | CurrentPositionPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
TripTime Trait
Indicates the motor travel time, i.e., the time required from fully open to fully closed (or vice versa), in seconds. Value range 1 to 300 seconds, default 1 second.
| Trait ID | Code |
|---|
| 0x80F9 | TripTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RV | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
Command Definitions
GoToPositionPercentage Command
This Command is used to perform the "go to position percentage" operation.
Parameters
GoToPositionPercentage Command Structure
StopMotion Command
This Command is used to perform the "stop" operation.
This Command has no parameters.
GoToMinPositionPercentage Command
This Command is used to perform the "go to minimum" operation.
This Command has no parameters.
GoToMaxPositionPercentage Command
This Command is used to perform the "go to maximum" operation.
This Command has no parameters.
AutoControl Command
This Command is used to perform the "automatic control" operation.
This Command has no parameters.
IRControl
Introduction
Provides infrared transmission control capability for controlling traditional IR appliances such as air conditioners and TVs.
Function Identification
| Function ID | Code | Name |
|---|
| 0x008B | IRControl | IR control |
Trait
Command
Data Types
IRKeyEnum32 Type
This enumeration defines the valid values of the Present Value of the IRKey Trait.
| Value | Name | Description |
|---|
| 0x00 | Reserved | Reserved |
| 0x01 | Power | Power |
| 0x02 | Mode | Mode |
| 0x03 | Temp+ | Temp+ |
| 0x04 | Temp- | Temp- |
| 0x05 | WindSpeed | WindSpeed |
| 0x25A5 | P_KEY | P_KEY |
IRTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the IRType Trait.
| Value | Name | Description |
|---|
| 0x00 | AirConditioner | AirConditioner |
| 0x01 | TV | TV |
| 0x02 | Fan | Fan |
| 0x03 | TVBox | TVBox |
| 0x04 | Projector | Projector |
| 0x05 | SettopBox | SettopBox |
| 0x06 | DVD | DVD |
| 0x07 | Heater | Heater |
| 0x08 | AirPurifier | AirPurifier |
| 0x09 | Speaker | Speaker |
| 0x0A | Lighting | Lighting |
| 0x0B | Camera | Camera |
| 0x0C | Customize | Customize |
IRCodeMatchStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the IRCodeMatchStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Default | Default |
| 0x01 | MatchSuccess | Match success |
| 0x02 | MatchFailure | Match failure |
| 0x03 | Redownload | Redownload firmware |
| 0x04 | DownloadSuccess | Code library download success |
IRLearnResultTraitPresentValueStructure Type
This structure defines the Present Value field layout of the IRLearnResult Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | did | characterString | M | Device ID of the gateway that performed the IR learning. |
| 1 | ircode | characterString | M | The learned IR code (Base64 or Hex encoded). |
| 2 | key | characterString | M | Key ID generated during the learning process. |
| 3 | len | uint32 | M | IR code length (in bits or bytes). |
| 4 | success | uint32 | M | Status code: 0 means success, non-zero means failure. |
SetIRDeviceInfo Command Structure Type
Parameter structure of the SetIRDeviceInfo Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | BrandId | uint32 | M | Brand ID; default value 0. |
| 1 | RemoteId | uint32 | M | Remote control ID; default value 0. |
| 2 | ACMode | uint32 | O | AC mode; default value 0. |
| 3 | ACType | uint32 | O | AC type; default value 0. |
SendIRCode Command Structure Type
Parameter structure of the SendIRCode Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Mode | enum8 | M | Mode. |
| 1 | BrandId | uint32 | M | Brand ID. |
| 2 | RemoteId | uint32 | M | Remote control ID. |
| 3 | IRCode | characterString | O | IR compressed code. |
| 4 | IRCodeLength | uint16 | O | IR raw data length. |
| 5 | ACKey | characterString | O | Air conditioner status data. |
| 6 | Frequency | uint32 | M | IR transmission frequency. |
SendIrKey Command Structure Type
Parameter structure of the SendIrKey Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | IRKey | uint32 | O | IR key. |
Trait Definitions
IRKey Trait
This Trait is used for access to and reporting of "IR key" data.
Parameters
IRType Trait
Defines the device type of the IR remote control.
Parameters
IRRemoteId Trait
Indicates the remote control identifier (code library ID) of the IR device.
| Trait ID | Code |
|---|
| 0x5089 | IRRemoteId |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 0 | RW | O |
IRBrandId Trait
Indicates the brand identifier of the IR device (e.g., air conditioner, TV).
| Trait ID | Code |
|---|
| 0x5088 | IRBrandId |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | O | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | O | 0 | RW | O |
IRCodeMatchStatus Trait
Indicates the IR code match or code library download status. Values: 0 = Default (idle), 1 = Match success, 2 = Match failure, 3 = File needs to be redownloaded, 4 = Code library download success.
| Trait ID | Code |
|---|
| 0x506F | IRCodeMatchStatus |
Parameters
IRLearnResult Trait
Reports the result of an IR code learning operation. The device publishes this result when IR code learning is completed. The value is a structure containing:
did (characterString): Device ID of the gateway that performed the learning.
ircode (characterString): The learned IR code (base64 or hex encoded).
key (characterString): Key ID generated during the learning process.
len (uint32): Length of the learned IR code (in bits or bytes).
success (uint32): Status code, 0 means success, 1 means failure (or other non-zero values indicate specific errors).
| Trait ID | Code |
|---|
| 0x508A | IRLearnResult |
Parameters
Command Definitions
SetIRDeviceInfo Command
This command configures IR device information, including brand ID, remote control ID, AC mode and AC type. After receiving the command, the device downloads the corresponding remote control code library. Setting all fields to 0 restores the device to the factory unconfigured state.
Parameters
SetIRDeviceInfo Command Structure
SendIRCode Command
This Command is used to perform the "send IR code" operation.
Parameters
SendIRCode Command Structure
SendIrKey Command
This command sends an IR key to control the target device (e.g., air conditioner, TV).
Parameters
SendIrKey Command Structure
EnergyManagement
Introduction
EnergyManagement is used to describe the energy measurement and management capabilities of a device, including data such as voltage, current, power, energy and grid connection status.
Abbreviations and Units
This section and related energy Functions use the following abbreviations and units. When first reading the energy data definitions, you may refer to this table first.
| Abbreviation/Unit | Full English Name | Chinese Description |
|---|
| PCC | Point of Common Coupling | Point of common coupling; the metering boundary connecting the user's energy system to the public grid. |
| PCS | Power Conversion System | Power conversion system; equipment that converts electric energy between the battery DC side and the AC system. |
| BMS | Battery Management System | Battery management system; monitors and manages battery status and operating boundaries. |
| SOC | State of Charge | State of charge; the percentage of currently available charge of the battery. |
| SOH | State of Health | State of health; describes the performance/capacity health of the battery relative to its initial state. |
| AC | Alternating Current | Alternating current. |
| DC | Direct Current | Direct current. |
| W | watt | Watt, unit of power. |
| kW | kilowatt | Kilowatt, unit of power; 1 kW = 1000 W. |
| W·h | watt-hour | Watt-hour, unit of energy. |
| kWh | kilowatt-hour | Kilowatt-hour, unit of energy; 1 kWh = 1000 W·h. |
| UTC | Coordinated Universal Time | Coordinated Universal Time; timestamps in this specification are expressed in UTC Unix epoch milliseconds. |
| Unix epoch | Unix epoch time | Unix time epoch; the cumulative time since 1970-01-01T00:00:00Z. |
Energy Data Model Usage Guide
This section explains common concepts and their boundaries in energy data, helping implementers select Functions and Traits based on the actual metering position of the device. Whether energy data is comparable first depends on whether the measurement boundary, direction convention and statistics period are consistent; having the same unit alone does not mean the data has the same meaning.
Basic Concepts
| Concept | Meaning | Common Unit | Description |
|---|
| Power | The rate at which energy is transferred or consumed at a given moment | W / kW | Instantaneous measurement; energy is obtained by integrating power over time. |
| Energy | Energy transferred or consumed over a period of time | Wh / kWh | Cumulative energy is usually a non-negative counter; import and export should be accumulated separately and should not cancel each other out. |
| Import | Energy flows from the grid to the user side | W / Wh | Import power/energy at the point of common coupling, used to represent electricity purchased from the grid. |
| Export | Energy flows from the user side to the grid | W / Wh | Export power/energy at the point of common coupling, used to represent electricity fed back to the grid. |
| Generation | Electric energy output by generating equipment | W / Wh | The total PV generation includes on-site self-consumption and grid export; it is not equal to the energy fed back to the grid. |
| Charge/Discharge | Energy flowing into/out of the storage battery respectively | W / Wh | Should be metered separately at the battery-side boundary; charge and discharge use independent non-negative values. |
| SOC | The percentage of the battery's currently available state of charge | % | Estimated or measured by the battery management system; not equivalent to the remaining battery power attribute. |
| Demand | Average power over a specified integration period | W / kW | Maximum demand is the maximum of the average power of each demand interval in a billing period, not the instantaneous power peak. |
Estimation of Currently Available Stored Energy
EnergyStorage/StoredEnergy should give priority to using the effective value directly reported by the device. Consumers may estimate the currently available energy only when the EnergyStorage/StateOfCharge of the same battery is a trusted, valid and sufficiently fresh value, and EnergyStorage/UsableEnergyCapacity is currently valid:
Currently available energy = UsableEnergyCapacity × StateOfCharge / 100
Here, 0% and 100% of SOC correspond to the usable discharge lower limit and charge upper limit configured by the BMS, so SOC should not be normalized again by the optional SOC lower/upper limit parameters. Rated capacity, SOH, power limits or missing parameters cannot replace a trusted SOC or usable capacity; when any input is missing, invalid, expired or semantically unclear, the result must not be calculated or falsely reported as 0. RatedEnergyCapacity, UsableEnergyCapacity, SOC allowed range, maximum charge/discharge power and SOH are all optional information by default.
Measurement Boundary and Direction
At the PCC, import means electric energy enters the user side from the grid, and export means electric energy is sent from the user side to the grid. CurrentForwardTotalActiveEnergy and CurrentReverseTotalActiveEnergy represent import cumulative energy and export cumulative energy respectively in meter/PCC scenarios; both are non-negative cumulative values.
Device-side data must be interpreted using the physical boundary of that device:
- PV generation represents the total generation on the AC output side of the inverter; the export energy at the PCC only represents the part fed into the grid and cannot replace the total generation.
- Storage charge/discharge energy and power use the battery DC terminal as the boundary; the import/export energy of the meter uses the grid AC PCC as the boundary. There are PCS conversion losses between the two boundaries, which cannot be directly treated as equal.
- For storage devices, in
EnergyStorage, charging power/energy means energy flowing into the battery, and discharging power/energy means energy flowing out of the battery. Itemized power and energy are all non-negative values.
ElectricityMetering/GridActivePower uses a signed value: a positive value means flowing from the upstream power source to the user side (purchasing at the PCC), a negative value means reverse flow (feeding back at the PCC).
Unsigned import, export, generation, charge and discharge cumulative values are counted separately, avoiding loss of direction information from netting. Before comparing or summing cumulative values across devices, you must confirm that the measurement boundary, multiplier, unit, counter reset/rollover handling and statistics time range are consistent.
Cumulative Values and Counter Generations
A cumulative value represents the non-negative total since the metering start. The same device endpoint, Function, Trait, metering boundary and counter field constitute a counter identity. Implementations must guarantee that logical cumulative values are monotonically non-decreasing; device restart, network reconnection or software upgrade must not cause readings to roll back. Implementations that can guarantee continuity of logical cumulative values may omit the counter generation.
When an implementation cannot guarantee continuity of logical cumulative values and requires consumers to compute precise differences, it must provide a Counter Generation Parameter (Parameter ID 0x0010, Uint32) on the corresponding cumulative Trait; this Parameter is at the same level as Trait Parameters such as Present Value, Minimum Value and Maximum Value, and is not required by default. The initial generation is 0; when the counter is reset, an uncompensable rollover, or a replacement of the underlying meter causes the cumulative reading to restart, the device must first increment the generation, then publish the new reading. The generation must be persisted and must not roll back; before reaching 4294967295, a new device endpoint/counter identity must be established, and wrap-around is not allowed. The reading and the generation must come from the same consistency snapshot. If the device can maintain the logical cumulative value losslessly after replacing the underlying meter or counter rollover, it may continue to use the same generation or omit the generation.
Maximum Value represents the upper limit of the Trait numeric range and does not automatically represent the hardware rollover modulus. The device should first compensate for identifiable hardware rollover to maintain the logical cumulative value; when lossless compensation is impossible and precise differences are required, increment the generation and re-establish the baseline according to the rules below.
Consumers compute the difference only when the counter identity is the same and the new reading is not less than the old reading: delta = newValue - oldValue. If a generation is provided, the consumer must also confirm that the old and new generations are the same; when the generation changes, the difference for that sampling interval is unknown, and the consumer should establish a baseline with the new reading instead of treating it as consumption for that interval. If the generation is unchanged but the reading decreases, it is invalid/inconsistent data and must not be silently corrected as a reset or rollover. When no generation is provided and the reading decreases, the consumer cannot determine whether it is a reset, rollover or anomaly, and should mark the difference as unavailable and establish a baseline with the new reading. The first reading only establishes a baseline unless there is another reliable metering start.
When a cumulative value is a member of a structure list, each independent counter may carry CounterGeneration in the corresponding data item; the counter identity also includes the stable list key (e.g., circuit number, tariff register number) and cumulative direction. This field is only required when the implementation cannot guarantee continuity of logical cumulative values and precise differences are required. When the source protocol does not provide a generation, the adapter may generate a generation only when it can reliably identify reset/meter replacement events; a decrease in reading alone cannot distinguish between reset, rollover and abnormal values. When it cannot be identified, the difference must be marked unavailable and a baseline re-established, without fabricating precise increments.
Function Selection Guide
| Device/Usage | Recommended Function | Primary Data | Concepts That Should Not Be Confused |
|---|
| General electrical parameters or power-consuming equipment | EnergyManagement | Voltage, current, power, cumulative energy consumption | The CumulativeEnergyConsumption in this Function represents consumption, not generation. |
| PV inverter/generating equipment | EnergyManagement | GeneratedActivePower, CumulativeGeneratedActiveEnergy | Total generation is different from the PCC export energy; self-consumed energy is not counted in the export register. |
| Battery energy storage system | EnergyManagement + EnergyStorage | Grid/device electrical parameters, as well as SOC, capacity, charge/discharge, SOH | PowerSource/BatPercentRemaining is the remaining battery power of the device power supply, not the SOC of the storage system. |
| Electricity meter/PCC metering device | EnergyManagement + ElectricityMetering | Import/export energy, directional grid power, demand, time-of-use registers | The meter measurement position and time/tariff configuration determine the data meaning; not equivalent to PV generation metering. |
Common Energy Flow Examples
In a residential PV storage system, the PCC meter reports the import energy purchased from the grid and the export energy sent to the grid; the PV inverter reports the total PV generation; the battery management system reports the battery-side SOC, cumulative charge energy and cumulative discharge energy. The load consumption of the user side can be reported by a dedicated load meter, or inferred from other metering values when the measurement boundary, time synchronization and conversion losses are all clear. Data from different devices cannot simply be subtracted/added by value to derive unmeasured quantities.
Function Identification
| Function ID | Code | Name |
|---|
| 0x008C | EnergyManagement | Energy management |
Trait
Command
This Function does not contain Commands.
Data Types
PowerModeEnum8 Type
This enumeration defines the valid values of the Present Value of the PowerMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Mains | Mains |
| 0x02 | Battery | Battery |
| 0x03 | DCSource | DC power |
| 0x04 | ACSource | AC power |
SystemInterconnectionStatusEnum8 Type
This enumeration represents the grid connection state of the energy device. Currently, the islanding operation value is defined; other values should be added after the semantics and interoperability rules are clarified.
| Value | Name | Description |
|---|
| 0x00 | Independent | Islanding operation |
Trait Definitions
PowerMode Trait
Indicates the power supply mode of the device.
| Trait ID | Code |
|---|
| 0x8141 | PowerMode |
Parameters
The load voltage value configured for device operation (unit: volts), overriding the internal measurement after initialization.
| Trait ID | Code |
|---|
| 0x4EAB | ConfiguredLoadVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CurrentPower Trait
Indicates the current real-time power consumption. Unit: watt (W).
| Trait ID | Code |
|---|
| 0x80B1 | CurrentPower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
CurrentVoltage Trait
Indicates the currently measured power supply voltage value. Unit: volt (V).
| Trait ID | Code |
|---|
| 0x80B0 | CurrentVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
The externally configured active power value (watts); the device should use it as the load power after initial setup. Unit: W.
| Trait ID | Code |
|---|
| 0x4E80 | ConfiguredLoadPower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 5000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CircuitCurrent Trait
The current flowing through a specific circuit or circuit section, usually used to measure the current load. Unit: A.
| Trait ID | Code |
|---|
| 0x4E3D | CircuitCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CumulativeEnergyConsumption Trait
This Trait is used for access to and reporting of "cumulative energy consumption" data. Unit: W·h.
| Trait ID | Code |
|---|
| 0x80B2 | CumulativeEnergyConsumption |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1.0E8 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
CumulativeGeneratedActiveEnergy Trait
Cumulative generation energy represents the cumulative active energy output by the generating equipment within the current counter generation. For PV devices, the metering boundary is the AC output side of the inverter, including generation for on-site self-consumption, storage charging and grid export; it is not the PCC export energy. This value is a non-negative cumulative counter, unit W·h. Device restart must not clear the reading or generation; when counter reset, uncompensable rollover or meter replacement causes the count to restart, the Counter Generation must be incremented.
| Trait ID | Code |
|---|
| 0x51F7 | CumulativeGeneratedActiveEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
GeneratedActivePower Trait
Generation power represents the active power currently output by the generating equipment. For PV devices, the metering boundary is the AC output side of the inverter; this value does not include the PCC net power direction, unit W. Report 0 when there is no generation or the device is in standby.
| Trait ID | Code |
|---|
| 0x51F8 | GeneratedActivePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
PhaseAVoltage Trait
Represents the real-time voltage of phase A in a three-phase power supply system, used to determine whether the phase power supply is stable and whether there are undervoltage, overvoltage or phase imbalance issues. Unit: V.
| Trait ID | Code |
|---|
| 0x51B0 | PhaseAVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 220 | RV | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 220 | RW | O |
PhaseBVoltage Trait
Represents the real-time voltage of phase B in a three-phase power supply system, used to determine the phase power supply stability and voltage anomalies. Unit: V.
| Trait ID | Code |
|---|
| 0x51B1 | PhaseBVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 220 | RV | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 220 | RW | O |
PhaseCVoltage Trait
Represents the real-time voltage of phase C in a three-phase power supply system, used to determine the phase power supply stability and voltage anomalies. Unit: V.
| Trait ID | Code |
|---|
| 0x51B2 | PhaseCVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 220 | RV | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 220 | RW | O |
CurrentForwardTotalActiveEnergy Trait
Represents the cumulative active energy obtained forward from the grid by the device, commonly used for statistics of actual power consumption, energy analysis and billing settlement. Unit: W·h.
In a PCC meter scenario, the forward direction is defined as flowing from the grid to the user side (import/purchase), and this value is a non-negative cumulative value. Other measurement boundaries must clarify the forward meaning in the corresponding device/Function definitions, and must not infer generation or storage charging from the Forward name alone.
| Trait ID | Code |
|---|
| 0x51B3 | CurrentForwardTotalActiveEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 100000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CurrentReverseTotalActiveEnergy Trait
Represents the cumulative active energy fed back to the grid by the device, commonly used for analyzing feedback energy, grid-connected operation and energy recovery. Unit: W·h.
In a PCC meter scenario, the reverse direction is defined as flowing from the user side to the grid (export/feed-in), and this value is a non-negative cumulative value. This value is not equal to the total generation of the generating equipment; other measurement boundaries must clarify the reverse meaning in the corresponding device/Function definitions.
| Trait ID | Code |
|---|
| 0x51B4 | CurrentReverseTotalActiveEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 100000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
PhaseACurrent Trait
Represents the real-time current of phase A in a three-phase power supply system, used to determine the phase load size, running current status and whether there is an overload risk.
| Trait ID | Code |
|---|
| 0x51B5 | PhaseACurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
PhaseBCurrent Trait
Represents the real-time current of phase B in a three-phase power supply system, used to determine the phase load size and whether there is phase imbalance among the three phases. Unit: A.
| Trait ID | Code |
|---|
| 0x51B6 | PhaseBCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
PhaseCCurrent Trait
Represents the real-time current of phase C in a three-phase power supply system, used to determine the phase load size and whether there is phase imbalance among the three phases. Unit: A.
| Trait ID | Code |
|---|
| 0x51B7 | PhaseCCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Frequency Trait
Represents the real-time frequency of the AC power supply system, used to determine whether the grid operation is stable and whether there are frequency fluctuations or supply anomalies. Unit: Hz.
| Trait ID | Code |
|---|
| 0x51B8 | Frequency |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
TotalActivePower Trait
Represents the total active power actually being done by the device, an important indicator reflecting the real load level, energy consumption state and operating intensity. Unit: W.
| Trait ID | Code |
|---|
| 0x51B9 | TotalActivePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
TotalReactivePower Trait
Represents the total reactive power of the device, used to evaluate reactive power compensation requirements, power quality levels and power supply/distribution operation status. Unit: kvar.
| Trait ID | Code |
|---|
| 0x51BA | TotalReactivePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
TotalApparentPower Trait
Represents the total apparent power of the device, i.e., the combined power formed by voltage and current, used together with active power and power factor to analyze load characteristics. Unit: kVA.
| Trait ID | Code |
|---|
| 0x51BB | TotalApparentPower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
PowerFactor Trait
Represents the ratio of active power to apparent power in an AC circuit, used to measure how effectively electric energy is utilized. The closer the value is to 1, the smaller the reactive loss; commonly used in distribution monitoring, energy efficiency evaluation and operation analysis.
| Trait ID | Code |
|---|
| 0x51BC | PowerFactor |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RV | O |
| 0x0002 | Maximum Value | float | | 1.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 1 | RW | O |
SystemInterconnectionStatus Trait
The system grid connection state represents the current grid connection operation mode of the energy device; currently the islanding operation state is defined, and other states will be added after the semantics and interoperability rules are clarified.
| Trait ID | Code |
|---|
| 0x5232 | SystemInterconnectionStatus |
Parameters
Command Definitions
This Function does not contain any Commands.
HeaterCooler (Heating/Cooling Control Function)
Introduction
Provides heating/cooling control capabilities, including HVAC parameters such as target temperature, operating mode, and fan speed.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x008D | HeaterCooler | Heating/cooling control function |
Trait
Command
Data Types
HeaterCoolerModeEnum8 Type
This enumeration defines the valid values of the Present Value of the HeaterCoolerMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Cool | Cooling |
| 0x01 | Heat | Heating |
| 0x02 | Auto | Auto |
| 0x03 | Fan | Fan only |
| 0x04 | Dry | Dehumidify |
| 0x05 | Sleep | Sleep |
| 0x06 | FreshAir | Fresh air |
| 0x07 | FloorHeat | Floor heating |
| 0x08 | HeatandFloorHeat | Strong heat |
| 0x09 | FloorHeatandFreshAir | Floor heating + fresh air |
| 0x0A | EmergencyHeat | Quick heat |
| 0x0B | Precooling | Pre-cool |
| 0x0C | Off | Off |
| 0x0D | Manual | Manual |
| 0x0E | AntiFreeze | Anti-freeze |
SchedulesTraitPresentValueStructure Type
This structure defines the Present Value field layout of the Schedules Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ScheduleHandle | characterString | O | Schedule handle; null when creating a new schedule. |
| 1 | SystemMode | enum8 | M | System mode. |
| 2 | Transitions | list[Struct] | M | Schedule transition list (ScheduleTransitionStruct). |
| 3 | BuiltIn | boolean | M | Whether it is a built-in schedule. |
ScheduleTypesTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ScheduleTypes Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SystemMode | enum8 | M | System mode (consistent with the HeaterCoolerMode enumeration). |
| 1 | NumberOfSchedules | uint8 | M | Number of schedules supported in this mode. |
| 2 | ScheduleTypeFeatures | uint8 | M | Schedule type capability bitmap. |
PresetTraitPresentValueStructure Type
This structure defines the Present Value field layout of the Preset Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresetHandle | characterString | M | Preset handle. |
| 1 | PresetScenario | enum8 | M | Preset scenario: 1=Occupied, 2=Unoccupied, 3=Sleep, 4=Wake, 5=Vacation, 6=GoingToSleep; 7-254=Reserved. |
| 2 | Name | characterString | O | Preset name; omitted if null. |
| 3 | CoolingSetpoint | float | O | Cooling set temperature, default 26. |
| 4 | HeatingSetpoint | float | O | Heating set temperature, default 20. |
| 5 | BuiltIn | boolean | M | Whether it is a built-in preset, default false. |
HeaterCoolerPolarityEnum8 Type
This enumeration defines the valid values of the Present Value of the HeaterCoolerPolarity Trait.
| Value | Name | Description |
|---|
| 0x00 | Forward | Forward (heating) |
| 0x01 | Reverse | Reverse (cooling) |
| 0x02 | Bidirectional | Bidirectional |
This enumeration defines the valid values of the Present Value of the HeaterCoolerButtonEvent Trait.
| Value | Name | Description |
|---|
| 0x00 | PowerShortPress | Power short press |
| 0x01 | FanSpeedShortPress | Fan speed short press |
| 0x02 | TempUpShortPress | Temperature + short press |
| 0x03 | TempDownShortPress | Temperature - short press |
| 0x04 | ModeShortPress | Mode short press |
| 0x10 | PowerMidPress | Power medium press |
| 0x11 | FanSpeedMidPress | Fan speed medium press |
| 0x12 | TempUpMidPress | Temperature + medium press |
| 0x13 | TempDownMidPress | Temperature - medium press |
| 0x14 | ModeMidPress | Mode medium press |
| 0x30 | PowerLongPress | Power long press |
| 0x31 | FanSpeedLongPress | Fan speed long press |
| 0x32 | TempUpLongPress | Temperature + long press |
| 0x33 | TempDownLongPress | Temperature - long press |
| 0x34 | ModeLongPress | Mode long press |
TemperatureUIDisplayModeEnum8 Type
This enumeration defines the valid values of the Present Value of the TemperatureUIDisplayMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Celsius | Celsius |
| 0x01 | Fahrenheit | Fahrenheit |
AcPumpStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the AcPumpStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | On | On |
HvacCommStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the HvacCommStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Abnormal | Communication abnormal |
| 0x01 | Normal | Communication normal |
ThermostatBaseTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the ThermostatBaseType Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Freon | Fluorine system version |
| 0x02 | Water | Water system version |
DefrostStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the DefrostStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | No | No |
| 0x01 | Yes | Defrosting |
AntifreezeStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the AntifreezeStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Inactive | Not in anti-freeze protection |
| 0x01 | Active | In anti-freeze protection |
This enumeration defines the valid values of the Present Value of the OpenWindowAlarm Trait.
| Value | Name | Description |
|---|
| 0x00 | NoAlarm | No open window alarm |
| 0x01 | InternalOpenWindowAlarm | Open window alarm detected by built-in probe |
| 0x02 | ExternalOpenWindowAlarm | Open window alarm detected by external sensor |
SetHvac Command Structure Type
Parameter structure of the SetHvac Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Power | enum8 | O | Power switch; default value 0. |
| 1 | Mode | enum8 | O | Mode; default value 0. |
| 2 | Temperature | float | O | Set temperature; default value 26. |
| 3 | FanSpeed | enum8 | O | Fan speed; default value 0. |
| 4 | SwingDirection | enum8 | O | Air direction; default value 0. |
| 5 | LightSwitch | enum8 | O | Light switch; default value 0. |
SetActiveSchedule Command Structure Type
Parameter structure of the SetActiveSchedule Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ScheduleHandle | characterString | M | Schedule handle. |
SetActivePreset Command Structure Type
Parameter structure of the SetActivePreset Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresetHandle | characterString | M | Preset operation. |
Trait Definitions
HeaterCoolerMode Trait
This Trait is used for access to and reporting of "heater/cooler mode" data.
| Trait ID | Code |
|---|
| 0x80B3 | HeaterCoolerMode |
Parameters
CurrentTemperature Trait
Indicates the current temperature. Unit: deg C.
| Trait ID | Code |
|---|
| 0x80B8 | CurrentTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 26 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 26 | RW | O |
TRVValvePosition Trait
This Trait is used for access to and reporting of "valve position" data. Unit: %.
| Trait ID | Code |
|---|
| 0x5050 | TRVValvePosition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
SummerMode Trait
This Trait is used for access to and reporting of "summer mode" data.
| Trait ID | Code |
|---|
| 0x504F | SummerMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Schedules Trait
This Trait is used for access to and reporting of "smart schedule" data.
| Trait ID | Code |
|---|
| 0x5045 | Schedules |
Parameters
ActiveScheduleHandle Trait
This Trait is used for access to and reporting of "current schedule handle" data.
| Trait ID | Code |
|---|
| 0x5044 | ActiveScheduleHandle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
NumberOfScheduleTransitionPerDay Trait
This Trait is used for access to and reporting of "number of schedule transitions per day" data.
| Trait ID | Code |
|---|
| 0x5043 | NumberOfScheduleTransitionPerDay |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
NumberOfScheduleTransitions Trait
This Trait is used for access to and reporting of "number of schedule transitions" data.
| Trait ID | Code |
|---|
| 0x5042 | NumberOfScheduleTransitions |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
NumberOfSchedules Trait
This Trait is used for access to and reporting of "number of schedules" data.
| Trait ID | Code |
|---|
| 0x5041 | NumberOfSchedules |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ScheduleTypes Trait
This Trait is used for access to and reporting of "schedule types" data.
| Trait ID | Code |
|---|
| 0x5040 | ScheduleTypes |
Parameters
Preset Trait
This Trait is used for access to and reporting of "preset" data.
Parameters
ActivePresetHandle Trait
This Trait is used for access to and reporting of "active preset handle" data.
| Trait ID | Code |
|---|
| 0x4EF1 | ActivePresetHandle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | null | RVW | O |
| 0x0007 | Default Value | characterString | | null | RW | O |
NumberOfPresets Trait
This Trait is used for access to and reporting of "number of presets" data.
| Trait ID | Code |
|---|
| 0x4EF0 | NumberOfPresets |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
PresetTypes Trait
This Trait is used for access to and reporting of "preset types" data.
| Trait ID | Code |
|---|
| 0x4EEF | PresetTypes |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RVW | O |
AntiFreezeTemperature Trait
The anti-freeze protection temperature setting usually refers to the threshold that triggers the anti-freeze mechanism (e.g., 5 degC).
| Trait ID | Code |
|---|
| 0x4EC4 | AntiFreezeTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 5 | RVW | O |
| 0x0002 | Maximum Value | float | | 15.0 | R | O |
| 0x0003 | Minimum Value | float | | 5.0 | R | O |
| 0x0005 | Step Value | float | | 0.5 | R | O |
| 0x0007 | Default Value | float | | 5 | RW | O |
HeaterCoolerPolarity Trait
Specifies the polarity configuration, used to determine whether the system controls cooling or heating.
| Trait ID | Code |
|---|
| 0x4E82 | HeaterCoolerPolarity |
Parameters
Events triggered by button interactions on the thermostat or climate control device.
| Trait ID | Code |
|---|
| 0x4E81 | HeaterCoolerButtonEvent |
Parameters
SetBack Trait
Represents the thermostat temperature setback range. Unit: deg C.
| Trait ID | Code |
|---|
| 0x4E6C | SetBack |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 25.5 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
TemperatureUIDisplayMode Trait
This feature should specify the unit used by the built-in screen of the thermostat to display temperature.
| Trait ID | Code |
|---|
| 0x4E37 | TemperatureUIDisplayMode |
Parameters
MinHeatCoolDeadBand Trait
Indicates the minimum difference between heating and cooling temperatures in auto mode. Unit: deg C.
| Trait ID | Code |
|---|
| 0x8144 | MinHeatCoolDeadBand |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 2 | RVW | O |
| 0x0002 | Maximum Value | float | | 2.5 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 2 | RW | O |
CurrentHumidity Trait
This Trait is used for access to and reporting of "humidity" data. Unit: %.
| Trait ID | Code |
|---|
| 0x80B9 | CurrentHumidity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
CoolingTemperature Trait
Indicates the cooling temperature. Unit: deg C.
| Trait ID | Code |
|---|
| 0x80B5 | CoolingTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 26 | RVW | O |
| 0x0002 | Maximum Value | float | | 32.0 | R | O |
| 0x0003 | Minimum Value | float | | 16.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 26 | RW | O |
HeatingTemperature Trait
Indicates the heating temperature. Unit: deg C.
| Trait ID | Code |
|---|
| 0x80B4 | HeatingTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 18 | RVW | O |
| 0x0002 | Maximum Value | float | | 30.0 | R | O |
| 0x0003 | Minimum Value | float | | 5.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 18 | RW | O |
SetTemperature Trait
SetTemperature allows the user to specify and adjust the target temperature of the device or system. Unit: deg C.
| Trait ID | Code |
|---|
| 0x4E5B | SetTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 20 | RVW | O |
| 0x0002 | Maximum Value | float | | 32 | R | O |
| 0x0003 | Minimum Value | float | | 5 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 20 | RW | O |
AcPreheatStatus Trait
Indicates whether the air conditioner is currently in the preheat state. A value of 0 means no (not preheating), 1 means yes (preheating).
| Trait ID | Code |
|---|
| 0x5154 | AcPreheatStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
FilterCleanRequired Trait
Indicates whether the air conditioner filter needs cleaning. A value of 0 means no cleaning required, 1 means cleaning required.
| Trait ID | Code |
|---|
| 0x5156 | FilterCleanRequired |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AcPumpStatus Trait
Indicates the current running status of the air conditioner water pump. A value of 1 means the pump is on (working), 0 means the pump is off (stopped).
| Trait ID | Code |
|---|
| 0x5157 | AcPumpStatus |
Parameters
HvacCommStatus Trait
Indicates whether the communication link between the HVAC equipment (such as air conditioner, fresh air system) and the controller (thermostat or gateway) is normal. A value of 0 indicates abnormal communication, in which case control operations cannot be performed; a value of 1 indicates normal communication, and control commands can be sent normally.
| Trait ID | Code |
|---|
| 0x5158 | HvacCommStatus |
Parameters
AntifreezeModeEnable Trait
Used to enable or disable the anti-freeze mode of the device. When enabled, the device starts the anti-freeze protection mechanism (such as maintaining a minimum temperature or circulating water) to prevent pipes or components from freezing and being damaged by low temperature.
| Trait ID | Code |
|---|
| 0x5159 | AntifreezeModeEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
FloorHeatingBrand Trait
Indicates the brand name of the floor heating system connected to the current thermostat. This value is a readable text string.
| Trait ID | Code |
|---|
| 0x515A | FloorHeatingBrand |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
QuickCoolEnable Trait
Used to start or stop the quick cool (fast cooling) function of the air conditioner. When enabled (value 1), the air conditioner operates at maximum cooling capacity to quickly lower the room temperature. When stopped (value 0), the quick cool function exits and the device returns to normal cooling mode. This Trait can be used both to send control commands (write) and to report the current quick cool status (report).
| Trait ID | Code |
|---|
| 0x515B | QuickCoolEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ThermostatBaseType Trait
Indicates the base type of the thermostat. A value of 0 means unknown, 1 means fluorine system version (refrigerant system), 2 means water system version (water system).
| Trait ID | Code |
|---|
| 0x515F | ThermostatBaseType |
Parameters
AcSelfCleaningEnable Trait
Used to enable or disable the self-cleaning function of the air conditioner. This function can only be enabled when the air conditioner is powered off and the device supports self-cleaning. When enabled (value 1), the air conditioner performs the self-cleaning process (such as drying, sterilization) to keep the interior clean.
| Trait ID | Code |
|---|
| 0x5160 | AcSelfCleaningEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AcErrorCode Trait
Indicates the fault code of the air conditioner device, used to diagnose abnormal operation. This value is a readable text string.
| Trait ID | Code |
|---|
| 0x5161 | AcErrorCode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
AcBrand Trait
Indicates the brand name of the air conditioner device connected to the thermostat. This value is a readable text string.
| Trait ID | Code |
|---|
| 0x5164 | AcBrand |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
DefrostStatus Trait
Indicates whether the device is currently performing a defrost operation. A value of 0 means not defrosting, 1 means defrosting.
| Trait ID | Code |
|---|
| 0x5165 | DefrostStatus |
Parameters
FloorHeatingErrorCode Trait
Indicates the fault code of the floor heating device, used to diagnose abnormal operation. This value is a readable text string.
| Trait ID | Code |
|---|
| 0x5167 | FloorHeatingErrorCode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
AntifreezeStatus Trait
Indicates whether the thermostat is currently in the anti-freeze protection state. When in anti-freeze protection, the device takes corresponding measures to prevent freezing damage.
| Trait ID | Code |
|---|
| 0x5168 | AntifreezeStatus |
Parameters
OpenWindowAlarm Trait
Indicates the current open window alarm state of the thermostat.
When open window detection is enabled (EnableOpenWindowDetection is true) and an open window is detected, the thermostat sets this Trait to internal probe alarm (Internal open window alarm) or external sensor alarm (External open window alarm) and pauses temperature control. If OpenWindowTemperatureControlPauseDuration is supported, the thermostat pauses temperature control for the specified duration unless the alarm is cleared in advance; if not supported, the pause duration is determined by the specific device implementation.
When the open window condition is resolved or the alarm is successfully cleared via ClearOpenWindowAlarmReq, the thermostat sets this Trait to no alarm (No alarm) and immediately resumes temperature control. When open window detection is disabled (EnableOpenWindowDetection is false), the thermostat may set this Trait to no alarm and immediately resume temperature control.
| Trait ID | Code |
|---|
| 0x518E | OpenWindowAlarm |
Parameters
EnableOpenWindowDetection Trait
Indicates whether the thermostat enables the open window detection function.
When set to true, the thermostat can detect an open window through rapid temperature changes, external sensor input or product-specific logic, and adjust local temperature control behavior accordingly. When set to false, the thermostat does not apply temperature control behavior specific to open window detection, resets OpenWindowAlarm to no alarm, and immediately resumes temperature control.
| Trait ID | Code |
|---|
| 0x518F | EnableOpenWindowDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
OpenWindowTemperatureControlPauseDuration Trait
Specifies the duration for which the thermostat pauses temperature control after an open window alarm is triggered, in minutes.
The value range is constrained by the minimum (OpenWindowTemperatureControlPauseDurationMin, default 1 minute) and the maximum (OpenWindowTemperatureControlPauseDurationMax, default 1440 minutes/24 hours). When an open window alarm is detected, the thermostat pauses temperature control for this duration unless restored in advance via the clear alarm command.
| Trait ID | Code |
|---|
| 0x5190 | OpenWindowTemperatureControlPauseDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 30 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 1440 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 30 | RW | O |
Command Definitions
SetHvac Command
This command configures the air conditioner; optional parameters include: power, running mode, target temperature, fan speed, swing direction and display light.
Parameters
SetHvac Command Structure
SetActiveSchedule Command
This Command is used to perform the "set active schedule" operation.
Parameters
SetActiveSchedule Command Structure
ClearActivePreset Command
This Command is used to perform the "clear active preset" operation.
This Command has no parameters.
SetActivePreset Command
This Command is used to perform the "set active preset" operation.
Parameters
SetActivePreset Command Structure
ClearOpenWindowAlarm Command
Requests the thermostat to clear the currently active open window alarm.
After successful execution, the thermostat sets OpenWindowAlarm to no alarm (No alarm) and immediately resumes temperature control.
This Command has no parameters.
FanControl
Introduction
Provides fan speed and mode control, supporting level adjustment and running status reading.
Function Identification
| Function ID | Code | Name |
|---|
| 0x008E | FanControl | Fan control |
Trait
Command
This Function does not contain Commands.
Data Types
FanModeEnum8 Type
This enumeration defines the valid values of the Present Value of the FanMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | LowSpeed | Low |
| 0x02 | MediumSpeed | Medium |
| 0x03 | HighSpeed | High |
| 0x04 | Auto | Auto |
| 0x05 | Smart | Smart |
RockSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the RockSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | RockLeftRight | Left and right |
| 0x02 | RockUpDown | Up and down |
| 0x03 | RockRound | Circulate |
| 0x04 | Swing | Rock |
| 0x05 | FixedDirection | Fixed |
| 0x15 | Fixed | Fixed air direction |
AirflowDirectionEnum8 Type
This enumeration defines the valid values of the Present Value of the AirflowDirection Trait.
| Value | Name | Description |
|---|
| 0x00 | Forward | Forward |
| 0x01 | Reverse | Reverse |
WindSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the WindSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Sleep | Sleep |
| 0x02 | Natural | Natural |
Trait Definitions
FanMode Trait
FanMode defines the mode of the fan.
| Trait ID | Code |
|---|
| 0x80B6 | FanMode |
Parameters
RockSetting Trait
Defines the swing/rocking mode.
| Trait ID | Code |
|---|
| 0x80B7 | RockSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | RockSettingEnum8 | | 0 | RVW | O |
| 0x0006 | Supported Value | list[RockSettingEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
FanSpeed Trait
FanSpeed represents the fan speed percentage.
| Trait ID | Code |
|---|
| 0x0008 | FanSpeed |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 100 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
AirflowDirection Trait
AirflowDirection defines the airflow direction.
| Trait ID | Code |
|---|
| 0x0007 | AirflowDirection |
Parameters
WindSetting Trait
WindSetting defines the type of wind.
| Trait ID | Code |
|---|
| 0x0006 | WindSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | WindSettingEnum8 | | 0 | RVW | O |
| 0x0006 | Supported Value | list[WindSettingEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Temperature
Introduction
Measures and reports the ambient temperature, providing attributes such as the current temperature value and valid range.
Function Identification
| Function ID | Code | Name |
|---|
| 0x008F | Temperature | Temperature |
Trait
Command
This Function does not contain Commands.
Data Types
TemperatureSourceTraitPresentValueStructure Type
This structure defines the list item field layout of the TemperatureSource Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DeviceDid | characterString | M | Unique identifier of the temperature source device (Device DID). If it is the local device, fill in the local DID. |
| 1 | PointPath | characterString | O | Temperature data point access path, format {Endpoint ID}.{Function ID}.{Trait ID}.{Parameter ID}, for example 2.143.32952.1. If empty, it means using the default temperature data point of the device specified by the device ID in parameter 0. |
Trait Definitions
CurrentTemperature Trait
Indicates the current temperature. Unit: deg C.
| Trait ID | Code |
|---|
| 0x80B8 | CurrentTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 26 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 26 | RW | O |
CentiCelsiusTemperature Trait
A numeric representation of temperature in degrees Celsius, where each unit equals one hundredth of a degree Celsius (0.01 degC). This format uses integer values to represent high-precision temperature readings; for example, the value 2500 corresponds to 25.00 degC.
| Trait ID | Code |
|---|
| 0x502F | CentiCelsiusTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RV | O |
| 0x0002 | Maximum Value | int32 | | 10000 | R | O |
| 0x0003 | Minimum Value | int32 | | -5000 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
TemperatureSource Trait
Represents the temperature source configuration used by the current temperature data. This Trait is a list; each list item contains a device ID (mandatory) and a temperature data point access path (optional), used to specify whether the temperature collected by the thermostat comes from the local sensor or an associated external sensor. If point_path is empty, it means using the default temperature data point of the device specified by that device ID. When multiple data sources exist in the list, it means there is more than one data source, and a certain agreed rule can be used to preferentially select one data source as the current temperature.
| Trait ID | Code |
|---|
| 0x5173 | TemperatureSource |
Parameters
InletTemperature Trait
Represents the temperature of the medium entering the pipe section where the flow meter is located, used to analyze operating conditions together with flow data. Unit: degC.
| Trait ID | Code |
|---|
| 0x51BF | InletTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
OutletTemperature Trait
Represents the temperature of the medium leaving the pipe section where the flow meter is located, used to analyze operating conditions together with flow data. Unit: degC.
| Trait ID | Code |
|---|
| 0x51C0 | OutletTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
OutdoorTemperature Trait
Outdoor temperature represents the outdoor ambient temperature measured by the device, unit deg C; it is reported separately from the indoor CurrentTemperature of the air conditioner.
| Trait ID | Code |
|---|
| 0x523D | OutdoorTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | -50-100 deg C | No fixed default value; reports the current value | RV | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | -50 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
Command Definitions
This Function does not contain Commands.
RelativeHumidity
Introduction
Measures and reports the ambient relative humidity, providing attributes such as the current humidity value and valid range.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0090 | RelativeHumidity | Humidity |
Trait
Command
This Function does not contain Commands.
Data Types
HumiditySourceTraitPresentValueStructure Type
This structure defines the list item field layout of the HumiditySource Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DeviceDid | characterString | M | Unique identifier of the humidity source device (Device DID). If it is the local device, fill in the local DID. |
| 1 | PointPath | characterString | O | Humidity data point access path, format: {Endpoint ID}.{Function ID}.{Trait ID}.{Parameter ID}, for example 2.144.32953.1. If empty, it means using the default humidity data point of the device specified by that device ID in parameter 0. |
Trait Definitions
CurrentHumidity Trait
This Trait is used for access to and reporting of "humidity" data. Unit: %.
| Trait ID | Code |
|---|
| 0x80B9 | CurrentHumidity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
CentiPercentHumidity Trait
The humidity value is represented as an integer, where each unit equals 0.01% relative humidity (e.g., the value 5000 represents 50.00% RH).
| Trait ID | Code |
|---|
| 0x5030 | CentiPercentHumidity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 10000 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
HumiditySource Trait
Represents the humidity source configuration used by the current humidity data. This Trait is a list; each list item contains a device ID (mandatory) and a humidity data point access path (optional), used to specify whether the humidity collected by the thermostat comes from the local sensor or an associated external sensor. If PointPath is empty, it means using the default humidity data point of the device specified by that device ID in parameter 0. When multiple data sources exist in the list, it means there is more than one data source, and a certain agreed rule can be used to preferentially select one data source as the current humidity.
| Trait ID | Code |
|---|
| 0x5174 | HumiditySource |
Parameters
Command Definitions
This Function does not contain Commands.
Introduction
Provides media playback control capabilities, including play, pause, track switching, volume and playback status management.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0091 | MediaPlayback | Media playback |
Trait
Command
Data Types
CurrentPlaybackStateEnum8 Type
This enumeration defines the valid values of the Present Value of the CurrentPlaybackState Trait.
| Value | Name | Description |
|---|
| 0x00 | Playing | Playing |
| 0x01 | Paused | Paused |
| 0x02 | Stopped | Stopped |
| 0x03 | Buffering | Buffering |
| 0x04 | FastForwarding | Fast forwarding |
| 0x05 | Rewinding | Rewinding |
TargetPlaybackStateEnum8 Type
This enumeration defines the valid values of the Present Value of the TargetPlaybackState Trait.
| Value | Name | Description |
|---|
| 0x00 | Play | Play |
| 0x01 | Pause | Pause |
| 0x02 | Stop | Stop |
| 0x03 | StartOver | Replay |
| 0x04 | FastForward | Fast forward |
| 0x05 | Rewind | Rewind |
| 0x06 | Previous | Previous track |
| 0x07 | Next | Next track |
| 0x08 | PlaySpecificList | Play specified playlist |
This enumeration defines the valid values of the Present Value of the SelectedMediaOutputSource Trait.
| Value | Name | Description |
|---|
| 0x00 | Internal | Internal |
| 0x01 | Bluetooth | Bluetooth |
| 0x02 | Aux | Auxiliary |
| 0x03 | SPDIF | SPDIF |
| 0x04 | Coaxial | Coaxial |
| 0x05 | Audio1 | Audio 1 |
| 0x06 | Audio2 | Audio 2 |
| 0x07 | Audio3 | Audio 3 |
| 0x08 | AV1 | AV1 |
| 0x09 | AV2 | AV2 |
| 0x0A | AV3 | AV3 |
| 0x0B | HDMI1 | HDMI1 |
| 0x0C | HDMI2 | HDMI2 |
| 0x0D | HDMI3 | HDMI3 |
| 0x0E | Other | Other |
SelectedSourceEnum8 Type
This enumeration defines the valid values of the Present Value of the SelectedSource Trait.
| Value | Name | Description |
|---|
| 0x00 | Internal | Internal |
| 0x01 | Bluetooth | Bluetooth |
| 0x02 | External | External |
PlaybackModeEnum8 Type
This enumeration defines the valid values of the Present Value of the PlaybackMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Shuffle | Shuffle |
| 0x01 | Order | Order |
| 0x02 | SingleCycle | SingleCycle |
| 0x03 | AllCycle | AllCycle |
This enumeration defines the valid values of the playlist/favorite load action.
| Value | Name | Description |
|---|
| 0x00 | APPEND | Append to the end of the current queue. |
| 0x01 | REPLACE | Clear the current queue and replace with the new content. |
| 0x02 | INSERT_NEXT | Insert after the currently playing item. |
Parameter structure of the MediaPlaybackCommand Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | MediaType | enum8 | M | Media type; default value 0; media types: 0: Music, 1: Video, 2: Radio. |
| 1 | Command | characterString | O | Command content, e.g., "I want to listen to Jay Chou's songs". |
| 2 | Title | characterString | O | Media name, e.g., "Qilixiang". |
SearchAndPlay Command Structure Type
Parameter structure of the SearchAndPlay Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Keyword | characterString | O | Search keyword, such as song name, artist name or other search criteria. |
| 1 | Artist | characterString | O | Artist name, used for precise filtering. |
| 2 | Track | characterString | O | Song name, used for precise filtering. |
Parameter structure of the PlayMediaURL Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | MediaURL | characterString | M | URL pointing to an audio resource that can be played directly. The device shall treat it as the playback target and shall not interpret it as a search keyword; URLs of ordinary web pages or search result pages are not directly playable resources. |
| 1 | Title | characterString | O | Media title, used only for display or media information; it does not change the playback target specified by MediaURL. |
Playlists Trait
This Trait is used to return the playlists created by the user in the current music service account; it supports reading and reporting.
PlaylistsTraitPresentValueStructure Type
Single playlist structure of the Playlists Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Id | characterString | M | Playlist ID. |
| 1 | Name | characterString | M | Playlist name. |
Parameters
FavoritePlaylistsTraitPresentValueStructure Type
Single favorite playlist structure of the FavoritePlaylists Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Id | characterString | M | Favorite item ID. |
| 1 | Name | characterString | M | Favorite item name. |
FavoritePlaylists Trait
This Trait is used to return the playlists favorited by the user in the current music service account; it supports reading and reporting.
Parameters
PlayPlaylist Command Structure Type
Parameter structure of the PlayPlaylist Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PlaylistId | characterString | M | Playlist ID. |
PlayFavorite Command Structure Type
Parameter structure of the PlayFavorite Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | FavoriteId | characterString | M | Favorite item ID. |
Trait Definitions
CurrentPlaybackState Trait
Describes the current playback state.
| Trait ID | Code |
|---|
| 0x80BA | CurrentPlaybackState |
Parameters
TargetPlaybackState Trait
This Trait is used for access to and reporting of "target playback state" data.
| Trait ID | Code |
|---|
| 0x80FD | TargetPlaybackState |
Parameters
Describes the selected media output source.
| Trait ID | Code |
|---|
| 0x816A | SelectedMediaOutputSource |
Parameters
PlaybackSampledPosition Trait
Sets and queries the current playback position. Unit: ms.
| Trait ID | Code |
|---|
| 0x8169 | PlaybackSampledPosition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint64 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint64 | | 0 | RW | O |
LoginState Trait
Describes the login state of the media service.
| Trait ID | Code |
|---|
| 0x80F7 | LoginState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
SelectedSource Trait
Indicates or sets the currently selected media output source (such as built-in speaker, Bluetooth, AUX, HDMI, etc.). Values: 0 = Internal, 1 = Bluetooth, 2 = Aux, 3 = SPDIF, 4 = Coaxial, 5-7 = Audio 1-3, 8-10 = AV1-3, 11-13 = HDMI1-3, 14 = Other.
| Trait ID | Code |
|---|
| 0x80BF | SelectedSource |
Parameters
Describes media information (title, artist, etc.).
| Trait ID | Code |
|---|
| 0x80BE | MediaInformation |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
PlaybackMode Trait
Describes the current playback mode.
| Trait ID | Code |
|---|
| 0x80BD | PlaybackMode |
Parameters
SampledPosition Trait
Indicates or sets the current playback position of the media. The value is a millisecond (ms) time offset, ranging from 0 to the total playback duration. On write, the device seeks to that position.
| Trait ID | Code |
|---|
| 0x80BC | SampledPosition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 7200000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
PlaybackDuration Trait
Indicates the playback duration, in ms.
| Trait ID | Code |
|---|
| 0x80BB | PlaybackDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 7200000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
Command Definitions
Stop Command
This command should request the device to stop the current operation.
This Command has no parameters.
Pause Command
This Command is used to perform the "pause" operation.
This Command has no parameters.
Play Command
This Command is used to perform the "play" operation.
This Command has no parameters.
PlaySpecificList Command
This Command is used to perform the "playlist" operation.
This Command has no parameters.
Rewind Command
This Command is used to perform the "rewind" operation.
This Command has no parameters.
FastForward Command
This Command is used to perform the "fast forward" operation.
This Command has no parameters.
MediaPlaybackCommand represents a media playback command, applicable to playback operations of multiple types of media (music, video, audiobooks, radio, etc.).
Parameters
MediaPlaybackCommand Command Structure
SearchAndPlay Command
Searches music content by keywords, artist, song name and other criteria, and plays the search results. Supports controlling the number of queue items and playback order (sequential/shuffle). This command is suitable for scenarios where the user actively requests a song.
Parameters
SearchAndPlay Command Structure
Plays the audio resource specified by MediaURL directly. This Command is used to play a direct link already known to the client and does not perform song search; to search by song name, artist or keyword, use SearchAndPlay. After the Command is executed, the device shall take the URL as the current playback item and start loading and playing it; if the resource pointed to by the URL is inaccessible, or its format or protocol is not supported by the device, the device shall not report it as playing and shall report a failure according to the Command execution mechanism. Supported URL protocols, audio formats and access conditions are determined by device capabilities, and the device implementation shall clearly define its supported scope. Resources requiring authentication can be played only when the device has the corresponding access credentials or authorization mechanism.
Title is optional display information and is not used as a resource locator or search condition. Command acceptance or the start of loading does not mean that the audio has been played successfully; the playback process and current state shall be reflected through the playback-status-related Trait of this Function.
Parameters
PlayMediaURL Command Structure
PlayPlaylist Command
Loads and plays the specified playlist by playlist ID. The load action controls how the new content affects the current queue, and supports playback modes such as auto-play, shuffle, loop, and fade in/out.
Parameters
PlayPlaylist Command Structure
PlayFavorite Command
Loads and plays the specified favorite content by favorite item ID. Supports controlling the load action, whether to auto-play, and playback modes such as shuffle, loop, and fade in/out.
Parameters
PlayFavorite Command Structure
Off Command
This Command is used to perform the "close" operation.
This Command has no parameters.
On Command
This Command is used to perform the "open" operation.
This Command has no parameters.
Next Command
This Command is used to perform the "next" operation.
This Command has no parameters.
Previous Command
This Command is used to perform the "previous" operation.
This Command has no parameters.
StartOver Command
This Command is used to perform the "replay" operation.
This Command has no parameters.
Speaker
Introduction
Describes the speaker output capability of the device, including audio output functions such as text-to-speech announcement, volume control and mute.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0092 | Speaker | Speaker |
Trait
Command
| Command ID | Code | Conformance |
|---|
| 0x9DB5 | PlayTTS | O |
Data Types
PlayTTS Command Structure Type
Parameter structure of the PlayTTS Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Text | string | M | Text content to be converted to speech and played, up to 200 bytes. |
Trait Definitions
Volume Trait
Indicates or sets the speaker volume of the camera device (e.g., two-way audio). The value is usually a percentage (0 to 100) or a device-defined numeric range.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
Mute Trait
Indicates the mute state of the speaker.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
StepValue Trait
Indicates or sets the step increment (e.g., volume adjustment). In this speaker application, the unit is percentage (%); the specific value range varies by device.
| Trait ID | Code |
|---|
| 0x80C2 | StepValue |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 10.0 | R | O |
| 0x0007 | Default Value | float | | 1 | RW | O |
Command Definitions
| Command ID | Name | Conformance |
|---|
| 0x9DB5 | PlayTTS | O |
PlayTTS Command
Controls the device to convert the specified text into speech and play it through the speaker. Text is a required string with content up to 200 bytes.
Parameters
PlayTTS Command Structure
PowerSource
Introduction
Describes the power supply source and battery status of the device, including battery level, charging status, battery quantity, replaceability, and user-facing battery replacement specification descriptions, and other information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0093 | PowerSource | Power source |
Trait
Command
This Function does not contain Commands.
Data Types
PowerModeEnum8 Type
This enumeration defines the valid values of the Present Value of the PowerMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Mains | Mains |
| 0x02 | Battery | Battery |
| 0x03 | DCSource | DC power |
| 0x04 | ACSource | AC power |
PowerDetectionResultEnum8 Type
This enumeration defines the valid values of the Present Value of the PowerDetectionResult Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Pass | Pass |
BatReplaceabilityEnum8 Type
This enumeration defines the valid values of the Present Value of the BatReplaceability Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unspecified |
| 0x01 | NotReplaceable | Not replaceable |
| 0x02 | UserReplaceable | User replaceable |
| 0x03 | FactoryReplaceable | Factory replaceable |
StateOfLowBatEnum8 Type
This enumeration defines the valid values of the Present Value of the StateOfLowBat Trait.
| Value | Name | Description |
|---|
| 0x00 | False | Sufficient charge |
| 0x01 | True | Low battery |
| 0x02 | Critical | Battery exhausted |
BatChargeStateEnum8 Type
This enumeration defines the valid values of the Present Value of the BatChargeState Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | TheBatteryIsCharging | Charging |
| 0x02 | TheBatteryIsAtFullCharge | Full charge |
| 0x03 | TheBatteryIsNotCharging | Not charging |
| 0x04 | TheBatteryIsNotChargeable | Not chargeable |
Trait Definitions
CurrentVoltage Trait
Indicates the currently measured power supply voltage value. Unit: volt (V).
| Trait ID | Code |
|---|
| 0x80B0 | CurrentVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
PowerMode Trait
Indicates the power supply mode of the device. 0: Unknown, 1: Mains, 2: Battery, 3: DC power.
| Trait ID | Code |
|---|
| 0x8141 | PowerMode |
Parameters
PowerDetectionMode Trait
Power detection mode. Used to indicate whether the device enters the power detection mode. Wired-powered doorbell devices (such as G400) may not work properly (e.g., automatic reboot) if the connected power supply is insufficient, so advance detection is required. Write 1 to enter detection mode, write 0 to exit detection mode.
| Trait ID | Code |
|---|
| 0x5175 | PowerDetectionMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
PowerDetectionResult Trait
Power detection result. Indicates whether the device returns that the power detection passed. When the detection passes, the device returns 1; when it fails, the device reboots and cannot return a result, in which case the APP determines that the detection failed by timeout.
| Trait ID | Code |
|---|
| 0x5176 | PowerDetectionResult |
Parameters
Rechargeable Trait
This feature should indicate whether the battery is rechargeable.
| Trait ID | Code |
|---|
| 0x4E3C | Rechargeable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
BatQuantity Trait
This feature should indicate the number of independent battery cells or battery packs in the battery source that can be maintained by the user or the factory.
| Trait ID | Code |
|---|
| 0x4E3B | BatQuantity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
BatReplacementDescription Trait
This feature must provide a user-facing battery description, used to explain the battery specifications to use when replacing the battery.
This Trait is optional in the PowerSource Function; when implementing this Trait, the Present Value parameter must be provided, supporting reading and reporting but not writing. The Present Value is a string of up to 32 characters, with a default value of null, indicating that the battery description has not been provided; Unspecified is a valid string value, different from null.
| Trait ID | Code |
|---|
| 0x4E3A | BatReplacementDescription |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | string32 | Up to 32; null allowed | null | RV | M |
| 0x0006 | Supported Value | list[string32] | Element is a supported battery description string, each string up to 32 characters | | R | O |
Supported String Values
This Trait supports at least the following string values. The spelling and case of the strings must be consistent with the table below; additional battery description strings may be extended, and the values are not limited to a closed enumeration.
| Value | Description |
|---|
| Unspecified | Unspecified battery specification |
| AA | AA battery |
| AAA | AAA battery |
| CR2450 | CR2450 battery |
| CR1632 | CR1632 battery |
| CR2032 | CR2032 battery |
| CR123A | CR123A battery |
| CR17450 | CR17450 battery |
The Supported Value parameter provides the list of battery description strings supported by the device; when implementing this parameter, the list includes the above string values.
BatReplaceability Trait
This feature should indicate whether the battery is replaceable and the applicable replacement method: unspecified or unknown, not replaceable, user replaceable, or replaceable by factory-authorized personnel.
| Trait ID | Code |
|---|
| 0x4E39 | BatReplaceability |
Parameters
BatReplacementNeeded Trait
This feature should indicate whether the battery needs replacement.
| Trait ID | Code |
|---|
| 0x4E38 | BatReplacementNeeded |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
WiredPresent Trait
Indicates whether a wired power source (power adapter) is detected.
| Trait ID | Code |
|---|
| 0x815B | WiredPresent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
BatPercentRemaining Trait
Indicates the remaining battery charge percentage. When the current battery level is being obtained and is temporarily unavailable, the Present Value uses 255 as the status indicator; this value indicates that the battery level is being obtained, not an actual battery percentage, and is not constrained by the 0-100 percentage range.
| Trait ID | Code |
|---|
| 0x80CD | BatPercentRemaining |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
StateOfLowBat Trait
Indicates whether the battery is in a low battery state. 0: Normal, 1: Low battery, 2: Critically low.
| Trait ID | Code |
|---|
| 0x80C9 | StateOfLowBat |
Parameters
BatChargeState Trait
Indicates the battery charging state. 0: Unknown, 1: Charging, 2: Full charge, 3: Not charging, 4: Not chargeable.
| Trait ID | Code |
|---|
| 0x80CE | BatChargeState |
Parameters
Command Definitions
This Function does not contain Commands.
DoorLock
Introduction
Provides core smart door lock capabilities, including lock state, user/credential management, lock/unlock operations and alarm events.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0094 | DoorLock | Door lock |
Trait
Command
Data Types
GetUserResponseCredentialStructure Type
This structure defines the Credential field layout in the GetUserResponse.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CredentialType | enum8 | M | Credential type: 0=ProgrammingPIN, 1=PIN, 2=RFID, 3=Fingerprint, 4=FingerVein, 5=Face, 6=AliroCredentialIssuerKey, 7=AliroEvictableEndpointKey, 8=AliroNonEvictableEndpointKey. |
| 1 | CredentialIndex | uint16 | O | Credential index. |
LockStateEnum8 Type
This enumeration defines the valid values of the Present Value of the LockState Trait.
| Value | Name | Description |
|---|
| 0x00 | NotFullyLocked | Bolt abnormal |
| 0x01 | Locked | Locked |
| 0x02 | Unlocked | Unlocked |
FingerprintEnrollProgressTraitPresentValueStructure Type
This structure defines the Present Value field layout of the FingerprintEnrollProgress Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CurrentAttempt | uint8 | M | Current enrollment attempt sequence number, starting from 1. |
| 1 | TotalAttempts | uint8 | M | Number of attempts required for a complete registration session (currently 8). |
| 2 | EnrollmentProgress | uint8 | M | Enrollment progress percentage, ranging from 0 to 100. |
| 3 | EnrollmentStatus | enum8 | M | Enrollment status of this attempt. |
LockErrorLogReportTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LockErrorLogReport Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | LockErrorCode | enum8 | M | External or internal exception; value is defined by the LockErrorCodeEnum Type. |
| 1 | LogIndex | uint16 | M | Log index. |
| 2 | TimestampUtc | uint32 | M | UTC timestamp of the event occurrence (Epoch Time in Seconds). |
LockLogReportTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LockLogReport Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | LockOperationType | enum8 | M | Type of door lock operation executed. |
| 1 | OperationSource | enum8 | M | Source of the door lock operation. |
| 2 | UserSource | enum8 | O | Source of UserId and CredentialId. Defaults to Lock Local when omitted. |
| 3 | UserId | uint32 | O | Unique user identifier. |
| 4 | CredentialId | uint32 | O | Unique credential identifier. |
| 5 | MatterVendorId | uint16 | O | Matter Vendor ID when OperationSource is Remote (Matter Ecosystem). |
| 6 | LockPosition | enum8 | O | Door lock operation location. |
| 7 | LogIndex | uint16 | M | Log index. |
| 8 | TimestampUtc | uint32 | M | UTC timestamp of the event occurrence (Epoch Time in Seconds). |
DoorLogReportTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DoorLogReport Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DoorState | enum8 | M | Door state event type. |
| 1 | LogIndex | uint16 | M | Log index. |
| 2 | TimestampUtc | uint32 | M | UTC timestamp of the event occurrence (Epoch Time in Seconds). |
LockDataTypeEnum8 Type
This enumeration identifies the data category of the change in the AqaraUserChange event.
| Value | Name | Description |
|---|
| 0x00 | User | User record |
| 0x01 | Credential | Generic credential record |
| 0x02 | Schedule | User validity schedule |
| 0x03 | NFC | NFC card credential |
| 0x04 | Fingerprint | Fingerprint credential |
| 0x05 | Face | Face credential |
| 0x06 | FingerVein | Finger vein credential |
| 0x07 | Password | Numeric or alphanumeric password credential |
| 0x08 | UWB | Ultra-wideband credential |
| 0x09 | Palm | Palm print credential |
DataOperationTypeEnum8 Type
This enumeration identifies the operation type performed by the AqaraUserChange event on a user or credential database entry.
| Value | Name | Description |
|---|
| 0x00 | Add | Add a database entry |
| 0x01 | Delete | Delete an existing database entry |
| 0x02 | Modify | Modify an existing database entry |
AqaraUserErrorTraitPresentValueStructure Type
This structure defines the Present Value field layout of the AqaraUserError Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserId | uint16 | M | User ID. |
| 2 | CredentialAttribute | uint8 | M | Credential properties. |
| 3 | CredentialType | uint8 | M | Credential type. |
AqaraUserChangeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the AqaraUserChange Trait. This Trait reports the relevant status only after a successful change to the user or credential database; when a credential changes, Credential may carry the complete AqaraCredentialItemStruct (including the credential type and its content). The CheckNumber in Extension events is for gateway-internal use only, does not belong to the Trait, and MUST NOT be reported to the App or the cloud.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | LockDataType | LockDataTypeEnum8 | M | The data category of the change. |
| 1 | DataOperationType | DataOperationTypeEnum8 | M | The operation type performed on the data. |
| 2 | UserId | uint16 | M | User ID involved in the change. |
| 3 | UserType | AqaraUserTypeEnum8 | M | The type and access level of the user after the change. |
| 4 | UserName | characterString | O | Username after the change, UTF-8 encoded, up to 20 bytes; may be null when not set. |
| 5 | Credential | AqaraCredentialItemStruct | O | Complete credential information involved in the change, including credential attributes, type, ID, index, name, validity period, and credential content corresponding to the type; may be omitted or null when there is no related credential, when a credential is deleted, or when the device does not provide sensitive credential content. |
WiFiConfigStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the WiFiConfigStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | ConfigFailed | Configuration failed |
| 0x01 | Configuring | Configuring |
| 0x02 | ConfigSucceeded | Configuration succeeded |
WifiModeEnum8 Type
This enumeration defines the valid values of the Present Value of the WifiMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | KeepAlive | Always online |
| 0x02 | Silence | Silent sleep |
| 0x03 | TempAlive | Temporary online |
WiFiStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the WiFiStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Undefined | Undefined |
| 0x01 | APConnected | AP connected |
| 0x02 | APConnectFailed | AP connection failed |
| 0x03 | CloudConnected | Connected to cloud |
| 0x04 | CloudConnectFailed | Cloud connection failed |
| 0x05 | APConnecting | AP connecting |
| 0x06 | PowerOff | Power-off state |
VoiceOTAStatusTraitPresentValueStructure Type
This structure defines the Present Value field layout of the VoiceOTAStatus Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Status | enum8 | M | Voice firmware OTA upgrade status. |
| 1 | Progress | uint8 | O | Upgrade progress percentage, ranging from 1 to 100. |
OTASilentUpgradeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the OTASilentUpgrade Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Enabled | boolean | M | Whether silent OTA upgrade is enabled. |
| 1 | ValidStartUtc | uint32 | O | UTC start time when the silent upgrade takes effect; both 0 with ValidEndUtc means always effective. |
| 2 | ValidEndUtc | uint32 | O | UTC end time of the silent upgrade. |
VoicePackageInfoTraitPresentValueStructure Type
This structure defines the Present Value field layout of the VoicePackageInfo Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PackageId | uint32 | M | Voice package ID. |
| 1 | PackageName | characterString | M | Voice package name. |
| 2 | Language | characterString | M | Voice package language identifier. |
| 3 | Version | characterString | M | Voice package version. |
CloseDoorAutoRelockTimeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the CloseDoorAutoRelockTime Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | AutoLockTime | uint32 | M | Auto relock delay in seconds; a value of 0 disables auto relock. |
| 1 | ValidStartUtc | uint32 | M | UTC start time when auto relock takes effect; both 0 with ValidEndUtc means always effective. |
| 2 | ValidEndUtc | uint32 | M | UTC end time of auto relock. |
LockQuietModeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LockQuietMode Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | QuietModeEnabled | boolean | M | Whether quiet mode is active. |
| 1 | QuietModeSpeed | enum8 | M | Motor speed within the quiet window; value is defined by the MotorSpeedEnum Type. |
| 2 | ValidStartUtc | uint32 | M | UTC start time when quiet mode takes effect; both 0 with ValidEndUtc means the schedule is not active. |
| 3 | ValidEndUtc | uint32 | M | UTC end time of quiet mode. |
NormalModeSpeedEnum8 Type
This enumeration defines the valid values of the Present Value of the NormalModeSpeed Trait.
| Value | Name | Description |
|---|
| 0x00 | Performance | Extremely fast |
| 0x01 | Standard | Standard |
| 0x02 | Quiet | Quiet |
| 0x03 | Silent | Silent |
DeviceOrientationTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DeviceOrientation Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DoorOpenDirection | enum8 | M | Door opening direction; value is defined by the DoorOpenDirectionEnum Type. |
| 1 | InstallationOrientation | enum8 | M | Lock body installation axis; value is defined by the InstallationOrientationEnum Type. |
MotorStrengthTraitPresentValueStructure Type
This structure defines the Present Value field layout of the MotorStrength Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | MotorStrength | uint8 | M | Motor strength. |
PullSpringTraitPresentValueStructure Type
This structure defines the Present Value field layout of the PullSpring Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Enabled | boolean | M | Whether the pull spring is activated. |
| 1 | LatchRetractTime | uint16 | M | Bolt retraction time (milliseconds). |
DoorHandleDirectionEnum8 Type
This enumeration defines the valid values of the Present Value of the DoorHandleDirection Trait.
| Value | Name | Description |
|---|
| 0x00 | RightOpen | Right open |
| 0x01 | LeftOpen | Left open |
LockWorkModeEnum8 Type
This enumeration defines the valid values of the Present Value of the LockWorkMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | InstallationInspection | Installation check |
| 0x02 | Demo | Demo |
DoorLockAlarmStatusTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DoorLockAlarmStatus Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | LockState | enum8 | M | Lock state snapshot. |
| 1 | DoorState | enum8 | M | Door state snapshot. |
| 2 | TamperActive | boolean | M | Whether tamper alarm is active. |
| 3 | AwayModeArmed | boolean | M | Whether away mode is armed. |
| 4 | LowBattery | boolean | M | Whether in low battery state. |
DoorAjarConfigTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DoorAjarConfig Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Enabled | boolean | M | Whether the door ajar alarm is enabled. |
| 1 | Volume | enum8 | M | Alarm volume. |
| 2 | WaitTime | uint32 | M | Timeout in seconds before the alarm is triggered while the door remains ajar. |
| 3 | AlarmDuration | uint32 | O | Alarm duration in seconds per trigger. |
DoorNotLockedConfigTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DoorNotLockedConfig Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Enabled | boolean | M | Whether the door not locked alarm is enabled. |
| 1 | Volume | enum8 | M | Alarm volume. |
| 2 | WaitTime | uint32 | M | Timeout in seconds before the alarm is triggered while the door remains closed but unlocked. |
| 3 | AlarmDuration | uint32 | O | Alarm duration in seconds per trigger. |
DoorNotClosedConfigTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DoorNotClosedConfig Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Enabled | boolean | M | Whether the door not closed alarm is enabled. |
| 1 | Volume | enum8 | M | Alarm volume. |
| 2 | WaitTime | uint32 | M | Timeout in seconds before the alarm is triggered while the door remains open. |
| 3 | AlarmDuration | uint32 | O | Alarm duration in seconds per trigger. |
AlarmVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the AlarmVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
LockJammedVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the LockJammedVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
AwayModePromptVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the AwayModePromptVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
DemoVoiceVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the DemoVoiceVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
AbnormalVibrationAlarmVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the AbnormalVibrationAlarmVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
VoiceVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the VoiceVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
DoorbellVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the DoorbellVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
UnlockVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the UnlockVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | High | High |
| 0x01 | Medium | Medium |
| 0x02 | Low | Low |
| 0x03 | Mute | Mute |
ConfigOperationEnum8 Type
This enumeration defines the valid values of the Present Value of the ConfigOperation Trait.
| Value | Name | Description |
|---|
| 0x00 | EnableElectronicLockoutMode | Enable electronic deadbolt |
| 0x01 | DisableElectronicLockoutMode | Disable electronic deadbolt |
StateOfLowBatEnum8 Type
This enumeration defines the valid values of the Present Value of the StateOfLowBat Trait.
| Value | Name | Description |
|---|
| 0x00 | False | Sufficient charge |
| 0x01 | True | Low battery |
| 0x02 | Critical | Battery exhausted |
GetCredentialStatusResponseTraitPresentValueStructure Type
This structure defines the Present Value field layout of the GetCredentialStatusResponse Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CredentialExists | boolean | M | Whether the credential exists. |
| 1 | UserIndex | uint16 | M | User index. |
| 2 | CreatorFabricIndex | uint16 | O | Not reported when empty. |
| 3 | LastModifiedFabricIndex | uint16 | O | Not reported when empty. |
| 4 | NextUserIndex | uint16 | O | Not reported when empty. |
SetCredentialResponseTraitPresentValueStructure Type
This structure defines the Present Value field layout of the SetCredentialResponse Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Status | enum8 | M | Response status. |
| 1 | UserIndex | uint16 | M | User index. |
| 2 | NextCredentialIndex | uint16 | O | Next credential index; not reported when empty. |
AqaraUserTypeEnum8 Type
This enumeration defines the Aqara user types and their corresponding access permission levels.
| Value | Name | Description |
|---|
| 0x00 | Unknown | User type unknown or unspecified. |
| 0x01 | Administrator | Administrator, with higher permissions. |
| 0x02 | RegularUser | Regular user, with standard access permissions. |
| 0x03 | FrequentVisitor | Frequent guest, with restricted access permissions. |
| 0x04 | Owner | Device owner; each lock has at most one Owner, and it cannot be deleted. |
AqaraCredentialAttributeEnum8 Type
This enumeration defines the security attributes of credentials.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal credential, without special attributes. |
| 0x01 | Duress | Duress credential; triggers a silent alarm when used. |
| 0x02 | OneToMany | One-to-many credential, can be associated with multiple users. |
AqaraCredentialTypeEnum8 Type
This enumeration defines the Aqara credential types.
| Value | Name | Description |
|---|
| 0x01 | Fingerprint | Fingerprint credential. |
| 0x02 | Password | Numeric or alphanumeric password credential. |
| 0x03 | NFC | NFC card credential. |
| 0x04 | ElectronicKey | Electronic key credential. |
| 0x06 | Face | Face credential. |
| 0x10 | OneTimePassword | One-time password credential. |
| 0x11 | Bluetooth | Bluetooth credential. |
AqaraCredentialRepeatTypeEnum8 Type
This enumeration defines the repeat period of credential validity.
| Value | Name | Description |
|---|
| 0x00 | Never | Single valid time range, no repetition. |
| 0x01 | Daily | Repeats daily. |
| 0x02 | Weekly | Repeats weekly. |
| 0x03 | BiWeekly | Repeats every two weeks. |
| 0x04 | Monthly | Repeats monthly. |
AqaraNFCCardTypeEnum8 Type
This enumeration defines the physical card standard used by NFC credentials.
| Value | Name | Description |
|---|
| 0x01 | TypeA | ISO 14443-A card. |
| 0x02 | TypeB | ISO 14443-B card. |
| 0x03 | TypeF | JIS X 6319-4 (FeliCa) card. |
AqaraCredentialValidityStruct Type
This structure defines the valid time and repeat schedule of a credential.
| Member ID | Field Name | Type | Mandatory | Description |
|---|
| 0 | RepeatType | AqaraCredentialRepeatTypeEnum8 | M | Validity repeat period. |
| 1 | StartTime | uint32 | M | Validity start time, in Epoch seconds; default value is 0. |
| 2 | EndTime | uint32 | M | Validity end time, in Epoch seconds; default value is 0. |
| 3 | EndRepeatTime | uint32 | M | Repeat schedule end time, in Epoch seconds; default value is 0xFFFFFFFF, meaning no end time. It should be 0xFFFFFFFF when RepeatType is Never. |
| 4 | RepeatDays | uint32 | M | Repeat date bitmap; default value is 0x00000000. For Weekly, bits 0-6 represent Sunday to Saturday; for Monthly, bits 0-30 represent days 1-31 of each month; for other repeat types it should be 0. |
AqaraNFCCardInfoStruct Type
This structure defines the additional card data of an NFC credential.
| Member ID | Field Name | Type | Mandatory | Description |
|---|
| 0 | Cid | octstr | O | Card CID, up to 32 bytes. |
| 1 | Key | octstr | O | Card key, up to 64 bytes. |
| 2 | CardType | AqaraNFCCardTypeEnum8 | O | NFC card standard. |
AqaraCredentialContentStruct Type
This structure carries the credential-type-specific content. The valid field is selected by CredentialType in the same credential item: for Password (0x02), PasswordData is non-empty and NFCCardInfo is empty; for NFC (0x03), NFCCardInfo is non-empty and PasswordData is empty; for other credential types, both fields are empty.
| Member ID | Field Name | Type | Mandatory | Description |
|---|
| 0 | PasswordData | octstr | O | Password content, up to 255 bytes; only used by Password credentials. |
| 1 | NFCCardInfo | AqaraNFCCardInfoStruct | O | NFC card additional data; only used by NFC credentials. |
AqaraCredentialItemStruct Type
This structure defines a single credential in the user record of GetAqaraUserResponse.
AqaraUserRecordStruct Type
This structure defines a single user record in the Users list of GetAqaraUserResponse, including user identifier, user type, credentials and optional username.
| Member ID | Field Name | Type | Mandatory | Description |
|---|
| 0 | UserId | uint16 | M | User ID. |
| 1 | UserType | AqaraUserTypeEnum8 | M | User type and access permission level. |
| 2 | Credentials | list[AqaraCredentialItemStruct] | O | User credential list; can be null or omitted (e.g., the user has no credentials yet, or the response does not include the credential list); an empty list is equivalent to null. |
| 3 | UserName | characterString | O | User display name, UTF-8 encoded, up to 20 bytes; null when not set. |
GetAqaraUserResponseTraitPresentValueStructure Type
This structure defines the Present Value of the GetAqaraUserResponse Trait. Users is a list of user record structures; NextUserId is a nullable pagination cursor.
| Member ID | Field Name | Type | Mandatory | Description |
|---|
| 0 | Users | list[AqaraUserRecordStruct] | O | User record list, returning at most the Number of records requested, sorted by UserId in ascending order; an empty list when the database is empty. |
| 1 | NextUserId | uint16 | M | Starting user ID for the next pagination query; null indicates the traversal is complete. |
GetUserResponseTraitPresentValueStructure Type
This structure defines the Present Value field layout of the GetUserResponse Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | UserIndex | uint16 | M | User index, ranging from 1 to NumberOfTotalUsersSupported. |
| 1 | UserName | characterString | O | Username; the entire key is not sent when empty. |
| 2 | UserUniqueID | uint32 | O | User unique ID; the entire key is not sent when empty. |
| 3 | UserStatus | enum8 | M | User status: 0=Available, 1=OccupiedEnabled, 2=OccupiedDisabled. |
| 4 | UserType | enum8 | M | User type: 0=UnrestrictedUser, 1=YearDayScheduleUser, 2=WeekDayScheduleUser, 3=ProgrammingUser, 4=NonAccessUser, 5=ForcedUser, 6=DisposableUser, 7=ExpiringUser, 8=ScheduleRestrictedUser, 9=RemoteOnlyUser. |
| 5 | CredentialRule | enum8 | M | Credential rule: 0=Single, 1=Dual, 2=Tri. |
| 6 | Credential | GetUserResponseCredentialStructure | M | Credential information. |
| 7 | CreatorFabricIndex | uint16 | O | Fabric index of the creator; not reported when null. |
| 8 | LastModifiedFabricIndex | uint16 | O | Fabric index of the last modifier; not reported when null. |
| 9 | NextUserIndex | uint16 | O | Next user index; not reported when null. |
GetWeekDayScheduleResponseTraitPresentValueStructure Type
This structure defines the Present Value field layout of the GetWeekDayScheduleResponse Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | WeekDayIndex | uint8 | M | Week Day schedule index. |
| 1 | UserIndex | uint16 | M | User index. |
| 2 | Status | enum8 | M | Response status. |
| 3 | DaysMask | uint16 | M | Day-of-week mask, bits 0..6 correspond to Sunday..Saturday respectively. |
| 4 | StartHour | uint8 | M | Start hour, max 23. |
| 5 | StartMinute | uint8 | M | Start minute, max 59. |
| 6 | EndHour | uint8 | M | End hour, max 23. |
| 7 | EndMinute | uint8 | M | End minute, max 59. |
GetYearDayScheduleResponseTraitPresentValueStructure Type
This structure defines the Present Value field layout of the GetYearDayScheduleResponse Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | YearDayIndex | uint8 | M | Year Day schedule index. |
| 1 | UserIndex | uint16 | M | User index. |
| 2 | Status | enum8 | M | Response status. |
| 3 | LocalStartTime | uint32 | M | Local start time, in Epoch Time in Seconds. |
| 4 | LocalEndTime | uint32 | M | Local end time, in Epoch Time in Seconds; should be greater than LocalStartTime. |
NetworkInterfacesTraitPresentValueStructure Type
This structure defines the Present Value field layout of the NetworkInterfaces Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Name | characterString | M | Network interface name, max length 32 bytes. |
| 1 | IsOperational | boolean | M | Whether the interface is in the running state. |
| 2 | OffPremiseServicesReachableIPv4 | boolean | O | Whether external network services can be accessed via IPv4; empty means unknown. |
| 3 | OffPremiseServicesReachableIPv6 | boolean | O | Whether external network services can be accessed via IPv6; empty means unknown. |
| 4 | HardwareAddress | octetString | M | Hardware MAC address. |
| 5 | IPv4Addresses | list[octetString] | M | IPv4 address list. |
| 6 | IPv6Addresses | list[octetString] | M | IPv6 address list. |
| 7 | Type | enum8 | M | Interface type (InterfaceTypeEnum). |
LockOperationErrorTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LockOperationError Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | LockOperationType | enum8 | M | Type of door lock operation executed. |
| 1 | OperationSource | enum8 | M | Source of the door lock operation. |
| 2 | OperationError | enum8 | M | Reason for the operation failure. |
| 3 | UserIndex | uint16 | M | User index that executed the door lock operation. |
| 4 | FabricID | uint64 | M | Fabric ID that executed the door lock operation. |
| 5 | SourceNode | uint64 | M | Node ID that executed the door lock operation. |
| 6 | Credentials | list[Struct] | O | Credential list used when executing the door lock operation; can be empty when no credential was used. |
LockUserChangeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LockUserChange Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | LockDataType | enum8 | M | Data type that was changed. |
| 1 | DataOperationType | enum8 | M | Data operation type. |
| 2 | OperationSource | enum8 | M | Source that executed the operation. |
| 3 | UserIndex | uint16 | M | User index that executed the door lock operation. |
| 4 | FabricID | uint64 | M | Fabric ID that executed the door lock operation. |
| 5 | SourceNode | uint64 | M | Node ID that executed the door lock operation. |
| 6 | DataIndex | uint16 | O | Index of the changed item in the corresponding LockDataType list. |
DoorLockAlarmTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DoorLockAlarm Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | AlarmCode | enum8 | M | Door lock alarm type. |
LockOperationTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LockOperation Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | LockOperationType | enum8 | M | Type of door lock operation executed. |
| 1 | OperationSource | enum8 | M | Source of the door lock operation. |
| 2 | UserSource | enum8 | O | Source of UserId and CredentialId. Defaults to Lock Local when omitted. |
| 3 | UserId | uint32 | O | Unique user identifier. |
| 4 | CredentialId | uint32 | O | Unique credential identifier. |
| 5 | MatterVendorId | uint16 | O | Matter Vendor ID when OperationSource is Remote (Matter Ecosystem). |
| 6 | LockPosition | enum8 | O | Door lock operation location. |
DoorStateEnum8 Type
This enumeration defines the valid values of the Present Value of the DoorState Trait.
| Value | Name | Description |
|---|
| 0x00 | DoorOpen | Door not closed |
| 0x01 | DoorClosed | Door closed |
| 0x02 | DoorJammed | Door jammed |
| 0x03 | DoorForcedOpen | Door forced open |
| 0x04 | DoorUnspecifiedError | Door abnormal |
| 0x05 | DoorAjar | Door ajar |
OperatingModeEnum8 Type
This enumeration defines the valid values of the Present Value of the OperatingMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Vacation | Vacation |
| 0x02 | Privacy | Privacy |
| 0x03 | NoRemoteLockUnlock | NoRemoteLockUnlock |
| 0x04 | Passage | Passage |
ClearCredential Command Structure Type
Parameter structure of the ClearCredential Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ClearCredential | struct | M | Credential to clear. |
GetCredentialStatus Command Structure Type
Parameter structure of the GetCredentialStatus Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Credential | struct | M | Credential. |
SetCredential Command Structure Type
Parameter structure of the SetCredential Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | OperationType | uint16 | M | Operation type. |
| 1 | Credential | struct | M | Credential. |
| 2 | CredentialData | characterString | M | Credential data. |
| 3 | UserIndex | uint16 | M | User index. |
| 4 | UserStatus | uint32 | M | User status; default value is OccupiedEnabled. |
| 5 | UserType | uint32 | M | User type; default value is UnrestrictedUser. |
GetUser Command Structure Type
Parameter structure of the GetUser Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | UserIndex | uint16 | M | User index to query. |
ClearUser Command Structure Type
Parameter structure of the ClearUser Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | UserIndex | uint16 | M | User index. |
SetUser Command Structure Type
Parameter structure of the SetUser Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | OperationType | uint16 | M | Operation type. |
| 1 | UserIndex | uint16 | M | User index. |
| 2 | UserName | characterString | M | Username. |
| 3 | UserUniqueID | uint32 | M | User unique ID; default value is 0xFFFFFFFF. |
| 4 | UserStatus | uint16 | M | User status; default value is OccupiedEnabled. |
| 5 | UserType | int64 | M | User type; default value is UnrestrictedUser. |
| 6 | CredentialRule | uint16 | M | Credential rule; default value is Single. |
UnboltDoor Command Structure Type
Parameter structure of the UnboltDoor Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Code | characterString | O | Code. |
GetYearDaySchedule Command Structure Type
Parameter structure of the GetYearDaySchedule Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | YearDayIndex | uint8 | M | Year day index; default value is 1. |
| 1 | UserIndex | uint16 | M | User index; default value is 1. |
ClearYearDaySchedule Command Structure Type
Parameter structure of the ClearYearDaySchedule Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | YearDayIndex | uint8 | M | Year day index; default value is 1. |
| 1 | UserIndex | uint16 | M | User index; default value is 1. |
SetYearDaySchedule Command Structure Type
Parameter structure of the SetYearDaySchedule Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | YearDayIndex | uint8 | M | Year day index; default value is 1. |
| 1 | UserIndex | uint16 | M | User index; default value is 1. |
| 2 | LocalStartTime | uint64 | M | Local start time. |
| 3 | LocalEndTime | uint64 | M | Local end time. |
ClearWeekDaySchedule Command Structure Type
Parameter structure of the ClearWeekDaySchedule Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | WeekDayIndex | uint8 | M | Week day index; default value is 1. |
| 1 | UserIndex | uint16 | M | User index; default value is 1. |
GetWeekDaySchedule Command Structure Type
Parameter structure of the GetWeekDaySchedule Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | WeekDayIndex | uint8 | M | Week day index; default value is 1. |
| 1 | UserIndex | uint16 | M | User index; default value is 1. |
SetWeekDaySchedule Command Structure Type
Parameter structure of the SetWeekDaySchedule Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | WeekDayIndex | uint8 | M | Week day index; default value is 1. |
| 1 | UserIndex | uint16 | M | User index; default value is 1. |
| 2 | DaysMask | enum8 | M | Date mask. |
| 3 | StartHour | uint8 | M | Start hour; default value is 0. |
| 4 | StartMinute | uint8 | M | Start minute; default value is 0. |
| 5 | EndHour | uint8 | M | End hour; default value is 0. |
| 6 | EndMinute | uint8 | M | End minute; default value is 0. |
UnlockDoor Command Structure Type
Parameter structure of the UnlockDoor Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Code | characterString | O | Unlock key. |
LockDoor Command Structure Type
Parameter structure of the LockDoor Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Code | characterString | O | |
GetLog Command Structure Type
Parameter structure of the GetLog Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartIndex | uint16 | M | Start index. |
| 1 | EndIndex | uint16 | M | End index. |
ExitAddAqaraCredential Command Structure Type
Parameter structure of the ExitAddAqaraCredential Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserId | uint16 | M | User ID. |
| 2 | CredentialAttribute | enum8 | M | Credential attribute. |
| 3 | CredentialType | enum8 | M | Credential type. |
GetAqaraCredential Command Structure Type
Parameter structure of the GetAqaraCredential Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserId | uint16 | M | User ID. |
| 2 | CredentialId | uint16 | M | Credential ID. |
DeleteAqaraCredential Command Structure Type
Parameter structure of the DeleteAqaraCredential Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | CredentialId | uint16 | M | Credential ID. |
ModifyAqaraCredential Command Structure Type
Parameter structure of the ModifyAqaraCredential Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | CredentialId | uint16 | M | Credential ID. |
| 2 | CredentialAttribute | enum8 | O | Credential attribute. |
| 3 | CredentialType | enum8 | O | Credential type. |
| 4 | CredentialContent | struct | O | Credential content. |
| 5 | Validity | struct | O | Validity. |
| 6 | CredentialName | characterString | O | Credential name. |
AddAqaraCredential Command Structure Type
Parameter structure of the AddAqaraCredential Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserId | uint16 | M | User ID. |
| 2 | CredentialAttribute | enum8 | M | Credential attribute. |
| 3 | CredentialType | enum8 | M | Credential type. |
| 4 | CredentialContent | struct | O | Credential content. |
| 5 | Validity | struct | O | Validity. |
| 6 | CredentialName | characterString | O | Credential name. |
DeleteAqaraUser Command Structure Type
Parameter structure of the DeleteAqaraUser Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserId | uint16 | M | User ID. |
ModifyAqaraUser Command Structure Type
Parameter structure of the ModifyAqaraUser Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserId | uint16 | M | User ID. |
| 2 | UserType | enum8 | O | User type. |
| 3 | UserName | characterString | O | Username. |
AddAqaraUser Command Structure Type
Parameter structure of the AddAqaraUser Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserType | enum8 | M | User type. |
| 2 | UserName | characterString | M | Username. |
GetAqaraUser Command Structure Type
Parameter structure of the GetAqaraUser Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 1 | UserId | uint16 | M | Starting user ID to query; user IDs start from 1. |
| 2 | Number | uint8 | M | Maximum number of user records returned per request, minimum value is 1. |
SetTravelCalibration Command Structure Type
Parameter structure of the SetTravelCalibration Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | TravelCalibrationCmd | enum8 | M | Travel calibration command. |
Trait Definitions
LockState Trait
This Trait is used for access to and reporting of "lock state" data.
| Trait ID | Code |
|---|
| 0x80CA | LockState |
Parameters
FingerprintEnrollProgress Trait
During a registration session, the device sends a FingerprintEnrollProgress event after each fingerprint enrollment attempt. A complete registration session consists of multiple attempts (currently 8); the device should emit this event after each attempt.
| Trait ID | Code |
|---|
| 0x50B4 | FingerprintEnrollProgress |
Parameters
LockErrorLogReport Trait
Emitted whenever the device records an external or internal exception defined by the LockErrorCodeEnum Type.
| Trait ID | Code |
|---|
| 0x50B3 | LockErrorLogReport |
Parameters
LockLogReport Trait
Emitted whenever the device records a lock or unlock operation.
| Trait ID | Code |
|---|
| 0x50B2 | LockLogReport |
Parameters
DoorLogReport Trait
Emitted whenever the device records a door state event.
| Trait ID | Code |
|---|
| 0x50B1 | DoorLogReport |
Parameters
AqaraUserError Trait
This Trait is used to report error information about failed Aqara user or credential management operations.
| Trait ID | Code |
|---|
| 0x50B0 | AqaraUserError |
Parameters
AqaraUserChange Trait
The result status should be broadcast to all subscribers, regardless of where the change originated (remote command, local touch panel, factory reset, etc.).
| Trait ID | Code |
|---|
| 0x50AF | AqaraUserChange |
Parameters
WiFiConfigStatus Trait
Should indicate the current Wi-Fi provisioning/configuration phase of the device, encoded as the WiFiConfigStatusEnum Type.
| Trait ID | Code |
|---|
| 0x50AC | WiFiConfigStatus |
Parameters
WifiMode Trait
Should configure the Wi-Fi runtime power/behavior mode of the device, encoded as the WifiModeEnum Type.
| Trait ID | Code |
|---|
| 0x50AB | WifiMode |
Parameters
WiFiStatus Trait
Should indicate the current Wi-Fi connection status of the device, encoded as the WiFiStatusEnum Type.
| Trait ID | Code |
|---|
| 0x50A9 | WiFiStatus |
Parameters
FirmwareDowngradeEnabled Trait
Should control whether the device firmware version can be downgraded. false (0) should prohibit downgrade; true (1) should allow downgrade.
| Trait ID | Code |
|---|
| 0x50A8 | FirmwareDowngradeEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | W | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
VoiceOTAStatus Trait
Should indicate the current voice firmware OTA upgrade status.
| Trait ID | Code |
|---|
| 0x50A7 | VoiceOTAStatus |
Parameters
OTASilentUpgrade Trait
Should configure the silent OTA firmware upgrade function.
| Trait ID | Code |
|---|
| 0x50A6 | OTASilentUpgrade |
Parameters
OTAProgress Trait
Should indicate the current OTA firmware progress, reporting the upgrade completion percentage in the range 1 to 100.
| Trait ID | Code |
|---|
| 0x50A5 | OTAProgress |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 100 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
UWBApproachDirection Trait
Should configure the UWB approach direction zones. Each bit enables detection of a specific side zone.
| Trait ID | Code |
|---|
| 0x50A4 | UWBApproachDirection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RVW | O |
SupportedNfcCardTypes Trait
Should indicate the set of NFC card types enabled for credential identification on the door lock, encoded as the SupportedNfcCardTypesBitmap Type.
| Trait ID | Code |
|---|
| 0x50A2 | SupportedNfcCardTypes |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RVW | O |
VoicePackageInfo Trait
Should configure the door lock voice package metadata. Each item in the list is encoded as the VoicePackageInfoItemStruct Type.
| Trait ID | Code |
|---|
| 0x50A1 | VoicePackageInfo |
Parameters
DetectionDistance Trait
This Trait indicates the effective detection distance of the door lock radar, in centimeters.
| Trait ID | Code |
|---|
| 0x518A | DetectionDistance |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 600 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 300 | RW | O |
DetectionThreshold Trait
This Trait indicates the radar detection sensitivity threshold used to distinguish valid detection events from noise.
| Trait ID | Code |
|---|
| 0x518B | DetectionThreshold |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 12 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
RemoteUnlockRelockDelay Trait
Should configure the delay in seconds before the door lock automatically relocks after a remote unlock. The unit is seconds.
| Trait ID | Code |
|---|
| 0x509C | RemoteUnlockRelockDelay |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 30 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 30 | RW | O |
CloseDoorAutoRelockEnabled Trait
This Trait is used to enable or disable the automatic relock function of the door lock after the door is closed. When enabled, the relock delay is configured by CloseDoorAutoRelockTime.
| Trait ID | Code |
|---|
| 0x513C | CloseDoorAutoRelockEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AqaraLockStateExtension Trait
This Trait is used to report Aqara door lock abnormal lock states that cannot be expressed by the standard LockState. This value can be NULL when the lock body cannot determine the lock mechanism state for the time being.
| Trait ID | Code |
|---|
| 0x514B | AqaraLockStateExtension |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 254 | RV | O |
AqaraDoorStateExtension Trait
This Trait is used to report Aqara door lock abnormal door states that cannot be expressed by the standard DoorState. This value can be NULL when the lock body cannot determine the door state for the time being.
| Trait ID | Code |
|---|
| 0x514C | AqaraDoorStateExtension |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 254 | RV | O |
DoorLockStateChangeTimestamp Trait
This Trait indicates the timestamp of the most recent change of the reported door lock state, using a Unix timestamp (milliseconds, ms). This value can be NULL when the device has not yet reported a state change.
| Trait ID | Code |
|---|
| 0x514D | DoorLockStateChangeTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
VoiceLanguage Trait
This Trait indicates the current voice broadcast language.
| Trait ID | Code |
|---|
| 0x4EF3 | VoiceLanguage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | | RVW | O |
| 0x0006 | Supported Value | list[uint8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 1 | RW | O |
OTAState Trait
This Trait indicates the current OTA firmware upgrade state of the device.
| Trait ID | Code |
|---|
| 0x4F09 | OTAState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RV | O |
This Trait is used to enable or disable the single-press button lock/unlock function. When the value is true, the user can lock or unlock by a single press of the button; when the value is false, this function is disabled.
| Trait ID | Code |
|---|
| 0x5169 | ButtonLockUnlockEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AlwaysOpenMode Trait
This Trait is used to enable or disable the always-open mode. When the value is true, always-open mode is enabled; when the value is false, always-open mode is disabled.
| Trait ID | Code |
|---|
| 0x509D | AlwaysOpenMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AuxRotationEnabled Trait
This Trait is used to control whether the auxiliary rotation function of the door lock is enabled.
| Trait ID | Code |
|---|
| 0x514E | AuxRotationEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SpeedFollowEnabled Trait
This Trait is used to control whether the speed follow function of the door lock is enabled.
| Trait ID | Code |
|---|
| 0x514F | SpeedFollowEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DoorbellEnabled Trait
This Trait is used to enable or disable the doorbell function.
| Trait ID | Code |
|---|
| 0x5149 | DoorbellEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DoorbellSensitivity Trait
This Trait indicates the doorbell sensing sensitivity level.
| Trait ID | Code |
|---|
| 0x514A | DoorbellSensitivity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RVW | O |
| 0x0007 | Default Value | uint8 | | 1 | RW | O |
UWBMinUnlockDistance Trait
This Trait indicates the UWB minimum unlock distance of the door lock, in mm.
UWBEnabled Trait
This Trait is used to enable or disable the UWB function.
| Trait ID | Code |
|---|
| 0x513F | UWBEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
UWBDoubleDoorMode Trait
This Trait is used to enable or disable the UWB double-door mode.
| Trait ID | Code |
|---|
| 0x5140 | UWBDoubleDoorMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
UWBFastStartMode Trait
This Trait is used to enable or disable the UWB quick start mode.
| Trait ID | Code |
|---|
| 0x5142 | UWBFastStartMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
UWBMultiEntrancesMode Trait
This Trait is used to enable or disable the UWB multi-entrance mode.
| Trait ID | Code |
|---|
| 0x5145 | UWBMultiEntrancesMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
| Trait ID | Code |
|---|
| 0x5141 | UWBMinUnlockDistance |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1000 | RVW | O |
UWBRangingTimeout Trait
This Trait indicates the timeout of the door lock UWB ranging session, in milliseconds.
| Trait ID | Code |
|---|
| 0x5143 | UWBRangingTimeout |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 10 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 10 | RW | O |
UWBSignalLostTimeout Trait
This Trait indicates the timeout that the door lock waits for subsequent actions after losing the UWB signal, in milliseconds.
| Trait ID | Code |
|---|
| 0x5144 | UWBSignalLostTimeout |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 30 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 30 | RW | O |
CloseDoorAutoRelockTime Trait
This Trait indicates the current close-door auto relock parameters of the door lock. AutoLockTime represents the delay in seconds before relocking.
| Trait ID | Code |
|---|
| 0x513D | CloseDoorAutoRelockTime |
Parameters
MagneticEncoderCalibrationStatus Trait
This Trait indicates the magnetic encoder calibration status of the door lock.
| Trait ID | Code |
|---|
| 0x5185 | MagneticEncoderCalibrationStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
This Trait indicates the bolt travel configuration status of the door lock.
| Trait ID | Code |
|---|
| 0x518D | BoltTravelConfigured |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
RemoteUnlockAutoRelockEnabled Trait
This Trait is used to enable or disable the automatic relock function after a remote unlock. When enabled, the relock delay is configured by RemoteUnlockAutoRelockTime.
| Trait ID | Code |
|---|
| 0x513E | RemoteUnlockAutoRelockEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LocalCredentialLockoutDuration Trait
Should indicate the remaining lockout seconds applied to local credential entry (e.g., device keypad PIN, fingerprint sensor, NFC reader, face/palm vein) after too many failed verification attempts. When this attribute is non-empty and non-zero, the device should reject local credential attempts and decrement this value over time.
| Trait ID | Code |
|---|
| 0x509B | LocalCredentialLockoutDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 90 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 90 | RW | O |
AutoUnlock Trait
Should configure the Aqara-specific automatic unlock behavior, encoded as a 32-bit unsigned integer, in seconds. This value should specify the delay before automatic unlock; a value of 0 should disable automatic unlock.
| Trait ID | Code |
|---|
| 0x509A | AutoUnlock |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
AwayModeArming Trait
Indicates the away mode arm/disarm state: false (0) disarmed, true (1) armed.
| Trait ID | Code |
|---|
| 0x5098 | AwayModeArming |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LockQuietMode Trait
Should configure the quiet motor speed mode for lock/unlock operations. QuietModeEnabled controls whether quiet mode is active. QuietModeSpeed uses the MotorSpeedEnum Type to set the motor speed within the quiet window. ValidStartUtc and ValidEndUtc specify the UTC time range in which quiet mode takes effect; setting both to 0 means the schedule is not active.
| Trait ID | Code |
|---|
| 0x5097 | LockQuietMode |
Parameters
NormalModeSpeed Trait
Should configure the motor speed level used in normal (daily) operating mode, i.e., when quiet mode is not active. This value should be a MotorSpeedEnum Type entry to select the speed level.
| Trait ID | Code |
|---|
| 0x5096 | NormalModeSpeed |
Parameters
DoorbellLightEnabled Trait
Should enable or disable the doorbell indicator light.
| Trait ID | Code |
|---|
| 0x5095 | DoorbellLightEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DeviceOrientation Trait
Should configure the physical orientation of the door lock. DoorOpenDirection uses the DoorOpenDirectionEnum Type to specify whether the door opens outward or inward.
InstallationOrientation uses the InstallationOrientationEnum Type to specify the installation axis of the lock body.
| Trait ID | Code |
|---|
| 0x5094 | DeviceOrientation |
Parameters
MotorStrength Trait
This Trait indicates the motor strength of the door lock.
| Trait ID | Code |
|---|
| 0x5047 | MotorStrength |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | | RVW | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
PullSpring Trait
Should configure the pull spring mechanism. Enabled controls whether the pull spring is activated. LatchRetractTime specifies the bolt retraction time (milliseconds).
| Trait ID | Code |
|---|
| 0x5092 | PullSpring |
Parameters
FrontLockConnectionStatus Trait
Should indicate the connection status between the front and rear lock bodies. false (0x00) means not connected; true (0x01) means connected.
| Trait ID | Code |
|---|
| 0x5090 | FrontLockConnectionStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
DoorHandleDirection Trait
Should configure the opening direction of the door handle. RightOpen means the door opens to the right; LeftOpen means the door opens to the left.
| Trait ID | Code |
|---|
| 0x508F | DoorHandleDirection |
Parameters
LocalSetting Trait
Should enable or disable the local settings function of the door lock. When set to true, local configuration changes on the device are allowed; when set to false, local configuration is locked.
| Trait ID | Code |
|---|
| 0x508E | LocalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DualVerification Trait
Should enable or disable the dual verification mode of the door lock. When enabled, the door lock requires two independent credential verifications to grant access.
| Trait ID | Code |
|---|
| 0x508D | DualVerification |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LockWorkMode Trait
Should configure the operating mode of the door lock. Normal (0) selects standard operation. InstallationInspection (1) activates the on-site installation function inspection mode for field testing. Demo (2) activates demo mode for product display.
| Trait ID | Code |
|---|
| 0x508C | LockWorkMode |
Parameters
Should configure the authentication method allowed to enter the device local menu.
| Trait ID | Code |
|---|
| 0x5060 | LocalMenuEntryMethod |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RVW | O |
DoorLockAlarmStatus Trait
Should report the current combined state of the door lock device as a read-only snapshot. This attribute should be null when the device has not yet reported its state.
| Trait ID | Code |
|---|
| 0x505F | DoorLockAlarmStatus |
Parameters
TamperAlarmEnabled Trait
Should enable or disable the tamper alarm. When set to true, the door lock should trigger an alarm when a tamper event is detected.
| Trait ID | Code |
|---|
| 0x505E | TamperAlarmEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
HardInfo Trait
Should provide a read-only string encoding the version and identity information of the door lock device and its back cover module. This string should be UTF-8 encoded, with a maximum length of 256 bytes.
| Trait ID | Code |
|---|
| 0x505D | HardInfo |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
DoorAjarConfig Trait
Should configure the door ajar alarm behavior. The Enabled field enables or disables the alarm. The Volume field sets the alarm volume. The WaitTime field defines the timeout in seconds before the alarm is triggered while the door remains ajar (bolt not fully engaged). The optional AlarmDuration field, if present, specifies the number of seconds the alarm should last per trigger.
| Trait ID | Code |
|---|
| 0x505C | DoorAjarConfig |
Parameters
DoorNotLockedConfig Trait
Should configure the door not locked alarm behavior. The Enabled field enables or disables the alarm. The Volume field sets the alarm volume. The WaitTime field defines the timeout in seconds before the alarm is triggered while the door remains closed but unlocked. The optional AlarmDuration field, if present, specifies the number of seconds the alarm should last per trigger.
| Trait ID | Code |
|---|
| 0x505B | DoorNotLockedConfig |
Parameters
DoorNotClosedConfig Trait
Should configure the door not closed alarm behavior. The Enabled field enables or disables the alarm. The Volume field sets the alarm volume. The WaitTime field defines the timeout in seconds before the alarm is triggered while the door remains open. The optional AlarmDuration field, if present, specifies the number of seconds the alarm should last per trigger.
| Trait ID | Code |
|---|
| 0x505A | DoorNotClosedConfig |
Parameters
AlarmVolume Trait
Should configure the general alarm volume level.
| Trait ID | Code |
|---|
| 0x5059 | AlarmVolume |
Parameters
LockJammedVolume Trait
Should configure the volume level of the alarm triggered when the lock mechanism is jammed.
| Trait ID | Code |
|---|
| 0x5058 | LockJammedVolume |
Parameters
AwayModePromptVolume Trait
Should configure the volume level of the away mode arm/disarm prompts.
| Trait ID | Code |
|---|
| 0x5057 | AwayModePromptVolume |
Parameters
DemoVoiceVolume Trait
Should configure the demo firmware voice volume level, used for showroom demonstration.
| Trait ID | Code |
|---|
| 0x5056 | DemoVoiceVolume |
Parameters
AbnormalVibrationAlarmVolume Trait
Should configure the abnormal vibration alarm volume level, used for the safe box function.
| Trait ID | Code |
|---|
| 0x5055 | AbnormalVibrationAlarmVolume |
Parameters
VoiceVolume Trait
Should configure the voice prompt volume level.
| Trait ID | Code |
|---|
| 0x5054 | VoiceVolume |
Parameters
DoorbellVolume Trait
Should configure the doorbell volume level.
| Trait ID | Code |
|---|
| 0x5053 | DoorbellVolume |
Parameters
UnlockVolume Trait
Should configure the unlock prompt tone volume level.
| Trait ID | Code |
|---|
| 0x5052 | UnlockVolume |
Parameters
EnableElectronicLockoutMode Trait
Should enable/disable the electronic lockout mode (child lock). When enabled, the touch panel and keypad are locked to prevent accidental operation.
| Trait ID | Code |
|---|
| 0x4F5D | EnableElectronicLockoutMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableAwayMode Trait
Enable/disable away mode.
| Trait ID | Code |
|---|
| 0x4F5B | EnableAwayMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableDeadbolt Trait
This Trait is used for access to and reporting of "enable deadbolt" data.
| Trait ID | Code |
|---|
| 0x507A | EnableDeadbolt |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ConfigOperation Trait
This Trait is used for access to and reporting of "door lock configuration operation" data.
| Trait ID | Code |
|---|
| 0x5031 | ConfigOperation |
Parameters
StateOfLowBat Trait
Indicates whether the battery is in a low battery state. 0: Normal, 1: Low battery, 2: Critically low.
| Trait ID | Code |
|---|
| 0x80C9 | StateOfLowBat |
Parameters
GetCredentialStatusResponse Trait
This Trait is used for access to and reporting of "get credential status reply" data.
| Trait ID | Code |
|---|
| 0x4E71 | GetCredentialStatusResponse |
Parameters
SetCredentialResponse Trait
This Trait is used for access to and reporting of "set credential reply" data.
| Trait ID | Code |
|---|
| 0x4E70 | SetCredentialResponse |
Parameters
GetUserResponse Trait
This Trait is used for access to and reporting of "get user reply" data.
| Trait ID | Code |
|---|
| 0x4E6F | GetUserResponse |
Parameters
GetAqaraUserResponse Trait
This Trait is used to carry the user record list returned by GetAqaraUserResponse.
| Trait ID | Code |
|---|
| 0x51F1 | GetAqaraUserResponse |
Parameters
GetWeekDayScheduleResponse Trait
This Trait is used for access to and reporting of "get weekly schedule reply" data.
| Trait ID | Code |
|---|
| 0x4E6D | GetWeekDayScheduleResponse |
Parameters
GetYearDayScheduleResponse Trait
This Trait is used for access to and reporting of "get yearly schedule reply" data.
| Trait ID | Code |
|---|
| 0x4E6E | GetYearDayScheduleResponse |
Parameters
NumberOfCredentialsSupportedPerUser Trait
This Trait is used for access to and reporting of "credentials per user supported" data.
| Trait ID | Code |
|---|
| 0x4E6B | NumberOfCredentialsSupportedPerUser |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
NumberOfYearDaySchedulesSupportedPerUser Trait
This Trait is used for access to and reporting of "yearly schedules per user supported" data.
| Trait ID | Code |
|---|
| 0x4E6A | NumberOfYearDaySchedulesSupportedPerUser |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
NumberOfWeekDaySchedulesSupportedPerUser Trait
This Trait is used for access to and reporting of "weekly schedules per user supported" data.
| Trait ID | Code |
|---|
| 0x4E69 | NumberOfWeekDaySchedulesSupportedPerUser |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
This Trait is used for access to and reporting of "RFID user count" data.
| Trait ID | Code |
|---|
| 0x4E68 | NumberOfRFIDUsersSupported |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
This Trait is used for access to and reporting of "PIN user count" data.
| Trait ID | Code |
|---|
| 0x4E67 | NumberOfPINUsersSupported |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
This Trait is used for access to and reporting of "total door lock user count" data.
| Trait ID | Code |
|---|
| 0x4E66 | NumberOfTotalUsersSupported |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
NetworkInterfaces Trait
This feature describes the network interfaces supported by the device.
| Trait ID | Code |
|---|
| 0x4E2A | NetworkInterfaces |
Parameters
LockOperationError Trait
When a door lock operation fails for various reasons, the door lock will emit a LockOperationError event.
| Trait ID | Code |
|---|
| 0x8171 | LockOperationError |
Parameters
RemoteControlWithAuthCode Trait
This Trait is used for access to and reporting of "remote control (with authorization code) - Aqara private" data.
| Trait ID | Code |
|---|
| 0x9C40 | RemoteControlWithAuthCode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | W | O |
LockUserChange Trait
When a door lock user, schedule or credential changes, the door lock will emit a LockUserChange event.
| Trait ID | Code |
|---|
| 0x8173 | LockUserChange |
Parameters
DoorLockAlarm Trait
The door lock can send various alarms when critical states occur.
| Trait ID | Code |
|---|
| 0x8172 | DoorLockAlarm |
Parameters
LockOperation Trait
When the device successfully unlocks/locks through any supported method, the lock operation event is recorded and reported. It provides detailed context of the unlock/lock operation, including the source (e.g., Matter ecosystem or local method), user identity and the specific credential used.
| Trait ID | Code |
|---|
| 0x8170 | LockOperation |
Parameters
RemoteUnlock Trait
This Trait is used for access to and reporting of "remote unlock - Aqara private" data.
| Trait ID | Code |
|---|
| 0x8125 | RemoteUnlock |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SupportedRemoteFeatures Trait
This Trait is used for access to and reporting of "supported remote features" data.
| Trait ID | Code |
|---|
| 0x8102 | SupportedRemoteFeatures |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | R | O |
EnableRemoteControl Trait
This Trait is used for access to and reporting of "remote control enable" data.
| Trait ID | Code |
|---|
| 0x8101 | EnableRemoteControl |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DoorState Trait
This Trait is used for access to and reporting of "door state" data.
| Trait ID | Code |
|---|
| 0x80CB | DoorState |
Parameters
ActuatorEnabled Trait
This Trait is used for access to and reporting of "actuator enable" data.
| Trait ID | Code |
|---|
| 0x8133 | ActuatorEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
AlarmMask Trait
This Trait is used for access to and reporting of "alarm mask" data.
| Trait ID | Code |
|---|
| 0x8130 | AlarmMask |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
CredentialRulesSupport Trait
This Trait is used for access to and reporting of "credential rules support" data.
| Trait ID | Code |
|---|
| 0x812A | CredentialRulesSupport |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ExpiringUserTimeout Trait
This Trait is used for access to and reporting of "user timeout expired" data. Unit: S.
| Trait ID | Code |
|---|
| 0x812F | ExpiringUserTimeout |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RVW | O |
| 0x0002 | Maximum Value | float | | 2880.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 1 | RW | O |
MaxPINCodeLength Trait
This Trait is used for access to and reporting of "max PIN code length" data.
| Trait ID | Code |
|---|
| 0x8126 | MaxPINCodeLength |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MaxRFIDCodeLength Trait
This Trait is used for access to and reporting of "max RFID length" data.
| Trait ID | Code |
|---|
| 0x8128 | MaxRFIDCodeLength |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MinPINCodeLength Trait
This Trait is used for access to and reporting of "min PIN code length" data.
| Trait ID | Code |
|---|
| 0x8127 | MinPINCodeLength |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MinRFIDCodeLength Trait
This Trait is used for access to and reporting of "min RFID length" data.
| Trait ID | Code |
|---|
| 0x8129 | MinRFIDCodeLength |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
OperatingMode Trait
This Trait is used for access to and reporting of "operating mode" data.
| Trait ID | Code |
|---|
| 0x812B | OperatingMode |
Parameters
RequirePINForRemoteOperation Trait
This Trait is used for access to and reporting of "PIN code required for remote operation" data.
| Trait ID | Code |
|---|
| 0x812E | RequirePINForRemoteOperation |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
SendPINOverTheAir Trait
This Trait is used for access to and reporting of "send PIN code over the air" data.
| Trait ID | Code |
|---|
| 0x812D | SendPINOverTheAir |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
UserCodeTemporaryDisableTime Trait
This Trait is used for access to and reporting of "user code temporary disable time" data. Unit: S.
| Trait ID | Code |
|---|
| 0x812C | UserCodeTemporaryDisableTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RVW | O |
| 0x0002 | Maximum Value | float | | 255.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 1 | RW | O |
SupportsTapToUnlock Trait
This Trait is used for access to and reporting of "supports tap to unlock" data.
| Trait ID | Code |
|---|
| 0x8131 | SupportsTapToUnlock |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
SupportsTapToLock Trait
This Trait is used for access to and reporting of "supports tap to lock" data.
| Trait ID | Code |
|---|
| 0x8132 | SupportsTapToLock |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
SetTravelCalibrationResponse Command
This command is used to respond to SetTravelCalibration, reporting the execution result of the travel calibration session.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | Travel calibration result; 0x00 means success, non-zero values indicate failure reasons. |
AddAqaraUserResponse Command
This command is used to respond to AddAqaraUser, reporting the user creation result and returning the UserId assigned by the device.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | User creation result. |
| 2 | UserId | uint16 | M | New user ID assigned by the device on success. |
ModifyAqaraUserResponse Command
This command is used to respond to ModifyAqaraUser, reporting the user modification result.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | User modification result. |
| 2 | UserId | uint16 | M | ID of the modified user. |
DeleteAqaraUserResponse Command
This command is used to respond to DeleteAqaraUser, reporting the user deletion result.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | User deletion result. |
| 2 | UserId | uint16 | M | ID of the deleted user. |
The device returns user records and a pagination cursor in this response. The table below only lists the fields used by the Aqara Spec user data model; the Trait only stores Users, not including ErrorCode. Field IDs follow the Extension definitions.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 2 | Users | list[AqaraUserRecordStruct] | O | User record list, returning at most the Number of records requested, sorted by UserId in ascending order; an empty list when the database is empty. |
| 3 | NextUserId | uint16 | M | Starting user ID for the next pagination query; null indicates the traversal is complete. |
AddAqaraCredentialResponse Command
This command is used to respond to AddAqaraCredential, reporting the credential addition result and returning the CredentialId on success.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | Credential addition result. |
| 2 | UserId | uint16 | M | User ID to which the credential belongs. |
| 3 | CredentialId | uint16 | O | Credential ID assigned by the device on success. |
ModifyAqaraCredentialResponse Command
This command is used to respond to ModifyAqaraCredential, reporting the credential modification result.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | Credential modification result. |
| 2 | CredentialId | uint16 | M | ID of the modified credential. |
DeleteAqaraCredentialResponse Command
This command is used to respond to DeleteAqaraCredential, reporting the credential deletion result.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | Credential deletion result. |
| 2 | CredentialId | uint16 | M | ID of the deleted credential. |
GetAqaraCredentialResponse Command
This command is used to respond to GetAqaraCredential, returning the credential query result and the credential record.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | Credential query result. |
| 2 | UserId | uint16 | O | User ID to which the credential belongs. |
| 3 | Credential | Struct | O | Credential record. |
ExitAddAqaraCredentialResponse Command
This command is used to respond to ExitAddAqaraCredential, reporting the result of exiting the credential enrollment session.
| Parameter No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ErrorCode | enum8 | M | Exit session result. |
| 2 | UserId | uint16 | M | User ID of the session being exited. |
Command Definitions
GetUser Command
This Command is used to perform the "get user" operation.
Parameters
GetUser Command Structure
ClearCredential Command
This Command is used to perform the "clear credential" operation.
Parameters
ClearCredential Command Structure
GetCredentialStatus Command
This Command is used to perform the "get credential status" operation.
Parameters
GetCredentialStatus Command Structure
SetCredential Command
This Command is used to perform the "set credential" operation.
Parameters
SetCredential Command Structure
ClearUser Command
ClearUser (Clear user)
Parameters
ClearUser Command Structure
SetUser Command
This Command is used to perform the "set user" operation.
Parameters
SetUser Command Structure
UnboltDoor Command
Open door -- retract the square bolt and the latch bolt
Parameters
UnboltDoor Command Structure
GetYearDaySchedule Command
This Command is used to perform the "get yearly schedule" operation.
Parameters
GetYearDaySchedule Command Structure
ClearYearDaySchedule Command
This Command is used to perform the "clear yearly schedule" operation.
Parameters
ClearYearDaySchedule Command Structure
SetYearDaySchedule Command
This Command is used to perform the "set yearly schedule" operation.
Parameters
SetYearDaySchedule Command Structure
ClearWeekDaySchedule Command
This Command is used to perform the "clear weekly schedule" operation.
Parameters
ClearWeekDaySchedule Command Structure
GetWeekDaySchedule Command
This Command is used to perform the "get weekly schedule" operation.
Parameters
GetWeekDaySchedule Command Structure
SetWeekDaySchedule Command
This Command is used to perform the "set weekly schedule" operation.
Parameters
SetWeekDaySchedule Command Structure
QuietUnlockDoor Command
This Command is used to perform the "quiet unlock" operation.
This Command has no parameters.
QuietLockDoor Command
This Command is used to perform the "quiet lock" operation.
This Command has no parameters.
UnlockDoor Command
This Command is used to perform the "unlock" operation.
Parameters
UnlockDoor Command Structure
LockDoor Command
This Command is used to perform the "lock" operation.
Parameters
LockDoor Command Structure
MagneticEncoderCalibration Command
This command is used to start the door lock magnetic encoder calibration. This command has no parameters.
GetLog Command
This command should request the door lock to return a segment of log entries. The device should respond with the GetLogResponse command.
Parameters
GetLog Command Structure
ExitAddAqaraCredential Command
This command should exit the add-credential session for the specified credential type and attribute. The client sends this command to cancel or complete the credential enrollment flow without submitting a new credential. The UserId field identifies the user whose credential enrollment session is being exited.
Parameters
ExitAddAqaraCredential Command Structure
GetAqaraCredential Command
This command should request the door lock to return the complete credential record for the specified credential. The device should respond with the GetAqaraCredentialResponse command.
Parameters
GetAqaraCredential Command Structure
DeleteAqaraCredential Command
This command should delete the credential identified by CredentialId from the door lock credential database.
Parameters
DeleteAqaraCredential Command Structure
ModifyAqaraCredential Command
This command should update one or more attributes of the credential identified by CredentialId.
Each updatable field can be omitted independently: when a field is omitted, the existing value of the credential on the device should remain unchanged. At least one of CredentialAttribute, CredentialType, CredentialContent, Validity or CredentialName should be provided; if all five are omitted, the device should respond with InvalidParameter (0x07) of the DoorLockErrorCodeEnum type and must not modify any credential data.
Parameters
ModifyAqaraCredential Command Structure
AddAqaraCredential Command
This command should add a new credential and associate it with the existing user identified by UserId. The CredentialContent field carries the type-specific credential payload as a structured value; CredentialName is a variable-length string with an implicit length prefix. The optional Validity field, when present, encodes the credential's periodic validity schedule using the CredentialValidityStruct type; when absent, the credential has no time boundary restrictions other than device default limits.
Parameters
AddAqaraCredential Command Structure
GetAqaraUser Command
This command should request the door lock to return one or more user records (each carrying user attributes and associated credentials). The device should respond with GetAqaraUserResponse, returning at most Number records starting from UserId. This command is also the basic operation for traversing the complete user database--the client traverses the database by making chained consecutive calls and consuming the NextUserId field of each response until it is null.
Parameters
GetAqaraUser Command Structure
DeleteAqaraUser Command
This command should delete the user identified by UserId from the door lock user database.
Parameters
DeleteAqaraUser Command Structure
ModifyAqaraUser Command
This command should update one or more attributes of the user identified by UserId on the door lock device. Each updatable field can be omitted independently: when a field is null or omitted, the existing value of the user on the device should remain unchanged. At least one of UserType or UserName should be provided with a non-null value; if both are null or omitted, the device should respond with InvalidParameter (0x07) of the DoorLockErrorCodeEnum type and must not modify any user data.
Parameters
ModifyAqaraUser Command Structure
AddAqaraUser Command
This command should create a new user entry in the door lock user database. The device should assign an unused UserId to the new user and return that identifier in the corresponding AddAqaraUserResponse. The newly created user is not yet associated with any credentials; credentials can subsequently be attached via AddAqaraCredential.
Parameters
AddAqaraUser Command Structure
SetTravelCalibration Command
This command should control the manual travel calibration session of the door lock. The client sends this command to drive the lock body through a full travel motion and record the unlock and lock endpoint positions.
Parameters
SetTravelCalibration Command Structure
Sweeper
Introduction
Provides basic control of the robot vacuum, including operations such as starting cleaning, pausing, returning to charge and status feedback.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0095 | Sweeper | Sweeper |
Trait
Command
Data Types
SweeperStateEnum8 Type
This enumeration defines the valid values of the Present Value of the SweeperState Trait.
| Value | Name | Description |
|---|
| 0x00 | Cleaning | Cleaning |
| 0x01 | Paused | Paused |
| 0x02 | NotCleaning | Not cleaning |
Trait Definitions
SweeperState Trait
This Trait is used for access to and reporting of "sweeper state" data.
| Trait ID | Code |
|---|
| 0x80CF | SweeperState |
Parameters
Command Definitions
ContinueCleaning Command
This Command is used to perform the "continue cleaning" operation.
This Command has no parameters.
PauseCleaning Command
This Command is used to perform the "pause cleaning" operation.
This Command has no parameters.
StartCleaning Command
This Command is used to perform the "start cleaning" operation.
This Command has no parameters.
StopCleaning Command
This Command is used to perform the "stop cleaning" operation.
This Command has no parameters.
AirQuality
Introduction
Monitors and reports air quality indicators, such as AQI or the overall air quality level.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0096 | AirQuality | Air quality |
Trait
Command
This Function does not contain Commands.
Data Types
VOCQualityEnum8 Type
This enumeration defines the valid values of the Present Value of the VOCQuality Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Excellent | Excellent |
| 0x02 | Good | Good |
| 0x03 | Fair | Fair |
| 0x04 | Inferior | Poor |
| 0x05 | Poor | Very poor |
AirQualityEnum8 Type
This enumeration defines the valid values of the Present Value of the AirQuality Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Excellent | Excellent |
| 0x02 | Good | Good |
| 0x03 | Fair | Fair |
| 0x04 | Inferior | Poor |
| 0x05 | Poor | Very poor |
Trait Definitions
VOCQuality Trait
Indicates the volatile organic compounds (VOC) air quality level. Values: 0 = Unknown, 1 = Excellent, 2 = Good, 3 = Fair, 4 = Poor, 5 = Very poor.
| Trait ID | Code |
|---|
| 0x80D5 | VOCQuality |
Parameters
VOCDensity Trait
This Trait is used for access to and reporting of "VOC density" data. Unit: ppb.
| Trait ID | Code |
|---|
| 0x80D4 | VOCDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 1 | RW | O |
AirQuality Trait
AirQuality represents the air quality level.
| Trait ID | Code |
|---|
| 0x0009 | AirQuality |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | AirQualityEnum8 | | 0 | RV | O |
| 0x0006 | Supported Value | list[AirQualityEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
NMHCDensity Trait
Represents the concentration of non-methane hydrocarbons in the air, which can be used to assess the overall level of volatile organic pollution. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x51A9 | NMHCDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
NegativeOxygenIons Trait
Represents the level of negative oxygen ions in the air, often used to describe air freshness or specific environmental characteristics. Unit: ions/cm^3.
| Trait ID | Code |
|---|
| 0x51AD | NegativeOxygenIons |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 1000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Pressure
Introduction
Measures and reports the atmospheric pressure or system pressure value.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0097 | Pressure | Pressure |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
CurrentPressure Trait
This Trait is used for access to and reporting of "pressure" data. Unit: kPa.
| Trait ID | Code |
|---|
| 0x80D6 | CurrentPressure |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 101 | RV | M |
| 0x0002 | Maximum Value | float | | 200000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 101 | RW | O |
Command Definitions
This Function does not contain Commands.
ParticulateMatter
Introduction
Monitors and reports particulate matter concentrations (such as PM2.5, PM10).
Function Identification
| Function ID | Code | Name |
|---|
| 0x0098 | ParticulateMatter | Particulate matter |
Trait
Command
This Function does not contain Commands.
Data Types
PM2.5LevelEnum8 Type
This enumeration defines the valid values of the Present Value of the PM2.5Level Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Excellent | Excellent |
| 0x02 | Good | Good |
| 0x03 | Fair | Fair |
| 0x04 | Inferior | Poor |
| 0x05 | Poor | Very poor |
Trait Definitions
PM2.5Density Trait
This Trait is used for access to and reporting of "PM2.5 concentration" data. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x80D7 | PM2.5Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 1000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
PM2.5Level Trait
This Trait is used for access to and reporting of "PM2.5 level" data.
| Trait ID | Code |
|---|
| 0x80D8 | PM2.5Level |
Parameters
PM1.0Density Trait
This Trait is used for access to and reporting of "PM1.0 concentration" data. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x80D9 | PM1.0Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 65535.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
PM10Density Trait
This Trait is used for access to and reporting of "PM10 concentration" data. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x80DA | PM10Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 65535.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
PM100Density Trait
Represents the mass concentration of larger particulate matter in the air, which can be used to assess the level of suspended particulate pollution and changes in environmental cleanliness. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x519E | PM100Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
TSPDensity Trait
Represents the concentration of total suspended particulate matter in the air, which can be used to assess the overall particulate pollution level and environmental cleanliness. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x51AA | TSPDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
CO2
Introduction
Measures and reports the carbon dioxide concentration in the environment.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0099 | CO2 | Carbon dioxide |
Trait
Command
This Function does not contain Commands.
Data Types
CO2LevelEnum8 Type
This enumeration defines the valid values of the Present Value of the CO2Level Trait.
| Value | Name | Description |
|---|
| 0x00 | Excellent | Excellent |
| 0x01 | LightPollution | Light pollution |
| 0x02 | HeavyPollution | Heavy pollution |
Trait Definitions
CO2Level Trait
Indicates the carbon dioxide concentration level with a qualitative index. Values: 0 = Excellent (normal/low CO2), 1 = Light Pollution (CO2 slightly elevated), 2 = Heavy Pollution (high CO2 concentration).
| Trait ID | Code |
|---|
| 0x80DC | CO2Level |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | CO2LevelEnum8 | | 0 | RV | M |
| 0x0006 | Supported Value | list[CO2LevelEnum8] | | | R | O |
CO2Density Trait
This Trait is used for access to and reporting of "CO2 concentration" data. Unit: ppm.
| Trait ID | Code |
|---|
| 0x80DB | CO2Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Illuminance
Introduction
Measures and reports the ambient illuminance (lux).
Function Identification
| Function ID | Code | Name |
|---|
| 0x009A | Illuminance | Illuminance |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
CurrentIlluminance Trait
This Trait is used for access to and reporting of "illuminance" data. Unit: lux.
| Trait ID | Code |
|---|
| 0x80DD | CurrentIlluminance |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | M |
| 0x0002 | Maximum Value | float | | 100000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
SamplingInterval Trait
Defines the data sampling time interval. Unit: S.
| Trait ID | Code |
|---|
| 0x4E99 | SamplingInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 5 | RVW | O |
| 0x0002 | Maximum Value | float | | 3600.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.5 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 5 | RW | O |
Command Definitions
This Function does not contain Commands.
Introduction
Detects binary contact/magnetic contact states, reporting the open or closed state and optional angle information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x009B | Contact | Contact |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9C75 | CalibrateReq | Remote calibration | O |
Data Types
CalibrationNotificationEnum8 Type
This enumeration defines the valid values of the Present Value of the CalibrationNotification Trait.
| Value | Name | Description |
|---|
| 0x00 | Success | Success |
| 0x01 | Failure | Failure |
Trait Definitions
This Trait is used for access to and reporting of "contact state" data.
| Trait ID | Code |
|---|
| 0x80DE | ContactSensorState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
OpenAngle Trait
The open/close angle of the door or window
| Trait ID | Code |
|---|
| 0x4E74 | OpenAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 360.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CalibrationNotification Trait
This Trait is used for access to and reporting of "calibration result" data.
| Trait ID | Code |
|---|
| 0x5061 | CalibrationNotification |
Parameters
Command Definitions
CalibrateReq Command
This Command is used to perform the "remote calibration" operation.
This Command has no parameters.
Smoke
Introduction
Detects smoke and reports alarm events, supporting related configurations such as sensitivity, self-check reminders and mute.
Function Identification
| Function ID | Code | Name |
|---|
| 0x009C | Smoke | Smoke |
Trait
Command
Data Types
SmokeChamberContaminationEnum8 Type
This enumeration defines the valid values of the Present Value of the SmokeChamberContamination Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Monitoring normal |
| 0x01 | Contaminated | Smoke chamber contaminated |
AlarmErrorEnum8 Type
This enumeration defines the valid values of the Present Value of the AlarmError Trait.
| Value | Name | Description |
|---|
| 0x00 | SUCCESS | Success |
| 0x01 | FAILURE | Failure |
| 0x02 | NOT_ALLOWED | Not allowed |
SmokeStateEnum8 Type
This enumeration defines the valid values of the Present Value of the SmokeState Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Warning | Warning |
| 0x02 | Critical | Severe |
ExpressedStateEnum8 Type
This enumeration defines the valid values of the Present Value of the ExpressedState Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | SmokeAlarm | Smoke leak |
| 0x02 | COAlarm | CO leak |
| 0x03 | BatteryAlert | Battery warning |
| 0x04 | Testing | Testing |
| 0x05 | HardwareFault | Hardware error |
| 0x06 | EndOfService | Service terminated |
| 0x07 | InterconnectSmoke | Interconnected smoke alarm |
| 0x08 | InterconnectCO | Interconnected CO alarm |
This enumeration defines the valid values of the Present Value of the InterconnectSmokeAlarm Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Warning | Alarm |
| 0x02 | Critical | Severe alarm |
SelfTestReminderEnum8 Type
This enumeration defines the valid values of the Present Value of the SelfTestReminder Trait.
| Value | Name | Description |
|---|
| 0x00 | NoReminder | Self-check is not currently required |
| 0x01 | SelfTestRequired | The device needs to perform a self-check |
TriggerWarning Command Structure Type
Parameter structure of the TriggerWarning Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Warning | enum8 | M | Warning. |
Trait Definitions
SmokeDetected Trait
This Trait is used for access to and reporting of "smoke detection state" data.
| Trait ID | Code |
|---|
| 0x80E0 | SmokeDetected |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
SmokeChamberContamination Trait
Indicates the smoke chamber contamination state. This Trait uses an enumeration to represent different contamination levels caused by dust or particulate buildup blocking the optical path. A non-zero value indicates that maintenance is required; a higher value may indicate more severe contamination.
| Trait ID | Code |
|---|
| 0x4F86 | SmokeChamberContamination |
Parameters
AlarmError Trait
This Trait is used for access to and reporting of "alarm error" data.
| Trait ID | Code |
|---|
| 0x4F47 | AlarmError |
Parameters
SmokeState Trait
This Trait is used for access to and reporting of "smoke state" data.
| Trait ID | Code |
|---|
| 0x4F11 | SmokeState |
Parameters
EnableHeartbeatIndicator Trait
This Trait is used for access to and reporting of "heartbeat indicator control" data.
| Trait ID | Code |
|---|
| 0x4F10 | EnableHeartbeatIndicator |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
FireProductIdentification Trait
This Trait is used for access to and reporting of "fire product identification code" data.
| Trait ID | Code |
|---|
| 0x4F0F | FireProductIdentification |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
SelfTestReminder Trait
This Trait is a read-only attribute used to indicate whether the device currently needs to perform a self-check. When the device detects that a self-check is needed, this Trait should be set to SelfTestRequired; when no self-check is needed, it should be set to NoReminder.
| Trait ID | Code |
|---|
| 0x519B | SelfTestReminder |
Parameters
AlarmsEnabled Trait
This Trait is used for access to and reporting of "alarm enable" data.
| Trait ID | Code |
|---|
| 0x4F0B | AlarmsEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SelfCheck Trait
Facilitates performing a self-check to verify that the device functions correctly.
| Trait ID | Code |
|---|
| 0x4E88 | SelfCheck |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ExpressedState Trait
ExpressedState defines the state of the alarm device.
| Trait ID | Code |
|---|
| 0x0005 | ExpressedState |
Parameters
SmokeDensitydB Trait
This Trait is used for access to and reporting of "smoke density dB" data. Unit: dB/m.
| Trait ID | Code |
|---|
| 0x80F0 | SmokeDensitydB |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
SmokeDensity Trait
This Trait is used for access to and reporting of "smoke density" data. Unit: OBS%/FT.
| Trait ID | Code |
|---|
| 0x80DF | SmokeDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Mute Trait
Indicates the mute state of the speaker.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
InterconnectSmokeAlarm Trait
This Trait is used for access to and reporting of "interconnected smoke alarm" data.
| Trait ID | Code |
|---|
| 0x503C | InterconnectSmokeAlarm |
Parameters
Command Definitions
TriggerWarning Command
This Command is used to perform the "trigger alarm" operation.
Parameters
TriggerWarning Command Structure
SelfTestRequest Command
SelfTestRequest represents the alarm device self-check.
This Command has no parameters.
Gas
Introduction
Detects combustible gas or harmful gas leaks and reports alarm events.
Function Identification
| Function ID | Code | Name |
|---|
| 0x009D | Gas | Gas |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
GasDetected Trait
This Trait is used for access to and reporting of "gas detection state" data.
| Trait ID | Code |
|---|
| 0x80E2 | GasDetected |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
GasDensity Trait
This Trait is used for access to and reporting of "gas concentration" data. Unit: %LEL.
| Trait ID | Code |
|---|
| 0x80E1 | GasDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
SelfCheck Trait
Facilitates performing a self-check to verify that the device functions correctly.
| Trait ID | Code |
|---|
| 0x4E88 | SelfCheck |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Mute Trait
Indicates the mute state of the speaker.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CurrentSensitivityLevel Trait
Indicates the currently selected general configuration sensitivity level.
| Trait ID | Code |
|---|
| 0x813B | CurrentSensitivityLevel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Sleep
Introduction
Monitors sleep-related states, reporting metrics such as sleep stage, duration or quality.
Function Identification
| Function ID | Code | Name |
|---|
| 0x009E | Sleep | Sleep |
Trait
Command
This Function does not contain Commands.
Data Types
SleepStateEnum8 Type
This enumeration defines the valid values of the Present Value of the SleepState Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Awake | Awake |
| 0x02 | Sleep | Asleep |
SleepStageEnum8 Type
This enumeration defines the valid values of the Present Value of the SleepStage Trait.
| Value | Name | Description |
|---|
| 0x00 | LightSleep | LightSleep |
| 0x01 | DeepSleep | DeepSleep |
| 0x02 | REM | REM |
Trait Definitions
SleepState Trait
This Trait is used for access to and reporting of "sleep state" data.
| Trait ID | Code |
|---|
| 0x80E3 | SleepState |
Parameters
SleepQuality Trait
Defines the sleep quality, ranging from 0 to 100.
| Trait ID | Code |
|---|
| 0x80E4 | SleepQuality |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
OnBed Trait
Defines the on-bed state.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
SleepStage Trait
Defines the sleep stage.
| Trait ID | Code |
|---|
| 0x80E6 | SleepStage |
Parameters
Command Definitions
This Function does not contain Commands.
WaterLeak
Introduction
Detects water leak events and reports an alarm in a timely manner when a leak is detected.
Function Identification
| Function ID | Code | Name |
|---|
| 0x009F | WaterLeak | Water leak |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x80E7 | LeakState | Leak state | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
LeakState Trait
This Trait is used for access to and reporting of "leak state" data.
| Trait ID | Code |
|---|
| 0x80E7 | LeakState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
Command Definitions
This Function does not contain Commands.
OccupancySensing
Introduction
Detects whether a person is present in the space, reporting occupied/idle states and parameters such as hold time.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A0 | OccupancySensing | Occupancy |
Trait
Command
This Function does not contain Commands.
Data Types
OccupancySensorTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the OccupancySensorType Trait.
| Value | Name | Description |
|---|
| 0x00 | PIR | Passive infrared |
| 0x01 | Ultrasonic | Ultrasonic |
| 0x02 | PIRAndUltrasonic | Infrared and ultrasonic |
| 0x03 | PhysicalContact | Physical contact |
| 0x04 | Radar | Radar |
| 0x05 | Vision | Vision |
RegionDimensionTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RegionDimension Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | unit | enum8 | M | The unit of width and height, e.g., GRID or PIXEL. |
| 1 | width | uint32 | M | The total width of the region in the specified unit. |
| 2 | height | uint32 | M | The total height of the region in the specified unit. |
BitmaskRegionSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the BitmaskRegionSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | detect_region | characterString | M | Bitmask in hexadecimal string form, where each bit corresponds to one grid cell. |
| 1 | effective_bits | int32 | M | The number of valid bits in the bitmask; bits beyond this count should be ignored. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Repeat flags with a fixed length of 7, ordered from Sunday to Saturday; 1 means active, 0 means inactive. |
Trait Definitions
OccupancySensorType Trait
Specifies the occupancy sensor type (e.g., PIR, ultrasonic, radar, vision, etc.).
| Trait ID | Code |
|---|
| 0x80E9 | OccupancySensorType |
Parameters
Occupancy Trait
This Trait is used for access to and reporting of "occupancy state" data.
| Trait ID | Code |
|---|
| 0x80E8 | Occupancy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
OccupancySensingEnable Trait
The master switch to enable or disable motion detection.
| Trait ID | Code |
|---|
| 0x5029 | OccupancySensingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
RegionDimension Trait
Defines the full canvas dimensions that the client (e.g., App) can use for region configuration (such as detection regions, privacy masks). Its value is a structure containing three fields:
unit (enum8): the unit of width and height, e.g., GRID (grid cells), PIXEL (pixels).
width (uint32): the total width of the region in the specified unit.
height (uint32): the total height of the region in the specified unit.
| Trait ID | Code |
|---|
| 0x502D | RegionDimension |
Parameters
BitmaskRegionSetting Trait
Defines region configuration based on a grid mask. It contains two fields: detect_region (hexadecimal string) and effective_bits (integer). Each bit in the hexadecimal string corresponds to one grid cell (for example, dividing the frame into 24 cells). A bit value of 1 means detection or recognition is enabled for the corresponding cell, and 0 means disabled. The bit arrangement follows a predefined order (e.g., left to right or most significant bit to least significant bit). The effective_bits field specifies the number of actually valid bits in the hexadecimal string, allowing the string to maintain a fixed length with only the first N bits being meaningful. For example, "FF" means 8 consecutive bits are all 1. If effective_bits is 32, all 32 bits are valid; if it is 24, only the first 24 bits are valid. This representation is commonly used for features such as motion detection and human detection that require flexibly selecting specific regions on a video frame.
| Trait ID | Code |
|---|
| 0x4FCC | BitmaskRegionSetting |
Parameters
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
PushEnable Trait
Controls whether to send push notifications to the user when specific functions (such as detection events, recognition events) are triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even when the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
SensitivityLevelEnum Trait
This enumeration configures the sensitivity level for various device functions (such as detection, recognition, sensing, alarm, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. A higher sensitivity makes the function more responsive to trigger conditions (e.g., more likely to detect weak signals or small targets); a lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
TimePeriodSetting Trait
Defines the scheduled plan of time periods and weekdays. The scheduling configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end times of the active period. If the two are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from starttime of the active day and ending at endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, whose index order corresponds to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. A value of 1 means the weekday is active, and 0 means inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
HoldTime Trait
The delay for determining unoccupied, in seconds.
| Trait ID | Code |
|---|
| 0x4E72 | HoldTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
DurationOccupiedWithinOneWeek Trait
Represents the total duration during which the occupancy sensor detected occupied state within one week (a natural week starting from Monday 00:00:00), in milliseconds.
| Trait ID | Code |
|---|
| 0x8115 | DurationOccupiedWithinOneWeek |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 6.048E8 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
DurationOccupiedWithinOneDay Trait
Represents the total duration during which the occupancy sensor detected occupied state within one day, in milliseconds.
| Trait ID | Code |
|---|
| 0x8114 | DurationOccupiedWithinOneDay |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 8.64E7 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
OccupancyStayTime Trait
The number of seconds a person stays in the detection region before the "loitering" event is triggered. Used to filter out brief movements.
| Trait ID | Code |
|---|
| 0x4FE2 | OccupancyStayTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 3 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 30 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 3 | RW | O |
OccupiedToUnoccupiedDelay Trait
This Trait is used for access to and reporting of "occupied to unoccupied delay" data. Unit: S.
| Trait ID | Code |
|---|
| 0x8134 | OccupiedToUnoccupiedDelay |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 4.294967295E9 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
UnoccupiedToOccupiedDelay Trait
This Trait is used for access to and reporting of "unoccupied to occupied delay" data. Unit: S.
| Trait ID | Code |
|---|
| 0x8135 | UnoccupiedToOccupiedDelay |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 4.294967295E9 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Location
Introduction
Provides location information reporting and query capabilities for devices or targets.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A1 | Location | Location |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x80EA | MotionDetected | Motion direction detection | M |
Command
This Function does not contain Commands.
Data Types
MotionDetectedEnum8 Type
This enumeration defines the valid values of the Present Value of the MotionDetected Trait.
| Value | Name | Description |
|---|
| 0x00 | Enter | Enter |
| 0x01 | Left | Leave |
| 0x02 | LeftIn | Enter from left |
| 0x03 | RightOut | Exit to right |
| 0x04 | RightIn | Enter from right |
| 0x05 | LeftOut | Exit to left |
| 0x06 | Access | Approach |
| 0x07 | Away | Recede |
Trait Definitions
MotionDetected Trait
This Trait is used for access to and reporting of "motion detection" data.
| Trait ID | Code |
|---|
| 0x80EA | MotionDetected |
Parameters
Command Definitions
This Function does not contain Commands.
Knob
Introduction
Describes rotation angle, press and combined action events of knob-type input devices.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A2 | Knob | Knob |
Trait
Command
This Function does not contain Commands.
Data Types
RotationEventEnum8 Type
This enumeration defines the valid values of the Present Value of the RotationEvent Trait.
| Value | Name | Description |
|---|
| 0x00 | Rotate | Rotate |
| 0x01 | HoldToRotate | Hold to rotate |
| 0x02 | InvertedRotate | Inverted rotate |
RotationDirectionEnum8 Type
This enumeration defines the valid values of the Present Value of the RotationDirection Trait.
| Value | Name | Description |
|---|
| 0x00 | Clockwise | Clockwise |
| 0x01 | CounterClockwise | CounterClockwise |
Trait Definitions
RotationAngle Trait
This Trait is used for access to and reporting of "rotation angle" data.
| Trait ID | Code |
|---|
| 0x80EB | RotationAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | V | M |
| 0x0002 | Maximum Value | float | | 3600.0 | R | O |
| 0x0003 | Minimum Value | float | | -3600.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
RotationEvent Trait
Describes the knob event type: Rotate, Hold to rotate or Inverted rotate. Values: 0 = Rotate, 1 = Hold to rotate, 2 = Inverted Rotate.
| Trait ID | Code |
|---|
| 0x80ED | RotationEvent |
Parameters
InvertedRotationAngle Trait
The angle of the inverted rotation
| Trait ID | Code |
|---|
| 0x4E28 | InvertedRotationAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | V | O |
| 0x0002 | Maximum Value | float | | 3600.0 | R | O |
| 0x0003 | Minimum Value | float | | -3600.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
HoldRotationInterval Trait
The duration of rotation for a hold-rotation event, i.e., the rotation interval duration, in ms.
| Trait ID | Code |
|---|
| 0x4E25 | HoldRotationInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | V | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
RotationInterval Trait
The duration of rotation for a rotation event, i.e., the rotation interval duration, in ms.
| Trait ID | Code |
|---|
| 0x4E24 | RotationInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | V | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
HoldRotationAngle Trait
This Trait is used for access to and reporting of "hold rotation angle" data.
| Trait ID | Code |
|---|
| 0x8167 | HoldRotationAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | V | O |
| 0x0002 | Maximum Value | float | | 3600.0 | R | O |
| 0x0003 | Minimum Value | float | | -3600.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
RotationDirection Trait
Describes the rotation direction. Values: 0 = Clockwise, 1 = Counterclockwise.
| Trait ID | Code |
|---|
| 0x80EC | RotationDirection |
Parameters
RotationSamplingInterval Trait
Should indicate the minimum time required to sample an angle change. The unit is milliseconds.
| Trait ID | Code |
|---|
| 0x50B6 | RotationSamplingInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 100 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 500 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain Commands.
Cube
Introduction
Describes gesture recognition of the cube controller, including actions such as flipping, rotation, shaking and face recognition.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A3 | Cube | Cube |
Trait
Command
This Function does not contain Commands.
Data Types
CubeEventEnum8 Type
This enumeration defines the valid values of the Present Value of the CubeEvent Trait.
| Value | Name | Description |
|---|
| 0x00 | Flip90 | Flip 90 deg |
| 0x01 | Flip180 | Flip 180 deg |
| 0x02 | Push | Nudge |
| 0x03 | TapTwice | Pick up and tap twice |
| 0x04 | Shake | Shake |
| 0x05 | Swing | Flick |
| 0x06 | Rotate | Rotate |
| 0x07 | TriggeredAfter1Minute | Touch after being stationary |
| 0x0A | PickUpHold | Pick up and hold |
CubeWorkModeSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the CubeWorkModeSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Action Mode | Action mode |
| 0x01 | Scene Mode | Scene mode |
TopFaceEnum8 Type
This enumeration defines the valid values of the Present Value of the TopFace Trait.
| Value | Name | Description |
|---|
| 0x00 | Face 1 Up | Face 1 up |
| 0x01 | Face 2 Up | Face 2 up |
| 0x02 | Face 3 Up | Face 3 up |
| 0x03 | Face 4 Up | Face 4 up |
| 0x04 | Face 5 Up | Face 5 up |
| 0x05 | Face 6 Up | Face 6 up |
TopFaceChangedEnum8 Type
This enumeration defines the valid values of the Present Value of the TopFaceChanged Trait.
| Value | Name | Description |
|---|
| 0x00 | Face 1 Up | Face 1 up |
| 0x01 | Face 2 Up | Face 2 up |
| 0x02 | Face 3 Up | Face 3 up |
| 0x03 | Face 4 Up | Face 4 up |
| 0x04 | Face 5 Up | Face 5 up |
| 0x05 | Face 6 Up | Face 6 up |
Trait Definitions
CubeEvent Trait
This Trait is used for access to and reporting of "cube event" data.
| Trait ID | Code |
|---|
| 0x80EE | CubeEvent |
Parameters
CubeWorkModeSetting Trait
Enables the setting of multiple operating modes of the Magic Cube device to enhance the experience and interaction.
| Trait ID | Code |
|---|
| 0x4F0D | CubeWorkModeSetting |
Parameters
TopFace Trait
Indicates the current upward-facing face of the cube controller, used to define the device state.
| Trait ID | Code |
|---|
| 0x4EC5 | TopFace |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | TopFaceEnum8 | | 0 | RV | O |
| 0x0006 | Supported Value | list[TopFaceEnum8] | | | R | O |
TopFaceChanged Trait
Indicates that the "upward-facing face" of the device has changed. Triggered when the user flips the device (e.g., the cube controller).
| Trait ID | Code |
|---|
| 0x4EC6 | TopFaceChanged |
Parameters
StationaryDuration Trait
Should indicate the stationary duration threshold reached before movement is detected, in minutes.
| Trait ID | Code |
|---|
| 0x50BB | StationaryDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | V | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
TapCount Trait
Should indicate the tap count
| Trait ID | Code |
|---|
| 0x50B9 | TapCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 3 | V | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain Commands.
Vibration
Introduction
Detects vibration or motion changes, reporting events such as movement, tilt and fall.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A4 | Vibration | Vibration |
Trait
Command
This Function does not contain Commands.
Data Types
VibrationEventEnum8 Type
This enumeration defines the valid values of the Present Value of the VibrationEvent Trait.
| Value | Name | Description |
|---|
| 0x00 | ThreeKnocks | Three knocks |
| 0x01 | Move | Movement |
| 0x02 | Vibrate | Vibration |
| 0x03 | Tilt | Tilt |
| 0x04 | FreeFall | Fall |
ObjectOrientationStateEnum8 Type
This enumeration defines the valid values of the Present Value of the ObjectOrientationState Trait.
| Value | Name | Description |
|---|
| 0x01 | HorizontalUp | Horizontal up |
| 0x02 | HorizontalDown | Horizontal down |
| 0x03 | Vertical | Vertical |
| 0x04 | Tilted | Tilted |
StationaryStateEnum8 Type
This enumeration defines the valid values of the Present Value of the StationaryState Trait.
| Value | Name | Description |
|---|
| 0x00 | InMotion | In motion |
| 0x01 | Stationary | Stationary |
Trait Definitions
VibrationEvent Trait
This Trait is used for access to and reporting of "vibration sticker event" data.
| Trait ID | Code |
|---|
| 0x80EF | VibrationEvent |
Parameters
FreeFallEnable Trait
Enables or disables the free fall detection function. When set to True, the device detects and reports fall events; when set to False, free fall detection is disabled.
| Trait ID | Code |
|---|
| 0x5194 | FreeFallEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
VibrationEnable Trait
Enables or disables the vibration detection function. When set to True, the device detects and reports vibration events; when set to False, vibration detection is disabled.
| Trait ID | Code |
|---|
| 0x5195 | VibrationEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ThreeKnocksEnable Trait
Enables or disables the three-knocks detection function. When set to True, the device detects and reports three-knock events; when set to False, three-knocks detection is disabled.
| Trait ID | Code |
|---|
| 0x5197 | ThreeKnocksEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ObjectOrientationEnable Trait
Enables or disables the object orientation monitoring function. When set to True, the device actively monitors and reports object orientation changes; when set to False, orientation monitoring is disabled.
| Trait ID | Code |
|---|
| 0x4F99 | ObjectOrientationEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
ObjectOrientationState Trait
Indicates the current spatial orientation of the object detected by the device. The value is an enumeration representing the object's posture relative to a reference plane; possible states are as follows:
1 - Horizontal Up (object facing up, e.g., lying flat on a table face up)
2 - Horizontal Down (object facing down, e.g., lying flat on a table face down)
3 - Vertical (object upright, e.g., perpendicular to the ground)
4 - Tilted (object tilted, not classified as horizontal or vertical)
| Trait ID | Code |
|---|
| 0x4F98 | ObjectOrientationState |
Parameters
EventReportInterval Trait
Indicates the time interval between consecutive event reports of the device, in seconds. For example, a value of 60 means the device reports an event every 60 seconds. This interval determines the frequency at which the device sends event data to the gateway or cloud.
| Trait ID | Code |
|---|
| 0x4F97 | EventReportInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 60 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 300 | R | O |
| 0x0003 | Minimum Value | uint32 | | 5 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 60 | RW | O |
ObjectMotionDetectionEnable Trait
Enables or disables the object motion detection function. True means enabled (object movement will be detected), False means disabled.
| Trait ID | Code |
|---|
| 0x4F96 | ObjectMotionDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
StationaryTiltAngle Trait
Indicates the tilt angle when the object is stationary after movement. Unit: deg.
| Trait ID | Code |
|---|
| 0x4F95 | StationaryTiltAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 180.0 | R | O |
| 0x0003 | Minimum Value | float | | -180.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
PeakTiltAngle Trait
Indicates the maximum tilt angle recorded from wake-up to stationary. Unit: deg.
| Trait ID | Code |
|---|
| 0x4F94 | PeakTiltAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 180.0 | R | O |
| 0x0003 | Minimum Value | float | | -180.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
TiltAngleDeviation Trait
Indicates the actual change (deviation) of the Tilt angle during the current movement.
| Trait ID | Code |
|---|
| 0x4F93 | TiltAngleDeviation |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 180.0 | R | O |
| 0x0003 | Minimum Value | float | | -180.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
InitialTiltAngle Trait
Indicates the initial tilt angle established during device calibration, representing the angle between the calibration direction (e.g., upward) and the nearest positive axis. Unit: deg.
| Trait ID | Code |
|---|
| 0x4F92 | InitialTiltAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 180.0 | R | O |
| 0x0003 | Minimum Value | float | | -180.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
StationaryState Trait
The current value of this feature should indicate, in enumeration form, whether the target is currently stationary. A value of 0 indicates the target is in motion, and a value of 1 indicates the target is stationary.
| Trait ID | Code |
|---|
| 0x4F8C | StationaryState |
Parameters
VibrationDuration Trait
Reports the actual duration (seconds) of vibration detected by the device. The reporting logic is as follows: when the vibration duration reaches the configured "Vibration Duration" threshold, a duration equal to the threshold is reported immediately. If the vibration continues beyond the threshold, no further duration reports are sent until the vibration stops and a "stationary event" is reported (usually a duration of 0 or a separate state). When a new vibration event starts, the timer resets and counts again, reporting once more when the threshold is reached.
| Trait ID | Code |
|---|
| 0x503B | VibrationDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
VibrationDurThreshold Trait
Sets the duration threshold (seconds) for the device to continuously monitor vibration events. When the vibration duration reaches this configured value, the device triggers a "Vibration Duration" event report. The current value range is 0 to 3600 seconds, with a default of 3600 seconds. It may be extended to 18 hours in the future.
| Trait ID | Code |
|---|
| 0x503A | VibrationDurThreshold |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 3600 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 3600 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 3600 | RW | O |
ObjectMotionDuration Trait
Reports the actual duration (seconds) of movement detected by the device. The reporting logic is similar to vibration: when the movement duration reaches the configured "Object Motion Duration" threshold, a duration equal to the threshold is reported immediately. If the movement continues beyond the threshold, no further duration reports are sent until the movement stops and a "stationary event" is reported. When a new movement event starts, the timer resets and counts again, reporting once more when the threshold is reached.
| Trait ID | Code |
|---|
| 0x5039 | ObjectMotionDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
ObjectMotionDurThreshold Trait
Sets the duration threshold (seconds) for the device to continuously monitor movement events. When the movement duration reaches this configured value, the device triggers a "Motion Duration" event report. The current value range is 0 to 3600 seconds, with a default of 3600 seconds. It may be extended to 18 hours in the future.
| Trait ID | Code |
|---|
| 0x5038 | ObjectMotionDurThreshold |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 3600 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 3600 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 3600 | RW | O |
Command Definitions
This Function does not contain Commands.
Modes
Introduction
Provides device multi-mode management capability, supporting switching and reading the current operating mode.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A5 | Modes | Modes |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x8168 | ModeCount | Mode count | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
ModeCount Trait
Describes the number of modes supported by the device. Format: int.
| Trait ID | Code |
|---|
| 0x8168 | ModeCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int32 | | 0 | RV | M |
| 0x0002 | Maximum Value | int32 | | 2147483647 | R | O |
| 0x0003 | Minimum Value | int32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain Commands.
PetFeeder
Introduction
Provides pet feeding control capability, including the number of portions dispensed, feeding schedule and remaining quantity state.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A6 | PetFeeder | Pet feeder |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x80F6 | Feed | Feed | M |
Command
This Function does not contain Commands.
Data Types
FeedEnum8 Type
This enumeration defines the valid values of the Present Value of the Feed Trait.
| Value | Name | Description |
|---|
| 0x01 | RemoteFeeding | Feed |
Trait Definitions
| Trait ID | Name | Conformance |
|---|
| 0x80F6 | Feed | M |
Feed Trait
This Trait is used for access to and reporting of "feed" data.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | FeedEnum8 | | 1 | RV | M |
| 0x0006 | Supported Value | list[FeedEnum8] | | | R | O |
Command Definitions
This Function does not contain Commands.
BridgeConfiguration
Introduction
Manages the gateway bridge configuration, describing sub-device access, bridging capability and network topology related information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A7 | BridgeConfiguration | Bridge configuration |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BridgedNodeList Trait
Represents the list of bridged node Device IDs added to this Bridge Node. String array.
| Trait ID | Code |
|---|
| 0x80FA | BridgedNodeList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
SupportedHubCapability Trait
This attribute reports, in bitmask form, the core functional features that the gateway possesses as a smart home hub. Each bit represents a specific capability (such as local automation, data storage, AI support). Upper-layer applications use this to discover and adapt to advanced device functions, enabling differentiated experiences.
bit 0: Supports gateway basic functions (supports creating gateway clusters, etc.)
bit 1: Has the local automation module ha_driven
bit 2: Supports gateway local data storage function NAS
bit 3: Supports SAAS
bit 4: Supports local AI
bit 5: Supports LAN App control
bit 6: Supports running Aqara Studio
bit 7: Supports bridging camera devices
bit 8: Supports Aqara Studio logic function blocks
bit 9 to 31: Reserved
| Trait ID | Code |
|---|
| 0x4F55 | SupportedHubCapability |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MatterBridgeCapability Trait
This Trait is used to identify the capability role of the device in the Matter bridge scenario. It uses a bitmask (Bitmap) form, where each bit represents a specific bridging or bridgeable capability.
| Trait ID | Code |
|---|
| 0x516B | MatterBridgeCapability |
Bit Definitions
| Bit | Name | Description |
|---|
| 0 | BridgeSubDevices | Supports bridging sub-devices to the Matter network (as a general Bridge). |
| 1 | BridgeCameraDevices | Supports bridging sub-devices with Camera functionality to the Matter network. |
| 2 | CameraBridgeable | The device itself has Camera functionality and can be bridged by devices with Bit1 capability. |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain Commands.
AttitudeDetection
Introduction
Detects changes in device posture or tilt angle, reporting posture anomalies or angle information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A8 | AttitudeDetection | Attitude detection |
Trait
Command
This Function does not contain Commands.
Data Types
AttitudeDetectedEnum8 Type
This enumeration defines the valid values of the Present Value of the AttitudeDetected Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | FallDown | Fall |
| 0x02 | SuspectedFall | Suspected fall |
Trait Definitions
AttitudeDetected Trait
This Trait is used for access to and reporting of "attitude detection" data.
| Trait ID | Code |
|---|
| 0x80FB | AttitudeDetected |
Parameters
Command Definitions
This Function does not contain Commands.
Group
Introduction
Manages device group configuration, maintaining the node list within the group and group-level control capability.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00A9 | Group | Group configuration |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x80FC | NodeList | Node list | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
NodeList Trait
This Trait is used for access to and reporting of "node list" data.
| Trait ID | Code |
|---|
| 0x80FC | NodeList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
Command Definitions
This Function does not contain Commands.
Doorbell
Introduction
Provides doorbell-related capabilities, including call event reporting and linkage with the indoor chime/relay.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00AA | Doorbell | Doorbell |
Trait
Command
Data Types
This enumeration defines the valid values of the Present Value of the ButtonEvent Trait.
| Value | Name | Description |
|---|
| 0x00 | SinglePress | Single click |
| 0x01 | DoublePress | Double click |
| 0x02 | LongPress | Long press |
| 0x03 | LongPressRelease | Long press release |
DoorbellRepeaterConnectionStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the DoorbellRepeaterConnectionStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Disconnected | Disconnected |
| 0x01 | Connected | Normal |
DoorbellRingCountEnum8 Type
This enumeration defines the valid values of the Present Value of the DoorbellRingCount Trait.
| Value | Name | Description |
|---|
| 0x01 | RingOnce | 1 time |
| 0x02 | RingTwice | 2 times |
TriggerDoorbellWake Command Structure Type
Parameter structure of the TriggerDoorbellWake Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Wake | uint32 | M | Wake; default value is 1. |
Trait Definitions
This Trait is used for access to and reporting of "button event" data.
| Trait ID | Code |
|---|
| 0x80A0 | ButtonEvent |
Parameters
Volume Trait
Indicates or sets the speaker volume of the camera device (e.g., two-way audio). The value is usually a percentage (0 to 100) or a device-defined numeric range.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
DoorbellRepeaterConnectionStatus Trait
Represents the connection status between the doorbell and the repeater (e.g., indoor chime).
| Trait ID | Code |
|---|
| 0x50E1 | DoorbellRepeaterConnectionStatus |
Parameters
DoorbellCallRecvEnable Trait
Receive doorbell call enable. When enabled, the App displays the call page when someone rings the doorbell. 0 = Off, 1 = On.
| Trait ID | Code |
|---|
| 0x517F | DoorbellCallRecvEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
DoorbellRingCount Trait
Doorbell ring count. 1 = 1 time, 2 = 2 times.
| Trait ID | Code |
|---|
| 0x5184 | DoorbellRingCount |
Parameters
OutdoorBellVolume Trait
Outdoor doorbell volume. Represents the volume level of the outdoor doorbell, ranging from 0-100 (percentage). This Trait is readable, writable and reportable, and is used to adjust and obtain the current volume of the outdoor doorbell.
| Trait ID | Code |
|---|
| 0x518C | OutdoorBellVolume |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
Command Definitions
TriggerDoorbellWake Command
This command wakes the doorbell device to improve streaming or response speed. The value 1 should be written to this command to wake the device.
Parameters
TriggerDoorbellWake Command Structure
NetworkCommissioning
Introduction
Provides network commissioning capability, supporting scanning, connection and configuration of Wi-Fi, Thread, Zigbee, Ethernet, BLE Endpoint and Wi-Fi Endpoint. The Magic Pair provisioning flow is described in ref_MagicPairNetworkCommissioning.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00AB | NetworkCommissioning | Network commissioning |
Trait
Command
Data Types
AuthenticationStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the AuthenticationStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | NotAuthenticated | Not authenticated |
| 0x01 | CertifiedAndValid | Authenticated and valid |
| 0x02 | NoCertificate | No certificate |
| 0x03 | CertificateInvalid | Has certificate but invalid |
HomeStationCredentialsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the HomeStationCredentials Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SSID | characterString | M | Home station SSID. |
| 1 | Credentials | characterString | M | Home station connection credential. |
ZigbeeDiagnosticsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ZigbeeDiagnostics Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Channel | uint8 | M | Zigbee radio channel. |
| 1 | ExtendedPANID | uint64 | M | Zigbee extended PAN identifier. |
| 2 | NetworkKey | octetString | M | Zigbee network key. |
| 3 | NetworkName | characterString | M | Zigbee network name. |
| 4 | PANID | uint16 | M | Zigbee PAN identifier. |
| 5 | RSSI | int8 | O | RSSI for the Zigbee network client in dBm. |
| 6 | LQI | uint8 | O | Link quality indicator. |
ThreadDiagnosticsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ThreadDiagnostics Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Channel | uint8 | M | The Thread network radio channel. |
| 1 | ExtendedPANID | uint64 | M | The Thread network extended PAN identifier. |
| 2 | NetworkKey | octetString | M | The Thread network key. |
| 3 | NetworkName | characterString | M | The Thread network name. |
| 4 | PANID | uint16 | M | The Thread network PAN identifier. |
| 5 | PSKc | octetString | M | The Thread network pre-shared key for the Commissioner. |
| 6 | ActiveTimeStamp | uint64 | M | Active timestamp. |
| 7 | SecurityPolicy | characterString | O | Security policy. |
| 8 | OperationalDataset | octetString | M | Thread Network Parameters dataset. |
| 9 | RSSI | int8 | O | RSSI for the Thread network client in dBm. |
| 10 | LQI | uint8 | O | Link quality indicator. |
| 11 | BorderAgentID | octetString | M | Identifier of an active Thread network Border Agent. |
| 12 | MeshLocalPrefix | characterString | O | Prefix of all interfaces reachable within the same Thread network. |
| 13 | CommissionerCredential | characterString | O | UTF-8 Commissioner Credential, 6 to 255 characters. |
| 14 | Version | characterString | O | OpenThread Version. |
| 15 | Role | uint8 | O | Thread Role bit mask. |
| 16 | BorderExtAgentID | characterString | M | Thread Border Agent ID. |
WiFiDiagnosticsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the WiFiDiagnostics Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | BSSID | characterString | M | The Wi-Fi BSSID. |
| 1 | Encryption | uint8 | O | 0: No Encryption;1: WEP;2: WPA;3: WPA/WPA2;4: WPA2;5: WPA3. |
| 2 | Version | uint8 | O | The Wi-Fi Version:0:a,1:b,2:g,3:n,4:ac,5:ax. |
| 3 | Channel | uint8 | M | The Wi-Fi network Channel. |
| 4 | RSSI | int8 | M | RSSI for the WiFi network client in dBm. |
| 5 | NetworkName | characterString | M | The Wi-Fi network name. |
| 6 | IPV4Address | characterString | O | IPV4 Address. |
| 7 | IPV6Address | characterString | O | IPV6 Address. |
| 8 | SubnetMask | characterString | O | Subnet mask. |
| 9 | Gateway | characterString | O | Gateway address. |
| 10 | DNS | characterString | O | DNS server. |
| 11 | AlternateDNS | characterString | O | Backup DNS server. |
EthernetDiagnosticsTraitPresentValueStructure Type
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | IsReady | boolean | M | Whether the Ethernet cable is plugged in |
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Mac | uint64 | M | The device's 64-bit Zigbee IEEE MAC address |
| 1 | InstallCode | characterString | O | Install Code; mandatory during the Magic Pair phase and optional in other scenarios |
| 2 | FirmwareVersion | uint32 | O | Device firmware version number |
| 3 | HardwareVersion | uint32 | O | Device hardware version number |
| 4 | ManufacturerCode | uint16 | O | Zigbee manufacturer code |
| 5 | Model | characterString | O | Device model |
| 6 | ShortAddr | uint16 | O | The short address of the device in the Zigbee network. |
| 7 | ZigbeeVersion | uint8 | O | Zigbee protocol version |
| 8 | DeviceType | uint8 | O | Zigbee device type |
| 9 | ExtendedXCode | uint16 | O | Extended X code; the specific meaning depends on the product Profile definition |
| 10 | LastResetType | uint8 | O | 0 Invalid; 1 Factory Reset; 2 Network Reset |
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EncryptionType | uint8 | M | 0 Tuple;1 Certificate |
| 1 | ProtocolPrefix | uint8 | M | Cloud ID prefix enumeration, see Trait definition |
| 2 | UniqueId | octetString | M | 64-bit Unique ID |
| 3 | Mac | octetString | C | Mandatory in Tuple mode |
| 4 | Token | octetString | C | Certificate mode |
| 5 | CloudId | characterString | O | |
| 6 | LastResetType | uint8 | O | |
TimeSynchronizationTraitPresentValueStructure Type
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | UTCTime | uint32 | M | Unix Epoch seconds |
| 1 | TimeZoneOffset | int32 | M | Second offset relative to UTC |
| 2 | TimeZoneName | characterString | O | IANA time zone name |
LocalizationConfigurationTraitPresentValueStructure Type
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | VoiceLanguage | characterString | O | BCP 47 |
| 1 | ScreenLanguage | characterString | O | BCP 47 |
| 2 | TemperatureUnit | uint8 | O | 0 Celsius; 1 Fahrenheit |
| 3 | CountryCode | characterString | O | ISO 3166-1 alpha-2 |
ScanWiFiNetworksResponse Command Structure Type
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SSID | characterString | M | |
| 1 | RSSI | int8 | M | |
| 2 | Encryption | uint8 | M | |
| 3 | BSSID | characterString | O | |
| 4 | Channel | uint16 | O | |
| 5 | WiFiBand | uint8 | O | 0 2.4 GHz;1 3.6 GHz;2 5 GHz;3 6 GHz;4 60 GHz |
ChildDeviceProvisioningStateEnum8 Type
This enumeration defines the valid values of the Present Value of the ChildDeviceProvisioningState Trait.
| Value | Name | Description |
|---|
| 0x00 | NotProvisioning | Not in provisioning state |
| 0x01 | Provisioning | In provisioning state |
This enumeration defines the valid values of the Action field of the TriggerWifiRssiUpdate Command.
| Value | Name | Description |
|---|
| 0x01 | Update | Update |
TriggerWifiRssiUpdate Command Structure Type
Parameter structure of the TriggerWifiRssiUpdate Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Action | TriggerWifiRssiUpdateActionEnum8 | M | Action to perform, taking the value 0x01 (Update), meaning to immediately update and report the current Wi-Fi RSSI. |
TriggerZigbeeNetworkInfoUpload Command Structure Type
Parameter structure of the TriggerZigbeeNetworkInfoUpload Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | InstallCode | characterString | M | Installation code. |
| 1 | MAC | characterString | M | MAC address. |
ConnectToHomeStationResponse Command Structure Type
Parameter structure of the ConnectToHomeStationResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ConnectToHomeStationResponse | enum8 | M | Home station connection feedback. |
ConnectToHomeStation Command Structure Type
Parameter structure of the ConnectToHomeStation Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SSID | characterString | M | SSID. |
| 1 | Credentials | characterString | M | Credential. |
| 2 | Type | uint8 | M | 0 Full-function Home Station; 1 Restricted-function Home Station |
| 3 | RelayKey | characterString | M | Relay credential generated by the Home Station, max 64 bytes |
| 4 | RelayPort | uint16 | M | Relay port, value provided by the Home Station |
| 5 | CloudIdOfStation | characterString | M | Cloud ID of the Home Station |
| 6 | AlivePort | uint16 | O | Keep-alive port |
| 7 | CountryDomain | characterString | O | Max 64 bytes |
| 8 | Bindkey | characterString | O | Max 64 bytes |
| 9 | TimeZone | characterString | O | Max 32 bytes |
| 10 | CountryCode | characterString | O | ISO 3166-1 alpha-2 |
ConfigStaticIPAddr Command Structure Type
Parameter structure of the ConfigStaticIPAddr Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | IPAddress | characterString | O | IP address, string (max length 32). Example: 192.168.1.100. |
| 1 | SubnetMask | characterString | O | Subnet mask, string (max length 32). Example: 255.255.255.0. |
| 2 | DefaultGateway | characterString | O | Default gateway, string (max length 32). Example: 192.168.1.1. |
| 3 | PrimaryDNS | characterString | O | Primary DNS, string (max length 32). Example: 8.8.8.8. |
| 4 | SecondaryDNS | characterString | O | Secondary DNS, string (max length 32). Example: 8.8.4.4. |
| 5 | InterfaceName | characterString | O | Interface name, string (max length 32). Example: eth0. When empty, it applies to all network interfaces. |
| 6 | AddressingMode | enum8 | O | Address assignment mode. 0 switches to DHCP for obtaining the IP (the IPAddress, SubnetMask, PrimaryDNS, DefaultGateway and SecondaryDNS parameters are ignored); 1 is static IP mode (the network parameters above can be configured). If this field is absent, static IP mode is used by default. |
Parameter structure of the ConfigureWiFiNetwork Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | InterfaceName | characterString | M | Network interface name, used to specify on which network interface to perform provisioning (should match the interface identifier in the device system). Example: wlan0 (2.4G Wi-Fi STA), wlan1 (5G Wi-Fi STA). |
| 1 | SSID | characterString | M | Target Wi-Fi network name (case-sensitive, recommended to exactly match the AP broadcast name). Example: Home_2.4G, Office-WiFi. |
| 2 | Credentials | characterString | M | Target Wi-Fi network access password (plaintext content should satisfy the device security policy). Example: Home@2026!, MyHome#12345. |
AddOrUpdateZigbeeNetworkResponse Command Structure Type
Parameter structure of the AddOrUpdateZigbeeNetworkResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StatusCodes | uint8 | M | |
AddOrUpdateZigbeeNetwork Command Structure Type
Parameter structure of the AddOrUpdateZigbeeNetwork Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Channel | uint8 | M | |
| 1 | ExtendedPANID | octetString | M | |
| 2 | NetworkKey | octetString | M | |
| 3 | NetworkName | characterString | O | |
| 4 | PANID | uint16 | M | |
| 5 | NetworkKeySequenceNumber | uint8 | M | Zigbee Network Key Sequence Number |
| 6 | TrustCenterAddress | characterString | M | Trust Center address |
AddOrUpdateThreadNetworkResponse Command Structure Type
Parameter structure of the AddOrUpdateThreadNetworkResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StatusCodes | uint8 | M | |
AddOrUpdateThreadNetwork Command Structure Type
Parameter structure of the AddOrUpdateThreadNetwork Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | OperationalDataset | octetString | O | Complete Thread Operational Dataset. When omitted or Null, the device creates a new network |
AddOrUpdateWiFiNetworkResponse Command Structure Type
Parameter structure of the AddOrUpdateWiFiNetworkResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StatusCodes | uint8 | M | |
AddOrUpdateWiFiNetwork Command Structure Type
Parameter structure of the AddOrUpdateWiFiNetwork Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SSID | characterString | O | |
| 1 | Credentials | characterString | O | |
| 2 | Encryption | uint8 | O | |
| 3 | CountryDomain | characterString | O | |
| 4 | Bindkey | characterString | O | |
| 5 | TimeZone | characterString | O | |
| 6 | CountryCode | characterString | O | ISO 3166-1 alpha-2 |
| 7 | Ecosystem | uint8 | O | 0 Aqara AIoT;1 Aqara Studio |
| 8 | ServerPort | uint16 | O | Cloud listening port |
VerifyDeviceAuthenticity Command Structure Type
Parameter structure of the VerifyDeviceAuthenticity Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Cmd | uint8 | M | 0 SendRandomCode;1 GetCertificateFile;2 ValidationPassed;3 ValidationFailed;4 WriteCloudId;5 Registered;6 RegisterFailed;7 SendSelfSignedCertificate;8 RefreshToken;9 WriteUserId;10 SendRandomCodeOfCertificate |
| 1 | Params | characterString | O | Varies with Cmd: random number, certificate, Cloud ID, Token or UserID; must not be treated as a fixed schema |
VerifyDeviceAuthenticityResponse Command Structure Type
Parameter structure of the VerifyDeviceAuthenticityResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Cmd | uint8 | M | |
| 1 | Params | characterString | O | |
SetZigbeeChannel Command Structure Type
Parameter structure of the SetZigbeeChannel Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Channel | uint8 | M | Channel; default value is 11. |
SetThreadChannel Command Structure Type
Parameter structure of the SetThreadChannel Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Channel | uint8 | M | Channel; default value is 11. |
Trait Definitions
SupportedNetwork Trait
Indicates the network protocols supported by the device for provisioning (MagicPair). The value is a bitmask: bit0=Wi-Fi, bit1=Thread, bit2=Ethernet, bit3=Zigbee, bit4=BLE, bit5=BLE Endpoint, bit6=Wi-Fi Endpoint, bit7=Wi-Fi Endpoint of the Limited Home Station, bit8=Aqara RS485. The BLE used for pairing is not included.
| Trait ID | Code |
|---|
| 0x8103 | SupportedNetwork |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | R | M |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MagicPairKeychain Trait
Used for the MagicPair network commissioning key chain.
| Trait ID | Code |
|---|
| 0x4F54 | MagicPairKeychain |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
SlaveAddress Trait
The address assigned to the device as a slave on the bus, used for master-slave communication addressing.
| Trait ID | Code |
|---|
| 0x4ECD | SlaveAddress |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | O | 255 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | O | 255 | RW | O |
AuthenticationStatus Trait
Indicates the device authentication status, reflecting whether it has passed authentication and whether the certificate is valid.
| Trait ID | Code |
|---|
| 0x4ECC | AuthenticationStatus |
Parameters
A metric that measures the Wi-Fi connection signal strength, in dBm, ranging from -100 dBm (very weak) to 0 dBm (strongest).
| Trait ID | Code |
|---|
| 0x4E97 | WiFiRSSI |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int8 | | 0 | RV | O |
| 0x0002 | Maximum Value | int8 | | 0 | R | O |
| 0x0003 | Minimum Value | int8 | | -100 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
WiFiChannel Trait
Wi-Fi channel, such as channels 1-14 in the 2.4GHz band or channels 149, 153, 157, 161, 165 in the 5GHz band, etc.
| Trait ID | Code |
|---|
| 0x4E96 | WiFiChannel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 165 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ZigbeeAuthRandcodeResponse Trait
The Confirm result returned when a Zigbee 3.0 device authenticates with the cloud.
| Trait ID | Code |
|---|
| 0x4E95 | ZigbeeAuthRandcodeResponse |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | V | O |
ZigbeeAuthRandcode Trait
The random number issued by the cloud when a Zigbee 3.0 device connects to the cloud for authentication.
| Trait ID | Code |
|---|
| 0x4E94 | ZigbeeAuthRandcode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | W | O |
HomeStationCredentials Trait
Home Station Credentials information
| Trait ID | Code |
|---|
| 0x4E73 | HomeStationCredentials |
Parameters
ZigbeeDiagnostics Trait
Provides diagnostic information about the Zigbee network. This includes the radio channel, extended PAN ID, network name, PAN ID, RSSI (if available) and LQI. NetworkKey belongs to the commissioning-secret: it MAY be used for provisioning in the Magic Pair secure session; CoIP normal Read/Report SHALL NOT read back this field, see ref_MagicPairModelMapping.
| Trait ID | Code |
|---|
| 0x8106 | ZigbeeDiagnostics |
Parameters
ThreadDiagnostics Trait
Provides diagnostic information about the Thread network. This includes the channel, extended PAN ID, network name, PAN ID, active timestamp, security policy, RSSI, LQI, border agent ID, mesh local prefix, OpenThread version and role. NetworkKey, PSKc, OperationalDataset and commissioner credentials belong to the commissioning-secret: they MAY be used for provisioning in the Magic Pair secure session; CoIP normal Read/Report SHALL NOT read back these fields.
| Trait ID | Code |
|---|
| 0x8105 | ThreadDiagnostics |
Parameters
WiFiDiagnostics Trait
Provides diagnostic information about the Wi-Fi network. This includes BSSID, encryption type, Wi-Fi version, channel, RSSI, network name, IPv4 address, IPv6 address, subnet mask, gateway, DNS and backup DNS (fields vary by availability).
| Trait ID | Code |
|---|
| 0x8104 | WiFiDiagnostics |
Parameters
EthernetDiagnostics Trait
Whether the Ethernet cable is plugged into the Ethernet port.
| Trait ID | Code |
|---|
| 0x811F | EthernetDiagnostics |
Parameters
Zigbee device identity and installation information. InstallCode belongs to the commissioning-secret and SHALL NOT be read back through normal diagnostic interfaces.
| Trait ID | Code |
|---|
| 0x8121 | ZigbeeDeviceInformation |
Parameters
LANStatus Trait
Device LAN connection status. 0 not connected; 1 connected.
| Trait ID | Code |
|---|
| 0x8122 | LANStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
Used for cloud registration starting from Magic Pair Version 20. ProtocolPrefix: 0 lumi; 1 lumi1; 2 lumi2; 3 O; 4 aqara; 5 matt; 6 lumi3; 7 lumi4.
| Trait ID | Code |
|---|
| 0x8145 | RegistrationInformation |
Parameters
TimeSynchronization Trait
The App writes the UTC time and time zone to the device in the pre-provisioning phase, for certificate validity verification.
| Trait ID | Code |
|---|
| 0x815A | TimeSynchronization |
Parameters
LocalizationConfiguration Trait
Voice/interface language, temperature unit and country code. The country code can be used for wireless compliance restrictions.
| Trait ID | Code |
|---|
| 0x8174 | LocalizationConfiguration |
Parameters
ChildDeviceProvisioningState Trait
Used by the gateway to report the provisioning window state for sub-devices (such as Zigbee devices, Matter devices, etc.). When the gateway opens the network for a certain type of sub-device, it reports "entering provisioning state"; when it closes the provisioning window for that type of sub-device, it reports "exiting provisioning state". Upper-layer applications use this to perceive in real time whether the gateway is in a state that allows adding a certain type of sub-device, to guide user operations or display provisioning progress.
| Trait ID | Code |
|---|
| 0x4FA6 | ChildDeviceProvisioningState |
Parameters
Command Definitions
Triggers a Wi-Fi signal strength update. When the device receives this command with Action set to 0x01 (Update), it should immediately update the current Wi-Fi signal strength (RSSI) and report the latest value through the Present Value of the WiFiRSSI Trait, in dBm.
On the signal test page of the device installation guide, the client or App can send this command every few seconds to trigger the device to report the latest Wi-Fi RSSI, allowing a timely determination of whether the signal at the current location is good. Periodic sending is controlled by the client or App, with each command triggering one update and report.
Parameters
TriggerWifiRssiUpdate Command Structure
TriggerZigbeeNetworkInfoUpload Command
Triggers the gateway to report Zigbee network information for subsequent operations, for example, enabling fast pairing of Zigbee devices based on the Zigbee network information.
Parameters
TriggerZigbeeNetworkInfoUpload Command Structure
ConnectToHomeStationResponse Command
Home station connection feedback
Parameters
ConnectToHomeStationResponse Command Structure
ConnectToHomeStation Command
Represents the command for a WiFi Endpoint to connect to the Home Station.
Parameters
ConnectToHomeStation Command Structure
ConfigStaticIPAddr Command
The ConfigStaticIPAddr Command represents configuring the device network address information. The optional parameter AddressingMode: when set to 0, switches to DHCP for obtaining the IP (ignoring IPAddress, SubnetMask, PrimaryDNS, DefaultGateway and SecondaryDNS); when set to 1, switches to static IP mode and applies the above parameters; if this field is absent, static IP mode is used by default. The optional parameter InterfaceName (example: eth0) specifies the target interface; when not passed, it applies to all network interfaces.
Parameters
ConfigStaticIPAddr Command Structure
This command is used to configure and connect to a Wi-Fi network on the specified network interface.
Parameters
ConfigureWiFiNetwork Command Structure
AddOrUpdateZigbeeNetworkResponse Command
This Command is used to perform the "add or update Zigbee network feedback" operation.
Parameters
AddOrUpdateZigbeeNetworkResponse Command Structure
AddOrUpdateZigbeeNetwork Command
This Command is used to perform the "add or update Zigbee network command" operation.
Parameters
AddOrUpdateZigbeeNetwork Command Structure
AddOrUpdateThreadNetworkResponse Command
This Command is used to perform the "add or update Thread network command feedback" operation.
Parameters
AddOrUpdateThreadNetworkResponse Command Structure
AddOrUpdateThreadNetwork Command
This Command is used to perform the "add or update Thread network command" operation. When OperationalDataset is omitted or Null, the device SHALL create a new Thread network.
Parameters
AddOrUpdateThreadNetwork Command Structure
AddOrUpdateWiFiNetworkResponse Command
This Command is used to perform the "add or update WiFi network command feedback" operation.
Parameters
AddOrUpdateWiFiNetworkResponse Command Structure
AddOrUpdateWiFiNetwork Command
This Command is used to perform the "add or update WiFi network command" operation.
Parameters
AddOrUpdateWiFiNetwork Command Structure
ScanWiFiNetworksResponse Command
This Command is used to return the list of nearby Wi-Fi hotspots. payload is an array of ScanWiFiNetworksResponse Command Structure.
Parameters
ScanWiFiNetworksResponse Command Structure
ScanWiFiNetworks Command
This Command is used to perform the "scan WiFi network command" operation.
This Command has no parameters.
VerifyDeviceAuthenticity Command
This Command is used to perform the "verify device authenticity" operation. Cmd values: 0 SendRandomCode; 1 GetCertificateFile; 2 ValidationPassed; 3 ValidationFailed; 4 WriteCloudId; 5 Registered; 6 RegisterFailed; 7 SendSelfSignedCertificate; 8 RefreshToken; 9 WriteUserId; 10 SendRandomCodeOfCertificate. See the flow in ref_MagicPairNetworkCommissioning.
Parameters
VerifyDeviceAuthenticity Command Structure
VerifyDeviceAuthenticityResponse Command
This Command is used to perform the "verify device authenticity response" operation.
Parameters
VerifyDeviceAuthenticityResponse Command Structure
SetZigbeeChannel Command
This command changes the Zigbee communication channel on the device (such as a gateway or coordinator). Channel values are typically 11 to 26 (2.4 GHz band). After execution, the device may need to restart the Zigbee protocol stack or perform network reconfiguration.
Parameters
SetZigbeeChannel Command Structure
SetThreadChannel Command
This command changes the Thread communication channel on the device. Channel values are typically 11 to 26 (2.4 GHz band). After execution, the device may need to restart the Thread protocol stack or perform network reconfiguration.
Parameters
SetThreadChannel Command Structure
Introduction
Describes the ecosystem platform information that the device is connected to, such as HomeKit, Matter Fabric binding states, etc.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00AC | EcosystemInformation | Ecosystem platform information |
Trait
Command
Data Types
MatterPayloadTraitPresentValueStructure Type
This structure defines the Present Value field layout of the MatterPayload Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | QRCode | characterString | M | Raw string data of the pairing QR code. |
| 1 | DigitalPairingCode | characterString | M | 11 or 21 digit numeric pairing code. |
HomeKitPayloadTraitPresentValueStructure Type
This structure defines the Present Value field layout of the HomeKitPayload Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | QRCode | characterString | M | Raw string data of the pairing QR code. |
| 1 | DigitalPairingCode | characterString | M | 8 digit numeric pairing code. |
MagicPairPayloadTraitPresentValueStructure Type
This structure defines the Present Value field layout of the MagicPairPayload Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | QRCode | characterString | M | Raw string data of the pairing QR code. |
| 1 | DigitalPairingCode | characterString | M | 8 digit numeric pairing code. |
StudioStatusSyncTraitPresentValueStructure Type
This structure defines the Present Value field layout of the StudioStatusSync Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Status | enum8 | M | Current key status enumeration value of Studio, used to identify sync events (such as first login). |
SysControl Command Structure Type
Parameter structure of the SysControl Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Cmd | uint8 | M | Cmd. |
| 1 | Params | characterString | O | Params. |
EnterHomeKitPairingMode Command Structure Type
Parameter structure of the EnterHomeKitPairingMode Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Action | enum8 | M | Action; default value is 1. |
Trait Definitions
SupportedEcosystem Trait
Indicates the ecosystems supported by the device (e.g., Aqara Hub M3 supports Aqara Home, Apple HomeKit and Matter). The value is a bitmask: bit0 = Aqara Home, bit1 = Apple HomeKit, bit2 = Matter, bit3 = Aqara Studio, bit4-7 reserved.
| Trait ID | Code |
|---|
| 0x810F | SupportedEcosystem |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | R | M |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MatterPayload Trait
Provides the pairing information required for Matter commissioning. The value is a structure containing: QRCode (raw string of the pairing QR code) and DigitalPairingCode (11 or 21 digit numeric pairing code). When the device is not bound, reading this payload may activate the Matter commissioning window for a period (10 minutes by default).
| Trait ID | Code |
|---|
| 0x8113 | MatterPayload |
Parameters
HomeKitPayload Trait
Provides the pairing information required for HomeKit commissioning. The value is a structure containing: QRCode (raw string of the pairing QR code) and DigitalPairingCode (8 digit numeric pairing code). When the device is not bound, reading this payload may activate the HomeKit commissioning window for a period (10 minutes by default).
| Trait ID | Code |
|---|
| 0x8112 | HomeKitPayload |
Parameters
MagicPairPayload Trait
Provides the pairing information required for MagicPair provisioning. The value is a structure containing: QRCode (raw string of the pairing QR code) and DigitalPairingCode (8 digit numeric pairing code). When the device is not bound, reading this payload may activate the MagicPair commissioning window for a period (10 minutes by default).
| Trait ID | Code |
|---|
| 0x8111 | MagicPairPayload |
Parameters
BoundEcosystem Trait
Indicates the ecosystems bound to the device. The value is a bitmask: bit0 = Aqara Home, bit1 = Apple HomeKit, bit2 = Matter, bit3 = Aqara Studio, bit4-7 reserved (should be 0). For example, a value of 0x03 indicates that both Aqara Home and HomeKit are bound.
| Trait ID | Code |
|---|
| 0x8110 | BoundEcosystem |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | R | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
StudioStatusSync Trait
Studio notifies other endpoints (gateway, devices, cloud, etc.) of its current key status. This structure contains a single status enumeration value, used to identify specific sync events (such as first login).
| Trait ID | Code |
|---|
| 0x50C4 | StudioStatusSync |
Parameters
Command Definitions
SysControl Command
This Command is used to perform system control operations. Cmd values:
| Cmd | Name | Description |
|---|
| 0 | FactoryReset | Erase all local user and network data |
| 1 | Reset | Soft reset without deleting data |
| 2 | Restart | Reboot |
| 3 | RemoveHomeKitPairing | Remove HomeKit binding and report the updated BoundEcosystem |
| 4 | RemoveMatterPairing | Remove all Matter Fabrics |
| 5 | OpenHomeKitCommissioningWindow | Open the HomeKit window, 10 minutes by default |
| 6 | OpenMatterCommissioningWindow | Open the Matter window, 10 minutes by default |
| 7 | RemoveSelectedMatterPairing | Remove the Fabric with the Vendor ID specified in Params |
| 8 | WriteAqaraUserId | Write the Aqara account User ID; Params is a string, max 128 bytes. Writing UserID during BLE Endpoint provisioning uses VerifyDeviceAuthenticity Cmd 9, not this Cmd |
Params appears only when the Cmd requires additional data and must not be narrowed to a fixed string unrelated to the Cmd. The key clearing rules for factory reset, unbinding and protocol switching are described in ref_MagicPairSecurity and ref_MagicPairStateMachine.
Parameters
SysControl Command Structure
EnterHomeKitPairingMode Command
This command instructs the device to enter HomeKit pairing mode so that it can be discovered and paired with Apple HomeKit. When action is set to ENTER, the device starts broadcasting as a HomeKit accessory and responding to pairing requests. The command includes an action enumeration field: NO_ACTION (0) does nothing, ENTER (1) triggers the device to enter HomeKit pairing mode.
Parameters
EnterHomeKitPairingMode Command Structure
MatterCommissioning
Introduction
Provides Matter commissioning and Fabric management capability, including the commissioning window, Fabric list and node identification. For two-in-one code devices, the Discriminator, Passcode and Vendor ID SHALL be consistent with this Function and the Matter QR; the Product ID is the same on single-firmware two-in-one code devices and different on dual-firmware two-in-one code devices, see ref_MatterMagicPairUnifiedTypes. The default timeout for opening the window is 10 minutes, and it can also be triggered by SysControl Cmd 6.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00AD | MatterCommissioning | Matter commissioning |
Trait
Command
Data Types
ConnectedMatterFabricsTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ConnectedMatterFabrics Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | VendorID | uint16 | M | Matter Vendor ID. |
| 1 | FabricID | uint64 | M | Fabric ID. |
| 2 | ManufacturerLabel | characterString | O | Manufacturer Label. |
| 3 | NodeID | uint64 | M | Node ID. |
MatterFabricsOperationTraitPresentValueStructure Type
This structure defines the Present Value field layout of the MatterFabricsOperation Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Fabric ID | uint32 | M | Fabric ID. |
| 1 | Vendor ID | uint32 | M | Vendor ID. |
RemoveMatterFabric Command Structure Type
Parameter structure of the RemoveMatterFabric Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Fabric ID | uint32 | M | Fabric ID. |
| 1 | Vendor ID | uint32 | M | Vendor ID. |
OpenMatterCommissioningWindow Command Structure Type
Parameter structure of the OpenMatterCommissioningWindow Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Commissioning Timeout | uint16 | M | Pairing time. |
| 1 | PAKE Passcode Verifier | characterString | M | Password verifier. |
| 2 | Discriminator | uint16 | M | Discriminator. |
| 3 | Iterations | uint32 | M | Iteration. |
| 4 | Salt | characterString | M | Salt. |
Trait Definitions
MatterNodeId Trait
Represents the Matter device ID. Format: Uint64.
| Trait ID | Code |
|---|
| 0x8142 | MatterNodeId |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MatterCommissioningWindowStatus Trait
Represents the current status of the Matter device commissioning window. Values: 0 = WindowNotOpen, 1 = EnhancedWindowOpen, 2 = BasicWindowOpen.
| Trait ID | Code |
|---|
| 0x8124 | MatterCommissioningWindowStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ConnectedMatterFabrics Trait
Represents the list of connected Matter ecosystem fabrics. Each fabric contains Vendor ID, Fabric ID, Manufacturer Label, Node ID.
| Trait ID | Code |
|---|
| 0x8123 | ConnectedMatterFabrics |
Parameters
MatterFabricsOperation Trait
This Trait is used for access to and reporting of "Matter ecosystem operations" data.
| Trait ID | Code |
|---|
| 0x4FA0 | MatterFabricsOperation |
Parameters
Command Definitions
RemoveMatterFabric Command
This Command is used to perform the "remove Matter device from the specified Fabric" operation.
Parameters
RemoveMatterFabric Command Structure
OpenMatterCommissioningWindow Command
This Command is used to perform the "open Matter device commissioning window" operation.
Parameters
OpenMatterCommissioningWindow Command Structure
IndicationLight
Introduction
Manages device indicator light behavior, including status indication, brightness, color and blinking patterns.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00AE | IndicationLight | Indicator light |
Trait
Command
Data Types
DNDTimePeriodTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DNDTimePeriod Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | BeginTime | characterString | M | Do Not Disturb mode start time, crontab format, default value is 0 21 *. |
| 1 | EndTime | characterString | M | Do Not Disturb mode end time, crontab format, default value is 0 9 *; if earlier than BeginTime, it means the time of the next day. |
IndicationLightSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the IndicationLightSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | NeverUse | Never used |
| 0x01 | Use | Used |
Trait Definitions
ChildEndpointList Trait
This attribute should report the child endpoints currently assigned in the configured partitions of the device.
| Trait ID | Code |
|---|
| 0x4F33 | ChildEndpointList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
EnableInvertIndicationLight Trait
This configuration enables or disables the inversion function of the indicator light state, corresponding to the EnableIndicationLightInversion attribute of the Aqara Indicator Light Configuration Cluster.
| Trait ID | Code |
|---|
| 0x4EA0 | EnableInvertIndicationLight |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableMotionDetectionIndicatorLight Trait
When written, turns the motion detection indicator light display on or off. Reading indicates the current on/off state. Values: false = Off, true = On.
| Trait ID | Code |
|---|
| 0x511B | EnableMotionDetectionIndicatorLight |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DNDTimePeriod Trait
Defines the Do Not Disturb time period. Its value is a structure containing two optional fields, begin_time and end_time, both expressed in crontab format. The crontab format follows the "minute hour day month weekday" pattern (e.g., "0 22 * * *" means 22:00 every day).
| Trait ID | Code |
|---|
| 0x8139 | DNDTimePeriod |
Parameters
EnableDNDMode Trait
When written, enables or disables the indicator light Do Not Disturb (DND) mode. In DND mode, the indicator light may not blink or may stay off during specific periods to avoid disturbance. Values: false = DND off (normal operation), true = DND on.
| Trait ID | Code |
|---|
| 0x8138 | EnableDNDMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
IndicationLightSetting Trait
Configures how the indicator light is used. Values: 0 = Never used (the indicator light is never activated), 1 = Used (the indicator light activates normally), 2 = Toggle (each time this value is written, the current state is toggled, e.g., from on to off or off to on). Reading returns the current setting mode.
| Trait ID | Code |
|---|
| 0x8137 | IndicationLightSetting |
Parameters
Command Definitions
EnableQuietMode Command
This Command is used to perform the "enable silent mode" operation.
This Command has no parameters.
DisableQuietMode Command
This Command is used to perform the "disable silent mode" operation.
This Command has no parameters.
SwitchConfiguration
Introduction
Provides wall switch configuration capability, including wiring mode, button mode, anti-flicker, forced control and line terminal configuration.
Function Identification
| Function ID | Code | Name |
|---|
| 0x011A | SwitchConfiguration | Switch configuration |
Trait
Command
This Function does not contain Commands.
Data Types
WireConfigurationEnum8 Type
This enumeration defines the valid values of the Present Value of the WireConfiguration Trait.
| Value | Name | Description |
|---|
| 0x00 | WithNeutral | With neutral wire |
| 0x01 | WithoutNeutral | Without neutral wire |
This enumeration defines the valid values of the Present Value of the ButtonMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | No button mode is configured. |
| 0x01 | DualMode | When the physical button is pressed, both the relay is controlled and the automation triggered by the wireless switch is executed. |
| 0x02 | StandardMode | When the physical button is pressed, only the relay is controlled. |
| 0x03 | WirelessMode | When the physical button is pressed, only the automation triggered by the wireless switch is executed. |
| 0x04 | DeviceAssociationMode | When the physical button is pressed, the associated device is controlled. |
| 0x05 | SceneAssociationMode | When the physical button is pressed, the associated scene is triggered. |
| 0x06 | QuickDoubleControlMode | When the physical button is pressed, the relay of the associated switch is toggled. |
| 0x07 | MarsTechMode | When the physical button is pressed, the load device is controlled in the Mars Technology manner. |
LineTerminalEnum8 Type
This enumeration defines the valid values of the Present Value of the LineTerminal Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unspecified |
| 0x01 | L1 | L1 |
| 0x02 | L2 | L2 |
| 0x03 | L3 | L3 |
QuickDoubleControlDeviceTraitPresentValueStructure Type
This structure defines the Present Value field layout of the QuickDoubleControlDevice Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DeviceId | characterString | M | Target device DID. |
| 1 | PointPath | characterString | M | Data point access path, containing Endpoint ID, Function ID, Trait ID, Parameter ID, separated by ., e.g., 2.132.32920.1. |
| 2 | SubscribeRecordId | uint32 | M | The data subscription record ID saved by the device for the quick double control function. |
DeviceAssociationTargetTraitPresentValueStructure Type
This structure defines the field layout of a single associated target device in the Present Value list of the DeviceAssociationTarget Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DeviceId | characterString | M | Target device DID. |
| 1 | PointPath | characterString | M | The data point access path of the target device, containing Endpoint ID, Function ID, Trait ID, Parameter ID, separated by .. |
| 2 | SubscribeRecordId | uint32 | M | The data subscription record ID associated with the target device. |
| 3 | GroupId | uint16 | M | Group ID used for group control; when non-zero, switch commands can be sent to this group. |
Trait Definitions
ChildEndpointList Trait
This attribute should report the child endpoints currently assigned in the configured partitions of the device.
| Trait ID | Code |
|---|
| 0x4F33 | ChildEndpointList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
EnableRelayLock Trait
This Trait is used for access to and reporting of "relay lock" data.
| Trait ID | Code |
|---|
| 0x510D | EnableRelayLock |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
WireConfiguration Trait
This Trait is used for access to and reporting of "wiring mode" data.
| Trait ID | Code |
|---|
| 0x510E | WireConfiguration |
Parameters
This Trait is used for access to and reporting of "button mode" data.
| Trait ID | Code |
|---|
| 0x510F | ButtonMode |
Parameters
DeviceAssociationTarget Trait
This Trait is used to configure the associated target devices controlled by the physical button when ButtonMode is DeviceAssociationMode. When the physical button is pressed, the associated devices in this Trait's list should be controlled.
The client should configure this Trait by writing the list of target device entries.
| Trait ID | Code |
|---|
| 0x5198 | DeviceAssociationTarget |
Parameters
QuickDoubleControlDevice Trait
This Trait represents the associated target switch device and its data points used when this switch's ButtonMode is set to QuickDoubleControl. This Trait is valid when ButtonMode is set to QuickDoubleControl. In this mode, pressing the physical button should toggle the relay of the associated switch identified by this Trait.
The client should configure this Trait by writing the target device entry.
| Trait ID | Code |
|---|
| 0x5172 | QuickDoubleControlDevice |
Parameters
EnableAntiFlicker Trait
This Trait is used for access to and reporting of "anti-flicker switch" data.
| Trait ID | Code |
|---|
| 0x5110 | EnableAntiFlicker |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableSwitchForcedControl Trait
This Trait is used for access to and reporting of "forced control switch" data.
| Trait ID | Code |
|---|
| 0x5111 | EnableSwitchForcedControl |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LineTerminal Trait
This Trait is used for access to and reporting of "line terminal" data.
| Trait ID | Code |
|---|
| 0x5114 | LineTerminal |
Parameters
Command Definitions
This Function does not contain Commands.
GeneralConfiguration
Introduction
Provides general device configuration items, such as sensitivity, delay, default parameters and other device-level settings.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00AF | GeneralConfiguration | General configuration |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9D7C | WakeupDevice | Wake up device | O |
Data Types
P2PCaptureIntervalEnum8 Type
This enumeration defines the valid values of the Present Value of the P2PCaptureInterval Trait.
| Value | Name | Description |
|---|
| 0x00 | Auto | Automatic |
| 0x01 | Seconds10 | 10 seconds |
| 0x02 | Seconds20 | 20 seconds |
| 0x03 | Seconds30 | 30 seconds |
| 0x04 | Minutes1 | 1 minute |
| 0x05 | Minutes2 | 2 minutes |
| 0x06 | Minutes5 | 5 minutes |
| 0x07 | Minutes10 | 10 minutes |
| 0x08 | Minutes30 | 30 minutes |
| 0x09 | Hours1 | 1 hour |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
WakeupDeviceActionEnum8 Type
This enumeration defines the valid values of the action field of the WakeupDevice Command.
| Value | Name | Description |
|---|
| 0x01 | Wakeup | Wake up device |
WakeupDeviceSourceEnum8 Type
This enumeration defines the valid values of the source field of the WakeupDevice Command.
| Value | Name | Description |
|---|
| 0x00 | PPCS | Wake up via PPCS stream pull |
| 0x01 | WebRTC | Wake up via WebRTC stream pull |
| 0x02 | NetworkWrite | Wake up via network write of a data point |
| 0x03 | Recording | Wake up via recording |
WakeupDevice Command Structure Type
Parameter structure of the WakeupDevice Command. The Server sends this Command to wake the device from sleep or standby mode, applicable to low-power devices such as cameras, sensors, door locks and control panels. Action is fixed to 1, meaning the wake-up operation is performed; Source identifies the wake-up trigger source, enabling the device to perform statistics, logging or differentiated behavior.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Action | WakeupDeviceActionEnum8 | M | Wake-up action, fixed to 0x01 (Wakeup). |
| 1 | Source | WakeupDeviceSourceEnum8 | M | Wake-up source: 0x00 = PPCS, 0x01 = WebRTC, 0x02 = NetworkWrite, 0x03 = Recording. |
ChildLockEnum8 Type
This enumeration defines the valid values of the Present Value of the ChildLock Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | On | On |
WiFiBandsEnum8 Type
This enumeration defines the valid values of the Present Value of the WiFiBands Trait.
| Value | Name | Description |
|---|
| 0x00 | 2G4 | 2.4G |
| 0x01 | 3G65 | 3.65G |
| 0x02 | 5G | 5G |
| 0x03 | 6G | 6G |
| 0x04 | 60G | 60G |
| 0x05 | 1G | 1G |
| 0xFF | Auto | Auto |
LightSourceCategoryEnum8 Type
This enumeration defines the valid values of the Present Value of the LightSourceCategory Trait.
| Value | Name | Description |
|---|
| 0x00 | SoftFilmHardLightBoard | Soft film hard light board |
| 0x03 | RGBCWLightSource | RGBCW light source |
| 0x04 | LightColorFourColorSource | Light color four-color light source |
This enumeration defines the valid values of the Present Value of the SoftSensorAlgorithm Trait.
| Value | Name | Description |
|---|
| 0x01 | Average | Average |
| 0x02 | Maximum | Maximum |
| 0x03 | Minimum | Minimum |
DetectionModeSettingEnum16 Type
This enumeration defines the valid values of the Present Value of the DetectionModeSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Unconfigured | Not configured |
| 0x03 | DoorWindowState | Door/window state detection |
| 0x05 | ObjectOrientation | Object posture detection |
NightLightModeEnum8 Type
This enumeration defines the valid values of the Present Value of the NightLightMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Always off |
| 0x01 | On | Always on |
| 0x02 | Auto | Auto sensing |
BuzzerVolumeEnum8 Type
This enumeration defines the valid values of the Present Value of the BuzzerVolume Trait.
| Value | Name | Description |
|---|
| 0x00 | Mute | Silent |
| 0x01 | Low | Low volume |
| 0x02 | Medium | Medium volume |
| 0x03 | High | High volume |
ActivityDetectionModeSettingEnum32 Type
This enumeration defines the valid values of the Present Value of the ActivityDetectionModeSetting Trait.
| Value | Name | Description |
|---|
| 0x01 | HumanPresence | Human presence |
| 0x03 | PersonnelLocation | Person location |
| 0x05 | FallDetection | Fall detection |
| 0x08 | CeilingFallSingleTracking | Ceiling-mounted fall and single-person location |
| 0x09 | SleepMode | Sleep |
| 0x11 | GestureControl | Gesture |
VoiceLanguageEnum8 Type
This enumeration defines the valid values of the Present Value of the VoiceLanguage Trait.
| Value | Name | Description |
|---|
| 0x01 | Chinese | Chinese |
| 0x02 | English | English |
| 0x03 | Cantonese | Cantonese |
| 0x04 | Spanish | Spanish |
| 0x05 | Russian | Russian |
| 0x06 | Korean | Korean |
| 0x07 | PortugueseBR | Brazilian Portuguese |
| 0x08 | German | German |
| 0x09 | French | French |
| 0x0A | Italian | Italian |
| 0x0B | Japanese | Japanese |
| 0x0C | Polish | Polish |
| 0x0D | Czech | Czech |
| 0x0E | Slovak | Slovak |
| 0x0F | Turkish | Turkish |
| 0x10 | Hungarian | Hungarian |
| 0x11 | Dutch | Dutch |
| 0x12 | Greek | Greek |
| 0x13 | Arabic | Arabic |
ResetModeEnum8 Type
This enumeration defines the valid values of the Present Value of the ResetMode Trait.
| Value | Name | Description |
|---|
| 0x01 | FactoryReset | Factory reset |
| 0x02 | NetworkReset | Reset network only |
| 0x03 | ConfigurationsReset | Reset configuration only |
| 0x04 | PSWReset | Reset device password only |
LightingModeSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the LightingModeSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Level | Monochrome mode |
| 0x01 | ColorTemp | Color temperature mode |
| 0x02 | RGB | RGB mode |
| 0x03 | RGBW mode | RGBW mode |
InstallationOrientationConfigurationEnum16 Type
This enumeration defines the valid values of the Present Value of the InstallationOrientationConfiguration Trait.
| Value | Name | Description |
|---|
| 0x00 | Horizontal | Horizontal |
| 0x01 | Vertical | Vertical |
InstallationOrientationEnum8 Type
This enumeration defines the valid values of the InstallationOrientation member in the DeviceOrientation structure of the DoorLock Function.
| Value | Name | Description |
|---|
| 0x00 | Horizontal | Horizontal |
| 0x01 | Vertical | Vertical |
DeviceControlFlagsBitmap32 Type
This bitmap defines the valid meaning of each bit of the Present Value of the DeviceControlFlags Trait.
| Value | Name | Description |
|---|
| 0x00000001 | DownloadImageDataDisabled | Bit0: a value of 1 prohibits downloading image data, a value of 0 allows normal downloading. |
PublicCapObjReasonEnum32 Type
This enumeration defines the valid values of the Present Value of the PublicCapObjReason Trait, used to represent the reason why the device's public capability object exists.
| Value | Key | Chinese Name | English Name | Description |
|---|
| 0x00000000 | Unknown | Unknown | Unknown | Default value, indicating no specific reason or unrecognizable. |
| 0x00000001 | BaseReplaceable | Replaceable base | Base Replaceable | The device supports the replaceable base feature and requires this public capability object. |
Trait Definitions
P2PCaptureInterval Trait (Home Page Card Capture Interval)
The home page card capture interval, maintained by the cloud. It can be configured and takes effect after P2PCaptureEnabled is enabled. A value of 0 means the cloud decides the capture interval automatically; a non-zero value follows the interval specified by the enumeration. The default value is 0, and it is readable, writable, and reportable.
| Trait ID | Code |
|---|
| 0x5248 | P2PCaptureInterval |
Parameters
ChildLock Trait
Indicates whether the device's physical buttons or remote control functions are locked to prevent accidental operation.
| Trait ID | Code |
|---|
| 0x5080 | ChildLock |
Parameters
WiFiBands Trait
Used to set the Wi-Fi band used by the device when connecting to the network via Wi-Fi.
| Trait ID | Code |
|---|
| 0x5009 | WiFiBands |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | WiFiBandsEnum8 | | 255 | RVW | O |
| 0x0006 | Supported Value | list[WiFiBandsEnum8] | | | R | |
| 0x0007 | Default Value | uint8 | | 255 | RW | |
UsbDataCommunicationEnable Trait
Enables or disables the data communication function of the device's USB port. It is disabled by default; users can enable it to transfer data through the USB interface (such as connecting to a PC or peripherals).
| Trait ID | Code |
|---|
| 0x5002 | UsbDataCommunicationEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | |
LightSourceCategory Trait
Indicates the light source technology category used inside the luminaire, such as soft film hard light board, RGBCW light source or light color four-color light source.
| Trait ID | Code |
|---|
| 0x4FF6 | LightSourceCategory |
Parameters
AiAgreement Trait
Whether to accept the AI agreement.
| Trait ID | Code |
|---|
| 0x4FEC | AiAgreement |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | |
SoftSensorAlgorithm Trait
Specifies the aggregation algorithm used by the virtual (soft) sensor to calculate the current value from the measurements of multiple physical sensors. Three basic algorithms are supported: average (the arithmetic mean of all source sensor values), maximum (the highest value among all source sensors) and minimum (the lowest value among all source sensors). This configuration determines how the soft sensor's current value is calculated from the underlying multi-source data, and is suitable for scenarios where readings from multiple sensors of the same type need to be combined into a representative value.
| Trait ID | Code |
|---|
| 0x502E | SoftSensorAlgorithm |
Parameters
SoftSensorSourceConfig Trait
Used to configure the physical devices and their attribute lists on which the soft sensor depends. Its value is a JSON string containing fields such as hublist (the list of involved gateways), temperature, humidity. Each field lists the sub-device DIDs under the corresponding gateway and their specific resource IDs (such as "0.1.85" for an attribute). It may also include an optional config object (such as the aggregation algorithm agg), but the algorithm is usually defined by the independent SoftSensorAlgorithm value. This configuration defines the input data sources of the soft sensor, based on which the soft sensor performs aggregation calculations.
| Trait ID | Code |
|---|
| 0x4FAF | SoftSensorSourceConfig |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
DetectionModeSetting Trait
Indicates the current detection mode setting of the device, determining the types of events or states that the device will monitor and report. This is a configurable parameter that can switch between different detection scenarios.
| Trait ID | Code |
|---|
| 0x4F9A | DetectionModeSetting |
Parameters
BeepEnable Trait
Enables or disables the sound feedback beep for device operations.
| Trait ID | Code |
|---|
| 0x4F60 | BeepEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnergySavingEnable Trait
Enables or disables the energy saving mode. When enabled, seat temperature, water temperature, etc. are maintained at the minimum level to reduce energy consumption.
| Trait ID | Code |
|---|
| 0x4F5F | EnergySavingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
NightLightMode Trait
Sets the night light mode. In Auto mode, the device automatically turns the night light on or off based on ambient light.
| Trait ID | Code |
|---|
| 0x4F5E | NightLightMode |
Parameters
HubArkTechEnable Trait
Used to enable or disable the local disaster recovery capability of the proxy gateway under Aqara Ark Technology. When enabled, if a gateway fails or loses power and some Zigbee devices under the gateway can act as proxy gateways, the proxy gateway is responsible for executing part of the basic local automation, scenes and device groups.
| Trait ID | Code |
|---|
| 0x4F51 | HubArkTechEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | |
TimeZone Trait
This attribute is used to set and report the time zone of the device (e.g., China Standard Time is "GMT+8"). Correct time zone configuration ensures that the device system time, scheduled tasks (such as timers) and log timestamps are consistent with the user's actual geographical time, and is the basis for the accurate operation of all time-related functions.
| Trait ID | Code |
|---|
| 0x4F49 | TimeZone |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
ActivityDetectionModeSetting Trait
Specifies the current working mode used by the device to detect and identify specific activities or states, such as human presence detection, fall detection, sleep monitoring or gesture recognition.
| Trait ID | Code |
|---|
| 0x4F0A | ActivityDetectionModeSetting |
Parameters
VoiceLanguage Trait
The language used for voice prompts and voice feedback.
| Trait ID | Code |
|---|
| 0x4EF3 | VoiceLanguage |
Parameters
OutputInterlockFlag Trait
When the values of two attributes are the same, it indicates that the states corresponding to these two attributes are in an interlock relationship.
| Trait ID | Code |
|---|
| 0x4E85 | OutputInterlockFlag |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | |
| 0x0003 | Minimum Value | uint8 | | 0 | R | |
| 0x0005 | Step Value | uint32 | | 1 | R | |
| 0x0007 | Default Value | uint8 | | 0 | RW | |
ResetMode Trait
Supports performing operations including factory reset and resetting network configuration.
| Trait ID | Code |
|---|
| 0x4EAA | ResetMode |
Parameters
LightingLinkageEnable Trait
Lighting linkage enable. Used to control the linkage behavior between the main light and secondary lights. When the enable is on (default), operations on the main light such as switching, brightness, color temperature and color adjustment are automatically applied to all secondary lights; when the enable is off, secondary lights can be adjusted independently and are not affected by the main light control.
| Trait ID | Code |
|---|
| 0x5134 | LightingLinkageEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | R | |
DeviceControlFlags Trait
Uses a bitmask (Bitmap) to express multiple device control states. Each bit represents an independent state switch, and upper-layer applications can read this value to determine whether a specific operation is allowed.
| Trait ID | Code |
|---|
| 0x5133 | DeviceControlFlags |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | DeviceControlFlagsBitmap32 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
PublicCapObjReason Trait
This Trait represents the reason why the device's public capability object DevicePublicCapabilities Object exists. It is used to describe why the device needs to have a certain public capability object.
For example: when the value is 1, it indicates that the device requires this public capability object because it supports the replaceable base feature.
| Trait ID | Code |
|---|
| 0x516C | PublicCapObjReason |
Parameters
PollingTime Trait
Sets the polling time interval for device communication with the network. Unit: ms.
| Trait ID | Code |
|---|
| 0x4E9A | PollingTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 7200000 | R | |
| 0x0003 | Minimum Value | uint32 | | 0 | R | |
| 0x0005 | Step Value | uint32 | | 250 | R | |
| 0x0007 | Default Value | uint32 | | 0 | RW | |
KeepAliveInterval Trait
Represents the sending interval between two consecutive keep-alive commands of a low-power device. Different low-power devices have different wake-up capabilities; the device reports its expected keep-alive command sending interval through this Trait, so that the APP or cloud can adjust the sending frequency of keep-alive commands. Unit: seconds, range 1 to 65535. This Trait is read-only and reportable. The default value is 7.
| Trait ID | Code |
|---|
| 0x519C | KeepAliveInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 7 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint32 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 7 | RW | O |
TransmissionPowerSetting Trait
A dedicated feature used to set the device transmission power.
| Trait ID | Code |
|---|
| 0x4E98 | TransmissionPowerSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 10.0 | R | |
| 0x0003 | Minimum Value | float | | -32.0 | R | |
| 0x0005 | Step Value | float | | 1.0 | R | |
| 0x0007 | Default Value | float | | 0 | RW | O |
LightingModeSetting Trait
Defines the working mode of the luminaire.
The LightingModeSetting trait is used to set or query the current working mode of the lighting device. This mode determines the range of control capabilities exposed by the device, including the availability of switch control, brightness adjustment, color temperature adjustment and color setting functions. Four modes are currently supported: monochrome mode (Level), color temperature mode (ColorTemp), RGB mode (RGB) and RGBW mode (RGBW). In different modes, the data points and executable operations exposed by the device differ.
Specifically, when the light device is in monochrome mode, it only supports switch state control and brightness adjustment control, does not support color temperature control or any color setting. This mode is suitable for single-color-temperature luminaires that only need dimming. When the device is in color temperature mode, it additionally supports color temperature adjustment in addition to switch and brightness control, enabling smooth changes from warm white to cool white, but still does not support RGB or RGBW color settings; it is suitable for dual-color-temperature luminaires. When the device switches to RGB mode, in addition to switch, brightness and color temperature control (color temperature can be simulated through RGB channel mixing), it supports full-color RGB settings that can be freely adjusted to any color, but does not support an independent white channel. When the device is in RGBW mode, it further adds an independent white channel on top of RGB mode, supporting RGBW four-channel color settings that can simultaneously present vivid colors and pure white light, satisfying richer lighting scenario needs.
It is particularly important to emphasize that the working mode setting is not an arbitrary switch at the software level; it usually needs to be determined in combination with the physical wiring scheme of the luminaire and the actual deployment situation. For example, if the luminaire only has warm/cool white LED connections, it should not be set to RGB mode or RGBW mode; if the luminaire has independent RGB+W pins, it can be set to RGBW mode. Once the mode is modified, the device's data model configuration is dynamically updated in sync - data points not supported in the new working mode are automatically hidden and no longer appear in the data model, while data points supported in the new mode are exposed as needed. This mechanism ensures that the client can correctly identify the current capability range of the device and avoid sending invalid commands. Therefore, before modifying this mode, it is necessary to fully confirm whether the hardware supports the target mode, and mode changes should be made with caution and not arbitrarily, to avoid abnormal device control functions or a mismatch between the client interface and the actual capabilities.
| Trait ID | Code |
|---|
| 0x4E83 | LightingModeSetting |
Parameters
InstallationOrientationConfiguration Trait
This Trait is used for access to and reporting of "installation orientation configuration" data.
| Trait ID | Code |
|---|
| 0x4E7E | InstallationOrientationConfiguration |
Parameters
CurrentSensitivityLevel Trait
Indicates the currently selected general configuration sensitivity level.
| Trait ID | Code |
|---|
| 0x813B | CurrentSensitivityLevel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | |
| 0x0003 | Minimum Value | uint8 | | 0 | R | |
| 0x0005 | Step Value | uint32 | | 1 | R | |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
SensitivityLevelEnum Trait
This enumeration provides a unified sensitivity level configuration for device functions such as detection, recognition, sensing and alarm.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
NumberOfSensitivityLevelIsSupported Trait
This Trait is used for access to and reporting of "number of supported sensitivity levels" data.
| Trait ID | Code |
|---|
| 0x813A | NumberOfSensitivityLevelIsSupported |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | |
| 0x0003 | Minimum Value | uint8 | | 0 | R | |
| 0x0005 | Step Value | uint32 | | 1 | R | |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
DynamicCoverRefreshEnable Trait
Enables or disables the dynamic refresh of the device cover image on the App home page.
| Trait ID | Code |
|---|
| 0x5027 | DynamicCoverRefreshEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | |
BuzzerVolume Trait
Used to set the volume level of the device buzzer. The buzzer is used for sound prompts such as button feedback, alarm notifications or operation notifications. This Trait supports read, write and active reporting.
| Trait ID | Code |
|---|
| 0x5163 | BuzzerVolume |
Parameters
P2PCaptureEnabled Trait
Indicates whether the camera's P2P (peer-to-peer) capture function is enabled.
| Trait ID | Code |
|---|
| 0x4E3E | P2PCaptureEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RV | O |
| 0x0007 | Default Value | boolean | | 1 | RW | |
P2PCaptureStatus Trait
P2P dynamic capture status switch
| Trait ID | Code |
|---|
| 0x4E44 | P2PCaptureStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
VibrationIntensity Trait
Vibration intensity setting, used to adjust the vibration intensity of the linear motor and control the strength of the device's haptic feedback. Value range: 0-100%, default 50%, step 1.
| Trait ID | Code |
|---|
| 0x51ED | VibrationIntensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 1 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
Command Definitions
WakeupDevice Command
The Server sends this command to wake the device from sleep or standby mode. This command is applicable to low-power devices such as cameras, sensors, door locks and control panels. The Payload contains two fields, Action and Source, where Action is fixed to 1 to indicate that the wake-up operation is performed, and Source identifies the wake-up trigger source, enabling the device to perform statistics, logging or differentiated behavior.
Parameters
WakeupDevice Command Structure
GeneralDiagnostics
Introduction
Provides general diagnostic information, including uptime, reboot count, network interfaces and hardware faults.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B0 | GeneralDiagnostics | General diagnostics |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9D22 | Reboot | Reboot command | O |
Data Types
RebootReasonEnum8 Type
This enumeration defines the valid values of the Present Value of the RebootReason Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unknown |
| 0x01 | PowerOnReboot | Power-on reboot |
| 0x02 | BrownOutReset | Brown-out reset |
| 0x03 | SoftwareWatchdogReset | Software watchdog reset |
| 0x04 | HardwareWatchdogReset | Hardware watchdog reset |
| 0x05 | SoftwareUpdateCompleted | Software update completed |
| 0x06 | SoftwareReset | Software reboot (general) |
| 0x07 | ApplicationExitReboot | Restart after normal application exit (e.g., terminated by a signal) |
| 0x08 | DebugLogEnabledReboot | Reboot after the cloud enables debug logging |
| 0x09 | RemoteRPCCommandReboot | Device reboot triggered by a remote RPC command |
| 0x10 | ButtonLongPressReboot | Reboot triggered by a long press of the physical button |
| 0x11 | MemoryExhaustionReboot | Reboot triggered by memory exhaustion (out of memory) |
| 0x12 | CameraHangReboot | Camera process unresponsive |
AntiDeletionNotificationEnum8 Type
This enumeration defines the valid values of the Present Value of the AntiDeletionNotification Trait.
| Value | Name | Description |
|---|
| 0x01 | Trigger | Reset triggered by button press |
| 0x02 | FactoryResetByButton | Factory reset triggered by button press |
AntiDeletionSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the AntiDeletionSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Disable | Disabled |
| 0x01 | Enable | Enabled |
ActiveHardwareFaultsEnum32 Type
This enumeration defines the valid values of the Present Value of the ActiveHardwareFaults Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unknown fault |
| 0x01 | Radio | Radio fault |
| 0x02 | Sensor | Sensor fault |
| 0x03 | ResettableOverTemp | Overheating protection |
| 0x04 | NonResettableOverTemp | Overheating anomaly |
| 0x05 | PowerSource | Power fault |
| 0x06 | VisualDisplayFault | Display fault |
| 0x07 | AudioOutputFault | Audio output fault |
| 0x08 | UserInterfaceFault | UI display fault |
| 0x09 | NonVolatileMemoryError | Memory fault |
| 0x0A | TamperDetected | Device disassembled/tampered |
| 0xFF | Normal | No fault |
AntiDeletionLevelSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the AntiDeletionLevelSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | EnableResetAndFactory | Enable network reset and factory reset |
| 0x01 | DisableFactoryOnly | Disable factory reset only |
| 0x02 | DisableResetAndFactory | Disable network reset and factory reset |
InterfaceTypeEnum8 Type
This enumeration defines the valid values of the Type field in the NetworkInterfacesTraitPresentValueStructure.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unspecified |
| 0x01 | WiFi | Wi-Fi interface |
| 0x02 | Ethernet | Ethernet interface |
| 0x03 | Cellular | Cellular interface |
| 0x04 | Thread | Thread interface |
AddressingModeEnum8 Type
This enumeration defines the valid values of the AddressingMode field in the NetworkInterfacesTraitPresentValueStructure.
| Value | Name | Description |
|---|
| 0x00 | DHCP | IP address dynamically allocated via DHCP |
| 0x01 | Static | Statically configured IP address |
| 0x02 | Auto | Auto-configuration (e.g., IPv6 SLAAC or link-local address) |
| 0xFF | Unspecified | Unspecified or unknown |
NetworkInterfacesTraitPresentValueStructure Type
This structure defines the Present Value field layout of the NetworkInterfaces Trait.
| Struct Member No. | Field Name | Type | Required | Mandatory |
|---|
| 0 | Name | characterString | O | Human-readable or system-level identifier of the network interface (e.g., eth0, wlan0), used to uniquely identify the interface within the device OS and for configuration or diagnostic reference. |
| 1 | IsOperational | boolean | M | Indicates whether this network interface can currently send and receive data normally. This usually requires the link to be available, an IP address to be assigned and the route to be reachable. |
| 2 | OffPremiseServicesReachableIPv4 | boolean | O | Indicates whether the device can access external (off-network) services such as cloud addresses via IPv4 through this interface; true means IPv4 external connectivity is available. |
| 3 | OffPremiseServicesReachableIPv6 | boolean | O | Indicates whether the device can access external (off-network) services via IPv6 through this interface; true means IPv6 external connectivity is available. |
| 4 | HardwareAddress | characterString | M | MAC address string, max length 24. Should be a 48-bit IEEE MAC or 64-bit IEEE MAC (EUI-64), in big-endian/display order (most significant byte on the left). Examples: 00:1A:2B:3C:4D:5E, 00:1A:2B:FF:FE:3C:4D:5E. |
| 5 | IPv4Addresses | list[characterString] | O | IPv4 address list, element type string (max length 16). Example: 192.168.2.235. |
| 6 | IPv6Addresses | list[characterString] | O | IPv6 address list, element type string (max length 40). Example: 2001:DB8:0:0:8:800:200C:417A. |
| 7 | Type | InterfaceTypeEnum8 | M | Interface type. |
| 8 | RSSI | int8 | O | Received signal strength indicator value (dBm), usually negative (e.g., -30). |
| 9 | AddressingMode | AddressingModeEnum8 | O | Indicates the current IP address configuration mode of this interface. |
| 10 | SSID | characterString | O | Network name (Service Set Identifier) of the currently connected Wi-Fi. Example: Home_2.4G. |
| 11 | BSSID | characterString | O | BSSID (MAC address) of the currently connected access point (AP). Example: 34:AB:37:12:CD:EF. |
| 12 | RouterMAC | characterString | O | MAC address of the currently connected upstream gateway/router. Example: 9C:3D:CF:AA:BB:CC. |
| 13 | Channel | uint8 | O | Current Wi-Fi operating channel (Channel). Examples: 1, 6, 11, 149. |
| 14 | SubnetMask | characterString | O | Subnet mask/prefix information, string (max length 32). Fill in the subnet mask for IPv4 scenarios (example: 255.255.255.0); for IPv6 scenarios, it is recommended to fill in the prefix length (example: 64); may be left empty if unknown or not applicable. |
| 15 | DefaultGateway | characterString | O | Default gateway address, string (max length 32). Can be an IPv4 or IPv6 gateway address. Examples: 192.168.1.1, fe80::1. |
| 16 | PrimaryDNS | characterString | O | Preferred DNS, string (max length 32). Can be an IPv4 or IPv6 DNS address. Examples: 8.8.8.8, 2001:4860:4860::8888. |
| 17 | SecondaryDNS | characterString | O | Alternate DNS, string (max length 32). Can be an IPv4 or IPv6 DNS address. Examples: 8.8.4.4, 2001:4860:4860::8844. |
BlockDeletionEnum8 Type
This enumeration defines the valid values of the Present Value of the BlockDeletion Trait.
| Value | Name | Description |
|---|
| 0x00 | Allow | Allow deletion |
| 0x01 | Block | Block deletion |
LogUploadTaskModeEnum8 Type
This enumeration defines the valid values of the Mode field of the LogUploadTask.
| Value | Name | Description |
|---|
| 0x00 | Oneshot | Upload the current RAM cached logs once |
| 0x01 | Continuous | Continuous upload mode; automatically uploads when RAM is full and loops until ValidTime |
This enumeration defines the valid values of the Present Value of the PlatformAccessEvent Trait.
| Value | Name | Description |
|---|
| 0x01 | HomeKit | HomeKit user access |
LogUploadTaskPresentValueStructure Type
Parameter structure of the LogUploadTask Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Mode | LogUploadTaskModeEnum8 | M | Upload mode. |
| 1 | ValidTime | uint32 | O | Validity deadline of the continuous upload mode (UTC Epoch seconds). Only effective when Mode=Continuous; a value of 0 or omitted means no deadline. |
RebootTypeEnum8 Type
This enumeration defines the valid values of the RebootType field of the Reboot Command.
| Value | Name | Description |
|---|
| 0x00 | RebootDevice | Reboot the whole device |
| 0x01 | RebootCoordinator | Reboot the coordinator only |
| 0x7F | RebootSubMCU | Reboot the sub MCU |
| 0x80 | RebootStudio | Reboot Studio |
Reboot Command Structure Type
Parameter structure of the Reboot Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | RebootType | RebootTypeEnum8 | M | Reboot type. |
| 1 | Delay | uint32 | O | Delay duration, unit s; range 0 ~ 4294967295, step 1, default value 0. |
Trait Definitions
RebootReason Trait
The current value should indicate the reason for the device's most recent boot.
| Trait ID | Code |
|---|
| 0x8149 | RebootReason |
Parameters
RebootCount Trait
The current value should indicate the number of times the device has rebooted as accurately as possible. It should increment each time the device reboots. It should not increment when the device wakes from low-power or sleep state. It should only reset to 0 when the device is factory reset.
| Trait ID | Code |
|---|
| 0x8148 | RebootCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
AntiDeletionNotification Trait
After AntiDeletion is enabled for a sub-device on the hub, if the sub-device performs a reset/delete operation, a notification report will be triggered.
| Trait ID | Code |
|---|
| 0x4F4B | AntiDeletionNotification |
Parameters
AntiDeletionSetting Trait
Used to set the function to prevent accidental deletion.
| Trait ID | Code |
|---|
| 0x4F4A | AntiDeletionSetting |
Parameters
ActiveHardwareFaults Trait
Hardware errors
| Trait ID | Code |
|---|
| 0x813D | ActiveHardwareFaults |
Parameters
AntiDeletionLevelSetting Trait
The anti-deletion level setting controls the permissions of the network reset and factory reset button operations during device operation, preventing accidental data loss.
| Trait ID | Code |
|---|
| 0x4F03 | AntiDeletionLevelSetting |
Parameters
FreeMemory Trait
Indicates the currently available memory size of the device, in kilobytes (KB).
| Trait ID | Code |
|---|
| 0x4EA3 | FreeMemory |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
TotalMemory Trait
Total memory size. Represents the total physical memory capacity (RAM) configured in the device hardware, in KB. This value is a static parameter, fixed at device factory or at boot, used to describe the hardware specification of the device.
| Trait ID | Code |
|---|
| 0x5152 | TotalMemory |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | 0 ~ 4294967295 (unit: KB) | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
CPUUsage Trait
Indicates the current overall CPU usage of the device (CPU usage, unit: %), used for device diagnostics and load monitoring.
| Trait ID | Code |
|---|
| 0x5147 | CPUUsage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0.0 ~ 100.0 (unit: %) | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
CPUFrequency Trait
Indicates the current CPU operating frequency of the device (CPU frequency, unit: MHz), used for device diagnostics and load monitoring.
| Trait ID | Code |
|---|
| 0x5148 | CPUFrequency |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | >= 0 (unit: MHz) | 1000 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
NetworkInterfaces Trait
This Trait describes the network interfaces supported by the device.
| Trait ID | Code |
|---|
| 0x4E2A | NetworkInterfaces |
Parameters
DebugInfo Trait
Debug information during device operation. Data type is string, max length 1024 bytes.
| Trait ID | Code |
|---|
| 0x4E29 | DebugInfo |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | V | O |
UpTime Trait
The UpTime Trait should indicate the length of time (seconds) elapsed since the node last rebooted as accurately as possible.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
BlockDeletion Trait
Written by the server when the device requests deletion (unbinding). Writing a value of 1 instructs the device to cancel the deletion operation (i.e., remain bound). When writing 0 or the Trait is absent, the device is allowed to continue deletion.
| Trait ID | Code |
|---|
| 0x50AE | BlockDeletion |
Parameters
LogUploadTask Trait
This Trait is used to trigger device log upload tasks. Writing to this Trait starts/stops the upload task; reading returns the current configuration.
| Trait ID | Code |
|---|
| 0x50C3 | LogUploadTask |
Parameters
When a user from an external platform (such as HomeKit, Alexa, Google Home, etc.) accesses the device, the device reports this event to generate access logs. This Trait identifies the source platform of the access, facilitating security auditing and log tracking.
| Trait ID | Code |
|---|
| 0x513B | PlatformAccessEvent |
Parameters
SupportedRebootType Trait
This Trait is used to report the reboot types supported by the device.
| Trait ID | Code |
|---|
| 0x5153 | SupportedRebootType |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[RebootTypeEnum8] | | | RV | O |
CommLinkDetection Trait
Used for communication link diagnostics, mainly carrying link detection information from the cloud or operations side.
| Trait ID | Code |
|---|
| 0x5106 | CommLinkDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
Command Definitions
| Command ID | Name | Conformance |
|---|
| 0x9D22 | Reboot | O |
Reboot Command
Controls or reports the device reboot status, which can be used to monitor or trigger a device reboot.
Parameters
Reboot Command Structure
PanTilt
Introduction
Provides Pan/Tilt/Zoom (PTZ) control capability, including preset positions, calibration and relative/absolute movement.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B1 | PanTilt | Pan/Tilt |
Trait
Command
Data Types
PTZPowerOffMemoryEnum8 Type
This enumeration defines the valid values of the Present Value of the PTZPowerOffMemory Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Disable power-off memory. |
| 0x01 | Hold | Enable power-off memory; the PTZ position before power-off is restored after power-on. |
ViewZoomModeEnum8 Type
This enumeration defines the valid values of the Present Value of the ViewZoomMode Trait.
| Value | Name | Description |
|---|
| 0x00 | FixedCenter | Fixed center zoom. |
| 0x01 | FollowGesture | Gesture-following zoom. |
PTZHomeModeEnum8 Type
This enumeration defines the valid values of the Present Value of the PTZHomeMode Trait.
| Value | Name | Description |
|---|
| 0x00 | AfterTrackingOnly | Return home after tracking ends. |
| 0x01 | AfterTrackingOrLiveView | Return home after tracking ends or after exiting the live view. |
PTZAutoModeSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the PTZAutoModeSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | None | None. |
| 0x01 | Cruise | Cruise. |
| 0x02 | HumanTracking | Human tracking. |
| 0x03 | PetTracking | Pet tracking. |
| 0x04 | SoundSourceLocalization | Sound source localization. |
CruiseStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the CruiseStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | AutoStopped | Auto stopped. |
| 0x01 | ManualStopped | Manually stopped. |
PTZDirectionEnum8 Type
This enumeration defines the valid values of the PTZ rotation direction fields (PanDir/TiltDir).
| Value | Name | Description |
|---|
| 0x01 | Forward | Forward. |
| 0x02 | Reverse | Reverse. |
PTZCalibrationActionEnum8 Type
This enumeration defines the valid values of the Action field of the PTZCalibration Command.
| Value | Name | Description |
|---|
| 0x00 | Stop | Stop calibration. |
| 0x01 | Calibrate | Start calibration. |
PTZPresetTypeEnum8 Type
This enumeration defines the valid values of the PTZ preset type field (PresetType).
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal preset. |
| 0x01 | Home | Home point preset. |
| 0x02 | Patrol | Patrol point preset. |
PTZPresetScenarioEnum8 Type
This enumeration defines the position semantics of PTZ presets (PresetScenario). Position semantics are used to identify standard positions across devices and languages; they are not preset IDs and do not indicate the preset source or control purpose.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unspecified standard position semantics. Used for compatibility with existing presets whose semantics cannot be determined; newly created user presets should use Custom. |
| 0x01 | Rightmost | The standard position where the PTZ faces the rightmost point of its valid horizontal travel. |
| 0x02 | Leftmost | The standard position where the PTZ faces the leftmost point of its valid horizontal travel. |
| 0x03 | Topmost | The standard position where the PTZ faces the topmost point of its valid vertical travel. |
| 0x04 | Bottommost | The standard position where the PTZ faces the bottommost point of its valid vertical travel. |
| 0x05 | Center | The standard position where both Pan and Tilt are at the midpoint of their calibrated valid travel. |
| 0x06 | Custom | Presets that do not have the standard position semantics defined by this enumeration. There may be multiple. |
| 0x07-0xFF | Reserved | Reserved for future standard extensions. Implementations must not assign other meanings. |
Rightmost, Leftmost, Topmost and Bottommost indicate the direction the camera faces, referenced to the device's calibrated normal installation posture and the un-mirrored, un-flipped video coordinates; semantics must not change according to client display mirroring. The motor positive/negative directions corresponding to each direction are determined by the device calibration result and must not assume that the Pan/Tilt positive direction is the same across all devices.
CurrentPTZPositionStructure Type
This structure defines the Present Value field layout of the CurrentPTZPosition Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Pan | int16 | M | Horizontal Pan angle, in degrees. |
| 1 | Tilt | int16 | M | Vertical Tilt angle, in degrees. |
| 2 | Zoom | float | O | Optical zoom magnification. |
| 3 | PanDir | PTZDirectionEnum8 | O | Pan direction. |
| 4 | TiltDir | PTZDirectionEnum8 | O | Tilt direction. |
PTZOffsetStructure Type
This structure defines the Present Value field layout of the PTZOffset Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PanOffset | int16 | M | Pan offset angle, in degrees. |
| 1 | TiltOffset | int16 | M | Tilt offset angle, in degrees. |
PTZRangeStructure Type
This structure defines the Present Value field layout of the PTZRange Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PanMin | int16 | M | Pan minimum angle, in degrees. |
| 1 | PanMax | int16 | M | Pan maximum angle, in degrees. |
| 2 | TiltMin | int16 | M | Tilt minimum angle, in degrees. |
| 3 | TiltMax | int16 | M | Tilt maximum angle, in degrees. |
PTZHomePositionStructure Type
This structure defines the Present Value field layout of the PTZHomePosition Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Mode | uint8 | M | Home mode: 0 = return to the pre-tracking position, 1 = return to a fixed position. |
| 1 | Pan | int16 | O | Fixed home point Pan angle, valid when Mode=1. |
| 2 | Tilt | int16 | O | Fixed home point Tilt angle, valid when Mode=1. |
| 3 | Zoom | float | O | Fixed home point Zoom, valid when Mode=1. |
PTZPresetItemStructure Type
This structure defines the field layout of a single PTZ preset item.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresetId | uint32 | M | Unique ID of the preset. |
| 1 | Name | characterString | M | Preset name. |
| 2 | Position | CurrentPTZPositionStructure | M | PTZ position corresponding to the preset. |
| 3 | IconUrl | characterString | O | Icon URL. |
| 4 | EncryptionKey | octetString | O | Image encryption key. |
| 5 | CoordinateData | octetString | O | Coordinate extension data. |
| 6 | PresetType | PTZPresetTypeEnum8 | O | Preset type. |
| 7 | SortOrder | uint32 | O | Sort value. |
| 8 | PresetScenario | PTZPresetScenarioEnum8 | O | Position semantics of the preset. New implementations conforming to this definition should provide it; a missing field means the semantics are unknown and must not be inferred from PresetId, Name or list order. |
| 9 | BuiltIn | boolean | O | Whether it is a built-in preset provided by the device. New implementations conforming to this definition should provide it; a missing field means the source is unknown and must not be treated as false. |
PanTiltDirectionControl Command Structure Type
Parameter structure of the PanTiltDirectionControl Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Direction | uint8 | M | Direction. |
PTZRelativeMove Command Structure Type
Parameter structure of the PTZRelativeMove Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PanDelta | int16 | M | Pan change amount. |
| 1 | TiltDelta | int16 | M | Tilt change amount. |
| 2 | ZoomDelta | float | O | Zoom change amount. |
PTZCalibration Command Structure Type
Parameter structure of the PTZCalibration Command.
PTZSetPosition Command Structure Type
Parameter structure of the PTZSetPosition Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Pan | int16 | M | Pan angle. |
| 1 | Tilt | int16 | M | Tilt angle. |
| 2 | Zoom | float | O | Zoom. |
| 3 | PanDir | PTZDirectionEnum8 | O | Pan rotation direction. |
| 4 | TiltDir | PTZDirectionEnum8 | O | Tilt rotation direction. |
PTZMoveToPreset Command Structure Type
Parameter structure of the PTZMoveToPreset Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresetId | uint32 | M | Preset ID. |
PTZSavePreset Command Structure Type
Parameter structure of the PTZSavePreset Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresetId | uint32 | O | Preset ID. |
| 1 | Name | characterString | O | Name. |
| 2 | Position | CurrentPTZPositionStructure | O | PTZ position. |
| 3 | IconUrl | characterString | O | Icon URL. |
| 4 | EncryptionKey | octetString | O | Image encryption key. |
| 5 | CoordinateData | octetString | O | Coordinate data. |
| 6 | PresetType | PTZPresetTypeEnum8 | O | Preset type. |
| 7 | SortOrder | uint32 | O | Sort. |
| 8 | PresetScenario | PTZPresetScenarioEnum8 | O | Omitted when creating a new user preset means Custom; this command is not allowed to create or modify the five standard position scenarios. |
PTZRemovePreset Command Structure Type
Parameter structure of the PTZRemovePreset Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresetId | uint32 | M | Preset ID. |
Trait Definitions
PTZPowerOffMemory Trait
Used to set or query the PTZ power-off memory function. When enabled, the device restores the PTZ position before power-off after reboot; when disabled, the device returns to the default position after reboot.
| Trait ID | Code |
|---|
| 0x50D9 | PTZPowerOffMemory |
Parameters
ViewZoomMode Trait
Used to set or query the PTZ behavior when the user performs a two-finger pinch zoom gesture in the live view. With fixed center zoom, the zoom center stays at the center of the frame and the PTZ does not follow the movement; with gesture-following zoom, the PTZ rotates to align with the center point of the pinch gesture.
| Trait ID | Code |
|---|
| 0x50D6 | ViewZoomMode |
Parameters
PTZHomeReturnDelay Trait
Used to set or query the delay before the PTZ auto home return is executed after being triggered, in seconds.
| Trait ID | Code |
|---|
| 0x50D5 | PTZHomeReturnDelay |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 5 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 60 | R | |
| 0x0003 | Minimum Value | uint32 | | 1 | R | |
| 0x0005 | Step Value | uint32 | | 1 | R | |
| 0x0007 | Default Value | uint32 | | 5 | RW | O |
PTZHomeMode Trait
Used to set or query the trigger condition for PTZ auto home return.
| Trait ID | Code |
|---|
| 0x50D4 | PTZHomeMode |
Parameters
PTZHomePosition Trait
Defines the PTZ auto home return target configuration. Mode=0 returns to the pre-tracking position; Mode=1 returns to a specified fixed Pan/Tilt/Zoom position.
| Trait ID | Code |
|---|
| 0x50D3 | PTZHomePosition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | PTZHomePositionStructure | | {"0":0,"1":999,"2":999} | RVW | O |
PTZAutoModeSetting Trait
Used to set or query the PTZ smart mode, such as cruise, human tracking, pet tracking, sound source localization, etc.
| Trait ID | Code |
|---|
| 0x50D2 | PTZAutoModeSetting |
Parameters
PTZPresets Trait
Represents the list of PTZ presets currently callable on the device, including device built-in presets and user-saved presets. Each item contains a unique ID, name, PTZ position and optional extension fields. PresetId is used to identify and call an item; PresetScenario represents standard position semantics; BuiltIn indicates whether the item is provided by the device. Name is for display only and must not be used to determine position semantics or preset source.
| Trait ID | Code |
|---|
| 0x50D1 | PTZPresets |
Parameters
Preset List Implementation Requirements
- The
PresetId in the current list of the same Endpoint must be unique. The ID must remain stable while the item exists; a device reboot must not change the ID of an item that still exists. The device should avoid reusing the ID of a deleted item within the configuration lifecycle, so that delayed requests do not act on a different preset. When a factory reset or reconfiguration may change the list, the client must re-read this Trait.
- For new implementations adopting this definition, each list item must provide
PresetScenario and BuiltIn. Since these two structure fields are optional at the encoding level, when legacy implementations or data lack the fields, consumers must treat them as unknown; a missing BuiltIn must not be treated as false, and direction or source must not be inferred from the ID, Name, array index or other non-standardized information.
- For new implementations, each of the five standard scenarios
Rightmost, Leftmost, Topmost, Bottommost and Center may appear at most once in the list of one Endpoint. The device should only report standard presets it actually supports, whose positions can be determined and to which it can execute movement; unsupported standard positions should be omitted and must not be fabricated with placeholder values or unreachable positions. Custom can be used for multiple items; Unspecified is only for compatibility with legacy items whose semantics cannot be determined, and newly created items must not use Unspecified.
PresetScenario and PresetType convey different information: the former describes position semantics, the latter describes purposes such as Normal, Home or Patrol. Direction must not be encoded into PresetType; nor should the PresetType of an item be inferred as Home merely because its scenario is Center.- The
Name of a standard position preset must use the canonical English names: Rightmost, Leftmost, Topmost, Bottommost or Center, consistent with its PresetScenario. Clients should localize standard position names based on PresetScenario rather than parsing Name. The Name of custom presets is provided by the user or device for display; it must not be used as machine-readable semantics.
- For the five standard positions,
Position must contain a callable complete Pan/Tilt position. For horizontal endpoint scenarios, the other axis Tilt uses the midpoint of the valid vertical travel; for vertical endpoint scenarios, the other axis Pan uses the midpoint of the valid horizontal travel; for Center, both Pan and Tilt use the midpoints of their corresponding valid travel. Travel boundaries should come from the device's calibrated actual usable travel; if PTZRange is not implemented, the device must still be able to reliably determine these boundaries, otherwise it must not report the corresponding standard scenarios.
- For midpoint calculation, the device computes
(minimum + maximum) / 2; when the result is not a representable integer angle, it rounds toward the smaller integer angle and ensures the target lies within the valid travel. Direction endpoints are determined according to the correspondence between the device's calibrated direction and the un-mirrored, un-flipped frame direction in the normal installation posture; it must not be assumed that the numerical sign of Pan/Tilt uniformly represents left/right or up/down.
- For standard position scenarios, when the device supports Zoom and
1.0 lies within its valid range, it should use Zoom=1.0; otherwise it should use the minimum effective optical zoom magnification supported by the device. Zoom may be omitted when the device does not support optical zoom. Client mirroring, flipping or digital cropping must not change the standard position semantics.
- Built-in items must report
BuiltIn=true; user-created items must report BuiltIn=false. When the source of an existing item cannot be determined, legacy data may omit the field, and consumers should treat it as unknown and avoid providing edit or delete operations that might damage the preset.
- The
PresetId, PresetScenario and standard position semantics of built-in items must remain stable. When actual coordinates change due to device calibration or available travel changes, the device should update Position and report the list; if the scenario can no longer be realized, the item should be removed. Clients must not cache the list long-term and assume the items exist forever.
- When a client writes the list, the device must validate the entire new list. If there are duplicate IDs, duplicate standard scenarios, invalid fields, or creation, deletion, fabrication, source changes or semantic changes of built-in items, the device must reject the entire write and must not apply it partially. Updating the
Position of built-in items is only permitted for the device due to calibration or hardware state changes; clients are not allowed to modify built-in items by directly writing the list.
- The above new fields and rules do not change the optionality of the existing
PTZPresets Trait. Implementations that only implement the legacy format are existing compatible implementations; new implementations should provide the new fields. When consumers encounter missing fields or unknown enumeration values, they should preserve the readable raw data, use Name for display, and must not guess semantics.
Client Handling Requirements
- The client should read the device's current
PTZPresets list and identify items by PresetId; it must not assume that a certain ID, array index or SortOrder corresponds to a standard position.
- When
PresetScenario is one of the five standard positions, the client should display the localized name and the corresponding standard position icon according to this enumeration value. Name is kept for auxiliary display and must not be used as a basis for judgment. For Custom, Unspecified, missing fields or enumeration values the client does not yet recognize, the client should display the Name provided by the device and avoid showing inferred direction semantics.
- When initiating move, save or delete operations, the client should use the
PresetId read from the current list. It must not treat the PresetScenario value as a PresetId, nor construct a target that does not exist in the list based solely on the scenario enumeration.
- Items with
BuiltIn=true should be displayed as device built-in presets without offering edit or delete operations. When BuiltIn is missing or unrecognizable, the client should hide or disable edit and delete operations until it obtains confirmable source information from the device.
- After a list report or command success, the client should refresh the local list and the scenario index. If the list violates ID uniqueness or standard scenario uniqueness, the client should treat the data as invalid and report it to the user or diagnostic system, and must not silently select one item.
CurrentPTZPosition Trait
Represents the current PTZ mechanical position (Pan/Tilt) and optical zoom magnification (Zoom), which can be used for status display and as a reference for subsequent control.
| Trait ID | Code |
|---|
| 0x50D0 | CurrentPTZPosition |
Parameters
CruiseStatus Trait
Used to report the current operating status of the PTZ cruise function. When the cruise stops automatically because preset conditions are met, it reports AutoStopped; when stopped manually by the user, it reports ManualStopped.
| Trait ID | Code |
|---|
| 0x50C7 | CruiseStatus |
Parameters
CruiseEnable Trait
Used to enable or disable the PTZ auto cruise function. When enabled, the device automatically moves along the predefined cruise path; when disabled, auto cruise stops and manual control is allowed.
| Trait ID | Code |
|---|
| 0x50C6 | CruiseEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | |
PTZRange Trait
Defines the motion boundary range of the PTZ Pan/Tilt, usually determined by the hardware mechanical limits, reported read-only.
| Trait ID | Code |
|---|
| 0x50C2 | PTZRange |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | PTZRangeStructure | | | RV | O |
PTZOffset Trait
Stores the fixed offset (Pan/Tilt) for PTZ relative control, used to correct the target position in incremental control.
| Trait ID | Code |
|---|
| 0x50C1 | PTZOffset |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | PTZOffsetStructure | | | RV | O |
Command Definitions
PanTiltDirectionControl Command
This Command is used to perform the "PTZ direction control" operation.
Parameters
PanTiltDirectionControl Command Structure
PTZStop Command
Immediately stops all ongoing PTZ motions (pan, tilt, zoom, etc.). The PTZ remains at the current position and enters the idle state.
This Command has no parameters.
PTZRelativeMove Command
Moves the camera PTZ mechanism relative to the current position by the specified pan, tilt or zoom delta values. Independent adjustment of any combination of the three axes is supported.
PanDelta: the delta value for horizontal pan movement, in degrees. 0 means no movement; negative values move left; positive values move right.
TiltDelta: the delta value for vertical tilt movement, in degrees. 0 means no movement; negative values move down; positive values move up.
ZoomDelta: the percentage delta for zoom adjustment. 0 means no change; negative values zoom out (wider field of view); positive values zoom in (narrower field of view).
Parameters
PTZRelativeMove Command Structure
PTZCalibration Command
Triggers or stops the PTZ calibration process. Writing 0 stops the ongoing calibration; writing 1 triggers automatic calibration (re-establishing limits, correcting errors, etc.).
Parameters
PTZCalibration Command Structure
PTZSetPosition Command
Moves the camera PTZ mechanism to the specified absolute pan angle, tilt angle and optical zoom magnification. Independent setting of any combination of the three axes is supported.
Pan: target horizontal pan angle, in degrees. 0 deg is straight ahead; negative values move left, positive values move right.
Tilt: target vertical tilt angle, in degrees. 0 deg is the horizontal reference; negative values move down, positive values move up.
Zoom: target optical zoom magnification. 1.0 is the widest field of view.
Parameters
PTZSetPosition Command Structure
PTZMoveToPreset Command
Moves the camera PTZ mechanism to the position stored in the specified preset. PresetId must correspond to an item in the device's current PTZPresets list; this field is the preset ID, not the PresetScenario enumeration value.
Parameters
PTZMoveToPreset Command Structure
Effect on Receipt
After receiving the command, the device should look up the item in the current list that exactly matches PresetId and move to the complete Position of that item.
- If
PresetId does not exist, the device should return a "preset does not exist" semantic error and must not move to another position.
- If the target position is currently unreachable, the device is not calibrated or the execution conditions are not met, the device should return the corresponding failure status and must not report movement success.
- The device successfully accepting a move request does not mean the target position has been reached; the actual position should still be confirmed through status feedback such as
CurrentPTZPosition.
PTZSavePreset Command
Creates a new user preset or updates an existing user preset. If PresetId is omitted, the device automatically assigns a unique ID; if provided and it exists, the corresponding user preset is updated; if provided but does not exist, a user preset with that ID is created when the device capacity limit has not been reached. The BuiltIn of newly created or updated items must be false.
When creating a preset, Position preferentially uses the value provided by the command; if omitted, the device's current effective PTZ position is used. If neither is available, the device should reject the command and must not substitute zero coordinates. When creating without Name, the device should generate a non-empty and readable name. When updating, omitted fields retain their original values; omitting PresetScenario must not reset an existing scenario. When creating without PresetScenario, it means Custom; if explicitly provided, the field must be Custom.
This command is only used to create and update user presets. Callers must not create the Rightmost, Leftmost, Topmost, Bottommost or Center standard position presets, nor mark user presets as built-in presets. The five standard positions (if supported by the device) are provided and maintained by the device according to the PTZPresets Trait definition.
Parameters
PTZSavePreset Command Structure
Effect on Receipt
The device should first validate the command and its impact on the preset list; after validation succeeds, update the list at once and report the new PTZPresets value.
- If the specified
PresetId already corresponds to a BuiltIn=true item, the device should return a "built-in presets cannot be modified" semantic error and must not change that item or other items in the list.
- If
PresetScenario is one of the five standard positions, the device should return a "standard positions are maintained by the device" semantic error; it must not add a second identical scenario or modify a standard position through this command.
- If
PresetScenario is an unknown or reserved value, PresetId conflicts with another item, the position exceeds the valid travel, the name or field format is invalid, or the device capacity is full, the device should reject the entire command and must not apply it partially.
- For updates to existing user presets, an omitted field means the original value is retained. The device must keep
PresetId unchanged; it must not change BuiltIn=false to true.
- For newly created user presets, the device should set
BuiltIn=false. If the command omits PresetScenario, the device should set Custom; if the field is explicitly provided, the device has confirmed through the command validation rules that its value is Custom.
- On success, the device should return a success status and update and report the list; on failure, it should return a failure status and the list remains unchanged. Specific error codes use the equivalent errors defined by the Aqara business interaction protocol, and no additional error codes are allocated in this Function.
PTZRemovePreset Command
Removes the specified user preset from the PTZPresets list. PresetId must correspond to an item in the device's current list.
Parameters
PTZRemovePreset Command Structure
Effect on Receipt
- If
PresetId does not exist, the device should return a "preset does not exist" semantic error and the list remains unchanged.
- If the target item has
BuiltIn=true, the device should return a "built-in presets cannot be deleted" semantic error and the list remains unchanged.
- If the source of the target item is unknown (e.g., a legacy list lacks
BuiltIn), the device must not delete it as a user preset; it should return a failure status of unknown source or not allowed to delete.
- If the target is a user preset, the device should delete the item and report the updated list. After successful deletion, the ID can no longer be used for move, update or delete commands; the device should avoid assigning this ID to other presets within the configuration lifecycle.
- The device must not partially modify the list on failure. Specific error codes use the equivalent errors defined by the Aqara business interaction protocol, and no additional error codes are allocated in this Function.
BridgedConfiguration
Introduction
Describes the configuration information of bridged sub-devices, used in Matter/Zigbee bridging scenarios.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B2 | BridgedConfiguration | Bridged configuration |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BridgeDeviceID Trait
Represents the DeviceID of the Bridge device to which this bridging node is connected. String(32).
| Trait ID | Code |
|---|
| 0x8140 | BridgeDeviceID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | M |
Command Definitions
This Function does not contain Commands.
Introduction
Provides Matter node related information, such as the first Endpoint ID and auxiliary node topology information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B3 | MatterNodeInformation | Matter device information |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
MatteNodeFirstEndpointId Trait
Represents the first endpoint ID of the Matter device. Format: Uint16.
| Trait ID | Code |
|---|
| 0x8143 | MatteNodeFirstEndpointId |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int16 | | 0 | RV | M |
| 0x0002 | Maximum Value | int16 | | 65535 | R | O |
| 0x0003 | Minimum Value | int16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain Commands.
ThreadNetworkDiagnostics
Introduction
Provides Thread network diagnostic metrics, including channel, PAN ID, neighbor table, routing role and send/receive statistics.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B5 | ThreadNetworkDiagnostics | Thread network diagnostics |
Trait
Command
This Function does not contain Commands.
Data Types
ThreadTopologyDataTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ThreadTopologyData Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | RouterID | uint8 | M | Unique ID of the router in the Thread network. |
| 1 | Rloc16 | uint16 | M | 16-bit RLOC address in the Thread network. |
| 2 | ExtAddress | uint64 | M | Thread extended address. |
| 3 | ThreadVersion | uint64 | M | Thread Version. |
| 4 | Flags | array[uint8] | M | Node role flag bits. |
| 5 | Links | array[uint8] | M | List of other RouterIDs with which the current router has established links. |
| 6 | IPv6 | characterString | M | IPv6 address list of the node. |
| 7 | Children | list[Struct] | M | List of child devices attached to the current router. |
| 8 | ThreadVersion | uint64 | M | Thread Version. |
| 9 | Timeout | uint32 | M | Child detach timeout, in seconds. |
| 10 | Age | uint32 | M | Time since the last successful communication, in seconds. |
| 11 | Supvn | uint8 | M | Supervision interval count. |
| 12 | FullNet | boolean | M | Whether the node has fully attached to the Thread network. |
| 13 | QMsgCount | uint8 | M | Number of queued messages to be sent to the child. |
| 14 | ErrRateFrame | float | M | Frame error rate. |
| 15 | ErrRateMsg | float | M | Message error rate. |
| 16 | ConnTime | characterString | M | Connection duration of the child after joining the parent. |
| 17 | CslSync | boolean | M | Whether CSL synchronization with the parent has been completed. |
| 18 | CslPeriod | uint16 | M | CSL sampling interval period. |
| 19 | CslTimeout | uint32 | M | CSL synchronization timeout, in seconds. |
| 20 | CslChannel | uint16 | M | Physical channel used for CSL communication. |
| 21 | Flags | array[uint8] | M | Node role flag bits. |
ConnectionStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the ConnectionStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | NotConnected | Not connected |
| 0x01 | Connected | Connected |
NetworkFaultChangeTraitPresentValueStructure Type
This structure defines the Present Value field layout of the NetworkFaultChange Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Current | list[enum8] | M | The current set of detected network faults. |
| 1 | Previous | list[enum8] | M | The set of network faults detected before the change. |
ThreadPingResultTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ThreadPingResult Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ip_addr | characterString | M | Target IP address. |
| 1 | status_code | enum8 | M | Execution result status code: 0=SUCCESS, 1=TIMEOUT, 2=BUSY. |
| 2 | avg_round_trip | uint32 | O | Average RTT, in ms; present only on success. |
| 3 | max_round_trip | uint32 | O | Maximum RTT, in ms; present only on success. |
| 4 | min_round_trip | uint32 | O | Minimum RTT, in ms; present only on success. |
| 5 | loss_percent | uint32 | O | Packet loss percentage; present only on success. |
Trait Definitions
The current value should specify the RSSI of frames most recently received from a neighboring node. If there is no known recent received frame, the current value should be NULL. The current value unit is dBm, ranging from -128 dBm to 0 dBm. For Thread networks, this attribute reflects the Thread-specific RSSI.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int8 | | 0 | RV | O |
| 0x0002 | Maximum Value | int8 | | 127 | R | O |
| 0x0003 | Minimum Value | int8 | | -128 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
LQI Trait
Indicates the Link Quality Indicator (LQI) of the Thread network, reflecting the RF link quality between Thread devices. Range: 0-255.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
PANID Trait
The current value indicates the Zigbee network PAN ID.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65534 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ExtendedPANID Trait
The current value is a 64-bit unique identifier used to identify the Personal Area Network (PAN) in the Thread network. It works together with PANID to distinguish different networks. Each network has a unique ExtendedPANID, and all nodes joining the network must use the same ExtendedPANID to communicate with each other.
| Trait ID | Code |
|---|
| 0x814C | ExtendedPANID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
MeshLocalPrefix Trait
The current value should indicate the mesh-local IPv6 prefix of the Thread network the device has been configured to join. A value of null indicates that the Thread interface is currently not configured or not running.
| Trait ID | Code |
|---|
| 0x8151 | MeshLocalPrefix |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ThreadTopologyReportInterval Trait
Specifies the time interval (seconds) at which the device automatically reports Thread network topology data to the cloud.
| Trait ID | Code |
|---|
| 0x4E7A | ThreadTopologyReportInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 86400 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 86400 | RW | O |
ThreadTopologyData Trait
Describes the current Thread network topology state observed by the device.
| Trait ID | Code |
|---|
| 0x4E79 | ThreadTopologyData |
Parameters
ConnectionStatus Trait
The device's connection status to the Thread network has changed.
| Trait ID | Code |
|---|
| 0x4E35 | ConnectionStatus |
Parameters
NetworkFaultChange Trait
Changes in the set of network faults currently detected by the device.
| Trait ID | Code |
|---|
| 0x4E34 | NetworkFaultChange |
Parameters
RxBroadcastCount Trait
Total number of unique broadcast MAC frames received.
| Trait ID | Code |
|---|
| 0x4E33 | RxBroadcastCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
RxUnicastCount Trait
Total number of unique unicast MAC frames received.
| Trait ID | Code |
|---|
| 0x4E32 | RxUnicastCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
TxTotalCount Trait
Total number of unique MAC frame transmission requests.
| Trait ID | Code |
|---|
| 0x4E2E | TxTotalCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
TxUnicastCount Trait
Total number of unique unicast MAC frame transmission requests.
| Trait ID | Code |
|---|
| 0x4E2F | TxUnicastCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
TxBroadcastCount Trait
Total number of unique broadcast MAC frame transmission requests.
| Trait ID | Code |
|---|
| 0x4E30 | TxBroadcastCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
RxTotalCount Trait
Total number of unique MAC frames received.
| Trait ID | Code |
|---|
| 0x4E31 | RxTotalCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
PartitionId Trait
The Leader Partition Id of the network.
| Trait ID | Code |
|---|
| 0x4E2D | PartitionId |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
OverrunCount Trait
The number of packets discarded at ingress or egress because the buffer memory was insufficient to hold all packets.
| Trait ID | Code |
|---|
| 0x4E2C | OverrunCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
The average RSSI of all received frames.
| Trait ID | Code |
|---|
| 0x4E2B | AverageRssi |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | int8 | | 0 | RV | O |
| 0x0002 | Maximum Value | int8 | | 0 | R | O |
| 0x0003 | Minimum Value | int8 | | -128 | R | O |
NeighborTable Trait
The current value should indicate the current list of devices that make up the device's neighbor table.
| Trait ID | Code |
|---|
| 0x8150 | NeighborTable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
RoutingRole Trait
This Trait is used for access to and reporting of "routing role" data.
| Trait ID | Code |
|---|
| 0x814F | RoutingRole |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
RouteTable Trait
The current value should indicate the current list of routing-capable devices with established routes.
| Trait ID | Code |
|---|
| 0x814E | RouteTable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
NetworkName Trait
The current value should indicate the readable (displayable) name of the Thread network the node has been configured to join. A value of NULL indicates that this interface is currently not configured or not running.
| Trait ID | Code |
|---|
| 0x814D | NetworkName |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
Channel Trait
The current value indicates the Zigbee network channel number.
| Trait ID | Code |
|---|
| 0x814A | Channel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ThreadPingResult Trait
Represents the result of a ping operation performed on a Thread device. The value is a structure containing the target IP address (IpAddr, string) and a status code (StatusCode, uint8). When the status code is 0 (success), the structure also contains optional fields: AvgRoundTrip (average RTT, ms), MaxRoundTrip (maximum RTT, ms), MinRoundTrip (minimum RTT, ms) and LossPercent (packet loss rate, 0-100). When the status code is non-zero (1 = timeout, 2 = busy), these optional fields are absent.
| Trait ID | Code |
|---|
| 0x5003 | ThreadPingResult |
Parameters
Command Definitions
This Function does not contain Commands.
GarageDoorOpener
Introduction
Provides garage door control and status feedback, including open/close/stop and position status.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B6 | GarageDoorOpener | Garage door opener |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x809A | Toggle | Open/close | O |
Data Types
CurrentGarageDoorStateEnum8 Type
This enumeration defines the valid values of the Present Value of the CurrentGarageDoorState Trait.
| Value | Name | Description |
|---|
| 0x01 | Unknown | Unknown |
| 0x02 | Open | Open |
| 0x03 | Closed | Closed |
| 0x04 | Opening | Opening |
| 0x05 | Closing | Closing |
| 0x06 | NotFullyOpen | Not fully open |
| 0x07 | NotFullyClosed | Not fully closed |
TargetGarageDoorStateEnum8 Type
This enumeration defines the valid values of the Present Value of the TargetGarageDoorState Trait.
| Value | Name | Description |
|---|
| 0x00 | Closed | Closed |
| 0x01 | Open | Open |
Trait Definitions
CurrentGarageDoorState Trait
Describes the current state of the garage door. Values: 1=Unknown, 2=Open, 3=Closed, 4=Opening, 5=Closing, 6=Not Fully Open, 7=Not Fully Closed.
| Trait ID | Code |
|---|
| 0x815C | CurrentGarageDoorState |
Parameters
TargetGarageDoorState Trait
This Trait is used for access to and reporting of "target (garage) door state" data.
| Trait ID | Code |
|---|
| 0x815D | TargetGarageDoorState |
Parameters
Command Definitions
| Command ID | Name | Conformance |
|---|
| 0x809A | Toggle | O |
Toggle Command
This Command is used to perform the "open/close" operation.
This Command has no parameters.
MatterBridgeCommissioning
Introduction
Manages the capability of the Matter Bridge to share bridged devices with third-party Matter ecosystems.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B7 | MatterBridgeCommissioning | Matter Bridge sharing to third-party Matter ecosystems |
Trait
Command
Data Types
MatterDACStateEnum8 Type
This enumeration defines the valid values of the Present Value of the MatterDACState Trait.
| Value | Name | Description |
|---|
| 0x00 | LoadingDAC | LoadingDAC |
| 0x01 | FailedDAC | FailedDAC |
| 0x02 | ReadyDAC | ReadyDAC |
MatterBindStateEnum8 Type
This enumeration defines the valid values of the Present Value of the MatterBindState Trait.
| Value | Name | Description |
|---|
| 0x00 | Unbound | Unbound |
| 0x01 | Bound | Bound |
MatterPairingStateEnum8 Type
This enumeration defines the valid values of the Present Value of the MatterPairingState Trait.
| Value | Name | Description |
|---|
| 0x00 | NonMatterPairingState | Not in Matter pairing state |
| 0x01 | MatterPairingState | Matter pairing state |
| 0x02 | LimitExceeded | Limit exceeded |
| 0x03 | InvalidDAC | Invalid device attestation certificate |
| 0x04 | UnderPreparation | Preparing |
MatterBridgeSupportedEnum8 Type
This enumeration defines the valid values of the Present Value of the MatterBridgeSupported attribute.
| Value | Name | Description |
|---|
| 0 | False | False |
| 1 | True | True |
Trait Definitions
MatterPairingSwitch Trait
Writing true starts Matter pairing mode on the bridge; if not completed, pairing automatically exits after 10 minutes. Writing false immediately disables pairing. Reading indicates whether pairing mode is currently active. Values: true = enter pairing, false = turn off/disable pairing.
| Trait ID | Code |
|---|
| 0x815E | MatterPairingSwitch |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
MatterDACState Trait
Indicates the ready state of the Matter Device Attestation Certificate (DAC). 0: DAC is being obtained; 1: DAC acquisition failed; 2: DAC is ready.
| Trait ID | Code |
|---|
| 0x815F | MatterDACState |
Parameters
MatterBindState Trait
Indicates the Matter binding state of the device. 0: not yet bound to any Matter ecosystem; 1: successfully bound to at least one Matter ecosystem.
| Trait ID | Code |
|---|
| 0x8160 | MatterBindState |
Parameters
MatterOnboardingPayload Trait
Provides the onboarding information required for Matter commissioning. The value is a JSON object containing the onboarding payload string and the manual pairing code. Example: {"onboarding_payload":"MT:AR7A0OEP01C26Y2SQ10","manual_pairing_code":"0118-064-9202"}.
| Trait ID | Code |
|---|
| 0x8161 | MatterOnboardingPayload |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
MatterManufacturerList Trait
Provides the list of Matter ecosystems (fabrics) to which the device is bound. The value is a JSON array, each object containing: vendor_id (decimal integer), Manufacturer (display name string), fabric (shared trust domain identifier), node_id (device identifier string). Example format: {"list":[{"vendor_id":24582,"Manufacturer":"Google","fabric":"10001","node_id":"10001"}, ...]}.
| Trait ID | Code |
|---|
| 0x8162 | MatterManufacturerList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
MatterPairingState Trait
Indicates the current Matter pairing state or error reason. Possible values: 0x00 = not in pairing mode; 0x01 = normal pairing mode active; 0x02 = device binding limit exceeded (up to 10), remove some ecosystems and retry; 0x03 = device certificate invalid, retry later; 0x04 = preparing, retry later.
| Trait ID | Code |
|---|
| 0x8163 | MatterPairingState |
Parameters
MatterBridgeSupported Trait
Indicates whether the current gateway version supports the Matter Bridge function. If true, the App can display the "Start Matter Journey" entry and the "Bind Matter" option in the device details; if false, such entries are hidden. Values: false = not supported, true = supported.
| Trait ID | Code |
|---|
| 0x8164 | MatterBridgeSupported |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
Command Definitions
RemoveOneMatterManufacturer Command
This Command is used to perform the "remove a Matter ecosystem platform from the Matter Bridge" operation.
This Command has no parameters.
RemoveAllMatterManufacturer Command
This Command is used to perform the "remove all Matter ecosystem platforms from the Matter Bridge" operation.
This Command has no parameters.
MARSConfiguration
Introduction
Provides smart load (MARS) related configuration for load identification and smart power distribution management.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B8 | MARSConfiguration | Smart load configuration |
Trait
Command
This Function does not contain Commands.
Data Types
LoadTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the LoadType Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unspecified |
| 0x01 | Linkable | Smart load |
| 0x02 | Pulsed | Pulse control |
This structure defines the Present Value field layout of the MarsSmartLoadList Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DeviceID | characterString | M | Target load light device ID. |
| 1 | PointPath | characterString | M | Access path of the switch control state data point in the target load light device, containing Endpoint ID, Function ID, Trait ID, Parameter ID, separated by ., e.g., 2.132.32920.1. |
| 2 | SubscribeRecordId | uint32 | O | This field only applies to Zigbee protocol switch devices, indicating the data subscription record ID saved by the switch device and required between it and the target load light device. |
| 3 | GroupId | uint16 | O | This field only applies to Zigbee protocol switch devices, indicating the device group ID to which the target load light device belongs in Mars Technology smart load mode. |
Trait Definitions
LoadType Trait
Describes the type of load connected to the switch. 0: Unspecified, 1: Linkable (smart load), 2: Pulsed (pulse control).
| Trait ID | Code |
|---|
| 0x816B | LoadType |
Parameters
Used to query the list of devices that can be linked with the smart load. Currently only some lighting devices are supported.
| Trait ID | Code |
|---|
| 0x816C | MarsSmartLoadList |
Parameters
PulseDuration Trait
Defines the pulse duration of the pulse load. Unit: ms.
| Trait ID | Code |
|---|
| 0x816D | PulseDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 200 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 3000 | R | O |
| 0x0003 | Minimum Value | uint16 | | 200 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 200 | RW | O |
EnableMarsForceOff Trait
Used to control whether the MARS force off capability is enabled.
| Trait ID | Code |
|---|
| 0x5113 | EnableMarsForceOff |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
Command Definitions
This Function does not contain Commands.
CustomizedConfiguration
Introduction
Provides read/write capability for vendor or user customized extension configuration items.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00B9 | CustomizedConfiguration | Customized configuration |
Trait
Command
This Function does not contain Commands.
Data Types
StartUpOnOffEnum8 Type
This enumeration defines the valid values of the Present Value of the StartUpOnOff Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Power-on off |
| 0x01 | On | Power-on on |
| 0x02 | Toggle | Power-on toggle |
| 0x03 | Hold | Power-on memory |
Trait Definitions
EnableIndicator Trait
This Trait is used for access to and reporting of "indicator light enable" data.
| Trait ID | Code |
|---|
| 0x816E | EnableIndicator |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | tlv | | | RVW | O |
StartUpOnOff Trait
Defines the startup behavior of a set of customized configuration parameters when the device is powered on (e.g., restoring user customized configuration). It may override the default OnOff behavior.
| Trait ID | Code |
|---|
| 0x8099 | StartUpOnOff |
Parameters
Command Definitions
This Function does not contain Commands.
FreshAirControl
Introduction
Provides fresh air system control capability, supporting the introduction of outdoor air and adjustment of airflow and modes.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00BA | FreshAirControl | Fresh air control |
Trait
Command
This Function does not contain Commands.
Data Types
FreshAirModeEnum8 Type
This enumeration defines the valid values of the Present Value of the FreshAirMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Manual | Manual |
| 0x01 | Auto | Auto |
| 0x02 | Exhaust | Exhaust |
| 0x03 | HeatExchange | Heat exchange |
| 0x04 | InternalCirculation | Recirculation |
| 0x05 | ExternalCirculation | Outdoor circulation |
| 0x06 | PowerSaving | Energy saving |
| 0x07 | Strong | Boost |
| 0x08 | FreshAir | Fresh air |
| 0x09 | Bypass | Bypass |
Trait Definitions
FreshAirMode Trait
This Trait defines the fresh air mode.
| Trait ID | Code |
|---|
| 0x4E27 | FreshAirMode |
Parameters
FreshAirBrand Trait
Represents the brand name of the fresh air (ventilation) system connected to the current thermostat. This value is a readable text string.
| Trait ID | Code |
|---|
| 0x515C | FreshAirBrand |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
FilterRemainingDuration Trait
Represents the remaining effective service life of the filter in the system, in seconds. This value is dynamically updated by the device based on actual operating time or usage, and reported periodically. When the value drops to 0, it indicates the filter is exhausted and needs replacement or cleaning.
| Trait ID | Code |
|---|
| 0x515D | FilterRemainingDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
FreshAirErrorCode Trait
Represents the fault code of the fresh air device, used to diagnose operational anomalies. This value is a readable text string.
| Trait ID | Code |
|---|
| 0x5162 | FreshAirErrorCode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
FilterRemainingPercent Trait
Represents the remaining effective service life of the filter as a percentage; 100 means the filter is brand new, 0 means the filter is completely exhausted and needs replacement or cleaning. This value is calculated and reported by the device based on actual operating time or usage.
| Trait ID | Code |
|---|
| 0x5166 | FilterRemainingPercent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 100 | RV | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 1 | R | O |
| 0x0007 | Default Value | float | | 100 | RW | O |
Command Definitions
This Function does not contain Commands.
ScreenDisplay
Introduction
Manages screen display related hardware properties, such as resolution, brightness, backlight and display state.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00BB | ScreenDisplay | Screen display |
Trait
Command
Data Types
ScreensaverStyleEnum32 Type
This enumeration defines the valid values of the Present Value of the ScreensaverStyle Trait.
| Value | Name | Description |
|---|
| 0x00 | DigitalClock | Digital clock |
| 0x01 | FamousArt | Masterpiece painting |
| 0x02 | PhotoAlbum | Album |
| 0x03 | AnalogClock | Analog clock |
| 0x04 | Weather | Weather |
| 0x05 | RhythmNotes | Rhythm notes |
| 0x06 | Environment | Ambient |
| 0x07 | WeatherUpdates | Dynamic weather |
| 0x08 | Cat | Cat |
| 0x09 | ColorNumbers | Colorful digits |
WakeDistanceSettingEnum32 Type
This enumeration defines the valid values of the Present Value of the WakeDistanceSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Level0 | 0 |
| 0x01 | Level1 | Level 1 |
| 0x02 | Level2 | Level 2 |
| 0x03 | Level3 | Level 3 |
| 0x04 | Level4 | Level 4 |
| 0x05 | Level5 | Level 5 |
| 0x06 | Level6 | Level 6 |
| 0x07 | Level7 | Level 7 |
| 0x08 | Level8 | Level 8 |
| 0x09 | Level9 | Level 9 |
| 0x0A | Level10 | Level 10 |
WakeUpScreenSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the WakeUpScreenSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Home | Enter home page |
| 0x01 | Screensaver | Enter screensaver |
ClearPanelConfigTypeEnum8 Type
This enumeration defines the panel configuration types that the ClearPanelConfig Command can clear.
| Value | Name | Description |
|---|
| 0x01 | ClearHomeDSL | Clear home page DSL |
ClearPanelConfig Command Structure Type
Parameter structure of the ClearPanelConfig Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ConfigType | ClearPanelConfigTypeEnum8 | M | The panel configuration type to clear. |
DownloadDSLConfigItem Structure Type
Structure of a single DSL configuration item in the DownloadDSL Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Url | characterString | M | Configuration file download URL. |
| 1 | Md5 | characterString | M | File MD5 (32-character hexadecimal string). |
| 2 | Ord | int32 | M | Order index, used to apply configurations in order. |
| 3 | Id | characterString | M | Configuration unique identifier. |
| 4 | PreviewUrl | characterString | O | Relative path of the screensaver configuration preview image on the cloud file service. Main screen configuration items should omit or leave it empty. |
DownloadDSL Command Structure Type
Parameter structure of the DownloadDSL Command.
DownloadDSLResponseResultItem Structure Type
Structure of the processing result of a single configuration item in the DownloadDSLResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Id | characterString | M | Configuration unique identifier (corresponding to the id in the request). |
| 1 | ResultCode | int32 | M | Result code: 0 means success, -1 means failure. |
| 2 | ErrorMessage | characterString | O | Error message; usually returned only when ResultCode is -1. |
DownloadDSLResponse Structure Type
Parameter structure of the DownloadDSLResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Items | list[DownloadDSLResponseResultItem Structure] | O | List of main screen DSL configuration item processing results, in the same order as the Items in the request. |
| 1 | ScreensaverItems | list[DownloadDSLResponseResultItem Structure] | O | List of screensaver DSL configuration item processing results, in the same order as the ScreensaverItems in the request. |
DeliverThemeResource Command Structure Type
Parameter structure of the DeliverThemeResource Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Id | characterString | M | Communication identifier of this theme resource delivery (theme ID identifier). |
| 1 | Version | characterString | M | The theme version number corresponding to this resource package. |
| 2 | Path | characterString | M | Relative file path of the theme resource zip/bin package on the server (Theme Square). |
| 3 | Hash | characterString | M | Theme package file validation identifier (MD5/Hash). |
DeliverThemeResourceResponse Command Structure Type
Parameter structure of the DeliverThemeResourceResponse Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Id | characterString | M | Communication identifier of this theme resource delivery (corresponding to the Id in the request). |
| 1 | ResultCode | int32 | M | Processing result code: 0 means success, -1 means failure. |
| 2 | ErrorMessage | characterString | O | Failure reason description; should be omitted on success. |
DeviceDataRefresh Command Structure Type
Parameter structure of the DeviceDataRefresh Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Action | enum8 | M | Action; default value is 1. |
TriggerWeatherUpdate Command Structure Type
Parameter structure of the TriggerWeatherUpdate Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Action | enum8 | M | Action; default value is 1. |
Trait Definitions
ScreenOnOff Trait
Controls the display power state through a boolean value: 0 means the screen is immediately turned off (backlight completely off), 1 means the screen is turned on and the previous frame is restored.
| Trait ID | Code |
|---|
| 0x4FF7 | ScreenOnOff |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | O | 0 | RVW | O |
| 0x0007 | Default Value | boolean | O | 0 | RW | O |
ThemeSquareSupport Trait
Indicates whether the screen device supports the Theme Square function. true means supported, false means not supported. This Trait is read-only and reportable, reported by the device according to its own capability.
| Trait ID | Code |
|---|
| 0x519A | ThemeSquareSupport |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DisplayLocale Trait
This Trait is used for access to and reporting of "screen display language" data, representing the language-region code, conforming to the RFC 5646 (BCP 47) standard.
| Language Code | Language Name |
|---|
| af | Afrikaans |
| af-ZA | Afrikaans |
| ar | Arabic |
| ar-AE | Arabic (UAE) |
| ar-BH | Arabic (Bahrain) |
| ar-DZ | Arabic (Algeria) |
| ar-EG | Arabic (Egypt) |
| ar-IQ | Arabic (Iraq) |
| ar-JO | Arabic (Jordan) |
| ar-KW | Arabic (Kuwait) |
| ar-LB | Arabic (Lebanon) |
| ar-LY | Arabic (Libya) |
| ar-MA | Arabic (Morocco) |
| ar-OM | Arabic (Oman) |
| ar-QA | Arabic (Qatar) |
| ar-SA | Arabic (Saudi Arabia) |
| ar-SY | Arabic (Syria) |
| ar-TN | Arabic (Tunisia) |
| ar-YE | Arabic (Yemen) |
| az | Azerbaijani |
| az-AZ | Azerbaijani (Latin) |
| az-AZ | Azerbaijani (Cyrillic) |
| be | Belgian |
| be-BY | Belgian |
| bg | Bulgarian |
| bg-BG | Bulgarian |
| bs-BA | Bosnian (Latin, Bosnia and Herzegovina) |
| ca | Catalan |
| ca-ES | Catalan |
| cs | Czech |
| cs-CZ | Czech |
| cy | Welsh |
| cy-GB | Welsh |
| da | Danish |
| da-DK | Danish |
| de | German |
| de-AT | German (Austria) |
| de-CH | German (Switzerland) |
| de-DE | German (Germany) |
| de-LI | German (Liechtenstein) |
| de-LU | German (Luxembourg) |
| dv | Divehi |
| dv-MV | Divehi |
| el | Greek |
| el-GR | Greek |
| en | English |
| en-AU | English (Australia) |
| en-BZ | English (Belize) |
| en-CA | English (Canada) |
| en-CB | English (Caribbean) |
| en-GB | English (UK) |
| en-IE | English (Ireland) |
| en-JM | English (Jamaica) |
| en-NZ | English (New Zealand) |
| en-PH | English (Philippines) |
| en-TT | English (Trinidad) |
| en-US | English (US) |
| en-ZA | English (South Africa) |
| en-ZW | English (Zimbabwe) |
| eo | Esperanto |
| es | Spanish |
| es-AR | Spanish (Argentina) |
| es-BO | Spanish (Bolivia) |
| es-CL | Spanish (Chile) |
| es-CO | Spanish (Colombia) |
| es-CR | Spanish (Costa Rica) |
| es-DO | Spanish (Dominican Republic) |
| es-EC | Spanish (Ecuador) |
| es-ES | Spanish (Traditional) |
| es-ES | Spanish (International) |
| es-GT | Spanish (Guatemala) |
| es-HN | Spanish (Honduras) |
| es-MX | Spanish (Mexico) |
| es-NI | Spanish (Nicaragua) |
| es-PA | Spanish (Panama) |
| es-PE | Spanish (Peru) |
| es-PR | Spanish (Puerto Rico (US)) |
| es-PY | Spanish (Paraguay) |
| es-SV | Spanish (El Salvador) |
| es-UY | Spanish (Uruguay) |
| es-VE | Spanish (Venezuela) |
| et | Estonian |
| et-EE | Estonian |
| eu | Basque |
| eu-ES | Basque |
| fa | Farsi |
| fa-IR | Farsi |
| fi | Finnish |
| fi-FI | Finnish |
| fo | Faroese |
| fo-FO | Faroese |
| fr | French |
| fr-BE | French (Belgium) |
| fr-CA | French (Canada) |
| fr-CH | French (Switzerland) |
| fr-FR | French (France) |
| fr-LU | French (Luxembourg) |
| fr-MC | French (Monaco) |
| gl | Galician |
| gl-ES | Galician |
| gu | Gujarati |
| gu-IN | Gujarati |
| he | Hebrew |
| he-IL | Hebrew |
| hi | Hindi |
| hi-IN | Hindi |
| hr | Croatian |
| hr-BA | Croatian (Bosnia and Herzegovina) |
| hr-HR | Croatian |
| hu | Hungarian |
| hu-HU | Hungarian |
| hy | Armenian |
| hy-AM | Armenian |
| id | Indonesian |
| id-ID | Indonesian |
| is | Icelandic |
| is-IS | Icelandic |
| it | Italian |
| it-CH | Italian (Switzerland) |
| it-IT | Italian (Italy) |
| ja | Japanese |
| ja-JP | Japanese |
| ka | Georgian |
| ka-GE | Georgian |
| kk | Kazakh |
| kk-KZ | Kazakh |
| kn | Kannada |
| kn-IN | Kannada |
| ko | Korean |
| ko-KR | Korean (South Korea) |
| kok | Konkani |
| kok-IN | Konkani |
| ky | Kyrgyz |
| ky-KG | Kyrgyz (Cyrillic) |
| lt | Lithuanian |
| lt-LT | Lithuanian |
| lv | Latvian |
| lv-LV | Latvian |
| mi | Maori |
| mi-NZ | Maori |
| mk | Macedonian |
| mk-MK | Macedonian (FYROM) |
| mn | Mongolian |
| mn-MN | Mongolian (Cyrillic) |
| mr | Marathi |
| mr-IN | Marathi |
| ms | Malay |
| ms-BN | Malay (Brunei Darussalam) |
| ms-MY | Malay (Malaysia) |
| mt | Maltese |
| mt-MT | Maltese |
| nb | Norwegian (Bokmal) |
| nb-NO | Norwegian (Bokmal) (Norway) |
| nl | Dutch |
| nl-BE | Dutch (Belgium) |
| nl-NL | Dutch (Netherlands) |
| nn-NO | Norwegian (Nynorsk) (Norway) |
| ns | Northern Sotho |
| ns-ZA | Northern Sotho |
| pa | Punjabi |
| pa-IN | Punjabi |
| pl | Polish |
| pl-PL | Polish |
| pt | Portuguese |
| pt-BR | Portuguese (Brazil) |
| pt-PT | Portuguese (Portugal) |
| qu | Quechua |
| qu-BO | Quechua (Bolivia) |
| qu-EC | Quechua (Ecuador) |
| qu-PE | Quechua (Peru) |
| ro | Romanian |
| ro-RO | Romanian |
| ru | Russian |
| ru-RU | Russian |
| sa | Sanskrit |
| sa-IN | Sanskrit |
| se | Northern Sami |
| se-FI | Northern Sami (Finland) |
| se-FI | Skolt Sami (Finland) |
| se-FI | Inari Sami (Finland) |
| se-NO | Northern Sami (Norway) |
| se-NO | Lule Sami (Norway) |
| se-NO | Southern Sami (Norway) |
| se-SE | Northern Sami (Sweden) |
| se-SE | Lule Sami (Sweden) |
| se-SE | Southern Sami (Sweden) |
| sk | Slovak |
| sk-SK | Slovak |
| sl | Slovenian |
| sl-SI | Slovenian |
| sq | Albanian |
| sq-AL | Albanian |
| sr-BA | Serbian (Latin, Bosnia and Herzegovina) |
| sr-BA | Serbian (Cyrillic, Bosnia and Herzegovina) |
| sr-SP | Serbian (Latin) |
| sr-SP | Serbian (Cyrillic) |
| sv | Swedish |
| sv-FI | Swedish (Finland) |
| sv-SE | Swedish |
| sw | Swahili |
| sw-KE | Swahili |
| syr | Syriac |
| syr-SY | Syriac |
| ta | Tamil |
| ta-IN | Tamil |
| te | Telugu |
| te-IN | Telugu |
| th | Thai |
| th-TH | Thai |
| tl | Tagalog |
| tl-PH | Tagalog (Philippines) |
| tn | Tswana |
| tn-ZA | Tswana |
| tr | Turkish |
| tr-TR | Turkish |
| ts | Tsonga |
| tt | Tatar |
| tt-RU | Tatar |
| uk | Ukrainian |
| uk-UA | Ukrainian |
| ur | Urdu |
| ur-PK | Urdu |
| uz | Uzbek |
| uz-UZ | Uzbek (Latin) |
| uz-UZ | Uzbek (Cyrillic) |
| vi | Vietnamese |
| vi-VN | Vietnamese |
| xh | Bantu |
| xh-ZA | Bantu |
| zh | Chinese |
| zh-CN | Chinese (Simplified) |
| zh-HK | Chinese (Hong Kong) |
| zh-MO | Chinese (Macau) |
| zh-SG | Chinese (Singapore) |
| zh-TW | Chinese (Traditional) |
| zu | Zulu |
| zu-ZA | Zulu |
| Trait ID | Code |
|---|
| 0x813C | DisplayLocale |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
DNDTimePeriod Trait
This Trait is used to define the Do Not Disturb time period for screen display.
This Trait is reused in this Function; for the full definition, see DNDTimePeriod under the IndicationLight Function.
| Trait ID | Code |
|---|
| 0x8139 | DNDTimePeriod |
EnableDNDMode Trait
This Trait is used to control whether the Do Not Disturb mode for screen display is enabled.
This Trait is reused in this Function; for the full definition, see EnableDNDMode under the IndicationLight Function.
| Trait ID | Code |
|---|
| 0x8138 | EnableDNDMode |
ScreenBrightness Trait
A Trait that controls the screen brightness level, with a value range of 1% to 100%.
| Trait ID | Code |
|---|
| 0x4E36 | ScreenBrightness |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | O | 50 | RW | O |
SupportsDslConfig Trait
Indicates whether the device supports DSL (Domain-Specific Language) configuration. A value of true means the device can parse and apply DSL-based configurations; false means the capability is not supported.
| Trait ID | Code |
|---|
| 0x507D | SupportsDslConfig |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | O | 0 | RV | O |
| 0x0007 | Default Value | boolean | O | 0 | RW | O |
StandbyTimeout Trait
This Trait is used to set the timeout duration for the screen to automatically enter standby, in seconds. 0 means never automatically enter standby.
| Trait ID | Code |
|---|
| 0x50F2 | StandbyTimeout |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 15 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 3600 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 5 | R | O |
| 0x0007 | Default Value | uint16 | | 15 | RW | O |
KeyToneEnable Trait
This Trait is used to control the screen key sound switch. 0 means off, 1 means on.
| Trait ID | Code |
|---|
| 0x50F3 | KeyToneEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ThemeUpdateFlag Trait
This Trait represents the theme update flag value. If the delivered value is greater than the current value, it indicates that a new theme update is available.
| Trait ID | Code |
|---|
| 0x50F4 | ThemeUpdateFlag |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
CurrentThemeSetting Trait
This Trait is used to represent the current theme setting value, encoded with the high 16 bits as themeId and the low 16 bits as version.
| Trait ID | Code |
|---|
| 0x50F5 | CurrentThemeSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
WallpaperSetting Trait
This Trait is used to represent the current wallpaper type setting value: 1-9 are local themes, 10 is the album, 11-20 are cloud themes, and 21 and above are cloud wallpapers.
| Trait ID | Code |
|---|
| 0x50F6 | WallpaperSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
AlwaysOnInStandby Trait
This Trait is used to control whether the screen stays always on in standby/screensaver state. 0 means off (default value), 1 means on.
| Trait ID | Code |
|---|
| 0x50F7 | AlwaysOnInStandby |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DarkScreenOffEnable Trait
Dark screen-off enable. Enables or disables the dark screen-off function. When this function is on, if the ambient light dims below the preset threshold, the screen automatically turns off to save power and improve viewing comfort; when off, the screen does not automatically turn off due to dimming ambient light. Values: 0 = False (off), 1 = True (on).
| Trait ID | Code |
|---|
| 0x517A | DarkScreenOffEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
WakeUpScreenSetting Trait
Wake-up screen setting. Used to set the interface automatically entered after the screen wakes from the wake-up interface; it can be configured to enter the home page or the screensaver. Values: 0 = enter home page, 1 = enter screensaver.
| Trait ID | Code |
|---|
| 0x517B | WakeUpScreenSetting |
Parameters
WakeDistanceSetting Trait
Sets the smart wake distance/sensitivity level.
| Trait ID | Code |
|---|
| 0x5100 | WakeDistanceSetting |
Parameters
SmartWakeEnabled Trait
Enables or disables the smart wake function.
| Trait ID | Code |
|---|
| 0x5102 | SmartWakeEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ScreensaverStyle Trait
This Trait is used for access to and reporting of "screensaver style" data.
| Trait ID | Code |
|---|
| 0x4EE2 | ScreensaverStyle |
Parameters
Command Definitions
DownloadDSL Command
This command is used to batch download DSL (Domain-Specific Language) configuration files, supporting the simultaneous delivery of main screen and screensaver configuration items.
The device should download each configuration file, verify integrity using MD5, and apply the configurations in the order specified by ord.
Parameters
DownloadDSL Command Structure
Upstream Result
After completing the download and application, the device SHALL report the processing result of each configuration item through the DownloadDSLResponse Command.
DownloadDSLResponse Command
This command is used to report the processing results of each DownloadDSL configuration item, supporting separate returns for main screen and screensaver configuration items.
Parameters
DownloadDSLResponse Structure
DeliverThemeResource Command
Theme resource package delivery. The server notifies the screen device through this command (invokeCommand, delivered as a request) to download the theme resource package from the specified file path, carrying information such as the communication identifier, theme version number and file validation identifier (MD5/Hash). After receiving it, the screen device downloads and validates the resource package based on the provided information.
Parameters
DeliverThemeResource Command Structure
Upstream Result
After the screen device completes the download, validation and application, it SHALL report the processing result through the DeliverThemeResourceResponse Command.
DeliverThemeResourceResponse Command
Theme resource package delivery response. Used for the screen device, after receiving theme resource package delivery data, to report the processing result to the server via the response of invokeCommand based on the resource package download, validation and application results.
Parameters
DeliverThemeResourceResponse Command Structure
DeviceDataRefresh Command
This command instructs the screen device (launcher) to comprehensively refresh data, including re-requesting the current dashboard list, card data and other related information from the server. After receiving the command, the device should obtain the latest data and update the display accordingly.
Parameters
DeviceDataRefresh Command Structure
TriggerWeatherUpdate Command
This command triggers the device to immediately update weather data from the configured weather service.
Parameters
TriggerWeatherUpdate Command Structure
ClearPanelConfig Command
Clear panel configuration. After the user confirms the clearing, the device should clear the panel configuration content of the type specified by ConfigType. Currently it supports clearing the home page DSL configuration of the screen device; other configuration types may be extended later.
Parameters
ClearPanelConfig Command Structure
ValveControl
Introduction
Provides automatic or manual valve control capability for precisely regulating water/gas flow.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00BC | ValveControl | Valve control |
Trait
Command
Data Types
CurrentValveStateEnum8 Type
This enumeration defines the valid values of the Present Value of the CurrentValveState Trait.
| Value | Name | Description |
|---|
| 0x00 | Closed | Closed |
| 0x01 | Open | Open |
| 0x02 | Transitioning | Transition |
OpenWithDuration Command Structure Type
Parameter structure of the OpenWithDuration Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresentValue | float | M | Current value; default value is 1. |
Trait Definitions
RemainingDuration Trait
RemainingDuration refers to the remaining time the valve will continue to run before automatically closing, in seconds.
| Trait ID | Code |
|---|
| 0x4E46 | RemainingDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 100000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | O | 0 | RW | O |
| 0x000D | Is Null | boolean | | False | RVW | O |
CurrentValveState Trait
CurrentValveState represents the current working state of the valve.
| Trait ID | Code |
|---|
| 0x4E47 | CurrentValveState |
Parameters
DefaultOpenDuration Trait
DefaultOpenDuration represents the default duration (seconds) the valve remains open when the OpenDuration field is not specified.
| Trait ID | Code |
|---|
| 0x4E5D | DefaultOpenDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 1 | RVW | O |
| 0x0002 | Maximum Value | float | | 100000.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | O | 1 | RW | O |
Command Definitions
Close Command
Close command.
This Command has no parameters.
Open Command
Open command.
This Command has no parameters.
OpenWithDuration Command
Open for a specified duration.
Parameters
OpenWithDuration Command Structure
FilterMonitoring
Introduction
Continuously monitors the usage status and remaining service life of various filter elements (e.g., HEPA, activated carbon).
Function Identification
| Function ID | Code | Name |
|---|
| 0x00BD | FilterMonitoring | Filter monitoring |
Trait
Command
Data Types
FilterTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the FilterType Trait.
| Value | Name | Description |
|---|
| 0x00 | HEPA | HEPA |
| 0x01 | Activated Carbon | Activated carbon |
| 0x02 | Photocatalytic | Photocatalyst |
| 0x03 | UV | Ultraviolet |
ChangeIndicationEnum8 Type
This enumeration defines the valid values of the Present Value of the ChangeIndication Trait.
| Value | Name | Description |
|---|
| 0x00 | OK | OK |
| 0x01 | Warming | Warning |
| 0x02 | Critical | Critical |
Trait Definitions
FilterType Trait
FilterType defines the filter type.
| Trait ID | Code |
|---|
| 0x4E4A | FilterType |
Parameters
ChangeIndication Trait
ChangeIndication defines the state of the filter life.
| Trait ID | Code |
|---|
| 0x4E49 | ChangeIndication |
Parameters
Condition Trait
Represents the remaining life of the filter, as a percentage %.
| Trait ID | Code |
|---|
| 0x4E48 | Condition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 100 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 100 | RW | O |
Command Definitions
ResetCondition Command
ResetCondition indicates resetting the filter.
This Command has no parameters.
OperationalState
Introduction
Describes the current operating state of the device, such as idle, running, paused, error, etc.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00BE | OperationalState | Device state |
Trait
Command
Data Types
OperationalErrorEnum16 Type
This enumeration defines the valid values of the Present Value of the OperationalError Trait.
| Value | Name | Description |
|---|
| 0x00 | NoError | No error |
| 0x01 | UnableToStartOrResume | Unable to start or resume |
| 0x02 | UnableToCompleteOperation | Unable to complete operation |
| 0x03 | CommandInvalidInState | Command invalid in state |
OperationalStateEnum16 Type
This enumeration defines the valid values of the Present Value of the OperationalState Trait.
| Value | Name | Description |
|---|
| 0x00 | Stopped | Stopped |
| 0x01 | Running | Running |
| 0x02 | Paused | Paused |
| 0x03 | Error | Error |
Trait Definitions
OperationalError Trait
OperationalError refers to the device or system being unable to perform its intended function.
| Trait ID | Code |
|---|
| 0x4E4C | OperationalError |
Parameters
OperationalState Trait
OperationalState refers to the current functional state or working condition of the device, indicating whether it is active or idle. It defines the device's operational status.
| Trait ID | Code |
|---|
| 0x4E4B | OperationalState |
Parameters
Command Definitions
Start Command
Start.
This Command has no parameters.
Stop Command
This command should request the device to stop the current operation.
This Command has no parameters.
Pause Command
This Command is used to perform the "pause" operation.
This Command has no parameters.
Resume Command
Resume.
This Command has no parameters.
Flow
Introduction
Measures and reports the flow rate of liquid or gas.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00BF | Flow | Flow |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
CurrentFlow Trait
CurrentFlow represents the current flow rate value, in m^3/h.
| Trait ID | Code |
|---|
| 0x4E4D | CurrentFlow |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 65535.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CumulativeFlow Trait
Represents the cumulative throughput recorded by the flow meter within the current counter generation, used to calculate the total medium delivered and historical usage changes. Unit: m^3. Device reboot must not reset the reading or the generation; reset, uncompensated rollback, or flow meter replacement must increment the Counter Generation.
| Trait ID | Code |
|---|
| 0x51BE | CumulativeFlow |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 100000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Mode
Introduction
Provides the device characteristic mode interface, supporting switching among multiple predefined modes.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C0 | Mode | Mode |
Trait
Command
Data Types
ChangeToModeResponseEnum16 Type
This enumeration defines the valid values of the Present Value of the ChangeToModeResponse Trait.
| Value | Name | Description |
|---|
| 0x00 | Success | Success |
| 0x01 | UnsupportedMode | Unsupported mode |
| 0x02 | GenericFailure | General failure |
| 0x03 | InvalidInMode | Invalid in mode |
| 0x41 | Stuck | Stuck |
| 0x42 | DustBinMissing | Dust bin missing |
| 0x43 | DustBinFull | Dust bin full |
| 0x44 | WaterTankEmpty | Water tank empty |
| 0x45 | WaterTankMissing | Water tank missing |
| 0x46 | WaterTankLidOpen | Water tank lid not closed |
| 0x47 | MopCleaningPadMissing | Mop cleaning pad missing |
| 0x48 | BatteryLow | Battery low |
ChangeToMode Command Structure Type
Parameter structure of the ChangeToMode Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CurrentMode | uint16 | M | Current mode. |
Trait Definitions
CurrentMode Trait
CurrentMode represents the current working state or setting of the device, with values from a predefined set of options.
| Trait ID | Code |
|---|
| 0x4E4E | CurrentMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | enum8 | | 0 | RV | M |
| 0x0002 | Maximum Value | enum8 | | 255 | R | O |
| 0x0003 | Minimum Value | enum8 | | 0 | R | O |
| 0x0007 | Default Value | enum8 | | 0 | RW | O |
ChangeToModeResponse Trait
ChangeToModeResponse is a response message or state indicating the result of a request to switch the device to a specific mode.
| Trait ID | Code |
|---|
| 0x4E4F | ChangeToModeResponse |
Parameters
Command Definitions
ChangeToMode Command
ChangeToMode is used to set the device mode.
Parameters
ChangeToMode Command Structure
VacuumOperationalState
Introduction
Describes the current operating state of the robot vacuum, such as cleaning, returning to charge, charging, etc.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C1 | VacuumOperationalState | Robot vacuum state |
Trait
Command
Data Types
VacuumOperationalErrorEnum16 Type
This enumeration defines the valid values of the Present Value of the VacuumOperationalError Trait.
| Value | Name | Description |
|---|
| 0x00 | NoError | No error |
| 0x01 | UnableToStartOrResume | Unable to start or resume |
| 0x02 | UnableToCompleteOperation | Unable to complete operation |
| 0x03 | CommandInvalidInState | Command invalid in state |
| 0x40 | FailedToFindChargingDock | Charging dock not found |
| 0x41 | Stuck | Stuck |
| 0x42 | DustBinMissing | Dust bin missing |
| 0x43 | DustBinFull | Dust bin full |
| 0x44 | WaterTankEmpty | Water tank empty |
| 0x45 | WaterTankMissing | Water tank missing |
| 0x46 | WaterTankLidOpen | Water tank lid not closed |
| 0x47 | MopCleaningPadMissing | Mop cleaning pad missing |
VacuumOperationalStateEnum16 Type
This enumeration defines the valid values of the Present Value of the VacuumOperationalState Trait.
| Value | Name | Description |
|---|
| 0x00 | Stopped | Stopped |
| 0x01 | Running | Running |
| 0x02 | Paused | Paused |
| 0x03 | Error | Error |
| 0x40 | SeekingCharger | Looking for charger |
| 0x41 | Charging | Charging |
| 0x42 | Docked | Docked |
Trait Definitions
VacuumOperationalError Trait
VacuumOperationalError refers to specific error types encountered when the device or system cannot perform the expected function.
| Trait ID | Code |
|---|
| 0x4E51 | VacuumOperationalError |
Parameters
VacuumOperationalState Trait
VacuumOperationalState refers to the current operating state or mode of the vacuum device.
| Trait ID | Code |
|---|
| 0x4E50 | VacuumOperationalState |
Parameters
Command Definitions
GoHome Command
The Vacuum GoHome command is used to instruct the robot vacuum to return to the charging dock or base station.
This Command has no parameters.
Start Command
Start.
This Command has no parameters.
Pause Command
This Command is used to perform the "pause" operation.
This Command has no parameters.
Stop Command
This command should request the device to stop the current operation.
This Command has no parameters.
Resume Command
Resume.
This Command has no parameters.
RefrigeratorState
Introduction
Describes the refrigerator operating state, including idle, cooling, defrosting, error, etc.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C2 | RefrigeratorState | Refrigerator state |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
RefrigeratorAlarm Trait
RefrigeratorAlarm refers to the current refrigerator alarm state.
| Trait ID | Code |
|---|
| 0x4E52 | RefrigeratorAlarm |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
Command Definitions
This Function does not contain Commands.
EVSE
Introduction
Provides Electric Vehicle Supply Equipment (EVSE) control capability, including charging start/stop, current limits and charging state.
The vehicle battery data represents the battery of the currently connected vehicle, not the spare battery of the charging pile itself. The vehicle connection state reuses EvseState, and the vehicle identifier reuses VehicleID; the vehicle battery capacity and read/write settings use the dedicated Traits under this Function.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C3 | EVSE | Electric vehicle supply equipment |
Trait
Command
Data Types
EvseStateEnum32 Type
This enumeration defines the valid values of the Present Value of the EvseState Trait.
| Value | Name | Description |
|---|
| 0x00 | NotPluggedIn | Not plugged in |
| 0x01 | PluggedInNoDemand | Plugged in, no demand |
| 0x02 | PluggedInDemand | Plugged in, with demand |
| 0x03 | PluggedInCharging | Plugged in, charging |
| 0x04 | PluggedInDischarging | Plugged in, discharging |
| 0x05 | SessionEnding | Session ended |
| 0x06 | Fault | Fault |
EvseSupplyStateEnum32 Type
This enumeration defines the valid values of the Present Value of the EvseSupplyState Trait.
| Value | Name | Description |
|---|
| 0x00 | Disabled | Disabled |
| 0x01 | ChargingEnabled | Charging allowed |
| 0x02 | DischargingEnabled | Discharging allowed |
| 0x03 | DisabledError | Disabled error |
| 0x04 | DisabledDiagnostics | Disabled diagnostics |
| 0x05 | EnabledChargingandDischarging | Charging and discharging allowed |
EvseFaultStateEnum32 Type
This enumeration defines the valid values of the Present Value of the EvseFaultState Trait.
| Value | Name | Description |
|---|
| 0x00 | NoError | No error |
| 0x01 | MeterFailure | Meter fault |
| 0x02 | OverVoltage | Over voltage |
| 0x03 | UnderVoltage | Under voltage |
| 0x04 | OverCurrent | Over current |
| 0x05 | ContactWetFailure | Wet contact fault |
| 0x06 | ContactDryFailure | Dry contact fault |
| 0x07 | GroundFault | Ground fault |
| 0x08 | PowerLoss | Power loss |
| 0x09 | PowerQuality | Power quality |
| 0x0A | PilotShortCircuit | Pilot short circuit |
| 0x0B | EmergencyStop | Emergency stop |
| 0x0C | EVDisconnected | EV disconnected |
| 0x0D | WrongPowerSupply | Power source error |
| 0x0E | LiveNeutralSwap | Line and neutral swapped |
| 0x0F | OverTemperature | Over temperature |
| 0xFF | Other | Other |
EnableChargingUntil Command Structure Type
Parameter structure of the EnableChargingUntil Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PresentValue | int32 | M | Current value. |
Trait Definitions
EvseState Trait
EVSEState represents the current state of the Electric Vehicle Supply Equipment (EVSE).
| Trait ID | Code |
|---|
| 0x4E53 | EvseState |
Parameters
EvseSupplyState Trait
EvseSupplyState represents the current supply state of the Electric Vehicle Supply Equipment (EVSE).
| Trait ID | Code |
|---|
| 0x4E54 | EvseSupplyState |
Parameters
MinChargeCurrent Trait
MinChargeCurrent refers to the minimum current level at which the electric vehicle can charge. Unit: A.
| Trait ID | Code |
|---|
| 0x4E5A | MinChargeCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | O | 0 | RW | O |
VehicleID Trait
VehicleID is the unique identifier assigned to each electric vehicle (EV).
| Trait ID | Code |
|---|
| 0x4E59 | VehicleID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | string32 | | | RV | M |
BatteryCapacity Trait
BatteryCapacity represents the nominal capacity of the vehicle battery associated with the EVSE, in W·h. This value describes the battery of the connected vehicle, not the spare battery capacity of the EVSE itself; if the device provides the currently dischargeable capacity, VehicleDischargeableCapacity should be used.
| Trait ID | Code |
|---|
| 0x4E58 | BatteryCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | O | 0 | RW | O |
MaxChargeCurrent Trait
MaxChargeCurrent refers to the maximum current level at which the electric vehicle can charge. Unit: A.
| Trait ID | Code |
|---|
| 0x4E57 | MaxChargeCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | O | 0 | RW | O |
CurrentFlow Trait
CurrentFlow represents the current flow rate value, in m^3/h.
| Trait ID | Code |
|---|
| 0x4E4D | CurrentFlow |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 65535.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | O | 0 | RW | O |
ChargingEnabledUntil Trait
ChargingEnabledUntil refers to the duration for which the charging process of the electric vehicle (EV) or device is allowed to continue.
| Trait ID | Code |
|---|
| 0x4E56 | ChargingEnabledUntil |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 6 | RV | M |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | O | 6 | RW | O |
| 0x000D | Is Null | boolean | | False | RV | O |
EvseFaultState Trait
EvseFaultState represents the current fault state of the Electric Vehicle Supply Equipment (EVSE).
| Trait ID | Code |
|---|
| 0x4E55 | EvseFaultState |
Parameters
BatPercentRemaining Trait
Indicates the remaining battery power percentage.
| Trait ID | Code |
|---|
| 0x80CD | BatPercentRemaining |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | O | 50 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | O | 50 | RW | O |
VehicleDischargeableCapacity Trait
The vehicle battery dischargeable capacity represents the energy capacity available for discharge from the currently connected vehicle, in W·h.
| Trait ID | Code |
|---|
| 0x5219 | VehicleDischargeableCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000 W·h | No fixed default; report the current vehicle value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
VehicleDischargeableCapacityPercent Trait
The vehicle battery dischargeable capacity percentage represents the ratio of the capacity available for discharge to its percentage baseline, in %.
| Trait ID | Code |
|---|
| 0x521A | VehicleDischargeableCapacityPercent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-100 % | No fixed default; report the current vehicle value | RV | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
VehicleDischargeableRemainingCapacity Trait
The vehicle battery remaining dischargeable capacity represents the energy that can still be discharged from the vehicle battery, in W·h.
| Trait ID | Code |
|---|
| 0x521B | VehicleDischargeableRemainingCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000 W·h | No fixed default; report the current vehicle value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
VehicleDischargeableRemainingCapacityPercent Trait
The vehicle battery remaining dischargeable capacity percentage represents the ratio of the remaining dischargeable energy to its percentage baseline, in %.
| Trait ID | Code |
|---|
| 0x521C | VehicleDischargeableRemainingCapacityPercent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-100 % | No fixed default; report the current vehicle value | RV | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
VehicleUsedCapacity Trait
The vehicle battery used capacity represents the energy capacity consumed from the vehicle battery, in W·h.
| Trait ID | Code |
|---|
| 0x521D | VehicleUsedCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000 W·h | No fixed default; report the current vehicle value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
VehicleUsedCapacityPercent Trait
The vehicle battery used capacity percentage represents the ratio of consumed energy to its percentage baseline, in %.
| Trait ID | Code |
|---|
| 0x521E | VehicleUsedCapacityPercent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-100 % | No fixed default; report the current vehicle value | RV | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
EVSERatedChargingCapability Trait
The charger rated charging capacity represents the nominal maximum charging power of the device, in W.
| Trait ID | Code |
|---|
| 0x521F | EVSERatedChargingCapability |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
EVSERatedDischargingCapability Trait
The discharger rated discharging capacity represents the nominal maximum discharging power of the device, in W.
| Trait ID | Code |
|---|
| 0x5220 | EVSERatedDischargingCapability |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
MinDischargeCurrent Trait
MinDischargeCurrent represents the minimum current the vehicle is allowed to discharge, in A.
| Trait ID | Code |
|---|
| 0x5221 | MinDischargeCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-10000 A | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
MaxDischargeCurrent Trait
MaxDischargeCurrent represents the maximum current the vehicle is allowed to discharge, in A.
| Trait ID | Code |
|---|
| 0x5222 | MaxDischargeCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-10000 A | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
EVSEChargeDischargePower Trait
The instantaneous charge/discharge power of the charge/discharge machine is represented by a signed value, in W; a positive value indicates charging, a negative value indicates discharging.
| Trait ID | Code |
|---|
| 0x5223 | EVSEChargeDischargePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | -5000000-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | -5000000 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
EVSEChargeDischargeCurrent Trait
The instantaneous charge/discharge current of the charge/discharge machine is represented by a signed value, in A; a positive value indicates charging, a negative value indicates discharging.
| Trait ID | Code |
|---|
| 0x5224 | EVSEChargeDischargeCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | -10000-10000 A | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 10000 | R | O |
| 0x0003 | Minimum Value | float | | -10000 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
EVSEChargeDischargeVoltage Trait
The instantaneous charge/discharge voltage of the charge/discharge machine represents the current voltage reported by the device, in V.
| Trait ID | Code |
|---|
| 0x5225 | EVSEChargeDischargeVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 V | No fixed default; report the current value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
EVSERatedVoltage Trait
The charge/discharge machine rated voltage represents the nominal working voltage of the device, in V.
| Trait ID | Code |
|---|
| 0x5226 | EVSERatedVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 V | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
VehicleChargingAmountSetting Trait
The vehicle charging amount setting represents the target charging energy, in W·h.
| Trait ID | Code |
|---|
| 0x5227 | VehicleChargingAmountSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | 0-1000000000 W·h | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 1000000000 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
VehicleChargingAmountPercentSetting Trait
The vehicle charging amount percentage setting represents the ratio of the target charging amount to the capacity baseline, in %.
| Trait ID | Code |
|---|
| 0x5228 | VehicleChargingAmountPercentSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-100 % | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
VehicleChargingPowerSetting Trait
The vehicle charging power setting represents the target charging power, in W.
| Trait ID | Code |
|---|
| 0x5229 | VehicleChargingPowerSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | 0-5000000 W | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 5000000 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
VehicleDischargingPowerSetting Trait
The vehicle discharging power setting represents the target discharging power, in W.
| Trait ID | Code |
|---|
| 0x522A | VehicleDischargingPowerSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | 0-5000000 W | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 5000000 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
VehicleChargingCurrentSetting Trait
The vehicle charging current setting represents the target charging current, in A.
| Trait ID | Code |
|---|
| 0x522B | VehicleChargingCurrentSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-10000 A | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | float | | 10000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
VehicleDischargingCurrentSetting Trait
The vehicle discharging current setting represents the target discharging current, in A.
| Trait ID | Code |
|---|
| 0x522C | VehicleDischargingCurrentSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-10000 A | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | float | | 10000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
EVSEIndependentRatedVoltage Trait
The standalone rated voltage represents the nominal output voltage of the EVSE when operating standalone, in V.
| Trait ID | Code |
|---|
| 0x522D | EVSEIndependentRatedVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 V | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ChargerDischargerType Trait
The charge/discharge machine type represents the category name of the charging/discharging device displayed externally. This Trait retains the type text provided by the device and is not used as an operating state.
| Trait ID | Code |
|---|
| 0x5240 | ChargerDischargerType |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | Category name defined by the device | No fixed default | RV | O |
Command Definitions
DisableCharging Command
DisableCharging Command.
This Command has no parameters.
EnableCharging Command
EnableCharging Command.
This Command has no parameters.
EnableChargingUntil Command
EnableChargingUntil Command.
Parameters
EnableChargingUntil Command Structure
VacuumRunMode
Introduction
Controls the robot vacuum run mode, such as auto, edge, spot, etc.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C4 | VacuumRunMode | Robot vacuum run mode |
Trait
Command
Data Types
ChangeToModeResponseEnum16 Type
This enumeration defines the valid values of the Present Value of the ChangeToModeResponse Trait.
| Value | Name | Description |
|---|
| 0x00 | Success | Success |
| 0x01 | UnsupportedMode | Unsupported mode |
| 0x02 | GenericFailure | General failure |
| 0x03 | InvalidInMode | Invalid in mode |
| 0x41 | Stuck | Stuck |
| 0x42 | DustBinMissing | Dust bin missing |
| 0x43 | DustBinFull | Dust bin full |
| 0x44 | WaterTankEmpty | Water tank empty |
| 0x45 | WaterTankMissing | Water tank missing |
| 0x46 | WaterTankLidOpen | Water tank lid not closed |
| 0x47 | MopCleaningPadMissing | Mop cleaning pad missing |
| 0x48 | BatteryLow | Battery low |
ChangeToMode Command Structure Type
Parameter structure of the ChangeToMode Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CurrentMode | uint16 | M | Current mode. |
Trait Definitions
CurrentMode Trait
CurrentMode represents the current working state or setting of the device, with values from a predefined set of options.
| Trait ID | Code |
|---|
| 0x4E4E | CurrentMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | enum8 | | 0 | RV | M |
| 0x0002 | Maximum Value | enum8 | | 255 | R | O |
| 0x0003 | Minimum Value | enum8 | | 0 | R | O |
| 0x0007 | Default Value | enum8 | | 0 | RW | O |
ChangeToModeResponse Trait
ChangeToModeResponse is a response message or state indicating the result of a request to switch the device to a specific mode.
| Trait ID | Code |
|---|
| 0x4E4F | ChangeToModeResponse |
Parameters
Command Definitions
ChangeToMode Command
ChangeToMode is used to set the device mode.
Parameters
ChangeToMode Command Structure
VacuumCleanMode
Introduction
Controls the robot vacuum cleaning mode, such as standard, strong, quiet, etc.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C5 | VacuumCleanMode | Robot vacuum cleaning mode |
Trait
Command
Data Types
ChangeToModeResponseEnum16 Type
This enumeration defines the valid values of the Present Value of the ChangeToModeResponse Trait.
| Value | Name | Description |
|---|
| 0x00 | Success | Success |
| 0x01 | UnsupportedMode | Unsupported mode |
| 0x02 | GenericFailure | General failure |
| 0x03 | InvalidInMode | Invalid in mode |
| 0x41 | Stuck | Stuck |
| 0x42 | DustBinMissing | Dust bin missing |
| 0x43 | DustBinFull | Dust bin full |
| 0x44 | WaterTankEmpty | Water tank empty |
| 0x45 | WaterTankMissing | Water tank missing |
| 0x46 | WaterTankLidOpen | Water tank lid not closed |
| 0x47 | MopCleaningPadMissing | Mop cleaning pad missing |
| 0x48 | BatteryLow | Battery low |
ChangeToMode Command Structure Type
Parameter structure of the ChangeToMode Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CurrentMode | uint16 | M | Current mode. |
Trait Definitions
CurrentMode Trait
CurrentMode represents the current working state or setting of the device, with values from a predefined set of options.
| Trait ID | Code |
|---|
| 0x4E4E | CurrentMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | enum8 | | 0 | RV | M |
| 0x0002 | Maximum Value | enum8 | | 255 | R | O |
| 0x0003 | Minimum Value | enum8 | | 0 | R | O |
| 0x0007 | Default Value | enum8 | | 0 | RW | O |
ChangeToModeResponse Trait
ChangeToModeResponse is a response message or state indicating the result of a request to switch the device to a specific mode.
| Trait ID | Code |
|---|
| 0x4E4F | ChangeToModeResponse |
Parameters
Command Definitions
ChangeToMode Command
ChangeToMode is used to set the device mode.
Parameters
ChangeToMode Command Structure
TemperatureControl
Introduction
Provides temperature setting and adjustment capability for target temperature control of constant-temperature devices.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C6 | TemperatureControl | Temperature control |
Trait
Command
Data Types
ChangeTemperatureLevel Command Structure Type
Parameter structure of the ChangeTemperatureLevel Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SetTemperatureLevel | uint8 | M | Set temperature level; default value is 0. |
ChangeTemperature Command Structure Type
Parameter structure of the ChangeTemperature Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | SetTemperature | float | M | Set temperature; default value is 20. |
Trait Definitions
SetTemperatureLevel Trait
SetTemperatureLevel allows the user to adjust the temperature to preset levels. Parameter Supported Values indicates the list of supported levels.
| Trait ID | Code |
|---|
| 0x4E5C | SetTemperatureLevel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0006 | Supported Value | list[characterString] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
SetTemperature Trait
SetTemperature allows the user to specify and adjust the target temperature of the device or system. Unit: deg C.
| Trait ID | Code |
|---|
| 0x4E5B | SetTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 20 | RVW | O |
| 0x0002 | Maximum Value | float | | 32 | R | O |
| 0x0003 | Minimum Value | float | | 5 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 20 | RW | O |
Command Definitions
ChangeTemperatureLevel Command
Allows the user to adjust the temperature to preset levels. Parameter Supported Values indicates the list of supported temperature levels.
Parameters
ChangeTemperatureLevel Command Structure
ChangeTemperature Command
ChangeTemperature allows the user to specify and adjust the target temperature of the device or system.
Parameters
ChangeTemperature Command Structure
Introduction
Describes media input source management and switching, supporting selection of the current playback source and the input list.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C7 | MediaInput | Playback source |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x4E5E | MediaInput | Playback source | M |
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9C53 | SelectInput | Select playback source | M |
Data Types
Parameter structure of the SelectInput Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | MediaInput | uint8 | M | Input source; default value is 0. |
Trait Definitions
MediaInput provides the list of available input sources and provides select and rename commands.
| Trait ID | Code |
|---|
| 0x4E5E | MediaInput |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | enum8 | | 0 | RVW | M |
| 0x0007 | Default Value | enum8 | | 0 | RW | O |
Command Definitions
This Command is used to perform the "select playback source" operation.
Parameters
SelectInput Command Structure
HEPAFilterMonitoring
Introduction
Monitors HEPA filter usage, remaining life and replacement reminders.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C8 | HEPAFilterMonitoring | HEPA filter monitoring |
Trait
Command
Data Types
ChangeIndicationEnum8 Type
This enumeration defines the valid values of the Present Value of the ChangeIndication Trait.
| Value | Name | Description |
|---|
| 0x00 | OK | OK |
| 0x01 | Warming | Warning |
| 0x02 | Critical | Critical |
Trait Definitions
ChangeIndication Trait
ChangeIndication defines the state of the filter life.
| Trait ID | Code |
|---|
| 0x4E49 | ChangeIndication |
Parameters
Condition Trait
Represents the remaining life of the filter, as a percentage %.
| Trait ID | Code |
|---|
| 0x4E48 | Condition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 100 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 100 | RW | O |
Command Definitions
ResetCondition Command
ResetCondition indicates resetting the filter.
This Command has no parameters.
ActivatedCarbonFilterMonitoring
Introduction
Monitors activated carbon filter usage, remaining life and replacement reminders.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00C9 | ActivatedCarbonFilterMonitoring | Activated carbon filter monitoring |
Trait
Command
Data Types
ChangeIndicationEnum8 Type
This enumeration defines the valid values of the Present Value of the ChangeIndication Trait.
| Value | Name | Description |
|---|
| 0x00 | OK | OK |
| 0x01 | Warming | Warning |
| 0x02 | Critical | Critical |
Trait Definitions
ChangeIndication Trait
ChangeIndication defines the state of the filter life.
| Trait ID | Code |
|---|
| 0x4E49 | ChangeIndication |
Parameters
Condition Trait
Represents the remaining life of the filter, as a percentage %.
| Trait ID | Code |
|---|
| 0x4E48 | Condition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 100 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 100 | RW | O |
Command Definitions
ResetCondition Command
ResetCondition indicates resetting the filter.
This Command has no parameters.
ThreadBorderRouter
Introduction
Manages the operation and configuration of the Thread border router and the Thread network it carries.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00CA | ThreadBorderRouter | Border router |
Trait
Command
Data Types
SetActiveDatasetRequest Command Structure Type
Parameter structure of the SetActiveDatasetRequest Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ActiveDataset | characterString | M | Active dataset. |
SetPendingDatasetRequest Command Structure Type
Parameter structure of the SetPendingDatasetRequest Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | PendingDataset | characterString | M | Pending dataset. |
Trait Definitions
BorderRouterName Trait
This Trait is used for access to and reporting of "border router name" data.
| Trait ID | Code |
|---|
| 0x4E5F | BorderRouterName |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | M |
BorderAgentID Trait
The unique ID of the Thread border router device.
| Trait ID | Code |
|---|
| 0x4E60 | BorderAgentID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | string32 | | 0 | RV | M |
| 0x0007 | Default Value | string32 | | 0 | RW | O |
ThreadVersion Trait
The Thread version of the border router.
| Trait ID | Code |
|---|
| 0x4E61 | ThreadVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
InterfaceEnabled Trait
Whether the Thread interface is enabled.
| Trait ID | Code |
|---|
| 0x4E62 | InterfaceEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RV | M |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
ActiveDatasetTimestamp Trait
The timestamp extracted from the Active Dataset value of the Thread node configuration to which the border router is connected.
| Trait ID | Code |
|---|
| 0x4E63 | ActiveDatasetTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0007 | Default Value | uint64 | | 0 | RW | O |
| 0x000D | Is Null | boolean | | False | RV | O |
PendingDatasetTimestamp Trait
The timestamp extracted from the Pending Dataset value of the Thread node configuration to which the border router is connected.
| Trait ID | Code |
|---|
| 0x4E64 | PendingDatasetTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0007 | Default Value | uint64 | | 0 | RW | O |
| 0x000D | Is Null | boolean | | False | RV | O |
DatasetResponse Trait
If no dataset is configured (as requested by the active or pending dataset), this field should be set to empty.
| Trait ID | Code |
|---|
| 0x4E65 | DatasetResponse |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | 0 | RV | O |
| 0x0007 | Default Value | characterString | | 0 | RW | O |
| 0x000D | Is Null | boolean | | False | RV | O |
Command Definitions
GetActiveDatasetRequest Command
This Command is used to perform the "request Active dataset" operation.
This Command has no parameters.
GetPendingDatasetRequest Command
This Command is used to perform the "request Pending dataset" operation.
This Command has no parameters.
SetActiveDatasetRequest Command
This Command is used to perform the "set Active dataset request" operation.
Parameters
SetActiveDatasetRequest Command Structure
SetPendingDatasetRequest Command
This Command is used to perform the "set Pending dataset request" operation.
Parameters
SetPendingDatasetRequest Command Structure
ThemePack
Introduction
Manages device theme pack resources, including theme download, switching and version information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00CB | ThemePack | Theme pack |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
ThemeID Trait
This Trait is used for access to and reporting of "theme ID" data.
| Trait ID | Code |
|---|
| 0x4E78 | ThemeID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
ThemeVersion Trait
Theme version.
| Trait ID | Code |
|---|
| 0x4E77 | ThemeVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
Command Definitions
This Function does not contain Commands.
WiFiNetworkDiagnostics
Introduction
Provides standardized Wi-Fi network diagnostic metrics to assist in troubleshooting connection quality and link state.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00CC | WiFiNetworkDiagnostics | WiFi network diagnostics |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9C68 | ResetCounts | Reset counts | O |
Data Types
WiFiVersionEnum8 Type
This enumeration defines the valid values of the Present Value of the WiFiVersion Trait.
| Value | Name | Description |
|---|
| 0x00 | a | a |
| 0x01 | b | b |
| 0x02 | g | g |
| 0x03 | n | n |
| 0x04 | ac | ac |
| 0x05 | ax | ax |
| 0x06 | ah | ah |
SecurityTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the SecurityType Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unspecified |
| 0x01 | None | None |
| 0x02 | WEP | WEP |
| 0x03 | WPA | WPA |
| 0x04 | WPA2 | WPA2 |
| 0x05 | WPA3 | WPA3 |
NetworksTraitPresentValueStructure Type
This structure defines the Present Value field layout of the Networks Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | NetworkID | characterString | M | Network identifier. SSID for Wi-Fi; Extended PAN ID for Thread; OS network interface name for Ethernet. Maximum length 32 bytes. |
| 1 | Connected | boolean | M | Whether this network is connected. Wi-Fi: associated with an AP; Ethernet: link active; Thread: in an operational mesh. |
Trait Definitions
CurrentMaxRate Trait
Indicates the current maximum PHY rate of data transmission (bits per second).
| Trait ID | Code |
|---|
| 0x0013 | CurrentMaxRate |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
PacketUnicastTxCount Trait
PacketUnicastTxCount should indicate the number of unicast packets transmitted by the node.
| Trait ID | Code |
|---|
| 0x0012 | PacketUnicastTxCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
PacketUnicastRxCount Trait
PacketUnicastRxCount should indicate the number of unicast packets received by the node.
| Trait ID | Code |
|---|
| 0x0011 | PacketUnicastRxCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
PacketMulticastTxCount Trait
PacketMulticastTxCount should indicate the number of multicast packets transmitted by the node.
| Trait ID | Code |
|---|
| 0x0010 | PacketMulticastTxCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
PacketMulticastRxCount Trait
Indicates the number of multicast packets received by the node.
| Trait ID | Code |
|---|
| 0x000F | PacketMulticastRxCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
BeaconLostCount Trait
BeaconLostCount should indicate the number of beacons lost as detected by the node.
| Trait ID | Code |
|---|
| 0x000E | BeaconLostCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
WiFiVersion Trait
WiFiVersion should indicate the version of the 802.11 standard currently used by the node.
| Trait ID | Code |
|---|
| 0x000D | WiFiVersion |
Parameters
SecurityType Trait
SecurityType should indicate the Wi-Fi security type currently in use.
| Trait ID | Code |
|---|
| 0x000C | SecurityType |
Parameters
BSSID Trait
BSSID should indicate the BSSID of the Wi-Fi network the node is currently connected to.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
OverrunCount Trait
The number of packets discarded at ingress or egress because the buffer memory was insufficient to hold all packets.
| Trait ID | Code |
|---|
| 0x4E2C | OverrunCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
Networks Trait
The Networks Trait should indicate the network configurations available on the network interface.
| Trait ID | Code |
|---|
| 0x0014 | Networks |
Parameters
SupportedWiFiBands Trait
SupportedWiFiBands should indicate all bands supported by the configured Wi-Fi interface.
| Trait ID | Code |
|---|
| 0x0015 | SupportedWiFiBands |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
Command Definitions
ResetCounts Command
Receiving this command should reset the following attributes to 0:
This Command has no parameters.
ZigbeeNetworkDiagnostics
Introduction
Provides Zigbee network diagnostics capability, including channel, PAN, neighbor and routing information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00CD | ZigbeeNetworkDiagnostics | Zigbee network diagnostics |
Trait
Command
This Function does not contain Commands.
Data Types
RebootReasonEnum8 Type
This enumeration defines the valid values of the Present Value of the RebootReason Trait.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unknown |
| 0x01 | PowerOnReboot | Power-on reboot |
| 0x02 | BrownOutReset | Low-voltage reset |
| 0x03 | SoftwareWatchdogReset | Software watchdog reset |
| 0x04 | HardwareWatchdogReset | Hardware watchdog reset |
| 0x05 | SoftwareUpdateCompleted | Software update completed |
| 0x06 | SoftwareReset | Software reboot |
PreOperationModeEnum8 Type
This enumeration defines the valid values of the Present Value of the PreOperationMode Trait.
| Value | Name | Description |
|---|
| 0x00 | UnjoinedMode | Not joined mode |
| 0x01 | NewlyJoinedMode | Newly joined mode |
| 0x02 | PollingMode | Warehouse polling mode |
| 0x03 | UserMode | User mode |
| 0x04 | DegradedMode | Sub-health mode |
| 0x05 | RejoinMode | Warehouse reconnection mode |
CurOperationModeEnum8 Type
This enumeration defines the valid values of the Present Value of the CurOperationMode Trait.
| Value | Name | Description |
|---|
| 0x00 | UnjoinedMode | Not joined mode |
| 0x01 | NewlyJoinedMode | Newly joined mode |
| 0x02 | PollingMode | Warehouse polling mode |
| 0x03 | UserMode | User mode |
| 0x04 | DegradedMode | Sub-health mode |
| 0x05 | RejoinMode | Warehouse reconnection mode |
CCAModeEnum8 Type
This enumeration defines the valid values of the Present Value of the CCAMode Trait.
| Value | Name | Description |
|---|
| 0x00 | CCA1 | CCA1 mode |
| 0x01 | CCA1 | CCA2 mode |
ZigbeeNeighborInfo Type
This structure defines the information of a single Zigbee neighbor node.
| ID | Name | Type | Constraint | Quality | Default | Access | Conformance |
|---|
| 0x0000 s | NeighborAddr | uint16 | | | | R | O |
| 0x0001 s | NeighborDescriptor | uint8 | | | | R | O |
| 0x0002 s | NeighborLqi | uint8 | | | | R | O |
NeighborAddr Field
This field should specify the network address of the Zigbee neighbor node.
NeighborDescriptor Field
This field should specify the descriptor byte of the Zigbee neighbor node.
It is an 8-bit unsigned integer that combines the three parts of information, DeviceType, RxOnWhenIdle and Relationship, encoded into the same byte.
7 6 5 4 3 2 1 0
+--------+------------+------------+----------+
|Reserved|Relationship|RxOnWhenIdle|DeviceType|
| 1 bit | 3 bit | 2 bit | 2 bit |
+--------+------------+------------+----------+
Relationship Field
This field should specify the relationship between the Zigbee neighbor node and the current device.
| Value | Name | Summary | Conformance |
|---|
| 0x00 s | Parent | Parent node of the current device | M |
| 0x01 s | Child | Child node of the current device | M |
| 0x02 s | Sibling | Peer node of the current device | M |
| 0x03 s | Unknown | Unknown relationship | M |
RxOnWhenIdle Field
This field should specify whether the neighbor node keeps its receiver on when idle.
| Value | Name | Summary | Conformance |
|---|
| 0x00 s | RX on when idle | Keep receiver on when idle | M |
| 0x01 s | RX off when idle | Turn receiver off when idle | M |
DeviceType Field
This field should specify the neighbor node type.
| Value | Name | Summary | Conformance |
|---|
| 0x00 s | Coordinator | Coordinator | M |
| 0x01 s | Router | Router | M |
| 0x02 s | EndDevice | End device | M |
| 0x03 s | Unknown | Unknown type | M |
NeighborLqi Field
This field should specify the Link Quality Indicator (LQI) value of the Zigbee neighbor node.
DeviceUnbindReasonTypeEnum8 Type
This enumeration defines the valid values of the Type field in the DeviceUnbindReason structure.
| Value | Name | Description |
|---|
| 0x00 | None | No reason |
| 0x01 | UserManualReset | User manually reset the device |
| 0x02 | CloudDelete | Cloud deletion and unbind |
| 0x03 | GatewayActiveDelete | Gateway proactively deleted and unbound |
| 0x04 | ChildCountExceed | Sub-device count limit exceeded |
| 0x05 | BatchAddExceed | Batch add limit exceeded |
| 0x06 | PollingTimeout | Polling timeout |
| 0x07 | IeeeAddressNotFound | IEEE address not found |
| 0x08 | DeviceAnnounceMissed | Device Announce not received |
DeviceUnbindReasonTraitPresentValueStructure Type
This structure defines the Present Value field layout of the DeviceUnbindReason Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Type | DeviceUnbindReasonTypeEnum8 | M | Unbind operation type. |
| 1 | Time | uint32 | M | Offline/unbind event occurrence time (UTC second-level timestamp). |
| 2 | PrevDel | boolean | M | Whether delete protection is enabled. |
| 3 | Did | characterString | O | DID of the removed sub-device. |
| 4 | Model | characterString | O | Model of the removed sub-device. |
Trait Definitions
ZigbeeNextHopMac Trait
Defines the Zigbee MAC address of the next-hop device.
| Trait ID | Code |
|---|
| 0x4E84 | ZigbeeNextHopMac |
Parameters
This Function has no additional parameters.
Detailed Description
ZigbeeNetworkDiagnostics is used to summarize diagnostic data such as Zigbee network operating state, link quality, retransmission statistics, neighbor/routing information and reboot reasons.
The goal of this Function is to help gateways, debugging tools and cloud diagnostic systems quickly locate link degradation, joining anomalies, reboot anomalies, message failures and neighbor relationship changes in the Zigbee network.
Applicability
This Function applies to devices that act as management nodes of the Zigbee network, usually gateways, coordinators, or public nodes with network proxy/diagnostics capability.
When a device does not have a full Zigbee network management view, it may implement only the subset of Traits consistent with its own visible network state, but should ensure that the implemented Traits are semantically complete, value-consistent and can be reported stably.
Semantic Conventions
RebootReason should reflect the reason for the most recent startup or reboot.PreOperationMode should reflect the network stage the device was in before entering the current working state.CurOperationMode should reflect the current Zigbee network operating state of the device.PANID, Channel, ZigbeeExtendedPANID should describe the Zigbee network identifier the device is currently joined to or managing.ZigbeeNeighborInfo and ZigbeeGeneralDiagnostics should carry the neighbor information list and general diagnostic statistics respectively; if the device internally uses finer-grained diagnostic metrics, they should also be organized through the structured values of these two Traits.ZigbeeDeviceInformation should carry the device's Zigbee identity and installation information; InstallCode belongs to the commissioning-secret and SHALL NOT be read back through normal diagnostic interfaces.
Trait Usage Recommendations
ZigbeeNextHopMac, ZigbeeKeySeqNumber, ZigbeeCoordNetworkKey, ZigbeeCoordMac, ZigbeeDeviceInformation are more oriented toward network security and network identity information; RebootReason, PreOperationMode, CurOperationMode are more oriented toward system state; APSRetransmissionCount, MACRetransmissionCount, NWKRetransmissionCount, RoutingAgingCountThreshold, MessageTransmissionFailureCountThreshold, EnableNWKACK, EnableAPSACK, CCAMode are more oriented toward link policy; ZigbeeTotalMessageInOneHour, ZigbeeResentMessageInOneHour, ZigbeeFrameCounter, ZigbeeAvgSuccessfulResendCount, ZigbeeFailedMessageInOneHour are more oriented toward operation statistics; ZigbeeNeighborInfo, ZigbeeGeneralDiagnostics, LQI, PANID, Channel, ZigbeeExtendedPANID are more oriented toward network observation values.
Data Update Principles
- Counter-type Traits should monotonically increase during device operation or refresh as defined by the implementation, but should not regress without cause.
- Network identifier-type Traits can be updated after network rejoin, network switching or rejoining.
- Enumeration-type Traits should always fall within their declared valid enumeration set.
- If the device temporarily cannot collect a certain diagnostic value, it should use the null value, default value or implementation-defined unavailable semantics allowed by the Trait definition, and should not output out-of-range values.
Relationship with Upper-Layer Systems
Cloud or local debugging tools can judge the following based on these Traits:
- Whether the device has successfully joined the Zigbee network.
- Whether the current Zigbee network has a large number of retransmissions, failures or routing aging.
- Whether the neighbor table shows abnormal growth, loss or link quality degradation.
- Whether the device has experienced abnormal reboots, watchdog resets or software upgrade reboots.
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ZigbeeKeySeqNumber Trait
Represents the network key sequence number currently used by the Zigbee coordinator, used to identify the key version. During Magic Pair joining, the gateway reports this attribute to the cloud or App, and the joining device must obtain the sequence number and configure it locally to ensure secure communication using the same network key as the coordinator. Default value is 0.
| Trait ID | Code |
|---|
| 0x4F53 | ZigbeeKeySeqNumber |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
ZigbeeCoordNetworkKey Trait
Used to represent the network key of the Zigbee coordinator.
| Trait ID | Code |
|---|
| 0x4F4C | ZigbeeCoordNetworkKey |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ZigbeeCoordMac Trait
Used to represent the MAC address of the Zigbee coordinator.
| Trait ID | Code |
|---|
| 0x4F4D | ZigbeeCoordMac |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
RebootReason Trait
The current value should indicate the reason for the most recent startup of the device.
| Trait ID | Code |
|---|
| 0x8149 | RebootReason |
Parameters
PreOperationMode Trait
Represents the previous Zigbee network connection state of the device.
| Trait ID | Code |
|---|
| 0x4EA9 | PreOperationMode |
Parameters
APSRetransmissionCount Trait
The number of automatic retransmission attempts by the ZigBee APS layer when a data packet does not receive an acknowledgment.
| Trait ID | Code |
|---|
| 0x4E9B | APSRetransmissionCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 3 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 20 | R | O |
| 0x0003 | Minimum Value | uint8 | | 3 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 3 | RW | O |
MACRetransmissionCount Trait
Indicates the number of retransmissions at the MAC layer during packet transmission.
| Trait ID | Code |
|---|
| 0x4EA5 | MACRetransmissionCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 3 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 14 | R | O |
| 0x0003 | Minimum Value | uint8 | | 3 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 3 | RW | O |
NWKRetransmissionCount Trait
Indicates the number of retransmissions at the network layer during packet transmission.
| Trait ID | Code |
|---|
| 0x4EA8 | NWKRetransmissionCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 3 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 20 | R | O |
| 0x0003 | Minimum Value | uint8 | | 3 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 3 | RW | O |
RoutingAgingCountThreshold Trait
The aging count threshold setting for device packet routing.
| Trait ID | Code |
|---|
| 0x4EA7 | RoutingAgingCountThreshold |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 5 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 20 | R | O |
| 0x0003 | Minimum Value | uint8 | | 3 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 5 | RW | O |
MessageTransmissionFailureCountThreshold Trait
The threshold count setting for device packet transmission failures.
| Trait ID | Code |
|---|
| 0x4EA6 | MessageTransmissionFailureCountThreshold |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 10 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 20 | R | O |
| 0x0003 | Minimum Value | uint8 | | 3 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 10 | RW | O |
EnableNWKACK Trait
Toggles the option to enable network layer acknowledgment in network communication.
| Trait ID | Code |
|---|
| 0x4EA2 | EnableNWKACK |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableAPSACK Trait
Toggles the option to enable APS acknowledgment in network communication.
| Trait ID | Code |
|---|
| 0x4E9F | EnableAPSACK |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CurOperationMode Trait
Represents the current Zigbee network connection state of the device.
| Trait ID | Code |
|---|
| 0x4E9D | CurOperationMode |
Parameters
CCAMode Trait
Indicates the CCA state of the device.
| Trait ID | Code |
|---|
| 0x4E9C | CCAMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | CCAModeEnum8 | | 0 | RV | O |
| 0x0006 | Supported Value | list[CCAModeEnum8] | | | R | O |
ZigbeeTotalMessageInOneHour Trait
Indicates the total number of Zigbee messages sent within 1 hour.
| Trait ID | Code |
|---|
| 0x4E93 | ZigbeeTotalMessageInOneHour |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ZigbeeResentMessageInOneHour Trait
Represents the number of Zigbee messages resent within one hour.
| Trait ID | Code |
|---|
| 0x4E92 | ZigbeeResentMessageInOneHour |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ZigbeeFrameCounter Trait
The ZigBee frame counter is a unique incrementing value appended to each data frame, used to prevent replay attacks and ensure communication security.
| Trait ID | Code |
|---|
| 0x4E91 | ZigbeeFrameCounter |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ZigbeeAvgSuccessfulResendCount Trait
Indicates the average number of successful resends of Zigbee messages.
| Trait ID | Code |
|---|
| 0x4E8F | ZigbeeAvgSuccessfulResendCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ZigbeeFailedMessageInOneHour Trait
Represents the number of Zigbee messages that failed to be sent within one hour.
| Trait ID | Code |
|---|
| 0x4E90 | ZigbeeFailedMessageInOneHour |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ZigbeeNeighborInfo Trait
Provides a list of Zigbee neighbor node information.
| Trait ID | Code |
|---|
| 0x5130 | ZigbeeNeighborInfo |
Parameters
ZigbeeGeneralDiagnostics Trait
A general reporting channel for sub-device self-diagnostic information.
| Trait ID | Code |
|---|
| 0x4E8D | ZigbeeGeneralDiagnostics |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
LQI Trait
Indicates the Link Quality Indicator (LQI) of the Thread network, reflecting the RF link quality between Thread devices. Range: 0-255.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
PANID Trait
The current value indicates the Zigbee network PAN ID.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65534 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Channel Trait
The current value indicates the Zigbee network channel number.
| Trait ID | Code |
|---|
| 0x814A | Channel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ZigbeeExtendedPANID Trait
Represents the string of the 64-bit extended identifier of the Zigbee network. Together with the 16-bit PAN ID, it is used to uniquely identify the network, usually expressed as a 16-character hexadecimal string (e.g., "00124B0001234567").
| Trait ID | Code |
|---|
| 0x4FA7 | ZigbeeExtendedPANID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
DeviceUnbindReason Trait
Reports the device unbind reason and associated metadata (type, time, prevDel, did, model).
| Trait ID | Code |
|---|
| 0x50FE | DeviceUnbindReason |
Parameters
Command Definitions
This Function does not contain Commands.
ZigbeeSubscribe
Introduction
Provides Zigbee subscription capability for recording subscribable device resources, subscription capability scope and subscription record management. This Function is mainly for gateways, bridges, or Zigbee nodes with resource proxy capability, used to establish stable mappings between external resource subscription relationships and local device resources.
This capability works together with the actual resource read/write capability of the Zigbee device: the device itself does not proactively initiate subscriptions, but passively receives subscription records, and then queries or controls the corresponding resources according to the subscription records.
Function Identification
| Function ID | Code | Name |
|---|
| 0x0125 | ZigbeeSubscribe | Zigbee subscription |
Trait
Command
Data Types
SubscribeStatusCodeEnum Type
This enumeration defines the execution results of subscription-related commands.
| Value | Name | Description |
|---|
| 0x00 | Success | Success |
| 0x01 | Failure | Failure |
SubscribeData Type
This structure is used to carry resource identifiers and values.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ResourceID | uint64 | M | Resource ID (BACnet format). |
| 1 | Value | octstr16 | M | Resource value. |
SubscribeCapabilityTraitPresentValueStructure Type
This type describes the decoding semantics of the SubscribeCapability Trait. In the wire protocol, SubscribeCapability is passed through as octstr16, with the content being Header + nested CBOR Payload.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | EffectDataHeader | octstr16 | M | EffectData header, containing protocol identifier, version and control flags. |
| 1 | NestedCborPayload | octstr16 | M | Nested CBOR payload, containing the Devices capability tree, the endpoint limit for each device type, and subscribable Aqara Spec tags. |
Trait Definitions
SubscribeRecordId Trait
Records the list of subscription record IDs currently saved by the device, for query, deletion and state synchronization.
| Trait ID | Code |
|---|
| 0x5131 | SubscribeRecordId |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[uint32] | | | RV | M |
SubscribeCapability Trait
Defines the capability limit and resource tag set of the device for subscribable resources.
| Trait ID | Code |
|---|
| 0x5132 | SubscribeCapability |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | octstr16 | Header + nested CBOR Payload | | RV | M |
Command Definitions
AddSubscribeRecord Command
This command is used to request the server to add a subscription record.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | SubscribeRecord | octstr16 | M | Raw subscription record; encoding format see the SubscribeRecord Encoding specification. |
AddSubscribeRecordRsp Command
This command is used to respond to AddSubscribeRecord, indicating the result of the add operation.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | Status | SubscribeStatusCodeEnum | M | Execution status. |
| 1 | SubscribeRecordId | uint32 | M | The subscription record ID after successful addition. |
RemoveSubscribeRecord Command
This command is used to request the server to delete the specified subscription record.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | SubscribeRecordId | uint32 | M | The subscription record ID to delete. |
RemoveSubscribeRecordRsp Command
This command is used to respond to RemoveSubscribeRecord, indicating the result of the delete operation.
GetSubscribeRecord Command
This command is used to request the server to return the subscription record content by subscription record ID.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | SubscribeRecordId | uint8 | M | The subscription record ID to read. |
GetSubscribeRecordRsp Command
This command is used to respond to GetSubscribeRecord, returning the subscription record content.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | Status | SubscribeStatusCodeEnum | M | Execution status. |
| 1 | SubscribeRecord | octstr16 | M | Raw subscription record. |
PublishSubscribeData Command
This command is used by the client to publish subscription data to the server.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | DeviceDid | octstr | M | Device Did. |
| 1 | SubscribeData | list[SubscribeDataType] | M | The list of subscription data to publish. |
PublishSubscribeDataRsp Command
This command is used to respond to PublishSubscribeData, indicating the result of the publish operation.
QuerySubscribeData Command
This command is used to request the server to query subscription data by device and resource ID list.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | DeviceDid | octstr | M | Device Did. |
| 1 | ResourceID | list[uint64] | M | The list of resource IDs to query. |
QuerySubscribeDataRsp Command
This command is used to respond to QuerySubscribeData, returning the subscription data content.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | Status | SubscribeStatusCodeEnum | M | Execution status. |
| 1 | DeviceDid | octstr | M | Device Did. |
| 2 | SubscribeData | list[SubscribeDataType] | M | The list of subscription data returned by the query. |
SetSubscribeData Command
This command is used to request the server to write subscription data by device.
| Param No. | Param Name | Type | Conformance | Description |
|---|
| 0 | DeviceDid | octstr | M | Device Did. |
| 1 | SubscribeData | list[SubscribeDataType] | M | The list of subscription data to write. |
SetSubscribeDataRsp Command
This command is used to respond to SetSubscribeData, indicating the result of the write operation.
Semantic Notes
- Subscription records should use the device Did as the ownership identifier and the resource ID as the targeting target.
- Subscription capability information should be as consistent as possible with the device's actual subscribable capability and should not exaggerate the supported scope.
- Resource value encoding should remain reversible and stable, facilitating subsequent query and data synchronization.
- If a record does not exist, a resource is not supported, or the data format is invalid, the related command should return a failure status.
Encoding Specifications
SubscribeRecord Encoding Specification
This section defines the binary encoding format of the SubscribeRecord fields in the return contents of AddSubscribeRecord and GetSubscribeRecord. The encoding uses the Header + Payload architecture, where Payload is encoded with CBOR (RFC 8949).
For the general EffectData header layout, Flags semantics, ProtocolID assignment, CBOR rules and parsing flow, see the composite data encoding protocol description in this repository. The subscription record protocol uses the following fixed parameters:
ProtocolID = 0x04ProtocolName = SubscribeRecordVersion = 0PayloadFormat = CBOR
The current version defines one subscription record type: subscribing to device resource values (SubscribeType = 0x00).
Overview
The EffectData binary format consists of the following parts:
- Header: at least 2 bytes, containing the protocol identifier, version and control flags.
- Payload: a CBOR-encoded Map, used to describe the subscription record content.
The overall structure is as follows:
+------------------+-------+---------------+--------+---------+
| ProtocolVersion | Flags | PayloadLength | CRC16 | Payload |
| (1 byte) |(1 byte)| (opt 2B) |(opt 2B)| (CBOR) |
+------------------+-------+---------------+--------+---------+
required required optional optional required
Byte 0 - ProtocolVersion
This byte combines the Protocol ID and Version into a single encoding.
7 6 5 4 3 2 1 0
+-------+---------------------------+
|Version| ProtocolID |
| 2 bit | 6 bit |
+-------+---------------------------+
| Bits | Name | Range | Description |
|---|
| bit 0-5 | ProtocolID | 0-63 | Protocol identifier, 0x04 indicates SubscribeRecord. |
| bit 6-7 | Version | 0-3 | Version number. |
Encoding formula: ProtocolVersion = (Version << 6) | ProtocolID
Decoding formula: ProtocolID = ProtocolVersion & 0x3F, Version = (ProtocolVersion >> 6) & 0x03
Byte 1 - Flags
This byte is used to control whether optional fields exist and the Payload attributes.
7 6 5 4 3 2 1 0
+-------+-------+---+---+---+---+
|Reserv |Format |Cmp|Enc|CRC|Len|
| 2 bit | 2 bit | 1 | 1 | 1 | 1 |
+-------+-------+---+---+---+---+
| Bits | Name | Description |
|---|
| bit 0 | HasPayloadLength | 1 indicates the presence of the PayloadLength field (2 bytes). |
| bit 1 | HasCRC | 1 indicates the presence of the CRC16 field (2 bytes), requiring HasPayloadLength = 1. |
| bit 2 | Encrypted | Reserved bit, must be 0. |
| bit 3 | Compressed | Reserved bit, must be 0. |
| bit 4-5 | PayloadFormat | 0x00 indicates CBOR (default); other values are reserved. |
| bit 6-7 | Reserved | Reserved bit, must be 0. |
Common Flags values:
| Flags | Header Length | Fields Present |
|---|
| 0x00 | 2 bytes | Only ProtocolVersion + Flags |
| 0x01 | 4 bytes | + PayloadLength |
| 0x03 | 6 bytes | + PayloadLength + CRC16 |
Flags = 0x02 (CRC only without PayloadLength) is an illegal configuration because CRC calculation requires a clear Payload boundary.
Optional Fields
- PayloadLength (2 bytes, big-endian): present when
Flags.bit0 = 1, indicating the byte length of the Payload.
- CRC16 (2 bytes, big-endian): present when
Flags.bit1 = 1, computed using CRC-16/MODBUS over the Payload body, excluding the Header.
Payload Structure (CBOR)
The Payload is a CBOR Map (RFC 8949), and Map Keys use unsigned integers. Key values 0-23 can be encoded as a single byte in CBOR to reduce overhead.
CBOR Key Definition
Map Keys use unsigned integers (CBOR major type 0); 0-23 can be encoded as a single byte.
| Key | Name | CBOR Type | Range/Unit | Description |
|---|
| 0 | SubscribeType | unsigned int | 0 | Subscription record type, used to determine the subsequent structure. |
| 1 | RecordId | unsigned int | | Subscription record ID. |
| 2 | SourceDeviceMac | byte string | 8 bytes | MAC address of the subscribed device. |
| 3 | SourceDeviceDid | string | | Did of the subscribed device. |
| 4 | DeviceType | unsigned int | | Device type. |
| 5 | ResouceId | byte string | 8 bytes | Resource value identifier, used inside the SubscribeItem sub-Map. |
| 6 | AqaraSpec | byte string | 8 bytes | Aqara Spec tag, used inside the SubscribeItem sub-Map. |
| 7 | SubscribeItem | array of map | | List of subscribed resource items. |
SubscribeType Field
This field is used to indicate the type of the subscription record.
| Value | Name | Description | Required top-level keys (for this type) |
|---|
| 0x00 | SubscribeDevice | Subscribe to device resource values | 0, 1, 3, 4, 7 (see structure below), where key 2 is optional. |
RecordId Field
This field carries the subscription record identifier RecordId.
SourceDeviceMac Field
This field is used to indicate the source device MAC address, fixed as an 8-byte byte string.
SourceDeviceDid Field
This field is used to indicate the source device Did.
DeviceType Field
This field is used to indicate the device type. Its value is the unsigned integer device type ID defined by Aqara Spec, consistent with the numeric space used by function / trait in Aqara Spec Tags.
SubscribeItem Field
This field is a CBOR Array; each element in the array is a Map, used to describe a subscribed resource. Each Map must contain key 5 (ResouceId) and key 6 (AqaraSpec).
ResouceId Field (inside SubscribeItem)
This field is used to indicate the resource value to subscribe to. The original spelling in the protocol is ResouceId; this document stays consistent.
AqaraSpec Field (inside SubscribeItem)
This field is used to indicate the Aqara Spec tag corresponding to this resource.
SubscribeType Encoding Details
SubscribeDevice(SubscribeType = 0x00)
The CBOR Payload structure is as follows:
{
0: <SubscribeType> // [M] SubscribeType = SubscribeDevice (0x00)
1: <RecordId> // [M] Subscribe record ID
2: <SourceDeviceMac>, // [O] Subscribed device MAC
3: <SourceDeviceDid>, // [M] Subscribed device Did
4: <DeviceType> // [M] Device type
7: [ // [M] SubscribeItem
{ 5: <ResouceId>, // [M] Resource value
6: <AqaraSpec>, // [M] Aqara spec tag
},
...
]
}
In addition to requiring the mandatory keys above, the receiving end should also require at least one of SourceDeviceMac (key 2) or SourceDeviceDid (key 3) to exist, for device identity identification.
Validation Rules
The receiving end should validate:
ProtocolID is 0x04.Version is 0.- Bits 2, 3, and 6-7 of
Flags are all 0.
PayloadFormat is 0 (CBOR).- If
HasCRC = 1, then HasPayloadLength must also be 1.
Payload Validation
The receiving end should validate:
- The Payload is a CBOR Map.
SubscribeType (key 0) exists, and its value must be 0x00 in the current specification version.- At least one of
SourceDeviceMac (key 2) and SourceDeviceDid (key 3) exists.
- Each
SubscribeItem contains both ResouceId (key 5) and AqaraSpec (key 6).
- All key values that appear are in the
0-100 range.
- Undefined keys are recommended to be ignored; strict implementations may reject data containing unknown keys.
Encoding Examples
Example 1: Subscribing to the switch state of one switch circuit
The resource value (point) is 4.1.85, and the Aqara Spec is 1.132.32920.85.
EffectData parameters:
SubscribeType = SubscribeDevice (0)RecordId = 1SourceDeviceDid = lumi.54ef441000645ad1DeviceType = 12
The CBOR diagnostic representation is as follows (for illustration, ResouceId and AqaraSpec below are shown as 8-byte byte strings):
{
0: 0,
1: 1,
3: "lumi.54ef441000645ad1",
4: 12,
7: [
{ 5: h'0100000100000055',
6: h'0001008480980055'
}
]
}
Payload(CBOR,hex):
A5 00 00 01 01 03 75 6C 75 6D 69 2E 35 34 65 66 34 34 31 30 30 30 36 34 35 61 64 31 04 0C 07 81 A2 05 48 01 00 00 01 00 00 00 55 06 48 00 01 00 84 80 98 00 55
Complete EffectData (minimal Header, Flags = 0x00):
Header: 04 00
Payload: A5 00 00 01 01 03 75 6C 75 6D 69 2E 35 34 65 66 34 34 31 30 30 30 36 34 35 61 64 31 04 0C 07 81 A2 05 48 01 00 00 01 00 00 00 55 06 48 00 01 00 84 80 98 00 55
Total: 53 bytes
Parsing notes (first few bytes):
04: ProtocolVersion, indicating ProtocolID = 4, Version = 0.00: Flags, indicating no length field, no CRC, and the Payload is CBOR.A5: CBOR Map, with 5 key-value pairs (key 0, 1, 3, 4, 7).00 / 00: key 0, indicating SubscribeType = SubscribeDevice.01 / 01: key 1, indicating RecordId = 1.03 ...: key 3, indicating the UTF-8 text Did lumi.54ef441000645ad1.04 / 0C: key 4, indicating DeviceType = 12.07 ...: key 7, indicating an array of length 1, where each element is a Map containing key 5 and key 6, corresponding respectively to the 8-byte ResouceId and AqaraSpec (48 indicates a byte string of length 8).
SubscribeCapability Encoding Specification
This section defines the binary encoding format of the SubscribeCapability Trait. The encoding uses the Header + Payload architecture, where Payload is encoded with CBOR (RFC 8949).
For the general EffectData header layout, Flags semantics, ProtocolID assignment, CBOR rules and parsing flow, see the composite data encoding protocol description in this repository. The subscription capability protocol uses the following fixed parameters:
ProtocolID = 0x05ProtocolName = SubscribeCapabilityVersion = 0PayloadFormat = CBOR
The current version merges the subscription capabilities of all device types into one nested CBOR Map. Within each device type, the Aqara Spec tags are encoded as a function → trait → [parameter] hierarchy tree, omitting the endpoint segment (which is always a placeholder value in the capability scenario).
Overview
The EffectData binary format consists of the following parts:
- Header: at least 2 bytes, containing the protocol identifier, version and control flags.
- Payload: a CBOR-encoded Map, used to describe the supported device types and their subscription capability limits.
The overall structure is as follows:
+------------------+-------+---------------+--------+---------+
| ProtocolVersion | Flags | PayloadLength | CRC16 | Payload |
| (1 byte) |(1 byte)| (opt 2B) |(opt 2B)| (CBOR) |
+------------------+-------+---------------+--------+---------+
required required optional optional required
Byte 0 - ProtocolVersion
This byte combines the Protocol ID and Version into a single encoding.
7 6 5 4 3 2 1 0
+-------+---------------------------+
|Version| ProtocolID |
| 2 bit | 6 bit |
+-------+---------------------------+
| Bits | Name | Range | Description |
|---|
| bit 0-5 | ProtocolID | 0-63 | Protocol identifier, 0x05 indicates SubscribeCapability. |
| bit 6-7 | Version | 0-3 | Version number. |
Encoding formula: ProtocolVersion = (Version << 6) | ProtocolID
Decoding formula: ProtocolID = ProtocolVersion & 0x3F, Version = (ProtocolVersion >> 6) & 0x03
Byte 1 - Flags
This byte is used to control whether optional fields exist and the Payload attributes.
7 6 5 4 3 2 1 0
+-------+-------+---+---+---+---+
|Reserv |Format |Cmp|Enc|CRC|Len|
| 2 bit | 2 bit | 1 | 1 | 1 | 1 |
+-------+-------+---+---+---+---+
| Bits | Name | Description |
|---|
| bit 0 | HasPayloadLength | 1 indicates the presence of the PayloadLength field (2 bytes). |
| bit 1 | HasCRC | 1 indicates the presence of the CRC16 field (2 bytes), requiring HasPayloadLength = 1. |
| bit 2 | Encrypted | Reserved bit, must be 0. |
| bit 3 | Compressed | Reserved bit, must be 0. |
| bit 4-5 | PayloadFormat | 0x00 indicates CBOR (default); other values are reserved. |
| bit 6-7 | Reserved | Reserved bit, must be 0. |
Common Flags values:
| Flags | Header Length | Fields Present |
|---|
| 0x00 | 2 bytes | Only ProtocolVersion + Flags |
| 0x01 | 4 bytes | + PayloadLength |
| 0x03 | 6 bytes | + PayloadLength + CRC16 |
Flags = 0x02 (CRC only without PayloadLength) is an illegal configuration because CRC calculation requires a clear Payload boundary.
Optional Fields
- PayloadLength (2 bytes, big-endian): present when
Flags.bit0 = 1, indicating the byte length of the Payload.
- CRC16 (2 bytes, big-endian): present when
Flags.bit1 = 1, computed using CRC-16/MODBUS over the Payload body, excluding the Header.
Payload Structure (CBOR)
The Payload is a CBOR Map (RFC 8949), and Map Keys use unsigned integers. Key values 0-23 can be encoded as a single byte in CBOR to reduce overhead.
CBOR Key Definition
Map Keys use unsigned integers (CBOR major type 0); 0-23 can be encoded as a single byte.
The fixed key space is shared by the top-level Payload Map and the Devices entry Maps:
- The top-level Payload Map uses key
0 (Devices).
- Each element in the
Devices array uses keys 1, 2, 3.
Inside AqaraSpecTree (key 3), Map Keys no longer use this fixed table, but directly use the numeric function and trait values themselves.
| Key | Name | CBOR Type | Range/Unit | Description |
|---|
| 0 | Devices | array of map | | List of subscription capability entries for each device type. |
| 1 | DeviceType | unsigned int | | Device type ID defined by Aqara Spec, located in each Devices entry. |
| 2 | MaxEndpointNum | unsigned int | 1-255 | The maximum number of distinct endpoints allowed to subscribe for this device type, located in each Devices entry. |
| 3 | AqaraSpecTree | map | | The Aqara Spec hierarchy tree supported for subscription by this device type, located in each Devices entry. |
Devices Field
This field is a CBOR Array; each Map in the array describes the subscription capability of one device type. An empty array indicates that the server currently does not support subscription for any device type.
DeviceType Field (inside Devices entries)
This field is used to indicate the device type corresponding to the capability entry, whose value is the unsigned integer device type ID defined by Aqara Spec. The same DeviceType may only appear once in a single Payload.
MaxEndpointNum Field (inside Devices entries)
This field is used to indicate how many distinct endpoints the server allows subscribing for this device type.
AqaraSpecTree Field (inside Devices entries)
This field uses a hierarchical CBOR Map to describe the set of Aqara Spec tags subscribable for this device type, with the encoding levels as follows:
function → trait → [ parameter, ... ]
An Aqara Spec Tag consists of four parts: endpoint, function, trait and parameter, all 16-bit unsigned integers. In SubscribeCapability:
- endpoint is the placeholder segment at the capability layer and must be omitted when encoding; when the receiving end restores the tree path to a complete Tag, it should treat its logical value as
0xFFFF.
- function is used as the outer Map Key (unsigned integer).
- trait is used as the inner Map Key (unsigned integer), located under each function.
- parameter is used as the CBOR Array element corresponding to each trait. Values are usually small (most do not exceed 16), so they can often be encoded as a single byte.
Each path function F → trait T → parameter P can be expanded into a logical Aqara Spec: (endpoint=0xFFFF, function=F, trait=T, parameter=P).
Encoding constraints are as follows:
function, trait and parameter must be unsigned integers.- In the same tree, each
function key may appear only once; under the same function, each trait key may appear only once.
- In the parameter array corresponding to the same
(function, trait), each parameter may appear only once, and it is recommended to arrange them in ascending order.
- An empty Map
{} indicates that this device type currently has no subscribable Aqara Spec tags.
Payload Encoding Shape
The CBOR Payload structure is as follows:
{
0: [ // [M] Devices
{
1: <DeviceType>, // [M] Device type
2: <MaxEndpointNum>, // [M] Max endpoint count
3: { // [M] AqaraSpecTree
<function>: { // [M] function as map key
<trait>: [ <parameter>, ... ], // [M] trait as map key; parameter array
...
},
...
}
},
...
]
}
Validation Rules
The receiving end should validate:
ProtocolID is 0x05.Version is 0.- Bits 2, 3, and 6-7 of
Flags are all 0.
PayloadFormat is 0 (CBOR).- If
HasCRC = 1, then HasPayloadLength must also be 1.
Payload Validation
The receiving end should validate:
- The Payload is a CBOR Map.
Devices (key 0) exists and its type is Array.- Each element in
Devices is a Map and must contain DeviceType (key 1), MaxEndpointNum (key 2) and AqaraSpecTree (key 3).
- Each
DeviceType is an unsigned integer device type ID defined by Aqara Spec.
DeviceType values must be unique in a single Payload.- Each
MaxEndpointNum must be an unsigned integer in the 1-255 range.
- Each
AqaraSpecTree is a Map and satisfies:
- Fixed Devices entry keys that appear should be in the
0-100 range.
- Undefined fixed keys are recommended to be ignored; strict implementations may reject unknown fixed keys.
Encoding Examples
Example 1: Switch device capability (single Spec)
EffectData parameters:
DeviceType = 12 (switch device, as defined in Aqara Spec)MaxEndpointNum = 4- One Aqara Spec path:
function=132, trait=32920, parameter=1
The CBOR diagnostic representation is as follows:
{
0: [
{
1: 12,
2: 4,
3: {
132: {
32920: [1]
}
}
}
]
}
Payload(CBOR,hex):
A1 00 81 A3 01 0C 02 04 03 A1 18 84 A1 19 80 98 81 01
Complete EffectData (minimal Header, Flags = 0x00):
Header: 05 00
Payload: A1 00 81 A3 01 0C 02 04 03 A1 18 84 A1 19 80 98 81 01
Total: 21 bytes
Parsing notes:
05: ProtocolVersion, indicating ProtocolID = 5, Version = 0.00: Flags, indicating no length field, no CRC, and the Payload is CBOR.A1: CBOR Map, with 1 key-value pair (key 0).00 / 81: key 0, indicating a Devices array of length 1.A3: Map, with 3 key-value pairs (key 1, 2, 3).01 / 0C: key 1, indicating DeviceType = 12 (Switch).02 / 04: key 2, indicating MaxEndpointNum = 4.03 / A1: key 3, indicating AqaraSpecTree, which contains one function.18 84:function key = 132.A1 19 80 98:trait key = 32920.81 01: parameter array [1].
Example 2: Multiple parameters under the same function / trait
The CBOR diagnostic representation is as follows:
{
0: [
{
1: 12,
2: 4,
3: {
132: {
32920: [1, 2, 3, 4, 5]
}
}
}
]
}
Payload(CBOR,hex):
A1 00 81 A3 01 0C 02 04 03 A1 18 84 A1 19 80 98 85 01 02 03 04 05
5 logical Specs share the same function key and trait key; the Payload length is 22 bytes, plus the 2-byte Header for a total of 24 bytes.
Example 3: Multiple device types
The CBOR diagnostic representation is as follows:
{
0: [
{
1: 12,
2: 4,
3: {
132: { 32920: [1] }
}
},
{
1: 10,
2: 2,
3: {
132: {
32920: [1],
32921: [1]
}
}
}
]
}
The above content indicates:
- Switch device (
DeviceType = 12): up to 4 endpoints, supporting Spec (function=132, trait=32920, parameter=1).
- Light device (
DeviceType = 10): up to 2 endpoints, supporting Specs (132, 32920, 1) and (132, 32921, 1).
Payload(CBOR,hex):
A1 00 82 A3 01 0C 02 04 03 A1 18 84 A1 19 80 98 81 01 A3 01 0A 02 02 03 A1 18 84 A2 19 80 98 81 01 19 80 99 81 01
Introduction
Acquires continuously varying analog input values (such as voltage, temperature analog signals) in read-only mode.
Function Identification
. Parameter values under the same (function, trait) must be unique.
| Function ID | Code | Name |
|---|
| 0x00CE | AnalogInputObject | Analog input object |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x4EB2 | AnalogInputPV | Analog input current value | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
AnalogInputPV conveys the real-time value of the analog input channel and its engineering metadata.
| Trait ID | Code |
|---|
| 0x4EB2 | AnalogInputPV |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 4294967295 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
Command Definitions
This Function does not contain Commands.
AnalogOutputObject
Introduction
Provides writable continuous analog output control signals.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00CF | AnalogOutputObject | Analog output object |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x4EB3 | AnalogOutputPV | Analog output current value | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
AnalogOutputPV Trait
AnalogOutputPV carries the commanded or actual value of the analog output object.
| Trait ID | Code |
|---|
| 0x4EB3 | AnalogOutputPV |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | | RVW | M |
| 0x0002 | Maximum Value | float | | 4294967295 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Introduction
Acquires binary state inputs, such as door sensors, switches and other true/false or active/inactive quantities.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D0 | BinaryInputObject | Binary input object |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x4EB4 | BinaryInputPV | Binary input current value | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BinaryInputPV reports the instantaneous logical state of a discrete input and may optionally describe polarity inversion.
| Trait ID | Code |
|---|
| 0x4EB4 | BinaryInputPV |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
BinaryOutputObject
Introduction
Drives binary actuator outputs, such as relays, contactors, solenoid valves or alarm signals.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D1 | BinaryOutputObject | Binary output object |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x4EB5 | BinaryOutputPV | Binary output current value | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BinaryOutputPV Trait
BinaryOutputPV holds the command or actual on/off state of the binary output.
| Trait ID | Code |
|---|
| 0x4EB5 | BinaryOutputPV |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
Introduction
Acquires multi-state discrete inputs, representing one of N states.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D2 | MultiStateInputObject | Multi-state input object |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
MultiStateInputPV provides the current enumerated state, along with human-readable state labels and optional descriptive text.
| Trait ID | Code |
|---|
| 0x4EB6 | MultiStateInputPV |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
Command Definitions
This Function does not contain Commands.
MultiStateOutputObject
Introduction
Outputs multi-state discrete control commands, such as HVAC mode or light scene switching.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D3 | MultiStateOutputObject | Multi-state output object |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
MultiStateOutputPV Trait
MultiStateOutputPV contains the requested or currently active enumerated output state.
| Trait ID | Code |
|---|
| 0x4EB7 | MultiStateOutputPV |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | | RVW | M |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
CharacterStringValueObject
Introduction
Defines a data object represented as a string and its externally visible characteristics.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D4 | CharacterStringValueObject | Character string value object |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
CharStringValuePV Trait
Indicates the current value of the CharacterString Value Object.
| Trait ID | Code |
|---|
| 0x4EB8 | CharStringValuePV |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | M |
Command Definitions
This Function does not contain Commands.
ScreenUserInterface
Introduction
Manages screen-side user interface configuration, including page layout, cards, themes and display data.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D5 | ScreenUserInterface | Screen-side configuration |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
ScreenHeight Trait
This Trait is used for access to and reporting of "screen height" data.
| Trait ID | Code |
|---|
| 0x4EBC | ScreenHeight |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | O | 240 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | O | 240 | RW | O |
ScreenWidth Trait
This Trait is used for access to and reporting of "screen width" data.
| Trait ID | Code |
|---|
| 0x4EBB | ScreenWidth |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | O | 240 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | O | 240 | RW | O |
MaxPageNum Trait
This Trait is used for access to and reporting of "maximum page count" data.
| Trait ID | Code |
|---|
| 0x4EBA | MaxPageNum |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | O | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | O | 1 | RW | O |
DataVersion Trait
This Trait is used for access to and reporting of "data version" data.
| Trait ID | Code |
|---|
| 0x4EB9 | DataVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | O | 0 | RV | M |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0007 | Default Value | uint64 | O | 0 | RW | O |
ThemeID Trait
This Trait is used for access to and reporting of "theme ID" data.
| Trait ID | Code |
|---|
| 0x4E78 | ThemeID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | O | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | O | 1 | RW | O |
ThemeVersion Trait
Theme version.
| Trait ID | Code |
|---|
| 0x4E77 | ThemeVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | O | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | O | 1 | RW | O |
Command Definitions
This Function does not contain Commands.
DeviceAnomalyMonitoring
Introduction
Continuously monitors device operating parameters, promptly detecting and reporting anomalies or fault states.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D6 | DeviceAnomalyMonitoring | Device anomaly monitoring |
Trait
Command
This Function does not contain Commands.
Data Types
VoltageSafetyManagementEnum8 Type
This enumeration defines the valid values of the Present Value of the VoltageSafetyManagement Trait.
| Value | Name | Description |
|---|
| 0x00 | VoltageNormal | Voltage normal |
| 0x01 | OverVoltageAnomaly | Over-voltage anomaly |
| 0x02 | OverVoltageProtection | Over-voltage protection |
| 0x03 | UnderVoltageProtection | Under-voltage protection |
LoadSafetyManagementEnum8 Type
This enumeration defines the valid values of the Present Value of the LoadSafetyManagement Trait.
| Value | Name | Description |
|---|
| 0x00 | LoadNormal | Load normal |
| 0x01 | OverLoadAnomaly | Overload anomaly |
| 0x02 | OverLoadProtection | Overload protection |
TemperatureSafetyManagementEnum8 Type
This enumeration defines the valid values of the Present Value of the TemperatureSafetyManagement Trait.
| Value | Name | Description |
|---|
| 0x00 | TempNormal | Temperature normal |
| 0x01 | OverTempAnomaly | Over-temperature anomaly |
| 0x02 | OverTempProtection | Over-temperature protection |
| 0x0B | UnderTempAnomaly | Under-temperature anomaly |
CurrentSafetyManagementEnum8 Type
This enumeration defines the valid values of the Present Value of the CurrentSafetyManagement Trait.
| Value | Name | Description |
|---|
| 0x00 | CurrentNormal | Current normal |
| 0x01 | OverCurrentAnomaly | Over-current anomaly |
| 0x02 | OverCurrentProtection | Over-current protection |
OverCurrentResponseSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the OverCurrentResponseSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | ShutdownSingle | Shut down a single one |
| 0x01 | ShutdownAll | Shut down all |
Trait Definitions
VoltageSafetyManagement Trait
A safety mechanism used to monitor the power supply voltage and provide protection during over-voltage or under-voltage anomalies.
| Trait ID | Code |
|---|
| 0x4ECA | VoltageSafetyManagement |
Parameters
LoadSafetyManagement Trait
A safety mechanism that monitors electrical or mechanical load, used to distinguish load normal, overload anomaly and overload protection states, so that the device can promptly alert and enter protection when the load exceeds the limit.
| Trait ID | Code |
|---|
| 0x4EC8 | LoadSafetyManagement |
Parameters
TemperatureSafetyManagement Trait
A safety mechanism that monitors device temperature, used to report whether the device is in normal, over-temperature anomaly or over-temperature protection state, and to provide state evidence for the subsequent recovery process after an anomaly is triggered.
| Trait ID | Code |
|---|
| 0x4EC7 | TemperatureSafetyManagement |
Parameters
CurrentSafetyManagement Trait
A safety mechanism that monitors device current, used to report whether the current is in normal, over-current anomaly or over-current protection state, and to support the execution of the over-current protection policy.
| Trait ID | Code |
|---|
| 0x4EC9 | CurrentSafetyManagement |
Parameters
OverCurrentResponseSetting Trait
This configuration is used to set the action scope of over-current protection, determining whether the device should act on a single load or all loads when over-current is detected.
| Trait ID | Code |
|---|
| 0x4ECB | OverCurrentResponseSetting |
Parameters
OverTempTemperature Trait
This Trait is used to carry the temperature value or threshold corresponding to the over-temperature alert, facilitating the synchronization of the current temperature context when reporting the alert. Unit: deg C.
| Trait ID | Code |
|---|
| 0x5136 | OverTempTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 70 | RV | O |
| 0x0002 | Maximum Value | float | | 150 | R | O |
| 0x0003 | Minimum Value | float | | -50 | R | O |
OverTemperatureAlertEnable Trait
Turns the over-temperature (high temperature) alert function on or off.
| Trait ID | Code |
|---|
| 0x50DE | OverTemperatureAlertEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
UnderTemperatureAlertEnable Trait
Turns the under-temperature alert function on or off.
| Trait ID | Code |
|---|
| 0x50DF | UnderTemperatureAlertEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
OverLoadPower Trait
This Trait is used to carry the power value or threshold corresponding to the overload alert, facilitating the synchronization of the current load context when reporting the alert. Unit: W.
| Trait ID | Code |
|---|
| 0x5137 | OverLoadPower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 60 | RV | O |
| 0x0002 | Maximum Value | float | | 200 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0007 | Default Value | float | | 60 | RW | O |
Command Definitions
This Function does not contain Commands.
OTA
Introduction
Manages the device firmware upgrade process, including download, installation scheduling and upgrade progress and result reporting.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D7 | OTA | Upgrade function |
Trait
Command
This Function does not contain Commands.
Data Types
OTAStateEnum8 Type
This enumeration defines the valid values of the Present Value of the OTAState Trait.
| Value | Name | Description |
|---|
| 0x00 | OTASuccessful | Upgrade successful |
| 0x01 | Idle | Idle |
| 0x02 | DownloadInProgress | Downloading |
| 0x03 | DownloadFailed | Download failed |
| 0x04 | DownloadComplete | Download complete |
| 0x05 | VerificationInProgress | Verifying |
| 0x06 | VerificationSuccessful | Verification successful |
| 0x07 | VerificationFailed | Verification failed |
| 0x08 | OTAInProgress | Upgrading |
| 0x09 | OTAFailed | Upgrade failed |
UpgradeTypeSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the UpgradeTypeSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | ManualUpdate | Manual upgrade |
| 0x01 | AutoUpdate | Automatic upgrade |
Trait Definitions
OTAState Trait
An enumerated value that provides real-time visibility into the overall progress and result of the device firmware over-the-air (OTA) update process. It represents the specific stage of the device in the firmware update lifecycle (e.g., download, verification, activation), serving as core information for management systems to monitor state, make decisions and diagnose problems.
| Trait ID | Code |
|---|
| 0x4F09 | OTAState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | OTAStateEnum8 | | 1 | RV | O |
| 0x0006 | Supported Value | list[OTAStateEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 1 | RW | O |
UpgradeTypeSetting Trait
Indicates the software or firmware upgrade method to be used, such as manual upgrade, automatic upgrade, etc.
| Trait ID | Code |
|---|
| 0x4EE1 | UpgradeTypeSetting |
Parameters
OTADegradeEnable Trait
Enables or disables the OTA degrade function. When enabled (value 1), firmware version downgrade is allowed; when disabled (value 0), downgrade is prohibited.
| Trait ID | Code |
|---|
| 0x5070 | OTADegradeEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
HumanRecognition
Introduction
Uses vision and other algorithms to detect human targets in the scene in real time, distinguishing humans from other objects and reporting events.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D8 | HumanRecognition | Human detection |
Trait
Command
This Function does not contain Commands.
Data Types
HumanRecognitionReportEnum8 Type
This enumeration defines the valid values of the Present Value of the HumanRecognitionReport Trait.
| Value | Name | Description |
|---|
| 0x01 | HumanDetected | Human event detected |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, ordered from Sunday to Saturday; 1 indicates active, 0 indicates inactive. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
BitmaskRegionSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the BitmaskRegionSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | detect_region | characterString | M | A bitmask in hexadecimal string form, where each bit corresponds to a grid cell. |
| 1 | effective_bits | int32 | M | The number of valid bits in the bitmask; bits beyond this count should be ignored. |
RegionDimensionTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RegionDimension Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | unit | enum8 | M | The unit of width and height, e.g., GRID or PIXEL. |
| 1 | width | uint32 | M | The total width of the region in the specified unit. |
| 2 | height | uint32 | M | The total height of the region in the specified unit. |
Trait Definitions
HumanRecognitionReport Trait
Reports whether a human is detected in the defined detection region.
| Trait ID | Code |
|---|
| 0x4EF7 | HumanRecognitionReport |
Parameters
HumanRecognitionEnable Trait
The master switch to enable or disable human detection (AI-based).
| Trait ID | Code |
|---|
| 0x4FCD | HumanRecognitionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
HumanTrackingEnable Trait
Enables or disables the camera's human tracking capability. When enabled, the camera automatically recognizes humans and adjusts the gimbal to keep the target centered.
| Trait ID | Code |
|---|
| 0x50C8 | HumanTrackingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CloseUpHumanEnable Trait
Controls whether to trigger close-up zoom on human targets in the close-up tracking scenario.
| Trait ID | Code |
|---|
| 0x50CB | CloseUpHumanEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
TimePeriodSetting Trait
Defines the schedule plan of time periods and weekdays. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the entire day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from the starttime of the active day to the endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, with index order corresponding to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday. A value of 1 indicates the weekday is active, and 0 indicates it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
SensitivityLevelEnum Trait
This enumeration configures sensitivity levels for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. Higher sensitivity makes the function more responsive to trigger conditions (e.g., easier to detect weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
PushEnable Trait
Controls whether push notifications are sent to the user when a specific function (such as detection events, recognition events) is triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even if the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IntervalSetting Trait
Configures the minimum time interval between two consecutive event triggers of a specific function (e.g., detection, recognition). The value is numeric, in seconds. After an event is triggered, any further detection of the same event within this interval will not generate a new trigger until the interval has elapsed.
| Trait ID | Code |
|---|
| 0x4FB7 | IntervalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
BitmaskRegionSetting Trait
Defines region configuration based on a grid mask. It contains two fields: detect_region (hexadecimal string) and effective_bits (integer). Each bit in the hexadecimal string corresponds to a grid cell (e.g., dividing the frame into 24 cells). A bit value of 1 indicates that detection or recognition is enabled for the corresponding cell, and 0 indicates disabled. The bit arrangement follows a predefined order (e.g., left to right or from the most significant bit to the least significant bit). The effective_bits field specifies the number of actually valid bits in the hexadecimal string, allowing the string to maintain a fixed length while only the first N bits are meaningful. For example, "FF" means 8 consecutive bits are all 1. If effective_bits is 32, all 32 bits are valid; if it is 24, only the first 24 bits are valid. This representation is commonly used for functions such as motion detection and human detection that need to flexibly select specific regions on video frames.
| Trait ID | Code |
|---|
| 0x4FCC | BitmaskRegionSetting |
Parameters
RegionDimension Trait
Defines the complete canvas size that a client (such as an App) can use for region configuration (such as detection regions, privacy masks). Its value is a structure containing three fields:
unit (enum8): the unit of width and height, e.g., GRID (grid cell), PIXEL (pixel).
width (uint32): the total width of the region in the specified unit.
height (uint32): the total height of the region in the specified unit.
| Trait ID | Code |
|---|
| 0x502D | RegionDimension |
Parameters
Command Definitions
This Function does not contain Commands.
SoundDetection
Introduction
Acquires ambient sound through a microphone, recognizes specific sound types (such as glass breaking, baby crying) and raises alerts.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00D9 | SoundDetection | Sound detection |
Trait
Command
This Function does not contain Commands.
Data Types
AnomalySoundDetectedEnum8 Type
This enumeration defines the valid values of the Present Value of the AnomalySoundDetected Trait.
| Value | Name | Description |
|---|
| 0x01 | CryDetected | Crying detected |
| 0x02 | SnoreDetected | Snoring detected |
| 0x03 | LoudSoundDetected | Loud sound detected |
| 0x04 | BabyCryDetected | Baby crying detected |
| 0x05 | AlarmSoundDetected | Alarm sound detected |
| 0x06 | DogBarkDetected | Pet barking detected |
| 0x07 | CoughDetected | Coughing detected |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, ordered from Sunday to Saturday; 1 indicates active, 0 indicates inactive. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
Trait Definitions
AnomalySoundDetected Trait
This function enables the device to intelligently recognize anomalous sounds in the environment. For example, when an event matching baby cry characteristics is detected, a cry event will be reported.
| Trait ID | Code |
|---|
| 0x4EF6 | AnomalySoundDetected |
Parameters
SnoreDetectionEnable Trait
The master switch to enable or disable snore detection. When enabled, the camera continuously listens to audio to recognize snore patterns.
| Trait ID | Code |
|---|
| 0x4FBC | SnoreDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LoudSoundDetectionEnable Trait
The master switch to enable or disable loud sound detection.
| Trait ID | Code |
|---|
| 0x4FBD | LoudSoundDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SoundDetectionEnable Trait
The master switch to enable or disable AI sound detection (including baby crying, dog barking, coughing, snoring, etc.).
| Trait ID | Code |
|---|
| 0x4FFE | SoundDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
TimePeriodSetting Trait
Defines the schedule plan of time periods and weekdays. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the entire day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from the starttime of the active day to the endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, with index order corresponding to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday. A value of 1 indicates the weekday is active, and 0 indicates it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
SensitivityLevelEnum Trait
This enumeration configures sensitivity levels for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. Higher sensitivity makes the function more responsive to trigger conditions (e.g., easier to detect weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
PushEnable Trait
Controls whether push notifications are sent to the user when a specific function (such as detection events, recognition events) is triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even if the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IntervalSetting Trait
Configures the minimum time interval between two consecutive event triggers of a specific function (e.g., detection, recognition). The value is numeric, in seconds. After an event is triggered, any further detection of the same event within this interval will not generate a new trigger until the interval has elapsed.
| Trait ID | Code |
|---|
| 0x4FB7 | IntervalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
BabyCryDetectionEnable Trait
The master switch to enable or disable baby cry detection.
| Trait ID | Code |
|---|
| 0x5004 | BabyCryDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
AlarmSoundDetectionEnable Trait
The master switch to enable or disable alarm sound recognition.
| Trait ID | Code |
|---|
| 0x5005 | AlarmSoundDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
DogBarkDetectionEnable Trait
The master switch to enable or disable dog barking detection.
| Trait ID | Code |
|---|
| 0x5006 | DogBarkDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CoughDetectionEnable Trait
The master switch to enable or disable cough detection.
| Trait ID | Code |
|---|
| 0x5007 | CoughDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
PetRecognition
Introduction
Recognizes individual pets such as cats and dogs in the scene, reporting pet appearance or related recognition events.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00DA | PetRecognition | Pet recognition |
Trait
Command
This Function does not contain Commands.
Data Types
PetRecognitionReportEnum16 Type
This enumeration defines the valid values of the Present Value of the PetRecognitionReport Trait.
| Value | Name | Description |
|---|
| 0x01 | CatDetected | Cat detected |
| 0x02 | DogDetected | Dog detected |
| 0x03 | CatOrDogDetected | Cat and dog detected |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, ordered from Sunday to Saturday; 1 indicates active, 0 indicates inactive. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
BitmaskRegionSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the BitmaskRegionSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | detect_region | characterString | M | A bitmask in hexadecimal string form, where each bit corresponds to a grid cell. |
| 1 | effective_bits | int32 | M | The number of valid bits in the bitmask; bits beyond this count should be ignored. |
RegionDimensionTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RegionDimension Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | unit | enum8 | M | The unit of width and height, e.g., GRID or PIXEL. |
| 1 | width | uint32 | M | The total width of the region in the specified unit. |
| 2 | height | uint32 | M | The total height of the region in the specified unit. |
Trait Definitions
PetRecognitionReport Trait
Enables a smart device to accurately recognize pet types. When a cat, dog or both are detected, the specific type is automatically reported.
| Trait ID | Code |
|---|
| 0x4EF8 | PetRecognitionReport |
Parameters
PetRecognitionEnable Trait
The master switch to enable or disable pet detection (cat and dog recognition).
| Trait ID | Code |
|---|
| 0x4FE3 | PetRecognitionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
PetTrackingEnable Trait
Enables or disables the camera's automatic tracking capability for pet (cat/dog) targets.
| Trait ID | Code |
|---|
| 0x50C9 | PetTrackingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CloseUpPetEnable Trait
Controls whether to trigger close-up zoom on pet (cat/dog) targets in the close-up tracking scenario.
| Trait ID | Code |
|---|
| 0x50CC | CloseUpPetEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
TimePeriodSetting Trait
Defines the schedule plan of time periods and weekdays. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the entire day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from the starttime of the active day to the endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, with index order corresponding to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday. A value of 1 indicates the weekday is active, and 0 indicates it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
SensitivityLevelEnum Trait
This enumeration configures sensitivity levels for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. Higher sensitivity makes the function more responsive to trigger conditions (e.g., easier to detect weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
PushEnable Trait
Controls whether push notifications are sent to the user when a specific function (such as detection events, recognition events) is triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even if the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IntervalSetting Trait
Configures the minimum time interval between two consecutive event triggers of a specific function (e.g., detection, recognition). The value is numeric, in seconds. After an event is triggered, any further detection of the same event within this interval will not generate a new trigger until the interval has elapsed.
| Trait ID | Code |
|---|
| 0x4FB7 | IntervalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
BitmaskRegionSetting Trait
Defines region configuration based on a grid mask. It contains two fields: detect_region (hexadecimal string) and effective_bits (integer). Each bit in the hexadecimal string corresponds to a grid cell (e.g., dividing the frame into 24 cells). A bit value of 1 indicates that detection or recognition is enabled for the corresponding cell, and 0 indicates disabled. The bit arrangement follows a predefined order (e.g., left to right or from the most significant bit to the least significant bit). The effective_bits field specifies the number of actually valid bits in the hexadecimal string, allowing the string to maintain a fixed length while only the first N bits are meaningful. For example, "FF" means 8 consecutive bits are all 1. If effective_bits is 32, all 32 bits are valid; if it is 24, only the first 24 bits are valid. This representation is commonly used for functions such as motion detection and human detection that need to flexibly select specific regions on video frames.
| Trait ID | Code |
|---|
| 0x4FCC | BitmaskRegionSetting |
Parameters
RegionDimension Trait
Defines the complete canvas size that a client (such as an App) can use for region configuration (such as detection regions, privacy masks). Its value is a structure containing three fields:
unit (enum8): the unit of width and height, e.g., GRID (grid cell), PIXEL (pixel).
width (uint32): the total width of the region in the specified unit.
height (uint32): the total height of the region in the specified unit.
| Trait ID | Code |
|---|
| 0x502D | RegionDimension |
Parameters
Command Definitions
This Function does not contain Commands.
FaceRecognition
Introduction
Acquires facial features and compares them with the local library, reporting face recognition results and matching information.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00DB | FaceRecognition | Face recognition |
Trait
Command
This Function does not contain Commands.
Data Types
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, ordered from Sunday to Saturday; 1 indicates active, 0 indicates inactive. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
BitmaskRegionSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the BitmaskRegionSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | detect_region | characterString | M | A bitmask in hexadecimal string form, where each bit corresponds to a grid cell. |
| 1 | effective_bits | int32 | M | The number of valid bits in the bitmask; bits beyond this count should be ignored. |
FaceRecognitionAlgorithmTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the FaceRecognitionAlgorithmType Trait.
| Value | Name | Description |
|---|
| 0x00 | NotSupported | Face recognition not supported |
| 0x01 | OnDevice | Face recognition on-device algorithm |
| 0x02 | Cloud | Face recognition cloud algorithm |
RegionDimensionTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RegionDimension Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | unit | enum8 | M | The unit of width and height, e.g., GRID or PIXEL. |
| 1 | width | uint32 | M | The total width of the region in the specified unit. |
| 2 | height | uint32 | M | The total height of the region in the specified unit. |
Trait Definitions
FaceIDReport Trait
A unique identifier associated with a specific face, used for face recognition or identity verification.
| Trait ID | Code |
|---|
| 0x4EF9 | FaceIDReport |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | V | M |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
StrangerFaceDetected Trait
An event triggered when an unrecognized (stranger) face is detected. The value is always "0", indicating an unknown person.
| Trait ID | Code |
|---|
| 0x4FD4 | StrangerFaceDetected |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | V | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint64 | | 0 | RW | O |
FaceRecognitionEnable Trait
The master switch to enable the face recognition function. When enabled, the camera detects faces and matches them against the known database.
| Trait ID | Code |
|---|
| 0x4FD5 | FaceRecognitionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TimePeriodSetting Trait
Defines the schedule plan of time periods and weekdays. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the entire day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from the starttime of the active day to the endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, with index order corresponding to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday. A value of 1 indicates the weekday is active, and 0 indicates it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
SensitivityLevelEnum Trait
This enumeration configures sensitivity levels for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. Higher sensitivity makes the function more responsive to trigger conditions (e.g., easier to detect weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
PushEnable Trait
Controls whether push notifications are sent to the user when a specific function (such as detection events, recognition events) is triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even if the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IntervalSetting Trait
Configures the minimum time interval between two consecutive event triggers of a specific function (e.g., detection, recognition). The value is numeric, in seconds. After an event is triggered, any further detection of the same event within this interval will not generate a new trigger until the interval has elapsed.
| Trait ID | Code |
|---|
| 0x4FB7 | IntervalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
BitmaskRegionSetting Trait
Defines region configuration based on a grid mask. It contains two fields: detect_region (hexadecimal string) and effective_bits (integer). Each bit in the hexadecimal string corresponds to a grid cell (e.g., dividing the frame into 24 cells). A bit value of 1 indicates that detection or recognition is enabled for the corresponding cell, and 0 indicates disabled. The bit arrangement follows a predefined order (e.g., left to right or from the most significant bit to the least significant bit). The effective_bits field specifies the number of actually valid bits in the hexadecimal string, allowing the string to maintain a fixed length while only the first N bits are meaningful. For example, "FF" means 8 consecutive bits are all 1. If effective_bits is 32, all 32 bits are valid; if it is 24, only the first 24 bits are valid. This representation is commonly used for functions such as motion detection and human detection that need to flexibly select specific regions on video frames.
| Trait ID | Code |
|---|
| 0x4FCC | BitmaskRegionSetting |
Parameters
FaceRecognitionAlgorithmType Trait
Specifies where the face recognition algorithm runs. On-device processing offers better privacy and lower latency; cloud processing can support larger face databases.
| Trait ID | Code |
|---|
| 0x4FDC | FaceRecognitionAlgorithmType |
Parameters
RegionDimension Trait
Defines the complete canvas size that a client (such as an App) can use for region configuration (such as detection regions, privacy masks). Its value is a structure containing three fields:
unit (enum8): the unit of width and height, e.g., GRID (grid cell), PIXEL (pixel).
width (uint32): the total width of the region in the specified unit.
height (uint32): the total height of the region in the specified unit.
| Trait ID | Code |
|---|
| 0x502D | RegionDimension |
Parameters
Command Definitions
This Function does not contain Commands.
GestureRecognition
Introduction
Analyzes gesture actions in real time, converting predefined gestures into control commands.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00DC | GestureRecognition | Gesture recognition |
Trait
Command
This Function does not contain Commands.
Data Types
GestureRecognitionReportEnum16 Type
This enumeration defines the valid values of the Present Value of the GestureRecognitionReport Trait.
| Value | Name | Description |
|---|
| 0x02 | Two | Two |
| 0x04 | Four | Four |
| 0x05 | Five | Five |
| 0x06 | Eight | Eight |
| 0x0A | Good | Good |
| 0x65 | TwoBothHands | Two (both hands) |
| 0x66 | FourBothHands | Four (both hands) |
| 0x67 | FiveBothHands | Five (both hands) |
| 0x68 | EightBothHands | Eight (both hands) |
GestureRecognitionModeEnum8 Type
This enumeration defines the valid values of the Present Value of the GestureRecognitionMode Trait.
| Value | Name | Description |
|---|
| 0x00 | OneHand | One-hand mode |
| 0x01 | TwoHand | Two-hand mode |
RectangularRegionSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RectangularRegionSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | x_begin | int32 | M | Top-left corner X coordinate. |
| 1 | y_begin | int32 | M | Top-left corner Y coordinate. |
| 2 | x_end | int32 | M | Bottom-right corner X coordinate. |
| 3 | y_end | int32 | M | Bottom-right corner Y coordinate. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, ordered from Sunday to Saturday; 1 indicates active, 0 indicates inactive. |
Trait Definitions
GestureRecognitionReport Trait
Enables the device to recognize specific user gestures through a vision sensor. When a predefined gesture action is detected, the corresponding gesture event is automatically reported.
| Trait ID | Code |
|---|
| 0x4EFA | GestureRecognitionReport |
Parameters
GestureRecognitionAntiFalseTrigger Trait
Enables or disables the gesture recognition anti-false-trigger protection to reduce accidental triggers.
| Trait ID | Code |
|---|
| 0x500D | GestureRecognitionAntiFalseTrigger |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
GestureRecognitionMode Trait
Specifies whether gesture recognition is in one-hand mode or two-hand mode.
| Trait ID | Code |
|---|
| 0x500C | GestureRecognitionMode |
Parameters
RectangularRegionSetting Trait
Defines a rectangular region using the absolute coordinates of the top-left corner (XBegin, YBegin) and the bottom-right corner (XEnd, YEnd); the coordinate origin is at the top-left of the image, X increases rightward and Y increases downward. Commonly used for configuring detection regions, privacy mask regions and similar functions.
| Trait ID | Code |
|---|
| 0x500B | RectangularRegionSetting |
Parameters
GestureRecognitionEnable Trait
The master switch to enable gesture recognition.
| Trait ID | Code |
|---|
| 0x5008 | GestureRecognitionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SensitivityLevelEnum Trait
This enumeration configures sensitivity levels for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. Higher sensitivity makes the function more responsive to trigger conditions (e.g., easier to detect weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
TimePeriodSetting Trait
Defines the schedule plan of time periods and weekdays. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the entire day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from the starttime of the active day to the endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, with index order corresponding to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday. A value of 1 indicates the weekday is active, and 0 indicates it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
GestureRecognitionSoundEnable Trait
Enables or disables the sound feedback during gesture recognition (such as static/dynamic gesture execution or dynamic gesture activation). When enabled, the device emits a sound prompt.
| Trait ID | Code |
|---|
| 0x4FE1 | GestureRecognitionSoundEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
VehicleDetection
Introduction
Detects the appearance of vehicles in the monitored area, reporting vehicle presence events for security or automation use.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00DD | VehicleDetection | Vehicle detection |
Trait
Command
This Function does not contain Commands.
Data Types
VehicleDetectedEnum8 Type
This enumeration defines the valid values of the Present Value of the VehicleDetected Trait.
| Value | Name | Description |
|---|
| 0x01 | VehicleDetected | Vehicle recognized |
RegionDimensionTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RegionDimension Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | unit | enum8 | M | The unit of width and height, e.g., GRID or PIXEL. |
| 1 | width | uint32 | M | The total width of the region in the specified unit. |
| 2 | height | uint32 | M | The total height of the region in the specified unit. |
BitmaskRegionSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the BitmaskRegionSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | detect_region | characterString | M | A bitmask in hexadecimal string form, where each bit corresponds to a grid cell. |
| 1 | effective_bits | int32 | M | The number of valid bits in the bitmask; bits beyond this count should be ignored. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, ordered from Sunday to Saturday; 1 indicates active, 0 indicates inactive. |
StrangeVehicleDetectedEnum8 Type
This enumeration defines the valid values of the Present Value of the StrangeVehicleDetected Trait.
| Value | Name | Description |
|---|
| 0x01 | Detected | Detected |
VehicleEntryExitEventEnum8 Type
This enumeration defines the valid values of the Present Value of the VehicleEntryExitEvent Trait.
| Value | Key | Chinese Name | English Name | Description |
|---|
| 0x01 | VehicleExit | Vehicle exited | Vehicle Exit | Detected that a vehicle has exited (left). |
| 0x02 | VehicleEntry | Vehicle entered | Vehicle Entry | Detected that a vehicle has entered. |
Trait Definitions
VehicleDetected Trait
Enables the device to recognize vehicles in the monitored area. When a vehicle entering, moving or parking is observed, a vehicle detection event is automatically reported.
| Trait ID | Code |
|---|
| 0x4EFB | VehicleDetected |
Parameters
VehicleDetectionEnable Trait
The master switch to enable or disable vehicle detection (cloud-based).
| Trait ID | Code |
|---|
| 0x4FEA | VehicleDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
RegionDimension Trait
Defines the complete canvas size that a client (such as an App) can use for region configuration (such as detection regions, privacy masks). Its value is a structure containing three fields:
unit (enum8): the unit of width and height, e.g., GRID (grid cell), PIXEL (pixel).
width (uint32): the total width of the region in the specified unit.
height (uint32): the total height of the region in the specified unit.
| Trait ID | Code |
|---|
| 0x502D | RegionDimension |
Parameters
BitmaskRegionSetting Trait
Defines region configuration based on a grid mask. It contains two fields: detect_region (hexadecimal string) and effective_bits (integer). Each bit in the hexadecimal string corresponds to a grid cell (e.g., dividing the frame into 24 cells). A bit value of 1 indicates that detection or recognition is enabled for the corresponding cell, and 0 indicates disabled. The bit arrangement follows a predefined order (e.g., left to right or from the most significant bit to the least significant bit). The effective_bits field specifies the number of actually valid bits in the hexadecimal string, allowing the string to maintain a fixed length while only the first N bits are meaningful. For example, "FF" means 8 consecutive bits are all 1. If effective_bits is 32, all 32 bits are valid; if it is 24, only the first 24 bits are valid. This representation is commonly used for functions such as motion detection and human detection that need to flexibly select specific regions on video frames.
| Trait ID | Code |
|---|
| 0x4FCC | BitmaskRegionSetting |
Parameters
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IntervalSetting Trait
Configures the minimum time interval between two consecutive event triggers of a specific function (e.g., detection, recognition). The value is numeric, in seconds. After an event is triggered, any further detection of the same event within this interval will not generate a new trigger until the interval has elapsed.
| Trait ID | Code |
|---|
| 0x4FB7 | IntervalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
PushEnable Trait
Controls whether push notifications are sent to the user when a specific function (such as detection events, recognition events) is triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even if the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
SensitivityLevelEnum Trait
This enumeration configures sensitivity levels for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. Higher sensitivity makes the function more responsive to trigger conditions (e.g., easier to detect weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
TimePeriodSetting Trait
Defines the schedule plan of time periods and weekdays. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the entire day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from the starttime of the active day to the endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, with index order corresponding to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday. A value of 1 indicates the weekday is active, and 0 indicates it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
VehicleID Trait
VehicleID is the unique identifier assigned to each electric vehicle (EV).
| Trait ID | Code |
|---|
| 0x4E59 | VehicleID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | string32 | | | RV | O |
StrangeVehicleDetected Trait
Used to report the event when a strange vehicle is detected.
| Trait ID | Code |
|---|
| 0x5066 | StrangeVehicleDetected |
Parameters
VehicleEntryExitEvent Trait
Vehicle entry/exit event. Indicates the event that the device has detected a vehicle entering or exiting. This Trait is an enumeration (uint8), report-only, and is actively reported by the device when a vehicle entry/exit event is detected.
| Trait ID | Code |
|---|
| 0x5196 | VehicleEntryExitEvent |
Parameters
Command Definitions
This Function does not contain Commands.
FlameDetection
Introduction
Detects visible flames through image or sensor algorithms, promptly reporting fire events for early warning.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00DE | FlameDetection | Flame detection |
Trait
Command
This Function does not contain Commands.
Data Types
FlameDetectedEnum8 Type
This enumeration defines the valid values of the Present Value of the FlameDetected Trait.
| Value | Name | Description |
|---|
| 0x01 | FlameDetected | Flame recognized |
Trait Definitions
FlameDetected Trait
Enables the device to recognize open flames or flame features in the monitored area. When a suspected flame is detected, an event is automatically triggered and reported.
| Trait ID | Code |
|---|
| 0x4EFC | FlameDetected |
Parameters
FlameDetectionEnable Trait
The master switch to enable or disable flame detection.
| Trait ID | Code |
|---|
| 0x4FF8 | FlameDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
PushEnable Trait
Controls whether push notifications are sent to the user when a specific function (such as detection events, recognition events) is triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even if the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
Command Definitions
This Function does not contain Commands.
PackageRecognition
Introduction
Automatically recognizes packages in the scene, sending reminders and recording events upon delivery or pickup.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00DF | PackageRecognition | Package recognition |
Trait
Command
This Function does not contain Commands.
Data Types
PackageRecognitionReportEnum8 Type
This enumeration defines the valid values of the Present Value of the PackageRecognitionReport Trait.
| Value | Name | Description |
|---|
| 0x01 | PackageAppeared | Package appeared |
| 0x02 | PackageDisappeared | Package disappeared |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the TimePeriodSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour clock). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour clock). |
| 2 | repeat | array[uint32] | M | Weekday repeat flags of fixed length 7, ordered from Sunday to Saturday; 1 indicates active, 0 indicates inactive. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
BitmaskRegionSettingTraitPresentValueStructure Type
This structure defines the Present Value field layout of the BitmaskRegionSetting Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | detect_region | characterString | M | A bitmask in hexadecimal string form, where each bit corresponds to a grid cell. |
| 1 | effective_bits | int32 | M | The number of valid bits in the bitmask; bits beyond this count should be ignored. |
RegionDimensionTraitPresentValueStructure Type
This structure defines the Present Value field layout of the RegionDimension Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | unit | enum8 | M | The unit of width and height, e.g., GRID or PIXEL. |
| 1 | width | uint32 | M | The total width of the region in the specified unit. |
| 2 | height | uint32 | M | The total height of the region in the specified unit. |
Trait Definitions
PackageRecognitionReport Trait
Automatically reports events when a package is delivered, picked up or its state changes.
| Trait ID | Code |
|---|
| 0x4EFD | PackageRecognitionReport |
Parameters
PackageRecognitionEnable Trait
The master switch to enable or disable package detection.
| Trait ID | Code |
|---|
| 0x4FF1 | PackageRecognitionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TimePeriodSetting Trait
Defines the schedule plan of time periods and weekdays. The schedule configuration structure contains three fields: starttime, endtime and repeat. starttime and endtime are strings in "HH:MM" format (24-hour clock), ranging from "00:00" to "23:59", defining the start and end time of the active period. If the two are equal, the period covers the entire day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period spans midnight, starting from the starttime of the active day to the endtime of the next day. repeat is an unsigned 8-bit integer array of length 7, with index order corresponding to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday. A value of 1 indicates the weekday is active, and 0 indicates it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
SensitivityLevelEnum Trait
This enumeration configures sensitivity levels for multiple device functions (such as detection, recognition, sensing, alerting, etc.). Valid values are 0, 1, 2, 3, 4, corresponding to lowest, low, medium, high and highest sensitivity respectively. Higher sensitivity makes the function more responsive to trigger conditions (e.g., easier to detect weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
PushEnable Trait
Controls whether push notifications are sent to the user when a specific function (such as detection events, recognition events) is triggered. The value is of boolean type: true (enabled) means a push notification is sent when the event occurs; false (disabled) means no notification is sent even if the event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RecordEnable Trait
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IntervalSetting Trait
Configures the minimum time interval between two consecutive event triggers of a specific function (e.g., detection, recognition). The value is numeric, in seconds. After an event is triggered, any further detection of the same event within this interval will not generate a new trigger until the interval has elapsed.
| Trait ID | Code |
|---|
| 0x4FB7 | IntervalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
BitmaskRegionSetting Trait
Defines region configuration based on a grid mask. It contains two fields: detect_region (hexadecimal string) and effective_bits (integer). Each bit in the hexadecimal string corresponds to a grid cell (e.g., dividing the frame into 24 cells). A bit value of 1 indicates that detection or recognition is enabled for the corresponding cell, and 0 indicates disabled. The bit arrangement follows a predefined order (e.g., left to right or from the most significant bit to the least significant bit). The effective_bits field specifies the number of actually valid bits in the hexadecimal string, allowing the string to maintain a fixed length while only the first N bits are meaningful. For example, "FF" means 8 consecutive bits are all 1. If effective_bits is 32, all 32 bits are valid; if it is 24, only the first 24 bits are valid. This representation is commonly used for functions such as motion detection and human detection that need to flexibly select specific regions on video frames.
| Trait ID | Code |
|---|
| 0x4FCC | BitmaskRegionSetting |
Parameters
RegionDimension Trait
Defines the complete canvas size that a client (such as an App) can use for region configuration (such as detection regions, privacy masks). Its value is a structure containing three fields:
unit (enum8): the unit of width and height, e.g., GRID (grid cell), PIXEL (pixel).
width (uint32): the total width of the region in the specified unit.
height (uint32): the total height of the region in the specified unit.
| Trait ID | Code |
|---|
| 0x502D | RegionDimension |
Parameters
Command Definitions
This Function does not contain Commands.
HumanPresence
Introduction
Detects human presence in a space, supporting advanced sensing capabilities such as people counting, trajectory and identity association.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E0 | HumanPresence | Human presence detection |
Trait
Command
Data Types
PresenceEnum8 Type
This enumeration defines the valid values of the Present Value of the Presence Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | NoHumanDetected | No person detected |
| 0x02 | HumanDetected | Person detected |
PresenceConfigurationTraitPresentValueStructure Type
This structure defines the Present Value field layout of the PresenceConfiguration Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | HubList | list[characterString] | M | List of gateway Device IDs. |
| 1 | Events | Struct | O | Event configuration, containing DeviceID and ResList. |
| 2 | States | Struct | O | State configuration, containing DeviceID and ResList. |
| 3 | Entries | characterString | O | Entrance configuration. |
| 4 | Config | uint32 | O | Configuration items, e.g., DetDuration, UnKnownDuration. |
Trait Definitions
Presence Trait
Presence is used to detect whether there is a person in the monitored area.
| Trait ID | Code |
|---|
| 0x4F01 | Presence |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | PresenceEnum8 | | 0 | RV | M |
| 0x0006 | Supported Value | list[PresenceEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
ActivityDetected Trait
Indicates whether any human activity is detected while the space is occupied.
| Trait ID | Code |
|---|
| 0x4F02 | ActivityDetected |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | V | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
HoldTime Trait
Absence hold time, unit: S.
| Trait ID | Code |
|---|
| 0x4E72 | HoldTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
PresenceConfiguration Trait
Used to configure the settings related to presence soft sensing.
| Trait ID | Code |
|---|
| 0x4F06 | PresenceConfiguration |
Parameters
Command Definitions
ResetPresence Command
The ResetPresence command is used to reset the current presence detection state of the device or space.
This Command has no parameters.
HeartMonitoring
Introduction
Uses sensors to continuously or periodically measure the user's heart rate, recording and analyzing heart-health-related data.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E1 | HeartMonitoring | Heart monitoring |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x4F08 | HeartRate | Heart rate | M |
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
HeartRate Trait
Measures the number of heartbeats per minute in real time. Unit: bpm.
| Trait ID | Code |
|---|
| 0x4F08 | HeartRate |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
BreathingMonitoring
Introduction
Uses sensors to continuously or periodically measure the user's breathing rate and pattern, supporting health monitoring.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E2 | BreathingMonitoring | Breathing monitoring |
Trait
Command
This Function does not contain Commands.
Data Types
This Function has no custom data types.
Trait Definitions
BreathingRate Trait
Measures the number of breaths per minute in real time. Unit: bpm.
| Trait ID | Code |
|---|
| 0x4F07 | BreathingRate |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 60.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain Commands.
AmbientSensingConfiguration
Introduction
Provides Aqara ambient sensing configuration capabilities, covering zone management, installation mode selection, fall detection, proximity sensing and PIR/Radar cooperative sensing configuration items, used for real-time parameter configuration and zone-based management of ambient sensing devices.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E3 | AmbientSensingConfiguration | Ambient sensing configuration |
Trait
Command
Data Types
ZonesInfoTraitPresentValueStructure Type
This structure defines the Present Value field layout of the ZonesInfo Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ZoneID | uint8 | M | Zone ID. |
| 1 | ZoneName | characterString | M | Zone name. |
| 2 | ZoneColorID | uint8 | M | Zone color ID. |
| 3 | ZoneTagID | uint8 | M | Zone label ID. |
| 4 | ZoneTagName | characterString | M | Zone label name. |
ZonesTraitPresentValueStructure Type
This structure defines the Present Value field layout of the Zones Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ZoneID | uint8 | M | Zone ID. |
| 1 | ZoneType | enum8 | M | Zone type (e.g., 0x00=Other, 0x01=LivingRoom, etc.; see the complete enumeration in the aqara-spec AppendZone command). |
| 2 | ZoneBitmask | characterString | M | Zone bitmask. |
| 3 | ZoneProximityDetectionEnable | boolean | M | Whether zone proximity detection is enabled. |
ProximityDistanceLevelEnum8 Type
This enumeration defines the valid values of the Present Value of the ProximityDistanceLevel Trait.
| Value | Name | Description |
|---|
| 0x00 | Far | Far |
| 0x01 | Medium | Medium |
| 0x02 | Near | Near |
FallDetectionSensitivityEnum8 Type
This enumeration defines the valid values of the Present Value of the FallDetectionSensitivity Trait.
| Value | Name | Description |
|---|
| 0x00 | Low | Low |
| 0x01 | Medium | Medium |
| 0x02 | High | High |
DetectionDirectionSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the DetectionDirectionSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | OmniDirectional | Omnidirectional |
| 0x01 | LeftRight | Left and right |
CoordinateReverseSettingEnum8 Type
This enumeration defines the valid values of the Present Value of the CoordinateReverseSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | Disabled | Disabled |
| 0x01 | Enabled | Enabled |
| 0x02 | Auto | Automatic |
InstallModeEnum8 Type
This enumeration defines the valid values of the Present Value of the InstallMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | SideMount | Side mount |
| 0x02 | TopMount | Top mount |
SideInstallEnum8 Type
This enumeration defines the valid values of the Present Value of the SideInstall Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Wall | Wall |
| 0x02 | LeftCorner | Left corner |
| 0x03 | RightCorner | Right corner |
InstallStatusEnum8 Type
This enumeration defines the valid values of the Present Value of the InstallStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | LevelFacingUp | Horizontal facing up |
| 0x01 | LevelTiltedFacingUp | Horizontal tilted facing up |
| 0x02 | LevelReverseTiltedFacingUp | Horizontal reverse tilted facing up |
| 0x03 | SideFacingForward | Side facing forward |
| 0x04 | SideReverseFacingForward | Side reverse facing forward |
| 0x05 | TopFacingDown | Top facing down |
| 0x06 | TiltedFacingDown | Tilted facing down |
| 0x07 | ReverseTiltedFacingDown | Reverse tilted facing down |
| 0x08 | Invalid | Invalid |
AISpaceBackgroundLearningCompleteEnum8 Type
This enumeration defines the valid values of the Present Value of the AISpaceBackgroundLearningComplete Trait.
| Value | Name | Description |
|---|
| 0x00 | SUCCESS | Success |
| 0x01 | INVALID_ARGUMENT | Invalid parameter |
| 0x02 | INVALID_STATE | Invalid state |
| 0x03 | RESOURCE_EXHAUSTED | Resource exhausted |
| 0x04 | BUSY | Busy |
| 0x05 | DUPLICATE_ZONE_ID | Duplicate zone ID |
RemoveZone Command Structure Type
The parameter structure of the RemoveZone Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | ZoneID | uint8 | M | Zone ID. |
UpdateZone Command Structure Type
The parameter structure of the UpdateZone Command.
AppendZone Command Structure Type
The parameter structure of the AppendZone Command.
SetZones Command Structure Type
The parameter structure of the SetZones Command.
SubscribeAutoEdgeRecognitionData Command Structure Type
The parameter structure of the SubscribeAutoEdgeRecognitionData Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Timeout | uint8 | M | Subscription timeout. |
Trait Definitions
ZonesInfo Trait
Contains parameters such as zone color and name. This trait is not reported by the device, but is generated by the cloud.
| Trait ID | Code |
|---|
| 0x4F8D | ZonesInfo |
Parameters
Zones Trait
This Trait is used to configure and read detection zone information, including the zone type, zone bitmap and whether proximity detection is enabled for the zone.
Parameters
ProximityDistanceLevel Trait
This Trait is used to set the current proximity sensing distance level and declare the maximum proximity sensing level range supported by the device.
| Trait ID | Code |
|---|
| 0x4F5A | ProximityDistanceLevel |
Parameters
AIEntryExitRegionRecognition Trait
This Trait is used to report AI entry/exit region recognition results, for the upper system to analyze zone entry/exit behavior.
| Trait ID | Code |
|---|
| 0x4F32 | AIEntryExitRegionRecognition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | V | O |
AutoEdgeRecognition Trait
This Trait is used to report automatic edge recognition results, helping to determine the effective detection boundary.
| Trait ID | Code |
|---|
| 0x4F31 | AutoEdgeRecognition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | V | O |
AutoInterferenceSourceRecognition Trait
This Trait is used to report automatic interference source recognition results, used to identify environmental factors that may affect sensing quality.
| Trait ID | Code |
|---|
| 0x4F30 | AutoInterferenceSourceRecognition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | V | O |
BedHeightSetting Trait
This Trait is used for access to and reporting of "bed height setting" data. Unit: mm.
| Trait ID | Code |
|---|
| 0x4F2E | BedHeightSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 40 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 1500 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 40 | RW | O |
FallDelayTimeSetting Trait
This Trait is used for access to and reporting of "fall delay time setting" data. Unit: S.
| Trait ID | Code |
|---|
| 0x4F2F | FallDelayTimeSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 20 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 300 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 20 | RW | O |
FallDetectionSensitivity Trait
This Trait is used for access to and reporting of "fall detection sensitivity" data.
| Trait ID | Code |
|---|
| 0x4F2D | FallDetectionSensitivity |
Parameters
FallMaskBitmask Trait
This Trait is used for access to and reporting of "fall mask bitmask" data.
| Trait ID | Code |
|---|
| 0x4F2C | FallMaskBitmask |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
EnableFallDetection Trait
This Trait is used for access to and reporting of "enable fall detection" data.
| Trait ID | Code |
|---|
| 0x4F2B | EnableFallDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
DetectionDirectionSetting Trait
This Trait is used for access to and reporting of "detection direction setting" data.
| Trait ID | Code |
|---|
| 0x4F2A | DetectionDirectionSetting |
Parameters
InstallHeightSetting Trait
This Trait is used for access to and reporting of "install height setting" data. Unit: mm.
| Trait ID | Code |
|---|
| 0x4F15 | InstallHeightSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 4000 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1500 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
CoordinateReverseSetting Trait
This Trait is used for access to and reporting of "coordinate reverse setting" data.
| Trait ID | Code |
|---|
| 0x4F29 | CoordinateReverseSetting |
Parameters
EnableAIAdaptiveSensitivity Trait
This Trait is used for access to and reporting of "enable AI adaptive sensitivity" data.
| Trait ID | Code |
|---|
| 0x4F28 | EnableAIAdaptiveSensitivity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableAIInterferenceSourceRecognition Trait
This Trait is used for access to and reporting of "enable AI interference source recognition" data.
| Trait ID | Code |
|---|
| 0x4F27 | EnableAIInterferenceSourceRecognition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableAverageOccupancyDurationDetection Trait
This Trait is used for access to and reporting of "enable average occupancy duration detection" data.
| Trait ID | Code |
|---|
| 0x4F25 | EnableAverageOccupancyDurationDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableActivityDetection Trait
This Trait is used for access to and reporting of "enable activity detection" data.
| Trait ID | Code |
|---|
| 0x4F24 | EnableActivityDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableAIHighPrecisionRecognition Trait
This Trait is used for access to and reporting of "enable AI high precision detection" data.
| Trait ID | Code |
|---|
| 0x4F23 | EnableAIHighPrecisionRecognition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableTrafficFlowDetection Trait
This Trait is used for access to and reporting of "enable traffic flow detection" data.
| Trait ID | Code |
|---|
| 0x4F22 | EnableTrafficFlowDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableWalkingDistanceDetection Trait
This Trait is used for access to and reporting of "enable walking distance detection" data.
| Trait ID | Code |
|---|
| 0x4F21 | EnableWalkingDistanceDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableVisitorCountDetection Trait
This Trait is used for access to and reporting of "enable visitor count detection" data.
| Trait ID | Code |
|---|
| 0x4F20 | EnableVisitorCountDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableHumanCountDetection Trait
This Trait is used for access to and reporting of "enable human count detection" data.
| Trait ID | Code |
|---|
| 0x4F1F | EnableHumanCountDetection |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EnableLargeMotionRecognition Trait
This Trait is used for access to and reporting of "enable large motion recognition" data.
| Trait ID | Code |
|---|
| 0x4F1E | EnableLargeMotionRecognition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
EdgeRegionBitmask Trait
This Trait is used for access to and reporting of "edge region bitmask" data.
| Trait ID | Code |
|---|
| 0x4F1D | EdgeRegionBitmask |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
InterferenceRegionBitmask Trait
This Trait is used for access to and reporting of "interference region bitmask" data.
| Trait ID | Code |
|---|
| 0x4F1C | InterferenceRegionBitmask |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
EntryExitRegionBitmask Trait
This Trait is used for access to and reporting of "entry/exit region bitmask" data.
| Trait ID | Code |
|---|
| 0x4F1B | EntryExitRegionBitmask |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
EnablePostureRecognition Trait
This Trait is used for access to and reporting of "enable posture recognition" data.
| Trait ID | Code |
|---|
| 0x4F1A | EnablePostureRecognition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
MaxDetectionAreas Trait
This Trait is used for access to and reporting of "maximum detection zone" data.
| Trait ID | Code |
|---|
| 0x4F18 | MaxDetectionAreas |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
InstallAngle Trait
This Trait is used for access to and reporting of "install angle" data.
| Trait ID | Code |
|---|
| 0x4F17 | InstallAngle |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
InstallMode Trait
This Trait is used for access to and reporting of "install mode" data.
| Trait ID | Code |
|---|
| 0x4F13 | InstallMode |
Parameters
SideInstall Trait
This Trait is used for access to and reporting of "side install" data.
| Trait ID | Code |
|---|
| 0x4F14 | SideInstall |
Parameters
InstallStatus Trait
This Trait is used for access to and reporting of "install status" data.
| Trait ID | Code |
|---|
| 0x4F16 | InstallStatus |
Parameters
AISpaceBackgroundLearningComplete Trait
This Trait is used for access to and reporting of "AI space background learning complete" data.
| Trait ID | Code |
|---|
| 0x4FAA | AISpaceBackgroundLearningComplete |
Parameters
AISpaceBackgroundLearningReportingTimeout Trait
This Trait is used for access to and reporting of "AI space background learning timeout" data. Unit: S.
| Trait ID | Code |
|---|
| 0x4FA9 | AISpaceBackgroundLearningReportingTimeout |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
InterferenceSourceRecognitionReportingTimeout Trait
This Trait is used for access to and reporting of "interference source recognition timeout" data. Unit: S.
| Trait ID | Code |
|---|
| 0x4FA8 | InterferenceSourceRecognitionReportingTimeout |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
DetectionRange Trait
This Trait is used to configure the radar detection range as a set of discrete detection range units.
The distance units of MinDetectionRange, MaxDetectionRange and DetectionRangeStep are all cm. The server should ensure that (MaxDetectionRange - MinDetectionRange) / DetectionRangeStep is always an integer multiple of 8, so that the detection range units can be completely mapped to bytes without padding bits.
The bitmask byte length of this Trait is (MaxDetectionRange - MinDetectionRange) / DetectionRangeStep / 8. For example, with a minimum range of 0, a maximum range of 600 and a step of 25 cm, the bitmask length is 600 / 25 / 8 = 3 bytes, representing 24 detection range units of 25 cm each.
image::../images/aqara_Ambient_configuration_cluster/detection_range_bitmask.svg[DetectionRangeBitmask layout example,780]
Bit n (with the least significant bit as bit 0) corresponds to the detection range unit from MinDetectionRange + n × DetectionRangeStep to MinDetectionRange + (n+1) × DetectionRangeStep cm. A value of 1 indicates that the unit is included in the current detection range, and 0 indicates it is not included.
When this Trait is NULL, it indicates that the detection range is not configured. A write operation should update the device's detection range configuration, a read operation should return the current configuration; writing NULL should clear the configured detection range. At least one detection range unit should be selected; all bits being 0 is not allowed.
| Trait ID | Code |
|---|
| 0x5117 | DetectionRange |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | | RVW | O |
MinDetectionRange Trait
This Trait indicates the minimum detection distance supported by the device, in cm. A value of 0 means 0 cm.
| Trait ID | Code |
|---|
| 0x5187 | MinDetectionRange |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 600 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
MaxDetectionRange Trait
This Trait indicates the maximum detection distance supported by the device, in cm. A value of 600 means 600 cm.
| Trait ID | Code |
|---|
| 0x5188 | MaxDetectionRange |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 600 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 600 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
DetectionRangeStep Trait
This Trait indicates the step of each detection range unit, in cm. A value of 25 means 25 cm. The client should use this value in combination with MinDetectionRange and MaxDetectionRange to determine the expected byte length of the DetectionRange bitmask and the distance represented by each bit.
| Trait ID | Code |
|---|
| 0x5189 | DetectionRangeStep |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 25 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 600 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 25 | RW | O |
SensingMode Trait
This Trait is used to configure the sensing working mode of PIR and Radar, such as PIR-only, Radar-only or dual-mode cooperation.
| Trait ID | Code |
|---|
| 0x5118 | SensingMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0006 | Supported Value | list[uint8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
DetectionRangeTargetPosition Trait
This Trait is used to report data related to target positions within the detection range, facilitating visual calibration and range calibration.
| Trait ID | Code |
|---|
| 0x511A | DetectionRangeTargetPosition |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | 0 | V | O |
| 0x0002 | Maximum Value | characterString | | 65535 | R | O |
| 0x0003 | Minimum Value | characterString | | 0 | R | O |
Command Definitions
RemoveZone Command
This Command is used to execute the "remove zone" operation.
Parameters
RemoveZone Command Structure
UpdateZone Command
This Command is used to execute the "update zone" operation.
Parameters
UpdateZone Command Structure
EnableAISpaceBackgroundLearning Command
This Command is used to execute the "start AI space background learning" operation.
This Command has no parameters.
SubscribeAIEntryExitRegionRecognitionData Command
This Command is used to execute the "subscribe AI entry/exit region recognition data" operation.
This Command has no parameters.
SubscribeAutoEdgeRecognitionData Command
This Command is used to execute the "subscribe automatic edge recognition data" operation.
Parameters
SubscribeAutoEdgeRecognitionData Command Structure
SubscribeAutoInterferenceSourceRecognitionData Command
This Command is used to execute the "subscribe automatic interference source recognition data" operation.
This Command has no parameters.
AppendZone Command
This Command is used to execute the "append zone" operation.
Parameters
AppendZone Command Structure
SetZones Command
This Command is used to execute the "set zones" operation.
Parameters
SetZones Command Structure
SubscribeDetectionRangeTargetPosition Command
This Command is used to execute the "subscribe target position within detection range" operation.
This Command has no parameters.
RadarSensingUnion
Introduction
Provides a unified aggregation interface for ambient sensing joint data, used to aggregate capabilities such as child endpoint lists, zone identifiers, people counting and motion status, supporting cross-zone information aggregation and zone-based reporting in Leader/Child scenarios.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E4 | RadarSensingUnion | Radar sensing union |
Trait
Command
This Function does not contain Commands.
Data Types
FirstNetInEnum8 Type
This enumeration defines the valid values of the Present Value of the FirstNetIn Trait.
| Value | Name | Description |
|---|
| 0x00 | FirstNetIn | First network entry |
| 0x01 | NetInGuide | Network entry guidance complete |
| 0x02 | SecondStep | Entered step two |
| 0x03 | ThirdStep | Entered step three |
| 0x04 | FourthStep | Entered step four |
CumulativeHumanExitCountTraitPresentValueStructure Type
This structure defines the Present Value field layout of the CumulativeHumanExitCount Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartTime | uint32 | M | Start time, unit s. |
| 1 | EndTime | uint32 | M | End time, unit s. |
| 2 | Count | uint16 | M | Cumulative number of people who exited. |
CumulativeHumanEntryCountTraitPresentValueStructure Type
This structure defines the Present Value field layout of the CumulativeHumanEntryCount Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartTime | uint32 | M | Start time, unit s. |
| 1 | EndTime | uint32 | M | End time, unit s. |
| 2 | Count | uint16 | M | Cumulative number of people who entered. |
PeriodicAverageOccupancyDurationTraitPresentValueStructure Type
This structure defines the Present Value field layout of the PeriodicAverageOccupancyDuration Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartTime | uint32 | M | Start time, unit s. |
| 1 | EndTime | uint32 | M | End time, unit s. |
| 2 | Duration | uint32 | M | Average occupancy duration, unit s. |
PeriodicTotalWalkingDistanceTraitPresentValueStructure Type
This structure defines the Present Value field layout of the PeriodicTotalWalkingDistance Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartTime | uint32 | M | Start time, unit s. |
| 1 | EndTime | uint32 | M | End time, unit s. |
| 2 | Distance | uint32 | M | Total walking distance, unit m. |
PeriodicPeakVisitorCountTraitPresentValueStructure Type
This structure defines the Present Value field layout of the PeriodicPeakVisitorCount Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartTime | uint32 | M | Start time, unit s. |
| 1 | EndTime | uint32 | M | End time, unit s. |
| 2 | Count | uint16 | M | Visitor count value. |
PeriodicPeakHumanCountTraitPresentValueStructure Type
This structure defines the Present Value field layout of the PeriodicPeakHumanCount Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartTime | uint32 | M | Start time, unit s. |
| 1 | EndTime | uint32 | M | End time, unit s. |
| 2 | Count | uint16 | M | People count value. |
MotionDetectedEnum8 Type
This enumeration defines the valid values of the Present Value of the MotionDetected Trait.
| Value | Name | Description |
|---|
| 0x00 | Enter | Entering |
| 0x01 | Left | Leaving |
| 0x02 | LeftIn | Left entry |
| 0x03 | RightOut | Right exit |
| 0x04 | RightIn | Right entry |
| 0x05 | LeftOut | Left exit |
| 0x06 | Access | Approaching |
| 0x07 | Away | Moving away |
VisitCountDeltaTraitPresentValueStructure Type
This structure defines the Present Value field layout of the VisitCountDelta Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CountDelta | uint16 | M | The visitor increment detected since the last VisitCountDelta report, in times, with a value of at least 1. |
| 1 | ObservationDuration | uint32 | M | The observation duration for collecting this increment, unit s. |
OccupancyDurationDeltaTraitPresentValueStructure Type
This structure defines the Present Value field layout of the OccupancyDurationDelta Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DurationDelta | uint32 | M | The accumulated occupancy duration increment since the last OccupancyDurationDelta report, unit s, with a value of at least 1. |
| 1 | ObservationDuration | uint32 | M | The observation duration for collecting this increment, unit s. |
WalkingDistanceDeltaTraitPresentValueStructure Type
This structure defines the Present Value field layout of the WalkingDistanceDelta Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | DistanceDelta | uint32 | M | The accumulated walking distance increment since the last WalkingDistanceDelta report, unit m, with a value of at least 1. |
| 1 | ObservationDuration | uint32 | M | The observation duration for collecting this increment, unit s. |
HumanEntryCountDeltaTraitPresentValueStructure Type
This structure defines the Present Value field layout of the HumanEntryCountDelta Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CountDelta | uint16 | M | The human entry increment detected since the last HumanEntryCountDelta report, in times, with a value of at least 1. |
| 1 | ObservationDuration | uint32 | M | The observation duration for collecting this increment, unit s. |
HumanExitCountDeltaTraitPresentValueStructure Type
This structure defines the Present Value field layout of the HumanExitCountDelta Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CountDelta | uint16 | M | The human exit increment detected since the last HumanExitCountDelta report, in times, with a value of at least 1. |
| 1 | ObservationDuration | uint32 | M | The observation duration for collecting this increment, unit s. |
Trait Definitions
DataStayCheck Trait
This Trait is used for access to and reporting of "space stay count calibration" data.
| Trait ID | Code |
|---|
| 0x4F57 | DataStayCheck |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | M |
| 0x0002 | Maximum Value | uint32 | | 10000 | R | O |
| 0x0003 | Minimum Value | uint32 | | -10000 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
StartTime Trait
This Trait is used for access to and reporting of "statistics start time" data. Unit: minute.
| Trait ID | Code |
|---|
| 0x4F58 | StartTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 1440 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
ViewZoom Trait
This Trait is used for access to and reporting of "grid view zoom function" data.
| Trait ID | Code |
|---|
| 0x4F59 | ViewZoom |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | M |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
FirstNetIn Trait
Used for the guidance and related functions when a device first joins the network and enters the device detail page.
| Trait ID | Code |
|---|
| 0x4F56 | FirstNetIn |
Parameters
CumulativeHumanExitCount Trait
This Trait is used for access to and reporting of "cumulative human exit count" data.
| Trait ID | Code |
|---|
| 0x4F3C | CumulativeHumanExitCount |
Parameters
CumulativeHumanEntryCount Trait
This Trait is used for access to and reporting of "cumulative human entry count" data.
| Trait ID | Code |
|---|
| 0x4F3B | CumulativeHumanEntryCount |
Parameters
PeriodicAverageOccupancyDuration Trait
This Trait is used for access to and reporting of "periodic average occupancy duration" data.
| Trait ID | Code |
|---|
| 0x4F39 | PeriodicAverageOccupancyDuration |
Parameters
PeriodicTotalWalkingDistance Trait
This Trait is used for access to and reporting of "periodic total walking distance" data.
| Trait ID | Code |
|---|
| 0x4F3A | PeriodicTotalWalkingDistance |
Parameters
PeriodicPeakVisitorCount Trait
This Trait is used for access to and reporting of "periodic peak visitor count" data.
| Trait ID | Code |
|---|
| 0x4F38 | PeriodicPeakVisitorCount |
Parameters
CurrentVisitorCount Trait
This Trait is used for access to and reporting of "current visitor count" data.
| Trait ID | Code |
|---|
| 0x4F37 | CurrentVisitorCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
PeriodicPeakHumanCount Trait
This Trait is used for access to and reporting of "periodic peak human count" data.
| Trait ID | Code |
|---|
| 0x4F36 | PeriodicPeakHumanCount |
Parameters
CurrentHumanCount Trait
This Trait is used for access to and reporting of "current human count" data.
| Trait ID | Code |
|---|
| 0x4F35 | CurrentHumanCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint16 | | 10 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
ZoneID Trait
This Trait is used for access to and reporting of "zone ID" data.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
ChildEndpointList Trait
This Trait is used to report the list of Child endpoint identifiers managed by the Leader endpoint. If the list is empty, it indicates that no Child endpoint is currently managed.
| Trait ID | Code |
|---|
| 0x4F33 | ChildEndpointList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
MotionDetected Trait
This Trait is used to report motion state changes. In the Leader role, the global motion state can be reported; in the Child role, the motion state of its bound zone is reported.
| Trait ID | Code |
|---|
| 0x80EA | MotionDetected |
Parameters
VisitCountDelta Trait
Used to report the visitor increment detected since the last VisitCountDelta report; the client can accumulate this increment to obtain the cumulative visitor count.
| Trait ID | Code |
|---|
| 0x50E2 | VisitCountDelta |
Parameters
OccupancyDurationDelta Trait
Used to report the accumulated occupancy duration increment since the last OccupancyDurationDelta report, in seconds.
| Trait ID | Code |
|---|
| 0x50E3 | OccupancyDurationDelta |
Parameters
WalkingDistanceDelta Trait
Used to report the accumulated walking distance increment since the last WalkingDistanceDelta report, in meters.
| Trait ID | Code |
|---|
| 0x50E4 | WalkingDistanceDelta |
Parameters
HumanEntryCountDelta Trait
Used to report the human entry increment (delta, not the cumulative total) detected since the last HumanEntryCountDelta, mapped and reported from the radar sensing Union Event. The server may report incrementally (CountDelta=1) or aggregate multiple detections before reporting; the same detection must not be reported repeatedly. The client should accumulate CountDelta to obtain the cumulative entry count, and should not rely on the server to persist or replay lost events.
| Trait ID | Code |
|---|
| 0x50E5 | HumanEntryCountDelta |
Parameters
HumanExitCountDelta Trait
Used to report the human exit increment (delta, not the cumulative total) detected since the last HumanExitCountDelta, mapped and reported from the radar sensing Union Event. The server may report incrementally (CountDelta=1) or aggregate multiple detections before reporting; the same detection must not be reported repeatedly. The client should accumulate CountDelta to obtain the cumulative exit count, and should not rely on the server to persist or replay lost events.
| Trait ID | Code |
|---|
| 0x50E6 | HumanExitCountDelta |
Parameters
Command Definitions
This Function does not contain Commands.
OccupantLocation
Introduction
Used to synchronize the location data of presence targets, providing information such as target type, posture and activity state, supporting per-target location subscription and detection target management.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E5 | OccupantLocation | Occupant location |
Trait
Command
Data Types
LocationInfoTraitPresentValueStructure Type
This structure defines the Present Value field layout of the LocationInfo Trait.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | TargetId | uint8 | M | Target ID. |
| 1 | TargetXCoordinate | int16 | M | Target X coordinate. |
| 2 | TargetYCoordinate | int16 | M | Target Y coordinate. |
| 3 | TargetZCoordinate | int16 | M | Target Z coordinate. |
| 4 | TargetVelocity | int16 | M | Target speed. |
| 5 | TargetSignalToNoiseRatio | uint16 | M | Target signal-to-noise ratio. |
| 6 | TargetType | enum8 | M | Target type: 0=Person, 1=NotPerson, 2=Fan, 3=Pet, 4=Curtain, 5=GreenPlants, 6=Sweeper, 7=AirPurifier, 8=Child, 0xFF=Unknown. |
| 7 | TargetPosture | enum8 | M | Target posture: 0=Walk, 1=Sit, 2=Stand, 3=Lie, 4=Fall, 0xFF=Undefined. |
| 8 | TargetZoneId | uint8 | M | The detection zone ID where the target is located. |
ActivityStateEnum8 Type
This enumeration defines the valid values of the Present Value of the ActivityState Trait.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown |
| 0x01 | Active | Active |
| 0x02 | Still | Static |
FallStateEnum8 Type
This enumeration defines the valid values of the Present Value of the FallState Trait.
| Value | Name | Description |
|---|
| 0x00 | Cleared | Cleared |
| 0x01 | Fall | Fall |
| 0x02 | SuspectedFall | Suspected fall |
LargeMotionStateEnum8 Type
This enumeration defines the valid values of the Present Value of the LargeMotionState Trait.
| Value | Name | Description |
|---|
| 0x00 | None | None |
| 0x01 | Action1 | Motion 1 |
| 0x02 | Action2 | Motion 2 |
LyingStateEnum8 Type
This enumeration defines the valid values of the Present Value of the LyingState Trait.
| Value | Name | Description |
|---|
| 0x00 | None | None |
| 0x01 | Present | Present |
StandingStateEnum8 Type
This enumeration defines the valid values of the Present Value of the StandingState Trait.
| Value | Name | Description |
|---|
| 0x00 | None | None |
| 0x01 | Present | Present |
SittingStateEnum8 Type
This enumeration defines the valid values of the Present Value of the SittingState Trait.
| Value | Name | Description |
|---|
| 0x00 | None | None |
| 0x01 | Present | Present |
WalkingStateEnum8 Type
This enumeration defines the valid values of the Present Value of the WalkingState Trait.
| Value | Name | Description |
|---|
| 0x00 | None | None |
| 0x01 | Present | Present |
RemoveDetectionTarget Command Structure Type
The parameter structure of the RemoveDetectionTarget Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | TargetID | uint8 | M | Target ID. |
SubscribeLocationData Command Structure Type
The parameter structure of the SubscribeLocationData Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Timeout | uint16 | M | Subscription timeout, in seconds. |
Trait Definitions
MaxDetectionTargets Trait
This Trait is used to report the maximum number of detection targets supported by the device.
| Trait ID | Code |
|---|
| 0x4F3E | MaxDetectionTargets |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
LocationInfo Trait
This Trait is used to report the list of currently detected target locations and tracking information.
| Trait ID | Code |
|---|
| 0x4F46 | LocationInfo |
Parameters
ActivityState Trait
This Trait is used to report the aggregated activity state, such as active, static or unknown.
| Trait ID | Code |
|---|
| 0x4F45 | ActivityState |
Parameters
FallState Trait
This Trait is used for access to and reporting of "fall state" data.
| Trait ID | Code |
|---|
| 0x4F44 | FallState |
Parameters
LargeMotionState Trait
This Trait is used for access to and reporting of "large motion state" data.
| Trait ID | Code |
|---|
| 0x4F43 | LargeMotionState |
Parameters
LyingState Trait
This Trait is used for access to and reporting of "lying state" data.
| Trait ID | Code |
|---|
| 0x4F42 | LyingState |
Parameters
StandingState Trait
This Trait is used for access to and reporting of "standing state" data.
| Trait ID | Code |
|---|
| 0x4F41 | StandingState |
Parameters
SittingState Trait
This Trait is used for access to and reporting of "sitting state" data.
| Trait ID | Code |
|---|
| 0x4F40 | SittingState |
Parameters
WalkingState Trait
This Trait is used for access to and reporting of "walking state" data.
| Trait ID | Code |
|---|
| 0x4F3F | WalkingState |
Parameters
Command Definitions
RemoveDetectionTarget Command
This Command is used to execute the "remove detection target" operation.
Parameters
RemoveDetectionTarget Command Structure
SubscribeLocationData Command
This Command is used to execute the "subscribe location data" operation.
Parameters
SubscribeLocationData Command Structure
MatterCoordination
Introduction
Centrally manages Matter protocol related coordination operations, including network entry, binding, data synchronization and certificate management.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E6 | MatterCoordination | Matter function coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIUnbindMatterDeviceDown Command
Matter device unbind command (downlink). The cloud sends a command to the gateway to remove (unbind) the specified Matter device from the home network. The gateway executes the local unbind flow and updates the network topology.
This Command has no parameters.
APIUnbindMatterDeviceUP Command
Matter device unbind state report (uplink). The gateway reports the result or state of a locally triggered Matter device unbind event to the cloud, ensuring that the cloud device list stays in sync with the local network state.
This Command has no parameters.
APIPushMatterBindInfo Command
Matter device network entry/binding info push. The cloud sends the network entry permission, network credentials or configuration information of a new Matter device to the gateway, guiding and authorizing the device to join the local Matter network.
This Command has no parameters.
APIStartBindMatterDeviceToHub Command
Aqara Spec device binding start. The gateway reports the discovery of a new Aqara Spec device to the cloud and requests to start the binding process. This is the first step of the multi-step device onboarding flow.
This Command has no parameters.
APIReportDeviceAqaraSpecModel Command
Aqara Spec device Thing model detailed report. During device onboarding, the gateway reports the complete thing model definition (functions, attributes, commands, etc.) supported by the newly discovered Aqara Spec device to the cloud, for device function registration and dynamic UI generation.
This Command has no parameters.
APISyncAqaraSpecDataToCloud Command
Aqara Spec device resource data cloud sync. The gateway batch-syncs all current state data (e.g., all attribute values) of the local Aqara Spec device to the cloud. This is typically used for full state recovery after initial device enabling or network restoration.
This Command has no parameters.
APIGenNextMatterNodeId Command
Matter network Node ID generation request. When preparing to assign a network identity to a new Matter device, the gateway requests the cloud to generate a globally unique and compliant Node ID.
This Command has no parameters.
APIGenHomeMatterNoc Command
Home Matter NOC certificate generation request. When establishing or managing a Matter Fabric, the gateway requests the cloud to generate or update the Matter Network Operation Certificate (NOC) for the current user's home, for secure authentication.
This Command has no parameters.
APIQueryMatterJoinLimit Command
Matter device network entry limit policy query. Before allowing a new device to join the Matter network, the gateway queries the cloud about whether the current home or gateway has reached the device limit, or whether other network entry limit policies exist.
This Command has no parameters.
OTACoordination
Introduction
Manages the OTA firmware upgrade coordination flow, including task dispatch, progress reporting, result feedback and version query.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E7 | OTACoordination | OTA function coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIUpgradeDeviceFirmware Command
Sub-device firmware upgrade command dispatch. The cloud sends an over-the-air (OTA) firmware upgrade command for the specified sub-device (Zigbee, Bluetooth, etc.) to the gateway, including firmware version and download address information.
This Command has no parameters.
APICancelOtaUpgrade Command
Device OTA upgrade cancel Command. The cloud sends a command to the gateway to cancel the ongoing firmware upgrade task of the specified device.
This Command has no parameters.
APIReportOtaProgress Command
OTA upgrade progress report. The gateway reports the current progress of the sub-device firmware upgrade to the cloud in real time (e.g., download percentage, flashing state), for display on the front-end interface.
This Command has no parameters.
APIReportOtaResult Command
OTA upgrade final result report. After the sub-device firmware upgrade task completes (success or failure), the gateway reports the final result and details to the cloud (e.g., the successful version number, the failure error code).
This Command has no parameters.
APIReportOtaDeviceListState Command
OTA upgrade device list state report. The gateway reports the aggregated state list of all devices that are currently upgrading, waiting to upgrade or failed to upgrade to the cloud, for centralized monitoring of the upgrade batch.
This Command has no parameters.
APIInquiryFirmwareInfo Command
Gateway firmware info query request. The gateway proactively queries the cloud about whether there is a new firmware version applicable to itself and related metadata (e.g., version number, update log, file size), to trigger the gateway's own OTA upgrade check.
This Command has no parameters.
StudioCoordination
Introduction
Manages the integration between the gateway and the Aqara Studio development environment, including account authentication, project backup and device synchronization.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E8 | StudioCoordination | Studio function coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIGetPositionByDeviceId Command
Query room by device ID. When the gateway needs to organize the device list or perform room-level control, it queries the cloud for the room name or room ID to which the specified device ID currently belongs.
This Command has no parameters.
APIGetAuthCode Command
User authentication code acquisition request.
This Command has no parameters.
APILoginByAuthCode Command
Auth code login request.
This Command has no parameters.
APILoginByGuardCode Command
Account password login request.
This Command has no parameters.
APIGetUserDeviceList Command
User device list acquisition request. The gateway requests the cloud for the list of all bound devices under the currently logged-in user account, including device ID, name, type and basic state, usually initiated during initialization, refresh or management interface operations.
This Command has no parameters.
APIGetStudioBackupUploadUrl Command
Studio backup file upload URL request. After creating a local Studio (development/configuration environment) backup, the gateway requests a temporary, secure file upload URL from the cloud to transfer the backup file to cloud storage.
This Command has no parameters.
APIGetStudioBackupInfo Command
Studio cloud backup info query request. The gateway queries the cloud for the list of existing Studio backup files of the current user or gateway and their metadata (e.g., backup time, size, description), for restoration or backup management.
This Command has no parameters.
APIConfirmStudioBackupSuccess Command
Studio cloud backup upload success confirmation. After the backup file is successfully uploaded to the cloud, the gateway sends a confirmation notification to the cloud, prompting it to mark the backup file as available and complete the storage flow.
This Command has no parameters.
APIDeleteStudioBackup Command
Studio cloud backup deletion request. The gateway requests the cloud to delete a specified historical Studio backup file, to free up storage space or clean up old data.
This Command has no parameters.
APIReportStudioInfo Command
Studio running info report. The gateway proactively reports the running state, version and configuration summary of the local Aqara Studio instance to the cloud, for monitoring and statistical analysis.
This Command has no parameters.
APIGetProxyServerInfo Command
Proxy server connection info query request. The gateway (or its Studio environment) requests the cloud for available proxy server addresses and configuration information, to establish specific network connections (e.g., remote debugging, external service access).
This Command has no parameters.
CameraCoordination
Introduction
Handles complex camera business logic, including WebRTC calls, gimbal control, recognition data synchronization and extended events.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00E9 | CameraCoordination | Camera function coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIIssueTokenForWebRTCCall Command
WebRTC device call token issuance request. When a WebRTC-capable video device (such as a camera) needs to establish a peer-to-peer audio/video call or stream, the device requests the cloud to issue a temporary security token on its behalf, for authentication and session establishment.
This Command has no parameters.
APIGetSignallingServerAddress Command
Signaling server address acquisition request. The device queries the cloud for the currently available signaling server address list, to support P2P connection negotiation for devices using real-time communication protocols such as WebRTC.
This Command has no parameters.
APIOperateCameraDown Command
Camera downlink operation Command. The cloud sends specific control commands to the camera device, such as gimbal control, adding/invoking presets, face database management, cruise settings, etc.
This Command has no parameters.
APIOperateBridgedDevice Command
Bridge device operation Command. The cloud sends commands through the gateway to devices acting as bridges (e.g., multi-function gateway, repeater), instructing them to perform specific operations (e.g., on/off, configuration) on the sub-devices they connect or manage.
This Command has no parameters.
APIUnbindWiFiSubdevice Command
WiFi sub-device unbind success report. The device reports to the cloud that a WiFi sub-device has been successfully unbound (removed) from this device or its bridge management.
This Command has no parameters.
APIDeviceCameraCall Command
Device-initiated call request (e.g., Camera). When the camera or other device detects a specific event (e.g., doorbell press, motion detection), it proactively initiates an audio/video call or push notification request to the cloud for the user to answer or view.
This Command has no parameters.
APIOperateCameraUp Command
Camera uplink operation request. The device proactively initiates special operation requests for the camera to the cloud, such as requesting cloud AI analysis of video clips, applying for temporary cloud storage quota upgrades, and reporting self-check exceptions.
This Command has no parameters.
APIBindWiFiSubdevice Command
WiFi sub-device bind success report. The device reports to the cloud that a WiFi sub-device (e.g., WiFi camera, smart plug) has been successfully bound to the home network and user account through this device or its bridging function.
This Command has no parameters.
APICheckFaceDataConsistency Command
Face recognition data consistency check request. The device reports the summary of the locally stored face recognition feature library to the cloud, requesting comparison and receiving differences (face data to be added or deleted) to keep the face library synchronized.
This Command has no parameters.
APIReportCameraExtEvents Command
Camera extended business event report. The device reports extended events generated by the camera beyond basic state changes (e.g., intelligent recognition results, abnormal behavior alerts, scene analysis events) to the cloud for advanced applications and AI analysis.
This Command has no parameters.
APICheckCarDataConsistency Command
Vehicle recognition data consistency check request. The device reports the summary of the locally stored vehicle recognition feature library to the cloud, requesting comparison and receiving differences (vehicle data to be added or deleted) to maintain vehicle database synchronization.
This Command has no parameters.
APIConfigCameraSpecific Command
Camera-specific configuration operation Command. The cloud sends configuration query, setting or modification commands for camera-specific functions (e.g., RTSP stream address, encoding parameters, motion detection area) to the camera.
This Command has no parameters.
SecurityGuardCoordination
Introduction
Manages home space security alerting capabilities, including arming/disarming, alarm confirmation, and local/cloud configuration synchronization.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00EA | SecurityGuardCoordination | Security guard coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIConfirmSecurityAlert Command
Home security alarm confirmation Command. After the user confirms the home security alarm (e.g., intrusion detection) reported by the device through the cloud App, the cloud sends this confirmation Command to the device. The device then stops pushing the alarm and may update its local state.
This Command has no parameters.
APIEnableSecurity Command
Home security function enable/disable Command. The cloud sends a command to enable or disable the overall home security subsystem functions on the device.
This Command has no parameters.
APIRepairSecurityEnable Command
Home security enable state repair Command. When the cloud detects that the device's local security enable state is inconsistent with the cloud records, it sends this Command to force the device's local enable state to synchronize with the cloud-specified state, used to repair state drift.
This Command has no parameters.
APISyncSecurityLanInfo Command
Home security LAN state sync Command. The cloud sends the latest home security-related configuration, device state or scene information to the device, ensuring that the gateway's local security logic is consistent with the cloud configuration.
This Command has no parameters.
APIDeleteSecurityLocal Command
Home security local configuration deletion Command. The cloud instructs the gateway to delete specific locally stored home security configurations (e.g., security scenes or device bindings), usually for configuration cleanup or reset.
This Command has no parameters.
APICheckSecurityConfigConsistency Command
Home security configuration consistency check request. The device proactively requests the cloud to compare whether the detailed home security configurations stored on both sides (e.g., arming mode, linkage rules) are completely consistent, and returns the comparison result.
This Command has no parameters.
APICheckSecurityEnableConsistency Command
Home security enable state consistency check request. The device queries the cloud to verify whether the "master switch" state (on/off) recorded for the home security function is consistent on both sides.
This Command has no parameters.
SceneCoordination
Introduction
Manages the lifecycle of smart scenes (automation rules), including synchronization, deletion, triggered execution and consistency checks.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00EB | SceneCoordination | Scene linkage coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIRunScene Command
Scene execution Command (generic). The cloud sends a command to the device to immediately execute the specified pre-configured scene. The device is responsible for parsing the scene actions and controlling local or sub-devices to perform the corresponding operations.
This Command has no parameters.
APIRunLocalScene Command
Cloud-triggered local scene execution Command. The cloud triggers an automation scene that has been stored and runs locally on the device (instead of a cloud-virtualized scene). Upon receipt, the device directly executes the local scene logic for low-latency response.
This Command has no parameters.
APIDownloadLocalScene Command
Scene configuration localization sync Command. The cloud sends the complete definition of the user-created automation scene (trigger conditions, execution actions) to the device. The device stores it locally and is responsible for subsequent execution, making the scene available offline.
This Command has no parameters.
APIDownloadCentralScene Command
Central scene configuration localization sync Command. For systems supporting multi-gateway hubs/edge computing, the cloud sends "central scene" configurations involving cross-gateway collaboration to the gateway acting as the hub, for localized storage and distributed coordinated execution.
This Command has no parameters.
APIDeleteLocalScene Command
Local scene deletion Command. The cloud instructs the device to delete one or more specified synchronized scenes from its local storage, usually for sync cleanup after the user deletes scenes in the cloud.
This Command has no parameters.
APICheckLocalSceneSync Command
Local scene info sync check request. The device reports summary information of all locally stored scenes (e.g., ID, version) to the cloud, requesting comparison and receiving the list of scenes to be updated or deleted, to maintain two-way synchronization.
This Command has no parameters.
HubCoordination
Introduction
As the core coordination module of the gateway, it manages sub-device onboarding, configuration, heartbeat, tokens and various proxy services.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00EC | HubCoordination | Gateway function coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APISyncTokenDown Command
Device Token sync downlink Command. The cloud sends the latest authorized Token or other security credentials of the user or device to the device, updating the authentication information used when the device communicates with the cloud or other services.
This Command has no parameters.
APIRpcDebugCommand Command
Gateway remote procedure call (RPC) debug Command. The cloud sends a generic RPC debug Command to the gateway for remotely performing diagnostics, retrieving internal state, testing specific functions or modifying debug parameters. It is an important tool for development and operations.
This Command has no parameters.
APIEnableSubdeviceJoining Command
Sub-device onboarding mode enable Command. The cloud instructs the gateway to enter pairing/discovery mode, allowing new sub-devices (Zigbee, Bluetooth, etc.) to join the network within a specified duration or until a stop command is received.
This Command has no parameters.
APIDisableSubdeviceJoining Command
Sub-device onboarding mode disable Command. The cloud instructs the gateway to immediately exit the pairing/discovery mode for new sub-devices and resume normal operation.
This Command has no parameters.
APIUnbindSubdeviceDown Command
Sub-device downlink unbind Command. The cloud sends a command to the gateway to remove (unbind) the specified sub-device from its management list. The gateway will perform the local unbind process and stop communicating with it.
This Command has no parameters.
APIUnbindHubDown Command
Hub downlink unbind Command. The cloud instructs the Hub to perform the unbind process from the current user account, usually including resetting network configuration, clearing user data and preparing for a new user binding.
This Command has no parameters.
APISetSubdeviceMixing Command
Sub-device combination and integration configuration Command. The cloud instructs the gateway to logically combine or integrate multiple independent physical sub-devices into virtual composite devices for unified control or complex scenes.
This Command has no parameters.
APISyncDataCloudToHub Command
Cloud-to-hub batch data sync Command. The cloud sends data packages to the hub to batch-synchronize non-real-time business data such as user configuration, device relationships and scene rules, ensuring the hub can restore full service state after going offline or initialization.
This Command has no parameters.
APIClearLocalData Command
Hub local data clear Command. The cloud instructs the Hub to clear specific types or all user data and configurations synchronized from the cloud and stored locally (e.g., scenes, device bindings), usually for account switching or data reset.
This Command has no parameters.
APICheckHubDataConsistency Command
Hub data consistency check Command. The cloud proactively requests the Hub to compare its stored data summary with the cloud.
This Command has no parameters.
APICheckHubConfig Command
Hub system configuration check Command. The cloud sends a command requiring the Hub to self-check the current system-level configuration and report the check result or configuration summary.
This Command has no parameters.
APIPushHubConfig Command
Hub system configuration push Command. The cloud sends system-level configuration parameters or policy files to the Hub to update or initialize its runtime environment, function module parameters or connection policies.
This Command has no parameters.
APIClearHubConfig Command
Hub system configuration clear Command. The cloud instructs the Hub to clear the specified system configuration, restoring it to factory default or empty state.
This Command has no parameters.
APINotifyConfigChange Command
Hub configuration change notification Command. The cloud notifies the Hub that some of its configurations have been changed in the cloud, requiring the Hub to actively pull the latest configuration or prepare to apply the new configuration, enabling proactive push of changes.
This Command has no parameters.
APINotifyNoSubdevice Command
No sub-device state notification Command. The cloud notifies the gateway that, according to cloud records, no sub-device is bound under the current account.
This Command has no parameters.
APIStartHubProvisioning Command
Hub onboarding configuration info push Command. After a new Hub is first powered on or reset, the cloud sends the bootstrap information needed for onboarding, such as connectable server addresses, configuration Token or initial configuration, to guide it through initialization.
This Command has no parameters.
APIBindBleDeviceToHub Command
Bluetooth device bind to Zigbee hub. This Command is a coordination interface between the cloud and the Hub; the request body is defined by YApi and is not used on the Magic Pair application channel.
For Magic Pair BLE Endpoint local onboarding, the current account UserID SHALL be written via VerifyDeviceAuthenticity Cmd 9 WriteUserId, and then the device discovers the designated nearby BLE gateway; this Command must not be used as an entry point for pairing or network credential delivery.
This Command has no local application channel parameters.
APIRunFunctionInstruction Command
Cloud predefined function instruction execution request. The cloud sends a predefined function instruction code or script identifier to the hub, requiring it to interpret and execute the corresponding complex logic or a series of operations locally.
This Command has no parameters.
APITriggerSubdeviceRead Command
Sub-device data proactive read trigger Command. The cloud instructs the gateway to immediately initiate a proactive data read request to the specified sub-device (e.g., query the latest sensor values), and asynchronously report the read results to the cloud, to obtain device state on demand.
This Command has no parameters.
APIBindSubdeviceWithSecurityCode Command
Security-code-based quintuple model sub-device binding request. When a new gateway (using the quintuple authentication model) binds a sub-device, it reports the sub-device information and pre-shared security code to the cloud, requesting the cloud to verify the validity of the security code to complete secure binding.
This Command has no parameters.
APIRefreshHubToken Command
Quintuple gateway Token refresh request. When the current security token of a gateway using the quintuple authentication model is about to expire, it requests a new valid token from the cloud to maintain secure communication with the cloud.
This Command has no parameters.
APIConnectHub Command
Hub onboarding request. The Hub initiates an onboarding request to the cloud using the new onboarding protocol and process (version V1.0), submitting device credentials and network information to complete identity registration and network access.
This Command has no parameters.
APIBindSubdeviceNoAuth Command
Sub-device binding request without authentication. In specific modes (e.g., local debugging, trusted network), the hub requests the cloud to bind a sub-device, declaring that strict security authentication (e.g., quintuple verification) is bypassed.
This Command has no parameters.
APIUnbindSubdeviceUp Command
Sub-device uplink unbind notification. The gateway proactively reports to the cloud that it has locally removed (unbound) a sub-device, requesting the cloud to update the device relationships and clean up related data.
This Command has no parameters.
APIUnbindHubUp Command
Hub uplink unbind request. The Hub proactively initiates an unbind request from the current user account to the cloud, usually triggered by the user.
This Command has no parameters.
APISubdeviceKeepAlive Command
Sub-device online heartbeat report. The gateway periodically or when sub-device state changes reports the online state (heartbeat) of its managed sub-devices to the cloud, for the cloud to monitor device liveness and update the online indicators in the device list.
This Command has no parameters.
APIReportPropertyExamination Command
Debug and diagnostic info report. During system operation, the device reports non-business information such as debug logs, diagnostic events and network environment parameters to the cloud, for remote troubleshooting, system optimization and data analysis.
This Command has no parameters.
APIReportDeviceResponse Command
Device Command execution response report. After executing a control or query Command sent by the cloud, the device reports the specific response result returned by the device (including success, failure and detailed data), completing the Command interaction loop.
This Command has no parameters.
APIReportHubLocalInfo Command
Device local comprehensive info report. The device proactively reports local information to the cloud for overall state awareness and data backup.
This Command has no parameters.
APICheckHubLocalSync Command
Hub local info two-way sync check request. The Hub proactively initiates a check request to the cloud, comparing the local info summary with the cloud, detecting and correcting inconsistencies to ensure data integrity.
This Command has no parameters.
APIExecuteSubstituteCommand Command
Hub requests the cloud to execute a Command on its behalf. When the Hub cannot directly execute a Command due to permission, capability or network limitations, it requests the cloud to send the Command to the target device or service on its behalf and return the result to the Hub.
This Command has no parameters.
APIAskOtherHubToken Command
Request other gateway security Token. In scenarios requiring cross-gateway collaboration or access, the gateway requests the cloud for the security token of another designated gateway, to establish secure direct or indirect communication with it.
This Command has no parameters.
APIUploadDeviceInfo Command
Device info update report. The device reports changes to its own or its managed sub-devices' attribute information (e.g., name modification, location adjustment, icon update), requesting the cloud to synchronously update the device profile.
This Command has no parameters.
APIReportHubLocalConfig Command
Hub detailed local configuration report. The Hub proactively reports its detailed local system configuration to the cloud.
This Command has no parameters.
APISyncSubdeviceList Command
Hub sub-device list batch sync. The Hub reports the complete list and basic information (ID, type, state) of all sub-devices it manages to the cloud, refreshing the cloud records and ensuring the device inventory is accurate.
This Command has no parameters.
APIQueryDeviceResMultiExt Command
Device resource multi-value extended query request. The gateway requests the cloud to simultaneously query the current values of multiple devices or multiple resources (attributes) of a single device, supporting extended query options for efficient batch data acquisition.
This Command has no parameters.
APIQueryDeviceResMultiExtGbk Command
Device resource multi-value extended query request (GBK encoding). The request and response text data use GBK character encoding to be compatible with systems or devices requiring this encoding format.
This Command has no parameters.
APIUploadLogFileEvent Command
Log file upload event notification. The device notifies the cloud that the log file upload has been completed, triggering the cloud log processing flow.
This Command has no parameters.
APIGetSubdeviceServiceConfig Command
Sub-device service configuration query request. The gateway queries the cloud for the service configuration parameters required or recommended for a specific sub-device, such as connection policy, data reporting frequency, function enablement suggestions, etc.
This Command has no parameters.
APIGetInstallCode Command
Quintuple Install Code acquisition request. A device using the quintuple security model requests its unique "Install Code" from the cloud, for identity verification during the secure onboarding process.
This Command has no parameters.
APIGetRandomJoinCode Command
Quintuple sub-device onboarding random code acquisition request. Under the quintuple security framework, the gateway requests a one-time random onboarding code from the cloud for a new sub-device preparing to join the network, ensuring the security and uniqueness of the onboarding process.
This Command has no parameters.
APIReportHeartbeat Command
Hub self online heartbeat report. The Hub periodically sends heartbeat signals to the cloud, indicating that itself (not sub-devices) is online and running normally, for the cloud to monitor the Hub liveness state.
This Command has no parameters.
APIGetVoiceFileUrl Command
Voice prompt file URL acquisition request. The gateway requests the download URL or configuration information of voice prompt files (e.g., alarm tones, welcome messages) from the cloud, for local playback.
This Command has no parameters.
APIGetWeatherData Command
Weather data acquisition request. The device requests current weather, forecast and other meteorological information for a specified location from the cloud, for smart scene triggering or interface display.
This Command has no parameters.
APISubscribeDeviceResource Command
Device-initiated resource subscription request. The device (or the gateway on its behalf) requests the cloud to start subscribing to changes of one or more device resources. When the resource values change, the cloud will proactively push updates.
This Command has no parameters.
APIUnsubscribeDeviceResource Command
Device-initiated resource unsubscribe request. The device (or the gateway on its behalf) requests the cloud to stop pushing updates for one or more previously subscribed device resources.
This Command has no parameters.
APIReportExceptionLog Command
Device Exception Log Report. The hub or device reports exceptions, error logs, or crash information captured during operation to the cloud, facilitating fault diagnosis and system improvement by developers.
This Command has no parameters.
APIGetLoginRandomCode Command
Device login random number (Nonce) acquisition request. During device login or authentication, a random number (Nonce) is requested from the cloud, used to construct security credentials against replay attacks.
This Command has no parameters.
APIRegisterDirectDevice Command
Direct device re-onboarding registration request. A direct-connect device (e.g., via Wi-Fi Direct) requests the cloud to restore network connection and services.
This Command has no parameters.
APIGetSubdeviceConfig Command
Sub-device detailed configuration query request. The gateway queries the cloud for the detailed configuration information of the specified sub-device.
This Command has no parameters.
APIReportSubdeviceModel Command
Sub-device thing model info report. After discovering a new sub-device or upgrading sub-device firmware, the gateway reports its complete supported thing model definitions (functions, properties, commands, events) to the cloud, for updating the device capability library and dynamic UI generation.
This Command has no parameters.
APINotifySubdeviceReadResult Command
Sub-device data proactive read result asynchronous report. In response to the cloud's APITriggerSubdeviceRead command, after completing the data read of the target sub-device, the gateway asynchronously reports the read result (or timeout/failure state) to the cloud, completing the loop of this on-demand query.
This Command has no parameters.
APIReportCommandExecResult Command
Cloud predefined instruction execution result report. After executing the cloud-delivered predefined function instruction via APIRunFunctionInstruction, the hub reports the success/failure result, output data or detailed error information of the instruction execution to the cloud.
This Command has no parameters.
LightBoxCoordination
Introduction
Manages configuration push for smart light box devices, controlling the displayed content and effects.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00ED | LightBoxCoordination | Light box function coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIPushLightBoxConfig Command
Light box device configuration info push Command. The cloud sends specific configurations of the smart light box device (e.g., lighting effects, color schemes, scheduled plans) to the gateway, which then forwards or applies them to the target light box device.
This Command has no parameters.
IRCoordination
Introduction
Manages gateway IR learning and transmission, including code library synchronization, virtual remote creation and key control.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00EE | IRCoordination | IR remote coordination |
Trait
This Function does not contain Traits.
Command
Data Types
APISaveMatchedRemoteInfoForApp Command Structure Type
This structure defines the parameters of the APISaveMatchedRemoteInfoForApp Command.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | Category | uint32 | M | Device type; the default value is 0. |
| 1 | BrandId | uint32 | M | Brand ID; the default value is 0. |
| 2 | RemoteId | uint32 | M | Remote ID; the default value is 0. |
| 3 | SpId | uint32 | O | Set-top box operator ID; the default value is 0. |
Trait Definitions
This Function does not contain Traits.
Command Definitions
APIStartIrLearningForApp Command
Starts IR code learning on the gateway and returns the learning identifier.
This Command has no parameters.
APIListIrControllersForApp Command
Lists all virtual IR remote devices under the gateway.
This Command has no parameters.
APIGetMatchTreeForApp Command
Retrieves the match tree (key mapping) of brand, set-top box or IPTV remotes.
This Command has no parameters.
APICreateIrVirtualDeviceForApp Command
Creates a virtual IR remote device (match-based or custom-based).
This Command has no parameters.
APICancelIrLearningForApp Command
Cancels the ongoing IR code learning session on the gateway.
This Command has no parameters.
APIQueryIrSpsForApp Command
Queries the set-top box operator list by city ID.
This Command has no parameters.
APIReadLearnedIrCodeForApp Command
Reads the learned IR code from the gateway using the keyId returned during the learning process.
This Command has no parameters.
APIAddIrKeyForApp Command
Adds the newly learned IR key to the remote.
This Command has no parameters.
APIGetAirConditionerFunctionsForApp Command
Gets the functions supported by the stateful air conditioner remote (mode, temperature, fan speed, etc.).
This Command has no parameters.
APIQueryIrAreaForApp Command
Queries administrative divisions such as province, city and district.
This Command has no parameters.
APIGetBrandByIdForApp Command
Retrieves brand information for the given category and brand ID.
This Command has no parameters.
APIGetBrandsByCategoryForApp Command
Retrieves the brand list supported by a specific IR device category.
This Command has no parameters.
APIGetKeysByRemoteIdForApp Command
Gets the key list supported by the remote code library using remoteId.
This Command has no parameters.
APIMatchRemoteByIrCodeForApp Command
Matches possible remotes based on the learned IR code.
This Command has no parameters.
APIGetSupportIrGatewaysForApp Command
Gets the gateway list supporting IR function at the specified location.
This Command has no parameters.
APIGetControllerKeysForApp Command
Gets all key information of the specified remote device.
This Command has no parameters.
APIDeleteIrKeysForApp Command
Deletes one or more keys from the remote.
This Command has no parameters.
APIClickIrKeyForApp Command
Sends a single key press command to the IR remote.
This Command has no parameters.
APIGetIrControllerInfoForApp Command
Gets the detailed information of a single IR remote (brand, type, etc.).
This Command has no parameters.
APIGetIrDeviceCategoriesForApp Command
Queries the IR device category list supported by the remote (e.g., TV, air conditioner).
This Command has no parameters.
APIUpdateIrKeyNameForApp Command
Renames a key on the IR remote.
This Command has no parameters.
APISyncIrLearningCodes Command
IR learning code two-way sync request. The device reports the summary of all locally stored IR learning codes to the cloud, requesting comparison and receiving the difference list (codes to be added or deleted), to achieve eventual consistency between the cloud and the device IR code library.
This Command has no parameters.
APIGetIrCodeDownloadUrl Command
IR code database download URL request. The device requests from the cloud a URL for downloading the complete or incremental IR code database file, to update or initialize the offline code library.
This Command has no parameters.
APIQueryIrLearningCode Command
Learned IR code info query request. The device requests the cloud to retrieve the list and metadata (e.g., bound appliance name, key name) of all locally stored user-defined learned IR codes.
This Command has no parameters.
APIQueryIrCodeLibrary Command
IR code cloud library query request. The device queries the cloud whether the preset IR code library for a specific brand and model of appliance exists, allowing users to add and control common appliances without manual learning.
This Command has no parameters.
APIGetIrCode Command
IR code raw data acquisition request. The device requests the raw or waveform data of the specified IR code from the cloud, for local transmission or verification.
This Command has no parameters.
APIGetIrCodeTarget Command
IR code target appliance info request. The device requests the detailed information of the target appliance associated with a specific IR code (e.g., brand, model, functions) from the cloud, to enrich the user interface display.
This Command has no parameters.
IR code single transmission Command. The cloud instructs the device to transmit a specific learned or preset IR code once to the target appliance (e.g., air conditioner, TV) through the IR emitter, simulating a single key press of the remote.
This Command has no parameters.
APIDeleteLearnedIrCode Command
Learned IR code deletion Command. The cloud instructs the device to delete one or more previously learned and saved IR remote codes from its local storage.
This Command has no parameters.
APISaveLearnedIrKey Command
Learned IR code key binding save Command. After the IR code learning succeeds, the cloud sends a command to bind the learned IR code to a user-defined virtual key (or scene action), and persists the binding in the device storage.
This Command has no parameters.
APIStartIrCodeLearning Command
IR code learning mode start Command. The cloud instructs the device to enter IR learning mode, preparing to receive the user's physical IR remote signals and encode them into a storable, replayable digital format.
This Command has no parameters.
APISaveMatchedRemoteInfoForApp Command
This Command is used to perform the "save matched remote info" operation.
Parameters
APISaveMatchedRemoteInfoForApp Command Structure
CommLinkCoordination
Introduction
Monitors the communication link quality between the gateway and the cloud, performs latency probing and reports the results.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00EF | CommLinkCoordination | Communication link coordination |
Trait
This Function does not contain Traits.
Command
Data Types
This Function has no custom data types.
GetAqaraCertificateInfoForAppRsp Command Structure Type
This structure defines the response parameters of the GetAqaraCertificateInfoForAppRsp Command. This command belongs to the platform-level (App <-> Studio) interaction; all fields are mandatory, and field indexes are used as keys in JSON encoding.
| Struct Member No. | Field Name | Type | Mandatory | Description |
|---|
| 0 | CaPem | characterString | M | CA root certificate (PEM format). |
| 1 | CaFingerprintSha256 | characterString | M | SHA-256 fingerprint of the CA certificate (hexadecimal string). |
| 2 | ServerChainPem | characterString | M | Server certificate chain (PEM format). |
| 3 | ServerNotAfterEpochMillis | uint64 | M | Server certificate expiry timestamp (Unix epoch, milliseconds). |
| 4 | DnsNames | list[characterString] | M | Domain name list allowed by the certificate. |
| 5 | IpAddresses | list[characterString] | M | IP address list allowed by the certificate. |
Trait Definitions
This Function does not contain Traits.
Command Definitions
APICheckLinkConsuming Command
Network link latency probing Command. The cloud sends a probing command to the device to measure the round-trip time (RTT) between the cloud and the device, usually for network quality monitoring and diagnosis.
This Command has no parameters.
APIReportLinkConsuming Command
Network link latency probing result report. After performing link probing, the device reports the measured network latency and other results to the cloud, for network performance analysis and statistics.
This Command has no parameters.
GetAqaraCertificateInfoForApp Command
This command is initiated by the App to Aqara Studio to request Aqara certificate information. Studio shall return the certificate details via the GetAqaraCertificateInfoForAppRsp Command. This request has no parameters.
Parameters
This Command has no parameters.
GetAqaraCertificateInfoForAppRsp Command
This command is returned by Aqara Studio as the response to GetAqaraCertificateInfoForApp. It contains the CA root certificate, the CA certificate SHA-256 fingerprint, the server certificate chain, the server certificate expiry timestamp, and the allowed domain name and IP address lists.
Parameters
GetAqaraCertificateInfoForAppRsp Command Structure
Response example (JSON, field indexes as keys):
{
"0": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
"1": "a1b2c3d4e5f6...",
"2": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
"3": 1735689600000,
"4": ["aqarastudio-4829.local", "aqarastudio-1234.local"],
"5": ["10.11.51.142", "192.168.1.100"]
}
RingtoneCoordination
Introduction
Manages gateway local ringtone/music files, including download, deletion and consistency check with the cloud library.
Function Identification
| Function ID | Code | Name |
|---|
| 0x00F0 | RingtoneCoordination | Ringtone management coordination |
Trait
This Function does not contain any Traits.
Command
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIDownloadMusic Command (Music Download)
Device music file download Command. The cloud sends a command instructing the device to download audio files (such as ringtones and chimes) from a specified address to local storage for subsequent playback.
This Command has no parameters.
APIDeleteMusic Command (Music Deletion)
Device local music file deletion Command. The cloud instructs the device to delete one or more specified audio files from local storage.
This Command has no parameters.
APICheckLocalMusicSync Command (Local Music Information Consistency Check)
Local music file information synchronization check request. The device reports the list of locally stored music files (for example, file names and MD5) to the cloud, requests comparison, and receives the list of files to be synchronized (downloaded or deleted) to keep the cloud and local music libraries consistent.
This Command has no parameters.
APIGetSupportDeviceInfoForApp Command (Query Supported Device Information by Location)
This command queries the list of devices at a specified location that support a specific file type (such as doorbell files). The request contains positionId (position ID) and fileType (file type). The response returns an array of devices, including details such as did, deviceName, state, model, positionId, and positionName.
This Command has no parameters.
APIGetCustomRingtoneInfoForApp Command (Query Custom Ringtone Information)
This command queries the list of custom ringtone files (such as doorbell files) that can be distributed to devices and their current distribution status. The request contains did (device ID) and fileType (file type, such as "bell_file"). The response returns an array of files, including details such as fileId, fileName, fileUrl, encryption key, sendState (distribution status), dataState (valid/deleted), failCode, and failMsg.
This Command has no parameters.
ScreenCoordination (Screen Function Coordination)
Introduction
Manages smart scene panel interactions, including configuration distribution, status query, and two-way passthrough between the cloud and the panel.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F1 | ScreenCoordination | Screen function coordination |
Trait
This Function does not contain any Traits.
Command
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIPushPanelConfig Command (Scene Panel Configuration Distribution)
Smart scene panel configuration distribution command. The cloud sends configuration related to smart scene panels (physical or virtual) to the device, including button icons, backlight colors, and associated scene or device control logic.
This Command has no parameters.
APICloudToPanelDownstream Command (Cloud-to-Panel Downstream General)
Cloud-to-panel downstream general command channel. The cloud uses this general interface to send various control, query, or configuration commands to scene panels.
This Command has no parameters.
APICheckPanelConfigConsistency Command (Scene Panel Configuration Consistency Check)
Scene panel configuration consistency check request. The device reports a summary of the current configuration of all scene panels it manages to the cloud, requests comparison, and receives differences to ensure cloud and local panel configurations stay in sync.
This Command has no parameters.
APIPanelUpstreamRequest Command (Panel Upstream Request General)
Panel-to-cloud upstream general request channel. This general interface is used to send various requests to the cloud, such as getting weather, executing complex scenes, or reporting panel events.
This Command has no parameters.
APISyncPositionDown Command (Position Information Downstream Synchronization)
Device position information downstream synchronization Command. The cloud sends position information such as the rooms and areas assigned by the user to the device, ensuring that the device's local device-position mapping matches the cloud settings.
This Command has no parameters.
ConfigurationCoordination (General Configuration Coordination)
Introduction
Manages general function configurations, resource subscriptions, and position information synchronization via multicast or batch methods.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F2 | ConfigurationCoordination | General configuration coordination |
Trait
This Function does not contain any Traits.
Command
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIGetConfiguration Command (General Configuration Acquisition)
General function configuration acquisition request. The device requests the latest configuration parameters or policy files for a specified function module (such as specific sensor data processing logic or device behavior rules) from the cloud.
This Command has no parameters.
APIDeleteConfiguration Command (General Configuration Deletion (Multicast))
General function configuration multicast deletion Command. The cloud sends a command requiring the device to delete one or more specified types of general configurations. This Command can be sent via multicast to affect multiple eligible gateways or devices at the same time.
This Command has no parameters.
APIReportConfiguration Command (General Configuration Report (Multicast))
General function resource multicast report. The device reports the current values or summary information of a certain type of locally stored general function resource (such as configurations or status caches) to the cloud via multicast or batch reporting, for centralized monitoring and synchronization.
This Command has no parameters.
APISyncConfiguration Command (General Configuration Synchronization)
General function configuration bidirectional synchronization request. The device reports a summary of locally stored general function configurations to the cloud, requests comparison, and receives the difference list (configurations to push or delete) to achieve eventual consistency between the cloud and the device.
This Command has no parameters.
APIPushConfiguration Command (General Configuration Distribution (Multicast))
General function configuration multicast distribution Command. The cloud distributes general function configurations (such as device behavior rules and data processing policies) to one or more devices. This Command can be sent via multicast to efficiently synchronize configurations across a batch of devices.
This Command has no parameters.
APIPushSubscribedResource Command (Subscribed Resource Distribution)
Device subscribed resource distribution Command. According to the resource types subscribed by the device or its sub-devices, the cloud sends corresponding resource configurations, status updates, or data streams to the device for real-time data push or configuration updates.
This Command has no parameters.
APIWriteFunctionResource Command (Function Resource Control (Multicast))
General function resource multicast control Command. The cloud sends write-operation Commands (such as setting values or triggering actions) for specific general function resources (such as virtual switches or counters) to one or more devices via multicast, enabling batch control.
This Command has no parameters.
APIReportThingModelDetail Command (Thing Model Detail Report)
Aqara new device Thing model detailed information report. For hubs or devices that support the Aqara device Thing model protocol, detailed Thing models (objects, properties, services) are reported to the cloud.
This Command has no parameters.
LockCoordination (Lock Function Coordination)
Introduction
Handles smart lock extended services, including dedicated passthrough channels, encryption/decryption assistance, and extended event reporting.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F3 | LockCoordination | Lock function coordination |
Trait
This Function does not contain any Traits.
Command
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIReportLockExtEvents Command (Lock Extended Service Event Report)
Smart lock extended service event report. The device reports extended events generated by the smart lock beyond basic state changes (such as unlock records of specific users, duress alarms, low battery warnings, and tamper alarms) to the cloud.
This Command has no parameters.
APILockPassthroughDownstream Command (External Passthrough Gateway Downstream)
External application passthrough downstream Command (dedicated channel). The cloud sends raw Commands or data that bypass business-layer parsing through the dedicated passthrough channel reserved for specific external applications, forwarding them directly to the designated sub-device (such as a smart lock).
This Command has no parameters.
APIAssistDeviceCrypto Command (Device Data Encryption/Decryption Assistance)
Device data encryption/decryption assistance request. Due to security policies or capability limitations, the gateway requests the cloud to encrypt or decrypt specific string data using the designated device's key and return the result.
This Command has no parameters.
APILockPassthroughUpstream Command (External Passthrough Upstream Report)
External application passthrough upstream information report (dedicated channel).
This Command has no parameters.
WakeupCoordination (Device Wakeup Coordination)
Introduction
Obtains wakeup service addresses or tokens for low-power devices that support remote wakeup.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F4 | WakeupCoordination | Device wakeup coordination |
Trait
This Function does not contain any Traits.
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9D0B | APIGetWakeupUrl | Wakeup address acquisition | O |
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIGetWakeupUrl Command (Wakeup Address Acquisition)
Device remote wakeup service address acquisition request. The device queries the cloud for the wakeup server address or access Token of sub-devices that support remote wakeup (such as low-power devices), so that they can be activated on demand.
This Command has no parameters.
CloudStorageCoordination (Cloud Storage Function Coordination)
Introduction
Manages cloud recording/cloud storage business resource configurations and obtains information such as storage quotas and upload credentials.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F5 | CloudStorageCoordination | Cloud storage function coordination |
Trait
This Function does not contain any Traits.
Command
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIRequestCloudStorageResource Command (Cloud Storage Business Resource Request)
Cloud storage business resource configuration request. The device (typically a camera or similar device) requests resource configuration information related to the cloud video storage service from the cloud, such as storage quotas, upload credentials, and recording plans.
This Command has no parameters.
CentralHubCoordination (Central Hub Function Coordination)
Introduction
Manages advanced central hub gateway capabilities, including central hub enabling, Broker information, and data passthrough channels.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F6 | CentralHubCoordination | Central hub function coordination |
Trait
This Function does not contain any Traits.
Command
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIEnableCentralHubFunction Command (Central Hub Function Enabling)
Hub central gateway core function enabling Command. The cloud commands the Hub to activate its core capabilities as a "smart home central gateway", such as the local automation engine, cross-protocol coordination, device management, and edge computing, upgrading it from an ordinary gateway to a home control center.
This Command has no parameters.
APIHubPassthroughDataDown Command (Gateway Passthrough Data Downstream)
Hub data passthrough downstream channel. The cloud sends raw data packets that do not require Hub business-layer parsing to the Hub through this general passthrough interface, and the Hub directly forwards them to the specific terminal devices or services connected to it.
This Command has no parameters.
APIInquiryCentralBroker Command (Central Hub Broker Information Query)
Central message broker information query request. The hub acting as the central hub queries the cloud for information about the message broker server it should connect to (for inter-device communication and event distribution).
This Command has no parameters.
APIInquiryCentralEnableState Command (Central Hub Enable State Query)
Central function enable state query request. The hub queries the cloud for the current enable state (enabled or disabled) of its own "central hub function", for state synchronization or UI display.
This Command has no parameters.
APIHubPassthroughDataUp Command (Gateway Passthrough Data Upstream)
Hub data passthrough upstream channel. The Hub reports raw data packets received from connected devices directly to the cloud or designated external services through this general passthrough interface, without business-layer parsing.
This Command has no parameters.
IftttCoordination (IFTTT Function Coordination)
Introduction
Serves as the automation rule coordination center, managing the synchronization, subscription, and execution of IFTTT/local automation rules.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F7 | IftttCoordination | IFTTT function coordination |
Trait
This Function does not contain any Traits.
Command
Data Types
This Function does not define any custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
APIEnableAutomation Command (Automation Enable)
Local automation rule master switch control command. The cloud sends a command to globally enable or disable all automation rules (IFTTT scenarios) stored and executed locally on the gateway, making them temporarily effective or ineffective.
This Command has no parameters.
APIEnableIfttt Command (IFTTT Enable)
The cloud sends a dedicated command to the gateway to control the overall enable state of its IFTTT (If This Then That) automation function.
This Command has no parameters.
APIDownloadIftttLocal Command (IFTTT Local Synchronization)
The cloud synchronizes the user-created IFTTT automation rules to the gateway's local storage, allowing them to be triggered and executed under local (offline) conditions.
This Command has no parameters.
APIDeleteIftttLocal Command (IFTTT Local Deletion)
The cloud instructs the gateway to delete the specified IFTTT automation rules from its local storage.
This Command has no parameters.
APIPushCentralAutomation Command (Central Automation Distribution)
Central-level automation rule delivery command. The cloud provides complex automation rule configurations that need to be coordinated across multiple hubs, or the hub centralizes processing on the hub that acts as the central hub.
This Command has no parameters.
APIDeleteCentralAutomation Command (Central Automation Deletion)
Central-level automation rule deletion command. The cloud instructs the hub acting as the central hub to delete the specified central-level automation rules from its storage.
This Command has no parameters.
APIEnableCentralAutomation Command (Central Automation Enable)
Central-level automation rule enabling command. The cloud controls whether the central hub hub enables the central-level automation rules stored in it.
This Command has no parameters.
APIPublishResourceChange Command (Resource Change Publication)
Resource change event publication command. When a resource value changes in the cloud, the change event is proactively "published" to local gateways that have subscribed to that resource, to trigger their local automation rules.
This Command has no parameters.
APIQueryHolidayList Command (Holiday List Query)
The device queries the cloud for the holiday list of a specified year and region.
This Command has no parameters.
APICheckLocalIftttSync Command (Local Automation Information Consistency Check)
Local automation rule information synchronization check request. The gateway reports summary information of all locally stored IFTTT automation rules to the cloud, requests comparison, and receives differences to keep the cloud and local rule libraries consistent.
This Command has no parameters.
APISubscribeIftttResChange Command (IFTTT Resource Change Subscription)
Local automation rule cloud resource change subscription request. The gateway subscribes to changes of one or more cloud resources on behalf of local automation rules. When these resources change in the cloud, the cloud will notify the gateway.
This Command has no parameters.
APIUnsubscribeIftttResChange Command (IFTTT Resource Change Unsubscription)
Local automation rule cloud resource change unsubscription request. The gateway requests the cloud to stop pushing change notifications for previously subscribed specific resources.
This Command has no parameters.
APIRunCloudAction Command (Cloud Action Execution)
Local automation-triggered cloud action execution request. When the conditions of a local automation rule on the gateway are met, the cloud is requested through this interface to execute actions that can only be completed in the cloud (such as sending notifications, calling internet APIs, or updating cloud databases).
This Command has no parameters.
APIQueryIftttRes Command (IFTTT Resource Query)
Automation-related resource value query request. When evaluating rule conditions, the hub's local automation engine queries the cloud for the current value of a specified resource (for example, device status in another home, weather data, or user modes).
This Command has no parameters.
APIGetSunriseSunsetByLatLon Command (Sunrise/Sunset Time Acquisition by Latitude and Longitude)
Sunrise/sunset time query request based on latitude and longitude. The device queries the cloud for the specific sunrise and sunset times of the day according to its latitude/longitude coordinates, to implement natural light-related smart automation scenarios (such as "turn on the light at sunset").
This Command has no parameters.
NetworkManagement (Network Management)
Introduction
Serves as the core control module for device network connections and access policies, managing remote proxies and access addresses.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F8 | NetworkManagement | Network management |
Trait
Command
This Function does not contain any Commands.
Data Types
NetworkSpeedTestResultTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the NetworkSpeedTestResult Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | UpThreshold | float | O | Uplink rate, in Mbps (megabits per second). |
| 1 | DownThreshold | float | O | Downlink rate, in Mbps (megabits per second). |
NetworkSpeedThresholdTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the NetworkSpeedThreshold Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | UpThreshold | float | O | Uplink rate threshold, in Mbps (megabits per second). |
| 1 | DownThreshold | float | O | Downlink rate threshold, in Mbps (megabits per second). |
Trait Definitions
RemoteProxyAccessEnable Trait (Remote Proxy Access Enable)
Remote proxy access enable switch. This attribute enables or disables the device's ability to be remotely accessed via an internet cloud proxy. When enabled, authorized users can remotely control the device through a secure cloud tunnel; when disabled, the device can only be accessed within the local area network (LAN).
| Trait ID | Code |
|---|
| 0x4F4E | RemoteProxyAccessEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
InternetAccessAddress Trait (Internet Access Address)
The public network access address assigned to the device by the cloud platform (usually a domain name or NAT-mapped address). The remote management service uses this address to locate and connect to the device, reflecting the device's logical position in the wide area network (WAN).
| Trait ID | Code |
|---|
| 0x4F4F | InternetAccessAddress |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
LanAccessAddress Trait (LAN Access Address)
The IP address assigned to the device by the router in the home local area network (LAN) (usually via DHCP). Other devices on the same network (such as mobile apps and computers) use this address to discover and communicate with the device locally at low latency.
| Trait ID | Code |
|---|
| 0x4F50 | LanAccessAddress |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
NetworkSpeedTestMode Trait (Network Speed Test Mode)
Configure or get the device's network speed test mode status. Writing 1 puts the device into speed test mode, and writing 0 exits speed test mode. After the speed test completes, the device automatically resets the status to 0 (idle). This Trait is readable, writable, and reportable.
| Trait ID | Code |
|---|
| 0x516E | NetworkSpeedTestMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
NetworkSpeedTestResult Trait (Network Speed Test Result)
Indicates the actual network speed obtained after the device completes the speed test, in Mbps (megabits per second), including both downlink and uplink dimensions. This Trait is a read-only property, actively reported by the device after the speed test, for client display or compliance assessment.
| Trait ID | Code |
|---|
| 0x516F | NetworkSpeedTestResult |
Parameters
NetworkSpeedThreshold Trait (Network Speed Threshold)
Reference thresholds used to determine whether the device's network speed meets requirements, in Mbps (megabits per second), including downlink and uplink speed threshold dimensions. When the measured speed (provided by NetworkSpeedTestResult) reaches or exceeds the corresponding threshold, it is judged as "pass"; otherwise, it is judged as "fail".
| Trait ID | Code |
|---|
| 0x5170 | NetworkSpeedThreshold |
Parameters
NetworkProtocolSupport Trait (Supported Network Protocols)
Supported network protocols. Represents the set of network communication protocols supported by the device in normal working conditions. This Trait uses a bitmask (Bitmap) form: bit0 = Wi-Fi, bit1 = Thread, bit2 = Ethernet, bit3 = Zigbee, bit4 = BLE, bit5 = Aqara RS485. Multiple protocols can be set simultaneously.
| Trait ID | Code |
|---|
| 0x5186 | NetworkProtocolSupport |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain any Commands.
ToiletCore (Toilet Core Functions)
Introduction
Integrates the most basic physical state sensing and component control of the smart toilet, including seating, lid opening, flushing, seat heating, and night light.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00F9 | ToiletCore | Toilet core functions |
Trait
Command
Data Types
SeatHeatingLevelEnum8 Type
This enumeration defines the valid values of the Present Value for the SeatHeatingLevel Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | 26C | 26deg C |
| 0x02 | 27C | 27deg C |
| 0x03 | 28C | 28deg C |
| 0x04 | 29C | 29deg C |
| 0x05 | 30C | 30deg C |
| 0x06 | 31C | 31deg C |
| 0x07 | 32C | 32deg C |
| 0x08 | 33C | 33deg C |
| 0x09 | 34C | 34deg C |
| 0x0A | 35C | 35deg C |
| 0x0B | 36C | 36deg C |
| 0x0C | 37C | 37deg C |
| 0x0D | 38C | 38deg C |
| 0x0E | 39C | 39deg C |
| 0x0F | 40C | 40deg C |
FlushCommand Command Structure Type
Parameter structure of the FlushCommand Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Flush type. |
SeatCommand Command Structure Type
Parameter structure of the SeatCommand Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Operation type. |
LidCommand Command Structure Type
Parameter structure of the LidCommand Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Operation type. |
Trait Definitions
SeatHeatingLevel Trait (Seat Heating)
Sets the seat heating level for a comfortable sitting experience. The "Off" level indicates that heating is disabled.
| Trait ID | Code |
|---|
| 0x4F66 | SeatHeatingLevel |
Parameters
SeatState Trait (Seat State)
Controls opening or closing the toilet seat. When opening the seat, if the toilet lid is closed, the lid will be automatically opened first.
| Trait ID | Code |
|---|
| 0x4F65 | SeatState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LidState Trait (Lid State)
Indicates the toilet lid state. When the lid is closed, writing 1 slowly opens it; when the lid is open, writing 0 slowly closes it.
| Trait ID | Code |
|---|
| 0x4F64 | LidState |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SeatOccupancy Trait (Seated/Standing State)
Indicates whether the toilet seat is occupied. 0 means unoccupied, 1 means occupied.
| Trait ID | Code |
|---|
| 0x4F62 | SeatOccupancy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
OnOff Trait (On/Off State)
When written, turns the camera device on or off. When read, indicates the current power state. Values: false = off, true = on.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Deodorization Trait (Deodorization)
Controls the deodorization function of the smart toilet. A value of 0 means off, and a value of 1 means on.
| Trait ID | Code |
|---|
| 0x508B | Deodorization |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
FlushCommand Command
Executes a Flush Command. Options include Full Flush (solid waste) or Half Flush (liquid waste or specific scenarios). Executing this Command will interrupt any ongoing washing or drying process.
Parameters
FlushCommand Command Structure
SeatCommand Command
Sends a control command to the toilet, such as "toggle", causing the seat to perform the opposite action of its current state (open if closed, close if open).
Parameters
SeatCommand Command Structure
LidCommand Command
Sends a control command to the toilet, such as "toggle", causing the lid to perform the opposite action of its current state (open if closed, close if open).
Parameters
LidCommand Command Structure
ToiletDiagnostic (Toilet Diagnostic Information)
Introduction
Monitors the health status of key hardware subsystems of the smart toilet, actively reporting faults such as temperature, flow, and fan issues.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00FA | ToiletDiagnostic | Toilet diagnostic information |
Trait
Command
This Function does not contain any Commands.
Data Types
SeatTempSensorFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the SeatTempSensorFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Overheat | Overheat |
| 0x02 | Fault | Fault |
PressureValveFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the PressureValveFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Fault | Fault |
WaterHeaterVoltageFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the WaterHeaterVoltageFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Fault | Fault |
FlowSensorFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the FlowSensorFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Insufficient | Insufficient |
| 0x02 | Excessive | Excessive |
OutletWaterTempSensorFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the OutletWaterTempSensorFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Overheat | Overheat |
| 0x02 | Fault | Fault |
InletWaterTempSensorFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the InletWaterTempSensorFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Overheat | Overheat |
| 0x02 | Fault | Fault |
WaterTempSensorsConsistencyFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the WaterTempSensorsConsistencyFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Fault | Fault |
DryerFanFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the DryerFanFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Fault | Fault |
Trait Definitions
SeatTempSensorFault Trait (Seat Temperature Sensor Fault)
Reports the seat temperature sensor status: Normal, Overheat, or Sensor Fault.
| Trait ID | Code |
|---|
| 0x4F67 | SeatTempSensorFault |
Parameters
PressureValveFault Trait (Pressure Valve Fault)
Reports pressure valve faults, such as solenoid valve or diaphragm abnormalities.
| Trait ID | Code |
|---|
| 0x4F68 | PressureValveFault |
Parameters
WaterHeaterVoltageFault Trait (Water Heater Voltage Fault)
Reports water heater voltage abnormalities, such as an open thermostat or fuse.
| Trait ID | Code |
|---|
| 0x4F69 | WaterHeaterVoltageFault |
Parameters
FlowSensorFault Trait (Flow Sensor Fault)
Reports the water flow status: Normal, Insufficient Flow, or Excessive Flow (possibly due to a pressure valve fault).
| Trait ID | Code |
|---|
| 0x4F6A | FlowSensorFault |
Parameters
OutletWaterTempSensorFault Trait (Outlet Water Temperature Sensor Fault)
Reports the outlet water temperature sensor status: Normal, Overheat, or Sensor Fault.
| Trait ID | Code |
|---|
| 0x4F6B | OutletWaterTempSensorFault |
Parameters
InletWaterTempSensorFault Trait (Inlet Water Temperature Sensor Fault)
Reports the inlet water temperature sensor status: Normal, Overheat, or Sensor Fault.
| Trait ID | Code |
|---|
| 0x4F6C | InletWaterTempSensorFault |
Parameters
WaterTempSensorsConsistencyFault Trait (Inlet/Outlet Water Temperature Sensor Consistency Fault)
Reports the consistency check status between the inlet and outlet water temperature sensors: Normal or Consistency Fault.
| Trait ID | Code |
|---|
| 0x4F6D | WaterTempSensorsConsistencyFault |
Parameters
DryerFanFault Trait (Dryer Fan Fault)
Reports the operating status of the dryer fan: Normal or Fault (e.g., loose terminals, open circuit, or stalled rotor).
| Trait ID | Code |
|---|
| 0x4F6E | DryerFanFault |
Parameters
Command Definitions
This Function does not contain any Commands.
ToiletHygiene (Toilet Hygiene Maintenance)
Introduction
Maintains the device's own cleanliness and hygiene, including nozzle cleaning, foam shield, plasma sterilization, and waterway cleaning.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00FB | ToiletHygiene | Toilet hygiene maintenance |
Trait
Command
Data Types
NozzleClean Command Structure Type
Parameter structure of the NozzleClean Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Cleaning type. |
FoamShieldControl Command Structure Type
Parameter structure of the FoamShieldControl Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Operation type. |
CleanFoamSystemCommand Command Structure Type
Parameter structure of the CleanFoamSystemCommand Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Operation type. |
Trait Definitions
PlasmaSterilizeStatus Trait (Plasma Sterilization)
Starts the deep plasma sterilization process. It can only be triggered when the seat is unoccupied and no other activity is in progress.
| Trait ID | Code |
|---|
| 0x4F61 | PlasmaSterilizeStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
NozzleClean Command
Controls the nozzle self-cleaning behavior: Auto Clean (automatic cleaning), Manual Maintenance (extend only for maintenance), or Off (retract).
Parameters
NozzleClean Command Structure
FoamShieldControl Command
Manually controls the release and stop of the foam shield. Set to "Start" to begin releasing foam; set to "Stop" to stop releasing foam.
Parameters
FoamShieldControl Command Structure
CleanFoamSystemCommand Command
Performs a cleaning cycle of the foam system waterway to prevent clogging.
Parameters
CleanFoamSystemCommand Command Structure
ToiletWashDry (Toilet Washing and Drying)
Introduction
Defines the complete smart toilet washing and drying process, covering washing modes, water temperature/pressure, drying wind speed, and duration settings.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00FC | ToiletWashDry | Toilet washing and drying |
Trait
Command
Data Types
ToiletWashingModeEnum8 Type
This enumeration defines the valid values of the Present Value for the ToiletWashingMode Trait.
| Value | Name | Description |
|---|
| 0x01 | Rinse | Posterior wash |
| 0x02 | RinseMoving | Posterior wash (moving) |
| 0x03 | FeminineWash | Feminine wash |
| 0x04 | FeminineWashMoving | Feminine wash (moving) |
| 0x00 | Stop | Stop |
| 0x05 | Enema | Enema |
| 0x06 | ChildWash | Child wash |
ToiletMassageModeEnum8 Type
This enumeration defines the valid values of the Present Value for the ToiletMassageMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | PressureMassage | Strong/weak massage |
| 0x02 | TemperatureMassage | Hot/cold massage |
ToiletWaterTemperatureEnum8 Type
This enumeration defines the valid values of the Present Value for the ToiletWaterTemperature Trait.
| Value | Name | Description |
|---|
| 0x00 | RoomTemp | Room temperature |
| 0x01 | 26C | 26deg C |
| 0x02 | 27C | 27deg C |
| 0x03 | 28C | 28deg C |
| 0x04 | 29C | 29deg C |
| 0x05 | 30C | 30deg C |
| 0x06 | 31C | 31deg C |
| 0x07 | 32C | 32deg C |
| 0x08 | 33C | 33deg C |
| 0x09 | 34C | 34deg C |
| 0x0A | 35C | 35deg C |
| 0x0B | 36C | 36deg C |
| 0x0C | 37C | 37deg C |
| 0x0D | 38C | 38deg C |
| 0x0E | 39C | 39deg C |
| 0x0F | 40C | 40deg C |
ToiletWaterPressureLevelEnum8 Type
This enumeration defines the valid values of the Present Value for the ToiletWaterPressureLevel Trait.
| Value | Name | Description |
|---|
| 0x00 | Gentle | Gentle |
| 0x01 | Standard | Standard |
| 0x02 | Strong | Strong |
NozzlePositionEnum8 Type
This enumeration defines the valid values of the Present Value for the NozzlePosition Trait.
| Value | Name | Description |
|---|
| 0x00 | Rear | Rear |
| 0x01 | Rearward | Rear-mid |
| 0x02 | Middle | Middle |
| 0x03 | Forward | Front-mid |
| 0x04 | Front | Front |
ToiletDryingStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the ToiletDryingStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | RoomTemp | Room temperature |
| 0x02 | LowTemp | Low temperature |
| 0x03 | MediumLowTemp | Medium-low temperature |
| 0x04 | MediumTemp | Medium temperature |
| 0x05 | MediumHighTemp | Medium-high temperature |
| 0x06 | HighTemp | High temperature |
| 0x07 | On | On |
FanSpeedLevelEnum8 Type
This enumeration defines the valid values of the Present Value for the FanSpeedLevel Trait.
| Value | Name | Description |
|---|
| 0x00 | LowSpeed | Low speed |
| 0x01 | MediumSpeed | Medium speed |
| 0x02 | HighSpeed | High speed |
WashDryCombinationCommand Command Structure Type
Parameter structure of the WashDryCombinationCommand Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Operation type. |
Trait Definitions
ToiletWashingMode Trait (Washing Mode)
Selects the washing function mode, including Rinse Wash, Feminine Wash, and their moving modes.
| Trait ID | Code |
|---|
| 0x4F7C | ToiletWashingMode |
Parameters
ToiletMassageMode Trait (Massage Wash Mode)
Selects and starts/stops the massage washing function. Modes include "Pressure Massage" and "Temperature Massage".
| Trait ID | Code |
|---|
| 0x4F7D | ToiletMassageMode |
Parameters
ToiletWaterTemperature Trait (Washing Water Temperature)
Sets the washing water temperature level, from room temperature to multiple heating levels.
| Trait ID | Code |
|---|
| 0x4F7E | ToiletWaterTemperature |
Parameters
ToiletWaterPressureLevel Trait (Washing Intensity)
Adjusts the washing water pressure, such as gentle, standard, and strong.
| Trait ID | Code |
|---|
| 0x4F7F | ToiletWaterPressureLevel |
Parameters
NozzlePosition Trait (Washing Position)
Adjusts the front-back position of the washing nozzle to suit different cleaning areas.
| Trait ID | Code |
|---|
| 0x4F80 | NozzlePosition |
Parameters
ToiletDryingStatus Trait (Toilet Drying)
Controls the start/stop of the drying function and sets the air temperature level.
| Trait ID | Code |
|---|
| 0x4F81 | ToiletDryingStatus |
Parameters
FanSpeedLevel Trait (Drying Fan Speed Level)
Sets the drying fan speed level, options include Low, Medium, and High.
| Trait ID | Code |
|---|
| 0x4F82 | FanSpeedLevel |
Parameters
RinseDuration Trait (Set Posterior Wash Duration)
Sets the duration of the Posterior Wash mode. Unit: S.
| Trait ID | Code |
|---|
| 0x4F83 | RinseDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 180 | RVW | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | 60.0 | R | O |
| 0x0005 | Step Value | float | | 30.0 | R | O |
| 0x0007 | Default Value | float | | 180 | RW | O |
FeminineWashDuration Trait (Set Feminine Wash Duration)
Sets the duration of the Feminine Wash mode. Unit: S.
| Trait ID | Code |
|---|
| 0x4F84 | FeminineWashDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 180 | RVW | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | 60.0 | R | O |
| 0x0005 | Step Value | float | | 30.0 | R | O |
| 0x0007 | Default Value | float | | 180 | RW | O |
DryingDuration Trait (Set Drying Duration)
Sets the duration of the drying function. Unit: S.
| Trait ID | Code |
|---|
| 0x4F85 | DryingDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 180 | RVW | O |
| 0x0002 | Maximum Value | float | | 600.0 | R | O |
| 0x0003 | Minimum Value | float | | 60.0 | R | O |
| 0x0005 | Step Value | float | | 60.0 | R | O |
| 0x0007 | Default Value | float | | 180 | RW | O |
Command Definitions
WashDryCombinationCommand Command
One-touch control combining washing, care, and drying. Select "Wash Only" or "Wash and Dry" to start the corresponding process; "Start" starts drying only; "Stop" stops any ongoing washing or drying activity.
Parameters
WashDryCombinationCommand Command Structure
ToiletSettings (Toilet Parameter Settings)
Introduction
Allows users to personalize default parameters and automation scenarios, such as automatic lid opening, automatic flushing, foam shield, and long-sitting reminders.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00FD | ToiletSettings | Toilet parameter settings |
Trait
Command
This Function does not contain any Commands.
Data Types
PostFlushCloseModeEnum8 Type
This enumeration defines the valid values of the Present Value for the PostFlushCloseMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Disable | Disabled |
| 0x01 | CloseLidAndSeat | Close lid and seat automatically |
| 0x02 | CloseSeatOnly | Close seat only |
SittingReminderAlertEnum8 Type
This enumeration defines the valid values of the Present Value for the SittingReminderAlert Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | SittingReminder | Long-sitting reminder |
Trait Definitions
AutoFoamDuration Trait (Foam Shield Release Duration)
Sets the automatic foam release duration, applicable to scenarios such as after sitting, after foot-flip seat lifting, and after flushing. Unit: S.
| Trait ID | Code |
|---|
| 0x4F63 | AutoFoamDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 10 | RVW | O |
| 0x0002 | Maximum Value | float | | 30.0 | R | O |
| 0x0003 | Minimum Value | float | | 5.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 10 | RW | O |
AutoFoamGlobalEnable Trait (Auto Foam Shield Release Enable)
Enables or disables the automatic foam shield function in all scenarios.
| Trait ID | Code |
|---|
| 0x4F6F | AutoFoamGlobalEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AutoFoamOnSit Trait (Foam Shield Release on Sitting)
Enables or disables automatic foam release when sitting.
| Trait ID | Code |
|---|
| 0x4F70 | AutoFoamOnSit |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AutoFoamAfterFlush Trait (Foam Shield Release on Leaving)
Enables or disables automatic foam replenishment after flushing.
| Trait ID | Code |
|---|
| 0x4F71 | AutoFoamAfterFlush |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Enables or disables automatic foam release triggered by foot-flip seat lifting (anti-splash).
| Trait ID | Code |
|---|
| 0x4F72 | AutoFoamOnFootFlip |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SittingReminderThreshold Trait (Set Long-Sitting Reminder Trigger Time)
Sets the time threshold for triggering the long-sitting reminder. Unit: S.
| Trait ID | Code |
|---|
| 0x4F73 | SittingReminderThreshold |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1200 | RVW | O |
| 0x0002 | Maximum Value | float | | 3600.0 | R | O |
| 0x0003 | Minimum Value | float | | 600.0 | R | O |
| 0x0005 | Step Value | float | | 60.0 | R | O |
| 0x0007 | Default Value | float | | 1200 | RW | O |
AutoLidEnable Trait (Auto Lid Opening Enable)
Enables or disables automatic lid opening when a person approaches. Disabled by default.
| Trait ID | Code |
|---|
| 0x4F74 | AutoLidEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AutoFlushEnable Trait (Auto Flush on Leaving Enable)
Enables or disables automatic flushing (Full or Half) based on the sitting duration after the user leaves the seat.
| Trait ID | Code |
|---|
| 0x4F75 | AutoFlushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
PostFlushCloseMode Trait (Auto Close Lid and Seat After Flush)
Sets the automatic closing strategy after flushing: Disabled, Close Lid and Seat, or Close Seat Only.
| Trait ID | Code |
|---|
| 0x4F76 | PostFlushCloseMode |
Parameters
PostFlushCloseDelay Trait (Auto Close Lid and Seat Delay After Flush)
Sets the delay in seconds before automatically closing the lid/seat after flushing.
| Trait ID | Code |
|---|
| 0x4F77 | PostFlushCloseDelay |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 15 | RVW | O |
| 0x0002 | Maximum Value | float | | 30.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 3.0 | R | O |
| 0x0007 | Default Value | float | | 15 | RW | O |
Enables or disables all foot-sensing functions (lid opening, seat lifting, flushing).
| Trait ID | Code |
|---|
| 0x4F78 | FootSensorEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
PreWettingEnable Trait (Pre-Wetting on Sitting)
Enables or disables automatically pre-wetting the inner wall of the toilet when sitting to enhance flushing performance.
| Trait ID | Code |
|---|
| 0x4F79 | PreWettingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AutoDeodorizerEnable Trait (Auto Deodorizer on Sitting Enable)
Enables or disables the automatic deodorization function when sitting.
| Trait ID | Code |
|---|
| 0x4F7A | AutoDeodorizerEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
SittingReminderAlert Trait (Long-Sitting Reminder Report)
When the actual sitting duration exceeds the set threshold, reports a "sitting reminder" event.
| Trait ID | Code |
|---|
| 0x4F7B | SittingReminderAlert |
Parameters
Command Definitions
This Function does not contain any Commands.
Lighting (Lighting Function)
Introduction
This Function provides the capability to activate and control dynamic lighting effects. The server provides a list of effects driven by different sources, from which the client can select and trigger.
Dynamic lighting effects can be used both for luminaires that support the Color Control Function and for those that only support the Level Control Function (for example, dimmable lights).
The specific implementation of effects falls within the vendor's custom scope. Devices from different vendors are not guaranteed to represent the same effect even if they use the same EffectID; the same vendor can reuse the same EffectID across different devices to express a consistent implementation.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00FE | Lighting | Lighting function |
Trait
Command
Data Types
EffectInfoTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the EffectInfo Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID. 0x00-0x7F indicates built-in effects, and 0x80-0xFE indicates user-defined effects. |
| 1 | EffectData | characterString | M | Effect data. Carries the raw encoding of the dynamic lighting effect, and its format should be consistent with the add/update/preview commands. |
| 2 | EffectName | characterString | M | Effect name. Display name for the client, and its length should satisfy the MaxEffectNameLength constraint. |
EffectOperationStateEnum8 Type
This enumeration defines the valid values of the Present Value for the EffectOperationState Trait.
| Value | Name | Description |
|---|
| 0x00 | Idle | Idle |
| 0x01 | Executing | Executing |
| 0x02 | Previewing | Previewing |
LightTypeEnum8 Type
This enumeration defines the valid values of the Present Value for the LightType Trait.
| Value | Name | Description |
|---|
| 0x00 | GenericLight | General light |
| 0x01 | CeilingLight | Ceiling light |
| 0x02 | Bulb | Bulb |
| 0x03 | EavesLight | Eaves light |
| 0x04 | FloorLamp | Floor lamp |
| 0x05 | StringLight | String light |
| 0x06 | DimmingDriver | Dimmable driver |
| 0x07 | LightStrip | Light strip |
| 0x08 | TrackLight | Track light |
| 0x09 | PendantLight | Pendant light |
ActionTypeEnum8 Type
This enumeration defines the valid values of the ActionType field in EffectData, and is used by the SupportedActionTypes Trait to declare the effect data modes supported by the device.
| Value | Name | Description |
|---|
| 0x00 | StaticEffect | Static scene |
| 0x01 | DynamicEffect | Dynamic scene using DynamicEffectId |
| 0x02 | SequenceEffect | Sequence scene using StepList |
| 0x03 | SegmentStaticEffect | Segmented static scene using SegmentPattern |
| 0x04 | SegmentDynamicEffect | Segmented dynamic scene |
| 0x05 | NaturalAtmosphereEffect | Natural atmosphere scene using NaturalEffectId |
NaturalEffectIdEnum8 Type
This enumeration defines the natural atmosphere effect IDs used when ActionType is NaturalAtmosphereEffect.
| Value | Name | Description |
|---|
| 0x00 | NearThunder | Near thunder |
| 0x01 | DistantThunder | Far thunder |
| 0x02 | Meteor | Meteor |
| 0x03 | Firefly | Firefly |
| 0x04 | BlueSkyWhiteClouds | Blue sky and white clouds |
| 0x05 | Overcast | Overcast |
UserDefinedEffectsTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the UserDefinedEffects Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectID | uint8 | M | User-defined effect ID, with a value range of 0x80-0xFE. |
| 1 | EffectName | characterString | M | User-set effect name, whose UTF-8 byte length must not exceed MaxEffectNameLength. |
BuiltInEffectsTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the BuiltInEffects Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectID | uint8 | M | Built-in effect ID, with a value range of 0x00-0x7F. |
| 1 | BuiltInEffectLabelID | enum8 | M | Built-in effect label ID, used to identify the human-readable semantics of the preset effect. |
FlowModeColorListTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the FlowModeColorList Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | X | uint16 | M | X component in CIE 1931 xy chromaticity coordinates. |
| 1 | Y | uint16 | M | Y component in CIE 1931 xy chromaticity coordinates. |
FlowModeEnum8 Type
This enumeration defines the valid values of the Present Value for the FlowMode Trait.
| Value | Name | Description |
|---|
| 0x01 | Stretch | Breathe |
| 0x02 | Pulse | Pulse |
| 0x03 | Running | Running |
| 0x04 | Blink | Blink |
InstallationConfigurationTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the InstallationConfiguration Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EavesWhiteLightCount | uint8 | EavesLight | Number of white light units of the eaves light. Valid only when LightType is EavesLight; 255 when not configured. |
| 1 | EavesBlueLightCount | uint8 | EavesLight | Number of blue light units of the eaves light. Valid only when LightType is EavesLight; 255 when not configured. |
| 2 | StringLightLengthSelection | uint8 | StringLight | Length level of the string light. Valid only when LightType is StringLight; 255 when not configured. |
| 3 | LightStripTrimSegmentCount | uint8 | LightStrip | Number of cut segments of the light strip. Valid only when LightType is LightStrip; 255 when not configured. |
LightStripModelEnum8 Type
This enumeration defines the valid values of the Present Value for the LightStripModel Trait.
| Value | Name | Description |
|---|
| 0x01 | DCLBDD01LM | DCLBDD01LM |
EnterConfigurationMode Command Structure Type
Parameter structure of the EnterConfigurationMode Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Stage | uint8 | M | Configuration phase number. 0 means exiting configuration mode, 1/2 indicate the first two phases, and 3-255 indicate subsequent phases. |
PreviewTransition Command Structure Type
Parameter structure of the PreviewTransition Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | OnTransitionTime | uint16 | M | Transition time for turning on the light, in units of 100 milliseconds. Example: 10 means 1 second. |
| 1 | OffTransitionTime | uint16 | M | Transition time for turning off the light, in units of 100 milliseconds. Example: 10 means 1 second. |
| 2 | DimmingCurvature | float | M | Dimmer curve power value used for preview. The larger the value, the longer the stay in the low-brightness area. |
| 3 | InitialBrightness | uint8 | M | Initial brightness percentage used for preview, with a value range consistent with the InitialBrightness Trait constraint. |
PreviewEffect Command Structure Type
Parameter structure of the PreviewEffect Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectData | characterString | M | Raw effect data to be previewed, with an encoding format consistent with that used when adding/updating user-defined effects. |
RemoveUserDefinedEffect Command Structure Type
Parameter structure of the RemoveUserDefinedEffect Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID to be removed. It should be an existing UserDefined effect (usually in the range 0x80-0xFE). |
UpdateUserDefinedEffect Command Structure Type
Parameter structure of the UpdateUserDefinedEffect Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID to be updated. It should be an existing UserDefined effect. |
| 1 | EffectData | characterString | M | Updated raw effect data, whose encoding format should be consistent with the Lighting EffectData specification. |
AddUserDefinedEffect Command Structure Type
Parameter structure of the AddUserDefinedEffect Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectName | characterString | M | Name of the new effect, whose UTF-8 byte length must not exceed MaxEffectNameLength. |
| 1 | EffectData | characterString | M | Raw data of the new effect, whose encoding format should comply with the Lighting EffectData specification. |
GetEffectData Command Structure Type
Parameter structure of the GetEffectData Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectID | uint8 | M | Effect ID whose effect data is to be read. It should exist in the BuiltIn or UserDefined list. |
StartEffect Command Structure Type
Parameter structure of the StartEffect Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectID | enum8 | M | Effect ID of the effect to be started. It should be a valid EffectID supported or saved by the device. |
RemoveUserDefinedEffects Command Structure Type
Parameter structure of the RemoveUserDefinedEffects Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | EffectIDs | list[Struct] | M | List of effect IDs to be removed in batch. Each item should be an existing UserDefined effect ID. |
Trait Definitions
LightModeEnum8 Type
This enumeration defines the working modes of general lighting.
| Value | Name | Description |
|---|
| 0x00 | Auto | Auto |
| 0x01 | Normal | Normal |
| 0x02 | Night | Night light |
| 0x03 | Color | Color light |
| 0x04 | ColorTemperature | Color temperature |
ColorTemperaturePresetEnum8 Type
This enumeration defines the discrete color temperature categories provided by lighting devices; it does not represent Kelvin color temperature values.
| Value | Name | Description |
|---|
| 0x00 | Incandescent | Incandescent |
| 0x01 | White | White |
| 0x02 | DaylightWhite | Daylight white |
| 0x03 | Daylight | Daylight |
| 0x04 | Other | Other |
EffectInfo Trait
This Trait provides a list of effect information, where each item contains EffectID, EffectData, and EffectName, for maintaining, displaying, and synchronizing effect details.
This Trait is maintained by the cloud and is not reported by the device.
The encoding of EffectData should be consistent with the effect write/preview commands, so that clients can directly display, back up, or reuse it after reading.
For the binary encapsulation of EffectData, CBOR payload format, field definitions, ActionType encoding, and examples, see EffectData Encoding Specification.
| Trait ID | Code |
|---|
| 0x4F8A | EffectInfo |
Parameters
EffectOperationState Trait
This Trait indicates the device's current effect operation state. Typical states include idle, executing, and previewing.
Clients can use this to determine whether there is a preview that can be stopped, whether an effect execution flow is in progress, and whether new effect control commands should be deferred.
| Trait ID | Code |
|---|
| 0x5062 | EffectOperationState |
Parameters
LightType Trait
This Trait indicates the physical form or installation type of the luminaire. Clients can use it to determine the product form and available capabilities of the device.
The valid field ranges of composite parameters such as installation configuration depend on the value of this Trait.
| Trait ID | Code |
|---|
| 0x5032 | LightType |
Parameters
WireReversed Trait
This Trait represents the reverse-connection protection configuration, indicating whether the logical mapping between the two output channels is swapped.
This Trait applies to luminaires with two output channels. A typical example is a dual-color-temperature PWM light, where the two channels correspond to warm white and cool white respectively. If the warm white and cool white wires are reversed during installation, controlling the cool color temperature may cause the luminaire to appear warm. In this case, the client can set this Trait to true to make the server swap the two channel outputs, allowing the luminaire to glow as expected without rewiring.
When this Trait is false, the server should use the product's default two-channel output mapping without reverse-connection correction.
When this Trait is true, the server should swap the two output channel mappings and treat the current installation as being in a reverse-connected state.
| Trait ID | Code |
|---|
| 0x5177 | WireReversed |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
ChildEndpointList Trait
This Trait indicates the list of endpoints associated with the current cluster instance.
This Trait should be a non-empty list.
When the current cluster instance owns the effect capabilities of other endpoints, this Trait should list those endpoints.
When the current cluster instance represents the effect capability of a luminaire, this Trait should include the endpoint where the cluster instance resides and may include other endpoints represented by the luminaire.
| Trait ID | Code |
|---|
| 0x4F33 | ChildEndpointList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | all | | RV | O |
MaxEffectNameLength Trait
This Trait indicates the maximum UTF-8 byte length allowed for user-defined effect names (EffectName).
This value is fixed per device and ranges from 1-32. Clients should not exceed this limit when writing names.
| Trait ID | Code |
|---|
| 0x4F9C | MaxEffectNameLength |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 32 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
UserDefinedEffects Trait
This Trait contains the list of all user-defined effects currently stored on the device. Each item contains EffectID (0x80-0xFE) and EffectName.
An empty list means there are currently no user-defined effects; a null value means the information is currently unavailable (for example, the device is initializing or the data cannot be read temporarily).
| Trait ID | Code |
|---|
| 0x4F9B | UserDefinedEffects |
Parameters
MaxUserDefinedEffects Trait
This Trait indicates the maximum number of user-defined effects the device can support.
When the number of effects reaches the limit, operations to add user-defined effects should return a capacity-related error.
| Trait ID | Code |
|---|
| 0x4F89 | MaxUserDefinedEffects |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 1 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 32 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
CurrentEffectID Trait
This Trait indicates the EffectID of the currently active effect; when empty, it means there is currently no active effect.
This value can be used to highlight the currently effective effect in the UI and serve as context for subsequent query, switch, or stop logic.
| Trait ID | Code |
|---|
| 0x4F88 | CurrentEffectID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x000D | Is Null | boolean | | False | RV | O |
BuiltInEffects Trait
This Trait contains the list of all built-in effects supported by the device. Each item contains EffectID (0x00-0x7F) and BuiltInEffectLabelID.
An empty list means there are currently no built-in effects; a null value means the information is currently unavailable.
| Trait ID | Code |
|---|
| 0x4F87 | BuiltInEffects |
Parameters
FlowModeColorList Trait
This Trait contains an ordered list of colors for Flow Mode, where each item is a CIE 1931 xy chromaticity point; the list length must not exceed MaxFlowModeColors.
When configuring this list, clients should ensure the order and quantity satisfy the constraints to obtain predictable rhythmic color-matching behavior.
| Trait ID | Code |
|---|
| 0x503F | FlowModeColorList |
Parameters
FlowModeSensitivity Trait
This Trait indicates the sensitivity percentage used by Flow Mode.
The higher the sensitivity, the more responsive the device typically is to input changes (such as music rhythm).
| Trait ID | Code |
|---|
| 0x503E | FlowModeSensitivity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 100 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
EnableFlowMode Trait
This Trait indicates whether Flow Mode is currently enabled on the device.
Clients can explicitly enable or disable it through this Trait and configure it in combination with FlowMode, FlowModeColorList, and FlowModeSensitivity.
| Trait ID | Code |
|---|
| 0x503D | EnableFlowMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | O | 0 | RVW | O |
| 0x0007 | Default Value | boolean | O | 0 | RW | O |
LedGridMask Trait
This Trait indicates and allows the client to control the enable state of each configurable LED grid cell on the device through a mask. A bit of 1 means the corresponding grid cell is enabled (participates in effect rendering), and a bit of 0 means the corresponding grid cell is disabled (does not participate in effect rendering). The bits the client can modify are defined by the SupportedLedGridMask Trait; when attempting to modify a bit whose value is 0 in SupportedLedGridMask, the device MUST reject the write and keep the original value of the attribute.
| Trait ID | Code |
|---|
| 0x5033 | LedGridMask |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
SupportedLedGridMask Trait
This Trait indicates which LED grid cells on the device the client can configure through LedGridEnableMask; the mask format follows the LedGridMask Type. A bit of 1 means the corresponding grid cell physically exists on the device and is open for client configuration; a bit of 0 means the corresponding position is not configurable, either because the device does not have that physical grid cell, or the server has not opened that cell for client control. This Trait describes a fixed hardware or product capability and SHALL NOT change over the device lifetime.
The Present Value carries the mask as a string; the string encoding SHALL be consistent with the LedGridMask representation used by the device.
| Trait ID | Code |
|---|
| 0x5242 | SupportedLedGridMask |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
FlowMode Trait
This Trait indicates the currently configured Flow Mode effect engine.
Clients can select the rhythmic effect type supported by the current device in combination with the Supported Value.
| Trait ID | Code |
|---|
| 0x5034 | FlowMode |
Parameters
ShortcutEffects Trait
This Trait contains an ordered list of EffectIDs used by shortcut buttons, defining the effect switching sequence for shortcut presses.
Each time the device receives a shortcut button trigger, it should switch to the next EffectID in this list; after reaching the last item, the next trigger should wrap around to the first item.
Each item in the list is a uint8 EffectID and should reference an effect that already exists in BuiltInEffects or UserDefinedEffects.
List items can mix built-in EffectIDs (0x00-0x7F) and user-defined EffectIDs (0x80-0xFE), and the number of list items must not exceed the MaxShortcutEffects constraint value.
An empty list (length 0) means the shortcut buttons are disabled; in this state, button presses should not trigger effect switching through this mechanism.
When a client writes this Trait, the server should validate each EffectID item by item to check whether it exists in BuiltInEffects or UserDefinedEffects; if any invalid item exists, the write should be rejected and the corresponding error returned.
| Trait ID | Code |
|---|
| 0x5036 | ShortcutEffects |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RVW | O |
InstallationConfiguration Trait
This Trait indicates the current installation (product layout) configuration; the valid fields vary depending on the LightType.
For example, the eave light scenario uses white/blue light count fields, light strings use a length selection field, and light strips use a trimming segment count field. Inapplicable fields should be empty; when writing a field that does not match the LightType, the device may return InvalidConfiguration.
| Trait ID | Code |
|---|
| 0x5035 | InstallationConfiguration |
Parameters
LightStripModel Trait
This Trait indicates the currently configured light strip model; it is meaningful only when the LightType is LightStrip.
A null value means no light strip model is set. When non-null, it should belong to the Supported Value list.
| Trait ID | Code |
|---|
| 0x4FAE | LightStripModel |
Parameters
SupportedSegmentPatterns Trait
This Trait indicates the list of segment modes supported by the server in the SegmentStaticEffect scenario.
If the device does not support SegmentStaticEffect, or supports it but does not provide any available segment modes, the list should be empty.
| Trait ID | Code |
|---|
| 0x4FAD | SupportedSegmentPatterns |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
SupportedDynamicEffectIds Trait
This Trait indicates the list of dynamic effect IDs supported by the server under DynamicEffect/SegmentDynamicEffect.
If the device does not support the above dynamic modes, or supports the modes but not any DynamicEffectId, the list should be empty.
| Trait ID | Code |
|---|
| 0x4FAC | SupportedDynamicEffectIds |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RV | O |
SupportedNaturalEffectIds Trait
This Trait indicates the list of natural atmosphere effect IDs supported by the server in the NaturalAtmosphereEffect scenario.
Clients can use this list to determine the NaturalEffectIds supported by the device before sending AddUserDefinedEffect, UpdateUserDefinedEffect, or PreviewEffect. If the device does not support NaturalAtmosphereEffect, or does not support any natural atmosphere effect IDs, the list should be empty.
| Trait ID | Code |
|---|
| 0x519D | SupportedNaturalEffectIds |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[NaturalEffectIdEnum8] | | | RV | O |
SupportedActionTypes Trait
This Trait indicates the list of ActionTypes supported by the server in EffectData.
Clients can use this list to constrain the selectable editing modes before sending AddUserDefinedEffect, UpdateUserDefinedEffect, or PreviewEffect.
| Trait ID | Code |
|---|
| 0x4FAB | SupportedActionTypes |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[ActionTypeEnum8] | | | RV | O |
LightMode Trait
The lighting mode represents the currently selected working mode of the luminaire, used to distinguish Auto, Normal, Night Light, Color Light, and Color Temperature modes.
| Trait ID | Code |
|---|
| 0x523A | LightMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | LightModeEnum8 | 0-4 | No fixed default value | RVW | O |
ColorTemperaturePreset Trait
Discrete color temperature categories represent the white light color presets provided by the device, modeled separately from continuous color temperature values expressed in mired or Kelvin.
| Trait ID | Code |
|---|
| 0x523B | ColorTemperaturePreset |
Parameters
ColorTemperatureLevel Trait
The color temperature level represents the discrete color temperature adjustment levels defined by the device, ranging from 0-20; its value does not represent Kelvin or mired.
| Trait ID | Code |
|---|
| 0x523C | ColorTemperatureLevel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | 0-20 | No fixed default value; reported by the device | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 20 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0005 | Step Value | uint8 | | 1 | R | O |
Command Definitions
EnterConfigurationMode Command
This command is used to request the device to enter a general configuration mode stage; Stage=0 indicates the end of the configuration mode.
Stage=1 indicates the first stage, Stage=2 indicates the second stage, and Stage=3-255 indicate subsequent stages. The behavior and timeout policy of each stage are defined by the device implementation.
Parameters
EnterConfigurationMode Command Structure
PreviewTransition Command
This command should request the device to preview the transition effect using the provided parameters. Users can preview how the light's on/off transition behaves under the specified timing and curve settings before committing.
This command is used to rehearse the combined visual impact of the On/Off transition time, dimming curve, and initial brightness.
Parameters
PreviewTransition Command Structure
StopPreview Command
This command should request the device to stop the currently running effect preview and resume normal lighting operation.
If there is currently no preview effect, the device may return a status code with the semantics of "no active effect preview".
This Command has no parameters.
PreviewEffect Command
This command should request the device to preview the effect using the provided EffectData without saving it. Users can preview the effect before adding or updating a user-defined effect.
The EffectData encoding should be consistent with the add/update user-defined effect commands.
Parameters
PreviewEffect Command Structure
RemoveUserDefinedEffect Command
This command should request the device to remove an existing user-defined effect. Only effects of the UserDefined type can be removed; BuiltIn effects cannot be removed.
If the specified EffectID does not exist or is not UserDefined, the device should return the corresponding error status.
Parameters
RemoveUserDefinedEffect Command Structure
UpdateUserDefinedEffect Command
This command should request the device to update an existing user-defined effect. Only effects of the UserDefined type can be updated.
An update request can include the effect name, effect data, or both.
Parameters
UpdateUserDefinedEffect Command Structure
AddUserDefinedEffect Command
This command should request the device to add a user-defined effect; the EffectID of the new effect is assigned by the device.
When the number of user-defined effects reaches the limit, the device should return a status code with the semantics of "capacity full".
Parameters
AddUserDefinedEffect Command Structure
GetEffectData Command
This command should request the device to return the effect data of the specified EffectID. Clients can use it to read stored effect data (such as for display, backup, or editing).
When the query succeeds, the returned EffectData should be consistent with the encoding used when writing that effect.
Parameters
GetEffectData Command Structure
StartEffect Command
This command should request the device to start the specified lighting effect.
The target EffectID should exist in the BuiltInEffects or UserDefinedEffects list.
Parameters
StartEffect Command Structure
RemoveUserDefinedEffects Command
This command should request the device to batch-remove user-defined effects; only effects of the UserDefined type can be removed.
The device can return the processing result for each EffectID individually, or return an overall error as defined by the implementation.
Parameters
RemoveUserDefinedEffects Command Structure
EffectData Encoding Specification
This section defines the binary encapsulation, CBOR payload structure, field encoding, and encoding examples of the lighting effect data EffectData. EffectData consists of a Header and a Payload: the Header contains at least the protocol identifier/version and flag bits; the Payload uses CBOR to describe the lighting effect. The top-level CBOR item of a single-channel effect is a Map, while that of a multi-channel effect is an array of Maps.
The EffectData binary data consists of the following parts in order:
- Header: at least 2 bytes, containing the protocol identifier, version, and control flags.
- Payload: CBOR-encoded lighting effect data. A single-channel effect uses one CBOR Map; a multi-channel effect uses an array of CBOR Maps.
+------------------+-------+---------------+--------+---------+
| ProtocolVersion | Flags | PayloadLength | CRC16 | Payload |
| (1 byte) |(1 byte)| (opt 2B) |(opt 2B)| (CBOR) |
+------------------+-------+---------------+--------+---------+
Required Required Optional Optional Required
Byte 0: ProtocolVersion
ProtocolVersion encodes ProtocolID and Version in the same byte: the high 2 bits represent the version, and the low 6 bits represent the protocol identifier.
7 6 5 4 3 2 1 0
+-------+---------------------------+
|Version| ProtocolID |
| 2 bit | 6 bit |
+-------+---------------------------+
ProtocolVersion Bit Layout
| Bit | Name | Range | Description |
|---|
| bit 0-5 | ProtocolID | 0-63 | Protocol identifier; 0x01 indicates LightingEffect. |
| bit 6-7 | Version | 0-3 | Protocol version number. |
Encoding: ProtocolVersion = (Version << 6) | ProtocolID
Decoding: ProtocolID = ProtocolVersion & 0x3F, Version = (ProtocolVersion >> 6) & 0x03
Byte 1: Flags
Flags controls whether optional Header fields and Payload properties are present.
7 6 5 4 3 2 1 0
+-------+-------+---+---+---+---+
|Reserved|Format|Cmp|Enc|CRC|Len|
| 2 bit | 2 bit | 1 | 1 | 1 | 1 |
+-------+-------+---+---+---+---+
Flags Bit Layout
| Bit | Name | Description |
|---|
| bit 0 | HasPayloadLength | When 1, the 2-byte PayloadLength field is present. |
| bit 1 | HasCRC | When 1, the 2-byte CRC16 field is present; requires HasPayloadLength = 1. |
| bit 2 | Encrypted | Reserved bit, must be 0. |
| bit 3 | Compressed | Reserved bit, must be 0. |
| bit 4-5 | PayloadFormat | 0x00 indicates CBOR (default); other values are reserved. |
| bit 6-7 | Reserved | Reserved bit, must be 0. |
Common Flags values:
| Flags | Header Length | Included Fields |
|---|
| 0x00 | 2 bytes | ProtocolVersion and Flags only |
| 0x01 | 4 bytes | ProtocolVersion, Flags, and PayloadLength |
| 0x03 | 6 bytes | ProtocolVersion, Flags, PayloadLength, and CRC16 |
Flags = 0x02 (CRC present but PayloadLength absent) is an invalid configuration, because the Payload boundary must be determined before computing the CRC.
- PayloadLength (2 bytes, big-endian): present when
Flags.bit0 = 1, indicating the byte length of the Payload.
- CRC16 (2 bytes, big-endian): present when
Flags.bit1 = 1. Uses CRC-16/MODBUS and computes the CRC over the Payload only, excluding the Header.
Payload Structure (CBOR)
The Payload uses CBOR (RFC 8949) encoding, and the keys of the Map are unsigned integers. Keys 0-23 can use single-byte CBOR encoding to reduce payload overhead.
Single-Channel and Multi-Channel Payload
The Payload structure is backward compatible. Clients and servers must determine its structure in the following way:
- When the top-level CBOR item is a Map, it represents single-channel (legacy)
EffectData and does not contain a Channel key.
- When the top-level CBOR item is an Array, it represents multi-channel
EffectData; each element in the array is a Map and must contain a Channel key.
The server can also determine multi-channel data by checking whether the channel Map contains a Channel key.
Upper-layer applications should check whether the product declares EffectOwner (EO) / EffectCapability (EC) consistency to decide whether to encode and distribute multi-channel or single-channel EffectData:
- When
EO/EC exists, the application must use multi-channel (Array) encoding and set Channel to the endpointTag reported by each lighting Endpoint.
- When
EO/EC does not exist (for example, single-light products supporting only DynamicLighting (DL)), the application must use single-channel (Map) encoding.
Multi-channel Payload rules are as follows:
- Each element in the array describes a configured channel and must contain
Channel.
Channel must equal the endpointTag reported by the corresponding lighting Endpoint. endpointTag usually increments sequentially starting from 1. For example, when the Fixed Label has Label="Number" and Value is "1", "2", "3", "4", they map to Channel 1, 2, 3, 4 respectively.- An element may contain
OnOff. OnOff=false means the channel is selected but kept off; in this case, effect fields such as ActionType, Level, and colors may be omitted.
- When
OnOff=true or OnOff is omitted, the element must contain the ActionType-specific fields required to apply the effect to that channel.
- Channels not present in the array are not configured by this
EffectData and must retain their original state.
CBOR Key Definitions
| Key | Name | CBOR Type | Range/Unit | Description | |
|---|
| 0 | ActionType | unsigned int | 0-5 | Effect action type, determining the data structure. | |
| 1 | SegmentPattern | unsigned int | 0-4 | Segment pattern. | |
| 2 | Level | unsigned int | 1-100(%) | Brightness percentage. | |
| 3 | ColorTemp | unsigned int | Mired | Color temperature, in Mired. | |
| 4 | ColorXY | unsigned int | 0 to 2^32−1 | Combined CIE XY encoding: (X << 16) \</td> <td>Y; X and Y are each 0-65535. |
| 5 | Reserved | - | - | Reserved. | |
| 6 | RelativeLevel | signed int | 1-100(%) | Relative brightness percentage. | |
| 7 | DynamicEffectId | unsigned int | See the corresponding enumeration table | Dynamic effect identifier. | |
| 8 | Speed | unsigned int | 1-100(%) | Speed percentage. | |
| 9 | LedGridCount | unsigned int | 1-255 | Number of LED grid cells (LED IC chips). | |
| 10 | HoldTime | unsigned int | In 100 ms units | Hold time of each step. | |
| 11 | TransitTime | unsigned int | In 100 ms units | Transition time between steps. | |
| 12 | CompletionAction | unsigned int | 0-2 | Action after the sequence completes. | |
| 13 | LoopCount | unsigned int | 0-255 | Number of loops; 0 means infinite looping. | |
| 14 | GradientEnabled | bool | true/false | Whether the gradient effect is enabled. | |
| 15 | SegmentCount | unsigned int | 0-255 | Number of segments. | |
| 16 | SegmentList | array of map | - | Segment definition list. | |
| 17 | StepCount | unsigned int | 0-255 | Number of steps. | |
| 18 | StepList | array of map | - | Step definition list. | |
| 19 | ColorCount | unsigned int | 0-255 | Number of colors. | |
| 20 | ColorList | array of map | - | Color list. | |
| 21 | Variant | unsigned int | 0-2 | Effect variant level: 0=small, 1=medium, 2=large. | |
| 22 | BlinkDensity | unsigned int | 1-10 | Flicker density level: 1 is lowest, 10 is highest. | |
| 23 | Channel | unsigned int | 1-255 | The endpointTag of the target lighting Endpoint in multi-channel EffectData; every element of a multi-channel array must contain this key, usually incrementing sequentially starting from 1. | |
| 24 | OnOff | bool | true/false | When false, the channel is selected but kept off; when true or omitted, the effect data is applied to the channel. | |
| 25 | NaturalEffectId | unsigned int | See the corresponding enumeration table | Natural atmosphere effect identifier (ActionType = NaturalEffect). | |
| 26 | DurationS | unsigned int | 0-65535 (seconds) | Effect duration; 0 means continuous operation. | |
| 27 | RandSeed | unsigned int | 0-65535 | Random seed; 0 means the device may choose the seed itself, 1-65535 means the device must use that seed. | |
| 28 | StartDelayMs | unsigned int | 0-65535 (milliseconds) | Start delay; wait for this duration after entering the scene before executing the effect data. | |
ColorXY Encoding (Key 4): CIE X and Y are combined into a single unsigned integer. Encoding: ColorXY = (X 16) \| Y. Decoding: X = ColorXY 16, Y = ColorXY & 0xFFFF.
ActionType Values
| Value | Name | Description | Required Keys |
|---|
| 0x00 | StaticEffect | Static scene | 2, and one of 3/4 (Level, ColorTemp/ColorXY) |
| 0x01 | DynamicEffect | Dynamic scene | 7,8,19,20(DynamicEffectId,Speed,ColorCount,ColorList) |
| 0x02 | SequenceEffect | Sequence scene | 12,13,17,18(CompletionAction,LoopCount,StepCount,StepList) |
| 0x03 | SegmentStaticEffect | Segment static scene | 1 (SegmentPattern); Whole mode requires 2, 3/4; other modes require 15, 16 (SegmentCount, SegmentList) |
| 0x04 | SegmentDynamicEffect | Segment dynamic scene | 15,16(SegmentCount,SegmentList) |
| 0x05 | NaturalEffect | Natural atmosphere scene | 25 (NaturalEffectId); requires one of 3/4 (ColorTemp/ColorXY, mutually exclusive); optional 26, 27, 28, 2, 8, 21 (DurationS, RandSeed, StartDelayMs, Level, Speed, Variant) |
DynamicEffectId Values
| Value | Name | Chinese Effect Name |
|---|
| 0 | Undefined | Undefined |
| 1 | Breathe | Breathing |
| 2 | Candle | Candlelight |
| 3 | Colorful | Colorful |
| 4 | Blink | Flicker |
| 5 | Gradient | Gradient |
| 6 | AlternateBreath | Alternating breathing |
| 7 | ForwardFlow | Forward flow |
| 8 | ReverseFlow | Reverse flow |
| 9 | Jump | Jump |
| 10 | Celebration | Celebration |
| 11 | BidirectionalCelebration | Bidirectional celebration |
| 12 | Chase | Chase |
| 13 | ReverseChase | Reverse chase |
| 14 | Firefly | Fluorescence |
| 15 | Starry | Starry sky |
| 16 | Bounce | Bounce |
| 17 | Meteor | Shooting star |
| 18 | ReverseMeteor | Reverse shooting star |
| 19 | Stack | Stacking |
NaturalEffectId Values
NaturalEffectId and DynamicEffectId are independent of each other. All NaturalEffect Payloads share the same set of optional parameters; this version does not define the individually required keys or parameter semantics of each natural effect.
| Value | Name | Chinese Name |
|---|
| 0 | NearThunder | Near thunder |
| 1 | DistantThunder | Distant thunder |
| 2 | Meteor | Shooting star |
| 3 | Firefly | Firefly |
| 4 | BlueSkyWhiteClouds | Blue sky and white clouds |
| 5 | Overcast | Overcast |
NaturalEffect common parameters:
| Key | Name | Range | Description |
|---|
| 3 / 4 | ColorTemp / ColorXY | See the key definition table | Required color parameters, mutually exclusive. |
| 26 | DurationS | 0-65535 seconds | Effect duration; 0 means continuous operation. |
| 27 | RandSeed | 0-65535 | Random seed; 0 means the device selects it itself, 1-65535 means the device uses that seed. |
| 28 | StartDelayMs | 0-65535 milliseconds | Start delay; wait for this duration after entering the scene before executing the effect data. |
| 2 | Level | 1-100(%) | Brightness. |
| 8 | Speed | 1-100(%) | Speed. |
| 21 | Variant | 0-2 | Effect variant/level: 0=small, 1=medium, 2=large. |
CompletionAction Values
| Value | Name | Description |
|---|
| 0 | TurnOff | Turn off the light. |
| 1 | Restore | Restore the state before execution. |
| 2 | Hold | Keep the last frame. |
SegmentPattern Values
| Value | Name | Description |
|---|
| 0 | Whole | The whole light, without segmentation. |
| 1 | UnitLoop | Unit loop mode. |
| 2 | Even | Evenly distributed segments. |
| 3 | Custom | Custom segment size and attributes. |
| 4 | DIY | DIY segment configuration. |
ActionType Encoding Details
StaticEffect(ActionType = 0x00)
{
0: <ActionType>, // Required: 0x00
2: <Level>, // Required: brightness percentage
3: <ColorTemp>, // Optional: color temperature (Mired)
4: <ColorXY> // Optional: combined CIE XY encoding
}
DynamicEffect(ActionType = 0x01)
{
0: <ActionType>, // Required: 0x01
7: <DynamicEffectId>, // Required: effect ID
8: <Speed>, // Conditional field: speed percentage
21: <Variant>, // Conditional field: effect variant
22: <BlinkDensity>, // Conditional field: blink density
19: <ColorCount>, // Required: color count
20: [ // Required: color list
{ 4: <ColorXY> }, // Color 1
... // Colors 2 to N
]
}
SequenceEffect(ActionType = 0x02)
{
0: <ActionType>, // Required: 0x02
12: <CompletionAction>, // Required: action after completion
13: <LoopCount>, // Required: loop count (0 means infinite looping)
17: <StepCount>, // Required: step count
18: [ // Required: step list
{
10: <HoldTime>, // Required: hold time (in 100 ms units)
11: <TransitTime>, // Required: transition time (in 100 ms units)
2: <Level>, // Required: brightness percentage
3: <ColorTemp>, // Optional: color temperature
4: <ColorXY> // Optional: combined CIE XY encoding
},
...
]
}
SegmentStaticEffect(ActionType = 0x03)
The data structure varies according to SegmentPattern (key 1).
Whole (SegmentPattern = 0): the whole light uses a single color.
{
0: 3, 1: 0, // ActionType + Whole mode
2: <Level>, // Brightness percentage
3: <ColorTemp>, // Optional
4: <ColorXY> // Optional
}
UnitLoop (SegmentPattern = 1): segments repeat in a looping pattern.
{
0: 3, 1: 1, // ActionType + UnitLoop mode
15: <SegmentCount>,
16: [
{ 9: <LedGridCount>, 4: <ColorXY> },
...
]
}
Even (SegmentPattern = 2): evenly distributed segments, with optional gradient.
{
0: 3, 1: 2, // ActionType + Even mode
14: <GradientEnabled>,
15: <SegmentCount>,
16: [
{ 4: <ColorXY> },
...
]
}
Custom (SegmentPattern = 3): custom segments, each segment can set brightness individually.
{
0: 3, 1: 3, // ActionType + Custom mode
14: <GradientEnabled>,
15: <SegmentCount>,
16: [
{ 9: <LedGridCount>, 6: <RelativeLevel>, 3: <ColorTemp>, 4: <ColorXY> },
...
]
}
DIY (SegmentPattern = 4): DIY segments, each segment can set colors individually.
{
0: 3, 1: 4, // ActionType + DIY mode
15: <SegmentCount>,
16: [
{ 9: <LedGridCount>, 3: <ColorTemp>, 4: <ColorXY> },
...
]
}
SegmentDynamicEffect(ActionType = 0x04)
Each segment has an independent dynamic effect, speed, and color list.
{
0: 4, // ActionType = SegmentDynamicEffect
15: <SegmentCount>,
16: [
{
9: <LedGridCount>,
7: <DynamicEffectId>,
8: <Speed>,
21: <Variant>,
22: <BlinkDensity>,
19: <ColorCount>,
20: [ { 4: <ColorXY> }, ... ]
},
...
]
}
NaturalEffect(ActionType = 0x05)
All NaturalEffectIds share the same parameter set. Either ColorTemp or ColorXY must be provided, and they are mutually exclusive. Other keys are conditional fields; when omitted, they are handled by the device's default values/capabilities. This version does not specify the individual interpretation of parameters by each natural effect.
{
0: 5, // Required: ActionType = NaturalEffect
25: <NaturalEffectId>, // Required
3: <ColorTemp> | 4: <ColorXY>, // Required: color (choose one of two)
26: <DurationS>, // Conditional field: duration 0-65535 seconds; 0 means continuous operation
27: <RandSeed>, // Conditional field: 0 means the device selects it itself; 1-65535 uses the specified seed
28: <StartDelayMs>, // Conditional field: delay before execution 0-65535 milliseconds
2: <Level>, // Conditional field: brightness 1-100%
8: <Speed>, // Conditional field: speed 1-100%
21: <Variant> // Conditional field: variant 0-2
}
Encoding Examples
Example 1: StaticEffect - red at 80% brightness
EffectData parameters: ActionType = StaticEffect, Level = 80, ColorXY = 0x9E9A4246 (red).
CBOR diagnostic notation: {0: 0, 2: 80, 4: 2660909638}
Complete EffectData (hexadecimal):
Header: 01 00
Payload: A3 00 00 02 18 50 04 1A 9E 9A 42 46
Total: 14 bytes
Example 2: DynamicEffect - Colorful effect with 3 colors
EffectData parameters: ActionType = DynamicEffect, DynamicEffectId = 3 (Colorful), Speed = 50%, 3 colors (red, green, blue).
CBOR diagnostic notation: {0: 1, 7: 3, 8: 50, 19: 3, 20: [{4: 2660909638}, {4: 1310044852}, {4: 616043336}]}
Complete EffectData (hexadecimal):
Header: 01 00
Payload: A5 00 01 07 03 08 18 32 13 03 14 83
A1 04 1A 9E 9A 42 46
A1 04 1A 4E 15 B2 B4
A1 04 1A 24 B8 13 48
Total: 35 bytes
Example 3: SequenceEffect - red gradient to warm white, looping 3 times
EffectData parameters: ActionType = SequenceEffect, CompletionAction = Hold, LoopCount = 3, containing 2 steps.
CBOR diagnostic notation: {0: 2, 12: 2, 13: 3, 17: 2, 18: [{10: 20, 11: 10, 2: 100, 4: 2660909638}, {10: 20, 11: 10, 2: 100, 3: 172}]}
Complete EffectData (hexadecimal):
Header: 01 00
Payload: A5 00 02 0C 02 0D 03 11 02 12 82
A4 0A 14 0B 0A 02 18 64 04 1A 9E 9A 42 46
A4 0A 14 0B 0A 02 18 64 03 18 AC
Total: 38 bytes
Example 4: Multi-channel - static effect, dynamic effect, and off channel
A product that supports EffectOwner (EO) / EffectCapability (EC) reports lighting endpointTags 1/2/3/4 (Fixed Label Number). One EffectData configures 3 channels and keeps endpointTag 4 unchanged:
- Channel 1 (endpointTag 1): StaticEffect, Level = 80%, ColorXY is red (
0x9E9A4246).
- Channel 2 (endpointTag 2): DynamicEffect, DynamicEffectId = Colorful (3), Speed = 50%, ColorList is red/green/blue.
- Channel 3 (endpointTag 3): selected but off (
OnOff = false).
- Channel 4 (endpointTag 4): not present in the array, so it retains its original state.
CBOR diagnostic notation:
[
{23: 1, 0: 0, 2: 80, 4: 2660909638},
{23: 2, 0: 1, 7: 3, 8: 50, 19: 3, 20: [{4: 2660909638}, {4: 1310044852}, {4: 616043336}]},
{23: 3, 24: false}
]
Complete EffectData (hexadecimal):
Header: 01 00
Payload: 83
A4 17 01 00 00 02 18 50 04 1A 9E 9A 42 46
A6 17 02 00 01 07 03 08 18 32 13 03 14 83
A1 04 1A 9E 9A 42 46
A1 04 1A 4E 15 B2 B4
A1 04 1A 24 B8 13 48
A2 17 03 18 18 F4
Total: 58 bytes
Example 5: NaturalEffect - near thunder
EffectData parameters: ActionType = NaturalEffect, NaturalEffectId = NearThunder (0), ColorTemp = 250, Level = 80%, Speed = 50%, Variant = 1, DurationS = 30.
CBOR diagnostic notation: {0: 5, 25: 0, 3: 250, 2: 80, 8: 50, 21: 1, 26: 30}
Complete EffectData (hexadecimal):
Header: 01 00
Payload: A7 00 05 18 19 00 03 18 FA 02 18 50 08 18 32 15 01 18 1A 18 1E
Total: 23 bytes
ScreenUIConfig (Unified Screen Configuration)
Introduction
Provides unified UI configuration for screens, including page layouts, themes, card counts, and multi-page information management.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x00FF | ScreenUIConfig | Unified screen configuration |
Trait
Command
Data Types
RemovePage Command Structure Type
Parameter structure of the RemovePage Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | PageList | list[Struct] | M | Page list. |
SetAllPagesInfo Command Structure Type
Parameter structure of the SetAllPagesInfo Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | AllPagesInfo | list[Struct] | M | All pages information. |
SetOnePageInfo Command Structure Type
Parameter structure of the SetOnePageInfo Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | PageInfo | struct | M | Page information. |
Trait Definitions
DataVersion Trait (Data Version)
This Trait is used for the access and reporting of data related to "Data Version".
| Trait ID | Code |
|---|
| 0x4EB9 | DataVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | M |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0007 | Default Value | uint64 | | 0 | RW | O |
AssociatedDeviceIconSize Trait (Associated Device Icon Size)
This Trait is used for the access and reporting of data related to "Associated Device Icon Size".
| Trait ID | Code |
|---|
| 0x4ED0 | AssociatedDeviceIconSize |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 32 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 128 | R | O |
| 0x0003 | Minimum Value | uint16 | | 32 | R | O |
| 0x0007 | Default Value | uint16 | | 32 | RW | O |
AssociatedDeviceNameSize Trait (Associated Device Name Size)
This Trait is used for the access and reporting of data related to "Associated Device Name Size".
| Trait ID | Code |
|---|
| 0x4ECF | AssociatedDeviceNameSize |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 32 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 128 | R | O |
| 0x0003 | Minimum Value | uint16 | | 32 | R | O |
| 0x0007 | Default Value | uint16 | | 32 | RW | O |
SupportedPageLayouts Trait (Supported Page Layouts)
This Trait is used for the access and reporting of data related to "Supported Page Layouts".
| Trait ID | Code |
|---|
| 0x4ED6 | SupportedPageLayouts |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RVW | M |
SupportedDeviceTypes Trait (Supported Device Types)
This Trait is used for the access and reporting of data related to "Supported Device Types".
| Trait ID | Code |
|---|
| 0x4ED5 | SupportedDeviceTypes |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list | | | RVW | M |
PageLayoutSize Trait (Page Layout Size)
This Trait is used for the access and reporting of data related to "Page Layout Size".
| Trait ID | Code |
|---|
| 0x4ED4 | PageLayoutSize |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 32 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 128 | R | O |
| 0x0003 | Minimum Value | uint16 | | 32 | R | O |
| 0x0007 | Default Value | uint16 | | 32 | RW | O |
This Trait is used for the access and reporting of data related to "Maximum Card Count".
| Trait ID | Code |
|---|
| 0x4ED3 | MaxWidgetNum |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
UserDataSize Trait (User Data Size)
This Trait is used for the access and reporting of data related to "User Data Size".
| Trait ID | Code |
|---|
| 0x4ED2 | UserDataSize |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 128 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 128 | R | O |
| 0x0003 | Minimum Value | uint16 | | 32 | R | O |
| 0x0007 | Default Value | uint16 | | 128 | RW | O |
PageNameSize Trait (Page Name Size)
This Trait is used for the access and reporting of data related to "Page Name Size".
| Trait ID | Code |
|---|
| 0x4ED1 | PageNameSize |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 32 | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 128 | R | O |
| 0x0003 | Minimum Value | uint16 | | 32 | R | O |
| 0x0007 | Default Value | uint16 | | 32 | RW | O |
HomePageIndex Trait (Home Page Index)
This Trait is used for the access and reporting of data related to "Home Page Index".
| Trait ID | Code |
|---|
| 0x4ECE | HomePageIndex |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | | RVW | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 0 | RW | O |
ScreenHeight Trait (Screen Height)
This Trait is used for the access and reporting of data related to "Screen Height".
| Trait ID | Code |
|---|
| 0x4EBC | ScreenHeight |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 240 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 240 | RW | O |
ScreenWidth Trait (Screen Width)
This Trait is used for the access and reporting of data related to "Screen Width".
| Trait ID | Code |
|---|
| 0x4EBB | ScreenWidth |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 240 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 240 | RW | O |
MaxPageNum Trait (Maximum Page Count)
This Trait is used for the access and reporting of data related to "Maximum Page Count".
| Trait ID | Code |
|---|
| 0x4EBA | MaxPageNum |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
ThemeID Trait (Theme ID)
This Trait is used for the access and reporting of data related to "Theme ID".
| Trait ID | Code |
|---|
| 0x4E78 | ThemeID |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
ThemeVersion Trait (Theme Version)
Theme version
| Trait ID | Code |
|---|
| 0x4E77 | ThemeVersion |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 1 | RV | M |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 1 | RW | O |
AllPagesInfo Trait (All Pages Information)
This feature should provide information about all configured pages and their components.
| Trait ID | Code |
|---|
| 0x4F8F | AllPagesInfo |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[AllPagesInfoTraitPresentValueStructure] | | | RVW | O |
Command Definitions
RemovePage Command
This Command is used to perform the "Remove Page" operation.
Parameters
RemovePage Command Structure
SetAllPagesInfo Command
This Command is used to perform the "Configure All Pages Information" operation.
Parameters
SetAllPagesInfo Command Structure
SetOnePageInfo Command
This Command is used to perform the "Configure Single Page Information" operation.
Parameters
SetOnePageInfo Command Structure
Ringtone (Ringtone)
Introduction
Provides ringtone and music playback control, supporting track selection, volume/duration adjustment, and playback status monitoring.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0100 | Ringtone | Ringtone |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9D37 | PlayRingtone | Play ringtone | O |
Data Types
RingtonePlayIndexEnum32 Type
This enumeration defines the valid values of the Present Value for the RingtonePlayIndex Trait.
| Value | Name | Description |
|---|
| 0x00 | PoliceCar1 | Police car sound 1 |
| 0x01 | PoliceCar2 | Police car sound 2 |
| 0x02 | SafetyAccident | Safety accident sound |
| 0x03 | MissileCountdown | Missile countdown |
| 0x04 | GhostSound | Ghost scream |
| 0x05 | SniperRifle | Sniper rifle |
| 0x06 | IntenseBattle | Intense battle sound |
| 0x07 | AirRaidSiren | Air raid siren |
| 0x08 | DogBark | Dog bark |
| 0x0A | Doorbell | Doorbell sound |
| 0x0B | Knock | Knock sound |
| 0x0C | Funny | Funny sound |
| 0x0D | AlarmClock | Alarm clock sound |
| 0x0E | Arming | Arming sound |
| 0x0F | Disarming | Disarming sound |
| 0x14 | MiMix | MiMix |
| 0x15 | Enthusiastic | Enthusiastic |
| 0x16 | GuitarClassic | GuitarClassic |
| 0x17 | IceWorldPiano | IceWorldPiano |
| 0x18 | LeisureTime | LeisureTime |
| 0x19 | Childhood | Childhood |
| 0x1A | MorningStreamIet | MorningStreamIet |
| 0x1B | MusixBox | MusixBox |
| 0x1C | Orange | Orange |
| 0x2710 | DefaultRingtone | Default ringtone |
RingtonePlayStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the RingtonePlayStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Stopped | Stopped |
| 0x01 | Playing | Playing |
CustomRingtoneCapabilityEnum8 Type
This enumeration defines the valid values of the Present Value for the CustomRingtoneCapability Trait.
| Value | Name | Description |
|---|
| 0x01 | Supported | Supported |
PlayRingtone Command Structure Type
Parameter structure of the PlayRingtone Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | PlayStatus | enum8 | M | Play status; default value is 0. |
| 1 | PlayIndex | enum8 | O | Play index; default value is 10000. |
| 2 | PlayVolume | float | O | Play volume; default value is 50. |
| 3 | PlayDuration | uint32 | O | Play duration; default value is 0. |
Trait Definitions
RingtonePlayIndex Trait (Ringtone Play Index)
Indicates the index of the ringtone or music to be played. This feature allows selecting a specific track from a predefined list, where each index corresponds to a unique ringtone or music identifier. This value is an enumeration that maps to audio files.
| Trait ID | Code |
|---|
| 0x4FA1 | RingtonePlayIndex |
Parameters
RingtonePlayDuration Trait (Ringtone Play Duration)
Indicates the playback duration of the ringtone or music. The value represents the playback time (in seconds). A value of 0 means play once (single playback); a value greater than 0 means play for the specified number of seconds.
| Trait ID | Code |
|---|
| 0x4FA4 | RingtonePlayDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
RingtonePlayStatus Trait (Ringtone Play Status)
Indicates the current playback status of the ringtone or music. Value 0 usually means stopped or idle, and 1 means playing. Allows querying and controlling whether audio is currently playing.
| Trait ID | Code |
|---|
| 0x4FA3 | RingtonePlayStatus |
Parameters
RingtonePlayVolume Trait (Ringtone Play Volume)
Indicates the volume level for playing the ringtone or music. The value range is 0 (mute) to 100 (maximum volume). Unit: %.
| Trait ID | Code |
|---|
| 0x4FA2 | RingtonePlayVolume |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
CustomRingtoneCapability Trait (Custom Ringtone Capability)
Indicates whether the device supports the custom ringtone feature (for example, uploading and playing user-defined ringtones). Value 1 means supported.
| Trait ID | Code |
|---|
| 0x50B5 | CustomRingtoneCapability |
Parameters
Command Definitions
PlayRingtone Command
Controls the device to play or stop the specified ringtone or music. The first parameter, PlayStatus, is required and specifies the play status (PLAYING means start playing, STOPPED means stop playing). When the status is PLAYING, the PlayIndex parameter must be provided to specify the ringtone to play. The optional parameter PlayVolume sets the play volume (range 0-100, 0 is mute, 100 is maximum volume). The optional parameter PlayDuration sets the play duration (in seconds) (0 means play once, greater than 0 means play for the specified number of seconds). When the status is STOPPED, all other parameters should be omitted, and the device will stop the currently playing ringtone.
Parameters
PlayRingtone Command Structure
FenceDetection (Virtual Fence Detection)
Introduction
Defines virtual fence areas in the camera view, detects people entering or leaving, and supports linkage policies such as recording and push notifications.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0101 | FenceDetection | Virtual fence detection |
Trait
Command
This Function does not contain any Commands.
Data Types
FenceDetectionReportEnum8 Type
This enumeration defines the valid values of the Present Value for the FenceDetectionReport Trait.
| Value | Name | Description |
|---|
| 0x01 | Enter | Person entering the fence detected |
| 0x02 | Exit | Person leaving the fence detected |
TimePeriodSettingTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the TimePeriodSetting Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour). |
| 2 | repeat | array[uint32] | M | A weekday repeat flag with a fixed length of 7, in order from Sunday to Saturday; 1 means active, 0 means inactive. |
SensitivityLevelEnum8 Type
This enumeration defines the valid values of the Present Value for the SensitivityLevelEnum Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Lowest |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Highest |
FenceAreaSettingTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the FenceAreaSetting Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | polygon_visible | boolean | M | Whether to display the fence area in the live view. |
| 1 | polygon_num | int32 | M | Number of polygons, which should match the length of the polygons array. |
| 2 | polygons | array[Struct] | M | Polygon array. Each Polygon contains id, points_num, and points. |
RegionDimensionTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the RegionDimension Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | unit | enum8 | M | Unit of width and height, such as GRID or PIXEL. |
| 1 | width | uint32 | M | Total width of the region in the specified unit. |
| 2 | height | uint32 | M | Total height of the region in the specified unit. |
Trait Definitions
FenceDetectionReport Trait (Virtual Fence Detection Report)
An event triggered when a person enters or leaves a predefined virtual fence area. This event distinguishes the entry and exit directions.
| Trait ID | Code |
|---|
| 0x4FB1 | FenceDetectionReport |
Parameters
FenceDetectionEnable Trait (Virtual Fence Enable)
The master switch to enable or disable the virtual fence detection function. When enabled, the camera analyzes video frames to detect whether anyone crosses the defined polygon boundaries.
| Trait ID | Code |
|---|
| 0x4FB2 | FenceDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TimePeriodSetting Trait (Time Period Setting)
Defines a scheduled plan of time periods and working days. The scheduling configuration structure contains three fields: starttime, endtime, and repeat. starttime and endtime are strings in "HH:MM" format (24-hour), ranging from "00:00" to "23:59", defining the start and end times of the active period. If they are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of unsigned 8-bit integers with a length of 7, whose index order corresponds to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. A value of 1 means the working day is active, and 0 means it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FB3 | TimePeriodSetting |
Parameters
SensitivityLevelEnum Trait (Recognition Sensitivity Setting)
This enumeration configures the sensitivity level for various device functions (such as detection, recognition, sensing, and alarm). Valid values are 0, 1, 2, 3, and 4, corresponding to lowest, low, medium, high, and highest sensitivity respectively. Higher sensitivity makes the function more sensitive to trigger conditions (such as more easily detecting weak signals or small targets); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FB4 | SensitivityLevelEnum |
Parameters
PushEnable Trait (Push Enable)
Controls whether push notifications are sent to the user when a specific function (such as detection events or recognition events) is triggered. The value is boolean: true (enabled) means a push notification is sent when an event occurs; false (disabled) means no notification is sent even when an event occurs.
| Trait ID | Code |
|---|
| 0x4FB5 | PushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RecordEnable Trait (Recording Enable)
Enables or disables local recording during face recognition.
| Trait ID | Code |
|---|
| 0x4FB6 | RecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IntervalSetting Trait (Time Interval Setting)
Configures the minimum time interval between two consecutive event triggers of a specific function (for example, detection or recognition). The value is numeric, in seconds. After an event is triggered, any further detection of the same event within this interval will not generate a new trigger until the interval has elapsed.
| Trait ID | Code |
|---|
| 0x4FB7 | IntervalSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
FenceAreaSetting Trait (Fence Area Setting)
Defines one or more polygon areas for the virtual fence. It contains three fields: PolygonVisible (characterString, value "0" or "1", indicating whether to display the fence area in the live preview), PolygonNum (characterString, total number of polygons), and Polygons (an array storing the definitions of each polygon). Each Polygon object contains: Id (characterString, unique identifier of the polygon), PointsNum (characterString, number of vertices), and Points (array of vertex coordinates). Each vertex is represented by x and y strings, with normalized values ranging from 0.0 to 1.0, corresponding to the proportional positions of the video frame width and height. Vertices are connected in order to form a closed polygon. This structure is used to configure the detection area of the fence function.
| Trait ID | Code |
|---|
| 0x4FB8 | FenceAreaSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | FenceAreaSettingTraitPresentValueStructure | | {"0":"1","1":"1","2":[{"0":"1","1":"6","2":[{"0":"0.50000000","1":"0.01694915"},{"0":"0.73528814","1":"0.25847459"},{"0":"0.73528814","1":"0.74152541"},{"0":"0.50000000","1":"0.98305082"},{"0":"0.26471186","1":"0.74152541"},{"0":"0.26471186","1":"0.25847459"}]}] | RVW | O |
FenceEntryDetectionEnable Trait (Fence Entry Detection Report Enable)
Enables event triggering when a person enters the virtual fence area (from outside to inside).
| Trait ID | Code |
|---|
| 0x4FB9 | FenceEntryDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
FenceExitDetectionEnable Trait (Fence Exit Detection Report Enable)
Enables event triggering when a person leaves the virtual fence area (from inside to outside).
| Trait ID | Code |
|---|
| 0x4FBA | FenceExitDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
DisplayFenceAreaEnable Trait (Display Fence Area Enable)
Shows or hides the virtual fence polygon overlay on the live video stream. When displayed, users can visually confirm the defined areas.
| Trait ID | Code |
|---|
| 0x4FBB | DisplayFenceAreaEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
RegionDimension Trait (Region Dimension)
Defines the complete canvas size that a client (such as an App) can use for region configuration (such as detection areas or privacy masks). Its value is a structure containing three fields:
unit (enum8): the unit of width and height, such as GRID (grid cell) or PIXEL (pixel).
width (uint32): the total width of the region in the specified unit.
height (uint32): the total height of the region in the specified unit.
| Trait ID | Code |
|---|
| 0x502D | RegionDimension |
Parameters
Command Definitions
This Function does not contain any Commands.
Security (Privacy and Security)
Introduction
Manages device security policies and access permissions, including user passwords, lost mode, and related verification mechanisms.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0102 | Security | Privacy and security |
Trait
Command
This Function does not contain any Commands.
Data Types
SecurityPasswordLevelEnum8 Type
This enumeration defines the valid values of the Present Value for the SecurityPasswordLevel Trait.
| Value | Key | Chinese Name | English Name | Description |
|---|
| 0x00 | High | High level | High | Security password strength is high (default). |
| 0x01 | Low | Low level | Low | Security password strength is low. |
LockScreenPasswordLevelEnum8 Type
This enumeration defines the valid values of the Present Value for the LockScreenPasswordLevel Trait.
| Value | Key | Chinese Name | English Name | Description |
|---|
| 0x00 | High | High level | High | Lock screen password strength is high (default). |
| 0x01 | Low | Low level | Low | Lock screen password strength is low. |
Trait Definitions
UserPassword Trait (User Password)
The user password used for device authentication and secure communication.
| Trait ID | Code |
|---|
| 0x502A | UserPassword |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | 0 | RVW | O |
| 0x0007 | Default Value | characterString | | 0 | RW | O |
SecurityPassword Trait (Security Password)
The security password. A security password used to verify administrator privileges. Before performing security-compliant operations such as factory reset or modifying advanced configurations, the user is required to enter this password for verification. This property is readable, writable, and reportable, and is usually stored and managed by the device side or the cloud.
| Trait ID | Code |
|---|
| 0x5178 | SecurityPassword |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
SecurityPasswordLevel Trait (Security Password Security Level)
Security password security level. Indicates the security level of the device's security password. The value is an enumeration (uint8), where 0 means high level and 1 means low level. This Trait is read-only and reportable, reported by the device according to the current strength of the security password. The frontend can implement different handling mechanisms based on this security level. For example, if the security level is low, the original password may not be required when changing the password.
| Trait ID | Code |
|---|
| 0x5192 | SecurityPasswordLevel |
Parameters
PasswordReminder Trait (Password Reminder Setting)
Controls whether the password reminder can be skipped in the App configuration flow. 0 means do not skip, 1 means skip.
| Trait ID | Code |
|---|
| 0x50EE | PasswordReminder |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
| 0x0006 | Supported Value | list[boolean] | | | R | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LockScreenPassword Trait (Lock Screen Password)
Used to set the lock screen password. The password is an encrypted 6-character string; an empty string means no lock screen password is set.
| Trait ID | Code |
|---|
| 0x50EF | LockScreenPassword |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
LockScreenPasswordLevel Trait (Lock Screen Password Security Level)
Lock screen password security level. Indicates the security level of the device's lock screen password. The value is an enumeration (uint8), where 0 means high level and 1 means low level. This Trait is read-only and reportable, reported by the device according to the current strength of the lock screen password. The frontend can implement different handling mechanisms based on this security level. For example, if the security level is low, the original password may not be required when changing the password.
| Trait ID | Code |
|---|
| 0x5193 | LockScreenPasswordLevel |
Parameters
PasswordRequirement Trait (Set Whether a Password Is Required)
Controls whether a password is required when performing operations such as unlocking or opening the door in non-consumer scenarios.
| Trait ID | Code |
|---|
| 0x50F0 | PasswordRequirement |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0006 | Supported Value | list[boolean] | | | R | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TheftModeNotificationEnable Trait (Lost Mode Push Enable)
Enables or disables push notifications for anti-theft mode events.
| Trait ID | Code |
|---|
| 0x501D | TheftModeNotificationEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TheftModeSupported Trait (Lost Mode Feature Support)
Indicates whether the device supports the lost/stolen mode feature.
| Trait ID | Code |
|---|
| 0x50AD | TheftModeSupported |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RV | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TheftModeEnable Trait (Lost Mode Enable)
Enables or disables the anti-theft/lost mode.
| Trait ID | Code |
|---|
| 0x501C | TheftModeEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
Storage (Local Storage)
Introduction
Manages local SD card recording, formatting, recording modes, and storage status monitoring and maintenance.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0103 | Storage | Local storage |
Trait
Command
Data Types
RecordingDurationTypeEnum8 Type
This enumeration defines the valid values of the Present Value of the RecordingDurationType Trait.
| Value | Name | Description |
|---|
| 0x00 | Auto | Automatic; the device decides the minimum and maximum recording duration automatically based on battery level and other information |
| 0x01 | Custom | Custom; the user configures the recording duration through MinRecordingDuration and MaxRecordingDuration |
NASServerBindingStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the NASServerBindingStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Unbound | Unbound |
| 0x01 | Bound | Binding successful |
NewStorageDeviceDetectedEnum8 Type
This enumeration defines the valid values of the Present Value for the NewStorageDeviceDetected Trait.
| Value | Name | Description |
|---|
| 0x00 | NoDevice | No storage device connected |
| 0x01 | SdCard | SD card connected |
| 0x02 | Usb | USB storage connected |
| 0x03 | SdCardAndUsb | SD card and USB storage connected |
SDCardStatusTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the SDCardStatus Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | totalsize | uint32 | M | Total SD card capacity, in KB. |
| 1 | freesize | uint32 | M | Available SD card capacity, in KB. |
| 2 | othersize | uint32 | M | Capacity used by non-camera files, in KB. |
| 3 | sdstatus | enum8 | M | SD card status: 0=Normal, 1=Not inserted, 2=Formatting, 3=Error. |
NASWorkModeEnum8 Type
This enumeration defines the valid values of the Present Value for the NASWorkMode Trait.
| Value | Name | Description |
|---|
| 0x00 | TranscodeFromSD | Transfer from local storage card |
| 0x01 | DirectUpload | Direct upload to NAS |
NASVerificationResultEnum8 Type
This enumeration defines the valid values of the Present Value for the NASVerificationResult Trait.
| Value | Name | Description |
|---|
| 0x00 | Failed | Verification failed |
| 0x01 | Success | Verification successful |
SetNASServersTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the SetNASServers Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | host | characterString | M | NAS server address, which can be an IP address, hostname, or UNC path. |
| 1 | user | characterString | M | NAS authentication username. |
| 2 | password | characterString | M | NAS authentication password. |
NASStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the NASStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Transferring | Transferring |
| 0x02 | Paused | Transfer paused |
| 0x03 | Clearing | Clearing videos |
| 0x04 | Error | Error |
DeleteNASServer Command Structure Type
Parameter structure of the DeleteNASServer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | enum8 | M | Status; default value is 0. |
NASClearHistoryVideos Command Structure Type
Parameter structure of the NASClearHistoryVideos Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
Parameter structure of the FormatSDCardCommand Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
Trait Definitions
NASServerBindingStatus Trait (NAS Server Binding Status)
Indicates the binding status between the device and the NAS server. Value 0 means unbound (not connected or not configured), value 1 means bound (successfully connected and authenticated).
| Trait ID | Code |
|---|
| 0x507B | NASServerBindingStatus |
Parameters
NewStorageDeviceDetected Trait (New Storage Device Detected)
Indicates that a new storage device (SD card or USB storage) has been detected and the device does not currently use it as the selected recording location. The device reports this Trait to trigger a pop-up notification. The value indicates the detected storage device type:
0: No storage device detected
1: SD card detected
2: USB storage detected
3: Both SD card and USB storage detected
| Trait ID | Code |
|---|
| 0x5067 | NewStorageDeviceDetected |
Parameters
NASLastWriteTimestamp Trait (NAS Last Write Timestamp)
Indicates the Unix timestamp (in milliseconds, without time zone) of the last successful write to NAS storage. The device records this timestamp when it finishes writing video files or any data to the NAS.
| Trait ID | Code |
|---|
| 0x4FE4 | NASLastWriteTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint64 | | 0 | RW | O |
SDCardStatus Trait (SD Card Status)
Reports the storage information and health status of the SD card. It contains totalsize (total capacity, KB), freesize (available space, KB), othersize (space occupied by non-camera files, KB), and sdstatus (card status: 0=Normal, 1=Not inserted, 2=Formatting, 3=Error).
| Trait ID | Code |
|---|
| 0x4FE7 | SDCardStatus |
Parameters
RecordingMode Trait (Recording Mode)
Configures the recording behavior of the device. The structure contains two fields: mode (uint8, values: 0 = off, 1 = continuous recording, 2 = event-triggered recording) and overwrite (uint8, value: 1 = circular overwrite when storage is full). Both fields are required.
| Trait ID | Code |
|---|
| 0x4FD2 | RecordingMode |
Parameters
SetNASSharedFolder Trait (Set Shared Folder)
Sets the shared folder path used for NAS storage.
| Trait ID | Code |
|---|
| 0x5025 | SetNASSharedFolder |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
NASSharedFoldersList Trait (Get Shared Folder List)
Retrieves the list of shared folders on the NAS as a JSON array.
| Trait ID | Code |
|---|
| 0x5024 | NASSharedFoldersList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array | | | RV | O |
NASServersList Trait (Get NAS Server List)
Retrieves the list of configured NAS servers as an array.
| Trait ID | Code |
|---|
| 0x5023 | NASServersList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array | | | RV | O |
NASStorageDuration Trait (NAS Storage Duration)
The retention duration of videos on the NAS (in seconds).
| Trait ID | Code |
|---|
| 0x502C | NASStorageDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 2592000 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 2592000 | RW | O |
NASTransferInterval Trait (NAS Transfer Interval)
The time interval for transferring videos to the NAS (in seconds).
| Trait ID | Code |
|---|
| 0x502B | NASTransferInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 86400 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 86400 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 60 | RW | O |
NASStorageEnable Trait (NAS Storage Enable)
Enables or disables NAS video storage.
| Trait ID | Code |
|---|
| 0x5021 | NASStorageEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
NASWorkMode Trait (NAS Work Mode)
Specifies the NAS storage mode: transfer from the SD card or direct upload.
| Trait ID | Code |
|---|
| 0x5022 | NASWorkMode |
Parameters
NASVerificationResult Trait (NAS Verification Result)
The result of the last NAS connection verification.
| Trait ID | Code |
|---|
| 0x5020 | NASVerificationResult |
Parameters
SetNASServers Trait (Set NAS Server)
Configures the parameters required for the device to connect to a NAS server. It contains three parameters: host (characterString, the address of the NAS server, which can be an IP address, hostname, or UNC path), user (characterString, the username used for NAS authentication), and password (characterString, the password corresponding to the username). After receiving this command, the device attempts to connect to the specified NAS server using the provided credentials and returns the connection result (success or failure).
| Trait ID | Code |
|---|
| 0x501E | SetNASServers |
Parameters
NASStatus Trait (NAS Status)
The current status of NAS video storage.
| Trait ID | Code |
|---|
| 0x501F | NASStatus |
Parameters
RecordingDurationType Trait (Recording Duration Type)
The recording duration type on the device side. 0 is automatic: the device decides the minimum and maximum recording duration automatically based on battery level and other information; 1 is custom: the durations configured by MinRecordingDuration and MaxRecordingDuration are used. The default value is 0, and it is readable, writable, and reportable.
| Trait ID | Code |
|---|
| 0x5245 | RecordingDurationType |
Parameters
MinRecordingDuration Trait (Minimum Recording Duration)
The minimum recording duration on the device side, in seconds (s), ranging from 1 to 6 with a step of 1 and a default value of 6. This configuration is used when RecordingDurationType is Custom. After recording starts, even if the detected object stops moving or leaves the field of view, recording continues until the minimum recording duration is reached, to ensure sufficient event footage is captured. It is readable, writable, and reportable.
| Trait ID | Code |
|---|
| 0x5246 | MinRecordingDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | 1..6 | 6 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 6 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint8 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | 1..6 | 6 | RW | O |
MaxRecordingDuration Trait (Maximum Recording Duration)
The maximum recording duration on the device side, in seconds (s), ranging from 10 to 30 with a step of 1 and a default value of 30. This configuration is used when RecordingDurationType is Custom. After recording starts, if the detected object stops moving or leaves the field of view, recording stops after the minimum recording duration is reached to save power; if the detected object keeps moving, recording continues until the maximum recording duration is reached. It is readable, writable, and reportable.
| Trait ID | Code |
|---|
| 0x5247 | MaxRecordingDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | 10..30 | 30 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 30 | R | O |
| 0x0003 | Minimum Value | uint8 | | 10 | R | O |
| 0x0005 | Step Value | uint8 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | 10..30 | 30 | RW | O |
Command Definitions
DeleteNASServer Command
Represents the operation of unbinding the NAS server.
Parameters
DeleteNASServer Command Structure
TriggerSDCardStatusUpload Command
Triggers the device to proactively report the current SDCardStatus (including total capacity, available space, other usage, and card status) to the cloud or client.
This Command has no parameters.
NASClearHistoryVideos Command
This Command is used to perform the "Clear NAS History Videos" operation.
Parameters
NASClearHistoryVideos Command Structure
This Command is used to perform the "Format Storage Card" operation.
Parameters
FormatSDCardCommand Command Structure
Introduction
Manages canvas layouts and image resources, supporting image download, storage, deletion, status reporting, and ID list maintenance.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0104 | ImageMediaManagement | Image media management |
Trait
Command
This Function does not contain any Commands.
Data Types
ImageTransferStateEnum8 Type
This enumeration defines the valid values of the Present Value for the ImageTransferState Trait.
| Value | Name | Description |
|---|
| 0x00 | Idle | Idle |
| 0x01 | DownloadFailed | Download failed |
| 0x02 | NoSpace | Download failed - insufficient space |
| 0x03 | DownloadFailedInProgress | Download failed - download in progress |
| 0x04 | CheckFailed | Verification failed |
| 0x10 | Downloading | Downloading |
| 0x20 | DownloadComplete | Download complete |
| 0x21 | TransferProgress10 | Image transfer progress 10% |
| 0x22 | TransferProgress20 | Image transfer progress 20% |
| 0x23 | TransferProgress30 | Image transfer progress 30% |
| 0x24 | TransferProgress40 | Image transfer progress 40% |
| 0x25 | TransferProgress50 | Image transfer progress 50% |
| 0x26 | TransferProgress60 | Image transfer progress 60% |
| 0x27 | TransferProgress70 | Image transfer progress 70% |
| 0x28 | TransferProgress80 | Image transfer progress 80% |
| 0x29 | TransferProgress90 | Image transfer progress 90% |
| 0x2F | TransferStart | Image transfer started |
| 0x30 | TransferComplete | Image transfer complete |
| 0x31 | DisplayFailedNoData | Image display failed - no image data |
| 0x32 | DisplayFailedTransferring | Image display failed - transfer in progress |
| 0x40 | DisplayComplete | Image display complete |
| 0xFF | OperationFailed | Operation failed |
Trait Definitions
CanvasLayoutConfiguration Trait (Canvas Layout Configuration)
Configuration parameters of the canvas layout used by the frontend.
| Trait ID | Code |
|---|
| 0x4FED | CanvasLayoutConfiguration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
CurrentImageId Trait (Current Image ID)
The ID of the currently displayed image, of type uint32.
| Trait ID | Code |
|---|
| 0x4FEE | CurrentImageId |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
DisplayImage Trait (Display Image)
The ID of the image to be displayed, of type uint32, sent by the App.
| Trait ID | Code |
|---|
| 0x4FEF | DisplayImage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | W | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
DownloadImageData Trait (Download Image Data)
The data used to download an image, including URL, MD5, size, type, ID, and storage flag.
| Trait ID | Code |
|---|
| 0x4FF0 | DownloadImageData |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | W | O |
ImageTransferState Trait (Image Transfer State)
Image transfer state (idle, downloading, completed, failed, etc.).
| Trait ID | Code |
|---|
| 0x4FF2 | ImageTransferState |
Parameters
ImageDataList Trait (Image Data List)
The image data list used by the App/server.
| Trait ID | Code |
|---|
| 0x4FF3 | ImageDataList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ImageIdList Trait (Image ID List)
An image ID list, containing several image IDs of type uint32, for example [123456, 345678].
| Trait ID | Code |
|---|
| 0x4FF4 | ImageIdList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array[uint32] | | | RV | O |
OnDeviceImageIdList Trait (On-Device Image ID List)
Chinese Name: On-Device Image ID List.
Represents the list of image IDs stored in the local memory of the endpoint device itself (rather than the gateway or cloud). Each ID corresponds to an image data stored in the device's internal storage medium (such as Flash or SD card). This list is readable and reportable, maintained by the device side; the client can use it to enumerate, preview, or manage the image resources local to the device.
Each image ID in the list is uint32.
| Trait ID | Code |
|---|
| 0x5135 | OnDeviceImageIdList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array[uint32] | | | RV | O |
RemoveImages Trait (Remove Image List)
The list of image IDs to be deleted, containing several image IDs of type uint32, for example [123456, 345678].
| Trait ID | Code |
|---|
| 0x4FF5 | RemoveImages |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array[uint32] | | | W | O |
FreeStorageCapacity Trait (Remaining Image Storage Capacity)
Reports the available remaining storage capacity of the device's album, in KB.
| Trait ID | Code |
|---|
| 0x50F1 | FreeStorageCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain any Commands.
VoiceAssistant (Voice Assistant)
Introduction
Manages the device's voice interaction capabilities, including wake words, voice control switch, voice timbre, continuous conversation, voice control language, near-field wake, and spatial area configuration.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0105 | VoiceAssistant | Voice assistant |
Trait
Command
Data Types
VoiceAssistantAuthStateEnum8 Type
This enumeration defines the valid values of the Present Value for the VoiceAssistantAuthState Trait.
| Value | Name | Description |
|---|
| 0x00 | Authorized | Authorized |
| 0x01 | Unauthorized | Unauthorized |
ControlScopeSettingEnum32 Type
This enumeration defines the valid values of the Present Value for the ControlScopeSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | CurrentRoom | Current room |
| 0x01 | WholeHouse | Whole house |
WakeSensitivityEnum32 Type
This enumeration defines the valid values of the Present Value for the WakeSensitivity Trait.
| Value | Name | Description |
|---|
| 0x00 | Low | Low |
| 0x01 | Medium | Medium |
| 0x02 | High | High |
VoiceTimbreEnum8 Type
This enumeration defines the valid values of the Present Value for the VoiceTimbre Trait.
| Value | Name | Description |
|---|
| 0x00 | Male | Male voice |
| 0x01 | Female | Female voice |
VoiceControlLanguageEnum8 Type
This enumeration defines the valid values of the Present Value for the VoiceControlLanguage Trait.
| Value | Name | Description |
|---|
| 0x01 | Chinese | Chinese |
| 0x02 | English | English |
TriggerVoiceAssistantWake Command Structure Type
Parameter structure of the TriggerVoiceAssistantWake Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Action | enum8 | M | Action; 0 = NO_ACTION (no operation), 1 = WAKE (activate the voice assistant), 2 = ExitVoiceControl (exit voice control); default value is 1. |
Trait Definitions
VoiceAssistantEnabled Trait
Determines whether the device responds to voice commands; when enabled (default), all built-in voice functions take effect; when disabled, the microphone ignores all wake words and commands, equivalent to having no voice hardware.
| Trait ID | Code |
|---|
| 0x4FF9 | VoiceAssistantEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | O | 1 | RVW | M |
| 0x0007 | Default Value | boolean | O | 1 | RW | O |
VoiceAssistantAuthState Trait
Indicates the voice control authorization state.
| Trait ID | Code |
|---|
| 0x50FC | VoiceAssistantAuthState |
Parameters
OneShotEnable Trait
Enables or disables the One-Shot voice control capability. 0 means off, 1 means on.
| Trait ID | Code |
|---|
| 0x50FD | OneShotEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
WakeWordSetting Trait
Used to configure the wake words of the voice assistant, supporting a primary wake word, auxiliary wake words, and user-defined wake words.
| Trait ID | Code |
|---|
| 0x50FF | WakeWordSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
ControlScopeSetting Trait
Sets the scope of voice control.
| Trait ID | Code |
|---|
| 0x5101 | ControlScopeSetting |
Parameters
WakeSensitivity Trait
Sets the voice wake sensitivity level.
| Trait ID | Code |
|---|
| 0x5103 | WakeSensitivity |
Parameters
NearFieldWakeEnabled Trait
Enables or disables the near-field wake function.
| Trait ID | Code |
|---|
| 0x5104 | NearFieldWakeEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AiRecommendEnabled Trait
Enables or disables the AI recommendation function.
| Trait ID | Code |
|---|
| 0x5105 | AiRecommendEnabled |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
VoiceTimbre Trait
Indicates the voice timbre used by the voice assistant. 0 means male voice, 1 means female voice.
| Trait ID | Code |
|---|
| 0x51F2 | VoiceTimbre |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | VoiceTimbreEnum8 | | 0 | RVW | O |
| 0x0006 | Supported Value | list[VoiceTimbreEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
ContinuousChatEnable Trait
Used to enable or disable the continuous conversation function of the voice assistant. When enabled, users can converse continuously without frequently waking the voice assistant; the user can quickly end the current continuous conversation by saying "Goodbye".
| Trait ID | Code |
|---|
| 0x51F3 | ContinuousChatEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
VoiceControlLanguage Trait
Indicates the language types supported for recognition by voice control.
| Trait ID | Code |
|---|
| 0x51F4 | VoiceControlLanguage |
Parameters
Command Definitions
TriggerVoiceAssistantWake Command
This command triggers the device to wake the voice assistant so that it is ready to receive voice commands. The action parameter is an enumeration: NO_ACTION (0) means no operation, WAKE (1) means activate the voice assistant, and ExitVoiceControl (2) means exit voice control.
Parameters
TriggerVoiceAssistantWake Command Structure
VoiceIntercom (Voice Intercom)
Introduction
Manages the voice intercom capabilities of the device, including the list of online devices available for intercom.
Function Identifier
| Function ID | Code | Name |
|---|
| TBD | VoiceIntercom | Voice intercom |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
IntercomDevicesList Trait (Online Intercom Device List)
Reports the list of devices currently discovered by the gateway that support intercom and are online.
| Trait ID | Code |
|---|
| 0x50F8 | IntercomDevicesList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
Command Definitions
This Function does not contain any Commands.
SpaceSecurity (Space Security)
Introduction
Manages the security capabilities of the device within a specific space, including alarm bell, volume, arm/disarm status, and alarm duration.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0106 | SpaceSecurity | Space security |
Trait
Command
This Function does not contain any Commands.
Data Types
AlarmStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the AlarmStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | ConfirmedAbnormal | Confirmed abnormal |
| 0x02 | UnconfirmedNormal | Unconfirmed normal |
| 0x03 | UnconfirmedAbnormal | Unconfirmed abnormal |
AlarmBellIndexEnum32 Type
This enumeration defines the valid values of the Present Value for the AlarmBellIndex Trait.
| Value | Name | Description |
|---|
| 0x00 | PoliceCarSound1 | Police car sound 1 |
| 0x01 | PoliceCarSound2 | Police car sound 2 |
| 0x02 | SafetyAccidentSound | Safety accident sound |
| 0x03 | MissileCountdown | Missile countdown |
| 0x04 | GhostScream | Ghost scream |
| 0x05 | SniperGun | Sniper rifle |
| 0x06 | BattleSound | Intense battle sound |
| 0x07 | AirRaidAlarm | Air raid siren |
| 0x08 | DogBark | Dog bark |
| 0x2710 | DefaultRingtone | Default ringtone |
GuardStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the GuardStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Home | Home guard |
| 0x01 | Away | Away guard |
| 0x02 | Sleep | Sleep guard |
| 0x03 | Off | Disarmed |
| 0x04 | Basic | Basic guard |
Trait Definitions
AlarmStatus Trait (Security Alarm Status)
Specifies the current alarm status of the system. The values include: Normal means no abnormality; ConfirmedAbnormal means a confirmed abnormality requiring action; UnconfirmedNormal means the abnormality has not yet been confirmed and monitoring continues; UnconfirmedAbnormal means a possible abnormality that needs verification.
| Trait ID | Code |
|---|
| 0x4FFA | AlarmStatus |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | AlarmStatusEnum8 | | 0 | RVW | M |
| 0x0006 | Supported Value | list[AlarmStatusEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
AlarmBellIndex Trait (Alarm Bell)
Sets or reads the security alarm bell index. When the value is 10000, the default ringtone is played.
| Trait ID | Code |
|---|
| 0x50F9 | AlarmBellIndex |
Parameters
AlarmDuration Trait (Alarm Duration)
Sets or reads the duration of the alarm bell, in seconds. A value of 0 means single playback.
| Trait ID | Code |
|---|
| 0x50FA | AlarmDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 60 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 60 | RW | O |
GuardStatus Trait (Security Guard Status)
Indicates the current security guard mode and is used to synchronize the guard status with ecosystems such as HomeKit.
| Trait ID | Code |
|---|
| 0x50FB | GuardStatus |
Parameters
Command Definitions
This Function does not contain any Commands.
Massage (Massage)
Introduction
Manages electric bed comfort and posture adjustment, including back/leg lifting, massage mode/intensity/timer, and child lock and emergency stop.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0107 | Massage | Massage |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x80C5 | Stop | Stop | O |
Data Types
MassageLevelEnum8 Type
This enumeration defines the valid values of the Present Value for the MassageLevel Trait.
| Value | Name | Description |
|---|
| 0x00 | Low | Weak |
| 0x01 | Medium | Medium |
| 0x02 | High | Strong |
MassageModeEnum8 Type
This enumeration defines the valid values of the Present Value for the MassageMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | ContinuousVibration | Continuous vibration massage |
| 0x02 | IntermittentPulse | Intermittent pulse massage |
| 0x03 | WaveCushion | Wave cushioning massage |
MassageEffectEnum8 Type
This enumeration defines the valid values of the Present Value for the MassageEffect Trait.
| Value | Name | Description |
|---|
| 0x00 | ZeroPressure | Zero pressure |
| 0x01 | Yoga | Yoga |
| 0x02 | Sleep | Sleep |
| 0x03 | Movie | Movie watching |
| 0x04 | Nursing | Nursing |
| 0x05 | AntiSnoring | Anti-snoring |
MassageTimerEnum8 Type
This enumeration defines the valid values of the Present Value for the MassageTimer Trait.
| Value | Name | Description |
|---|
| 0x00 | 10mins | 10 minutes |
| 0x01 | 20mins | 20 minutes |
| 0x02 | 30mins | 30 minutes |
BackLegLiftEnum8 Type
This enumeration defines the valid values of the Present Value for the BackLegLift Trait.
| Value | Name | Description |
|---|
| 0x00 | Pause | Paused |
| 0x01 | Start | Executing |
BackLegDownEnum8 Type
This enumeration defines the valid values of the Present Value for the BackLegDown Trait.
| Value | Name | Description |
|---|
| 0x00 | Pause | Paused |
| 0x01 | Start | Executing |
Trait Definitions
MassageLevel Trait (Massage Intensity)
Defines the intensity or speed level of the massage function, usually from low to high.
| Trait ID | Code |
|---|
| 0x507E | MassageLevel |
Parameters
MassageMode Trait (Massage Mode)
Specifies the operating mode or style of the massage function.
| Trait ID | Code |
|---|
| 0x507F | MassageMode |
Parameters
MassageEffect Trait (Massage Effect)
Specifies a preset massage effect or environment to provide a curated experience.
| Trait ID | Code |
|---|
| 0x5081 | MassageEffect |
Parameters
MassageTimer Trait (Massage Timer)
Specifies the target duration or timer setting of the massage session, which automatically turns off after the timeout.
| Trait ID | Code |
|---|
| 0x5082 | MassageTimer |
Parameters
BackrestLift Trait (Backrest Lift Adjustment)
Controls the adjustment of the backrest section, allowing it to rise or lower to support the user's upper body. Unit: deg.
| Trait ID | Code |
|---|
| 0x5083 | BackrestLift |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 60.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
LegrestLift Trait (Legrest Lift Adjustment)
Controls the adjustment of the leg support section, allowing it to rise or lower to support the user's legs. Unit: deg.
| Trait ID | Code |
|---|
| 0x5084 | LegrestLift |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 40.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
BackLegLift Trait (Back and Leg Lift Together)
Executes or controls the simultaneous rise of the backrest and leg rest for synchronized lifting.
| Trait ID | Code |
|---|
| 0x5085 | BackLegLift |
Parameters
BackLegDown Trait (Back and Leg Lower Together)
Executes or controls the simultaneous lowering of the backrest and leg rest to flatten the bed.
| Trait ID | Code |
|---|
| 0x5086 | BackLegDown |
Parameters
Command Definitions
| Command ID | Name | Conformance |
|---|
| 0x80C5 | Stop | O |
Stop Command
This command should request the device to stop the current operation.
This Command has no parameters.
TowelRackDry (Towel Rack Drying)
Introduction
Manages the towel rack drying process, controlling the target temperature and drying duration, and reporting the remaining time and fault status.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0108 | TowelRackDry | Towel rack drying |
Trait
Command
This Function does not contain any Commands.
Data Types
TowelRackFaultEnum8 Type
This enumeration defines the valid values of the Present Value for the TowelRackFault Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | TemperatureSensorFault | Temperature probe fault |
| 0x02 | HeatingWireFault | Heating wire fault (no temperature rise) |
| 0x03 | WiFiFault | WiFi fault |
| 0x04 | ControllerFault | Controller fault |
DryingModeEnum8 Type
This enumeration defines the valid values of the Present Value for the DryingMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Off | Off |
| 0x01 | On | On |
Trait Definitions
CurrentTemperature Trait (Temperature)
Indicates the current temperature. Unit: deg C.
| Trait ID | Code |
|---|
| 0x80B8 | CurrentTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 26 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 26 | RW | O |
TowelRackFault Trait (Towel Rack Fault)
Indicates detected operational errors or hardware faults related to the drying system.
| Trait ID | Code |
|---|
| 0x5087 | TowelRackFault |
Parameters
RemainingDuration Trait (Remaining Duration)
RemainingDuration indicates the remaining time that the valve will continue to operate before it automatically turns off. Unit: S.
| Trait ID | Code |
|---|
| 0x4E46 | RemainingDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 100000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
| 0x000D | Is Null | boolean | | False | RVW | O |
DryingDuration Trait (Set Drying Duration)
Sets the duration of the drying function. Unit: S.
| Trait ID | Code |
|---|
| 0x4F85 | DryingDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 180 | RVW | O |
| 0x0002 | Maximum Value | float | | 600.0 | R | O |
| 0x0003 | Minimum Value | float | | 60.0 | R | O |
| 0x0005 | Step Value | float | | 60.0 | R | O |
| 0x0007 | Default Value | float | | 180 | RW | O |
SetTemperature Trait (Set Temperature)
SetTemperature allows the user to specify and adjust the target temperature of the device or system. Unit: deg C.
| Trait ID | Code |
|---|
| 0x4E5B | SetTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 20 | RVW | O |
| 0x0002 | Maximum Value | float | | 32 | R | O |
| 0x0003 | Minimum Value | float | | 5 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 20 | RW | O |
DryingMode Trait (Drying Mode)
Should indicate the on/off state of the drying mode.
| Trait ID | Code |
|---|
| 0x5078 | DryingMode |
Parameters
Command Definitions
This Function does not contain any Commands.
Live (Live)
Introduction
Controls the live video stream, supporting enhanced capabilities such as timelapse, zoom, sleep/wake, and related event recording.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0109 | Live | Live |
Trait
Command
Data Types
CameraActiveToggle Command Structure Type
Parameter structure of the CameraActiveToggle Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
Trait Definitions
SmartEventFilterEnable Trait (Smart Event Filter Enable)
Smart event filter enable. When enabled, the camera reduces duplicate recording and reporting of similar events. When an event is first detected, the event video is recorded normally; when similar events continue to occur within a short period, the recording frequency is reduced, recording event changes through interval snapshots that can be viewed continuously on the timeline. This Trait is boolean with a default value of 0 (disabled).
| Trait ID | Code |
|---|
| 0x51EE | SmartEventFilterEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CloudTimelapseInfo Trait (Cloud Timelapse Info)
Provides cloud timelapse task information, including task count, task ID, activation status, daily repeat flag, start and end dates, start and end times (absolute time or relative to sunrise/sunset), and capture interval.
| Trait ID | Code |
|---|
| 0x4FFF | CloudTimelapseInfo |
Parameters
CloseUpTrackingEnable Trait (Close-Up Tracking Enable)
Enables or disables the close-up tracking capability of the camera. When enabled, the camera can automatically zoom in on the target area when a target is detected.
| Trait ID | Code |
|---|
| 0x50CA | CloseUpTrackingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Enables or disables local recording when related events (such as those from other Zigbee/Thread sensors) occur. Allows recording to be triggered by external devices such as door/window sensors.
| Trait ID | Code |
|---|
| 0x4FC0 | RelatedEventRecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TimelapseEnable Trait (Timelapse Enable)
Enables or disables the timelapse function. When enabled, the device captures an image sequence at fixed intervals (configured separately) and composites them into a video.
| Trait ID | Code |
|---|
| 0x4FC7 | TimelapseEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
TimelapseTimePeriod Trait (Timelapse Time Period)
Defines a scheduled plan for the active period of timelapse recording. The scheduling configuration structure contains three fields: starttime, endtime, and repeat. starttime and endtime are strings in "HH:MM" format (24-hour), ranging from "00:00" to "23:59", defining the start and end times of the active period. If they are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of unsigned 8-bit integers with a length of 7, whose index order corresponds to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. A value of 1 means the working day is active, and 0 means it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FC8 | TimelapseTimePeriod |
Parameters
TimelapsePushEnable Trait (Timelapse Push Enable)
Timelapse push enable. Controls whether timelapse content is pushed. 0 = off, 1 = on.
| Trait ID | Code |
|---|
| 0x517E | TimelapsePushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
CameraActiveToggle Command
This Command is used to perform the "Camera Sleep Toggle Command" operation.
Parameters
CameraActiveToggle Command Structure
Playback (Playback)
Interaction Flow
Downloading the Local Recording Index File
This section describes the flow in which the App downloads the local recording index file over the WebRTC DataChannel.
The index granularity is day: at most one entry per day. A single query can span multiple days, and the response member LocalRecordIndex is the list of those days. When the number of days is small, MaxCount / Cursor are usually not needed.
- Command: LocalRecordQuery with
QueryLocalRecordType=LocalRecordIndex; the parameters are in the member LocalRecordIndex. It is exchanged via InvokeCommand on label aqara.control; the request OpCode is 0x008D and the response OpCode is 0x038D.
- Response: the ComplexACK of this Command. Member 0 is
Status, and the member LocalRecordIndex is a list of LocalRecordIndexEntryStructure.
To query a time range, pass the whole range; the device puts one entry per day into the response member LocalRecordIndex. The file transfer uses the FileDescriptor of that entry, written into initRequest. Date does not enter the transfer. On label aqara.download, only one FileDescriptor is transferred at a time; a new initRequest SHALL NOT be issued before the previous one finishes. Block interactions are not expanded in this diagram.
Downloading Local Recording Files
This section describes the flow in which the App downloads local recording files over the WebRTC DataChannel.
The App first downloads the local recording index file, reads the timestamp values to fetch from the index file, and then queries the local recording file descriptors.
- Command: the same LocalRecordQuery with
QueryLocalRecordType=LocalRecordSegment; the parameters are in the member LocalRecordSegment, where Timestamps come from the index. It is exchanged via InvokeCommand on label aqara.control.
- Response: the ComplexACK of this Command. The member
LocalRecordSegment has the same length and order as Timestamps, and each entry is a FileDescriptorStructure.
On label aqara.download, only one FileDescriptor is transferred at a time; a new initRequest SHALL NOT be issued before the previous one finishes. When an entry has a fileSize of 0, skip that entry and do not issue an initRequest for it. Block interactions are not expanded in this diagram. When the list exceeds a single message, the App splits it into multiple requests. Retransmitting the same query after a timeout is safe; queries do not change device state.
Introduction
Manages recording playback and history, including cloud clip type identification, local recording download capability, and the state and playback position of local playback sessions. Playback sessions are established by WebRTCProvideOffer (StreamUsage=LocalPlayback); pause, resume, seek, and speed are handled by LocalPlaybackControl. Local recording index and recording file descriptors are queried by LocalRecordQuery.
Function Identification
| Function ID | Code | Name |
|---|
| 0x010A | Playback | Playback |
Trait
Command
The Commands of this Function are exchanged via InvokeCommand on the aqara.control label of the playback session.
Data Types
CloudClipRecordingTypeEnum8 Type
This enumeration defines the valid values of the Present Value for the CloudClipRecordingType Trait.
| Value | Name | Description |
|---|
| 0x00 | Default | Default |
| 0x01 | Recording | Recording |
| 0x16 | AssociatedEvent | Related event |
| 0x1B | SecurityAssociated | Security related event |
LocalPlaybackStateEnum8 Type
| Value | Name | Description |
|---|
| 0x00 | Idle | Not playing |
| 0x01 | Playing | Playing |
| 0x02 | Paused | Paused; the PeerConnection is kept |
| 0x03 | Eof | Played to the end of the file |
| 0x04 | Stopped | Stopped by the device side |
| 0x05 | StorageUnavailable | SD card removed or unreadable |
LocalPlaybackStatusStructure Type
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | State | LocalPlaybackStateEnum8 | M | Current state |
| 1 | SessionId | uint16 | O | Carried when reporting or reading over COIP. Omitted in DataChannel reporting; the session is determined by that channel |
LocalRecordTypeEnum Type
This enumeration is the type of each record in the per-day sub-index file. The App reads it from the downloaded index file; query responses do not return it again.
| Value | Name | Description |
|---|
| 0 | FullRecording | Full-time recording |
| 1 | EventTriggered | Event triggered |
| 2 | AlarmRecord | Alarm record |
LocalPlaybackControlOpEnum8 Type
| Value | Name | Description |
|---|
| 0x00 | Pause | Pause. Stops reading frames; the PeerConnection is kept |
| 0x01 | Play | Resume playback |
| 0x02 | Seek | Seek. Timestamp is valid |
| 0x03 | Speed | Speed. Speed is valid |
LocalPlaybackControl Command Structure Type
The request structure of LocalPlaybackControl.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Op | LocalPlaybackControlOpEnum8 | M | Operation |
| 1 | Speed | uint8 | C | Shall be 1 / 2 / 4 when Op=Speed; SHALL be omitted for other Op values |
| 2 | Timestamp | uint32 | C | The target UTC timestamp (seconds) when Op=Seek, aligned with the timestamp in the index entry; SHALL be omitted for other Op values |
| 3 | SessionId | uint16 | O | Carried over COIP to specify the playback session to control. Omitted on DataChannel; the session is determined by that channel |
LocalPlaybackControlResponse Command Structure Type
The response structure of LocalPlaybackControl.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Status | StatusCodeEnum8 | M | Command execution result; see the command definition for values |
| 1 | CurrentTimestamp | uint32 | M | The current playback position (seconds) on the device side after execution |
Recording Queries
Queries only distinguish LocalRecordIndex and LocalRecordSegment. QueryLocalRecordType indicates which one it is, and only the member it points to appears in the request and response. File descriptors use FileDescriptorStructure, filled in by the device. The App SHALL write it into initRequest as-is and SHALL NOT construct fileDesignator by itself from dates or timestamps.
ContentType remains a business convention and is not carried in queries or file transfers.
LocalRecordIndex and LocalRecordSegment form two levels. The index lists which days exist; segment resolution is not responsible for listing segments.
| Answers | What it corresponds to on the device |
|---|
LocalRecordIndex | Which days have index files matching the query conditions | Per-day sub-index files. After download, each record in the file gives the timestamp, duration, and type of a recording segment |
LocalRecordSegment | The recording files corresponding to these timestamp values | The device locates recording files by timestamp and returns FileDescriptorStructure |
Index entries additionally carry a UTC date outside FileDescriptorStructure, used only for display and not entering initRequest. The response of segment resolution is FileDescriptorStructure.
QueryLocalRecordTypeEnum8 Type
LocalRecordQuery uses it to select the parameters and results of this query. It is not the same enumeration as LocalRecordTypeEnum inside the index file.
| Value | Name | Description |
|---|
| 0x00 | LocalRecordIndex | Query which days have index files. The parameters and results use the member LocalRecordIndex |
| 0x01 | LocalRecordSegment | Resolve the timestamp values in the index into recording file descriptors. The parameters and results use the member LocalRecordSegment |
LocalRecordQuery Command Structure Type
QueryLocalRecordType decides which condition member appears. If the appearing member is inconsistent with the value, or both condition members appear, or neither appears, the response Status is INVALID_COMMAND. Cursor and MaxCount appear only when QueryLocalRecordType=LocalRecordIndex.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Type | QueryLocalRecordTypeEnum8 | M | Kind of this query |
| 1 | Index | LocalRecordIndexQueryParamsStructure | C | Appears when QueryLocalRecordType=LocalRecordIndex |
| 2 | Segment | LocalRecordSegmentQueryParamsStructure | C | Appears when QueryLocalRecordType=LocalRecordSegment |
| 3 | Cursor | uint16 | O | Only for LocalRecordIndex. The entry index within the matching results, starting from 0. Taken from the NextCursor of the previous response; omitted or 0 means starting from the first entry |
| 4 | MaxCount | uint16 | O | Only for LocalRecordIndex. The desired maximum number of entries; omitted or 0 means decided by the device |
LocalRecordIndexQueryParamsStructure Type
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | StartTimestamp | uint32 | O | Start of the range (UTC, seconds); omitted means no lower bound |
| 1 | EndTimestamp | uint32 | O | End of the range (UTC, seconds); omitted means no upper bound |
Both fields are Unix second timestamps, synonymous with the global field name timestamp in this specification; the device is responsible for mapping them to the corresponding UTC day. To query a single day, pass [00:00 of that day, 00:00 of the next day). The date in the returned entries is YYYYMMDD; fetching the file uses the FileDescriptor in the same entry.
FileDescriptorStructure Type
The file descriptor required by the file transfer business interaction protocol before initRequest. The field meanings follow the dependency section of that protocol.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | fileDesignator | characterString | M | File reference. UTF-8, no more than 256 bytes, bound to the authorized identity and the fixed version, and SHALL NOT be a local absolute path. Written into member 0 of initRequest. Identifies a file in the results of LocalRecordIndex and LocalRecordSegment respectively |
| 1 | fileSize | uint64 | M | Full length in bytes. When it is 0, the entry may still be returned, but SHALL NOT issue an initRequest for it. When fetching the whole file, it is used as the length of initRequest |
| 2 | fileVersion | uint32 | M | File version, range 0..4294967295. Written into member 1 of initRequest |
LocalRecordIndexEntryStructure Type
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | FileDescriptor | FileDescriptorStructure | M | Per-day index file; written to initRequest when fetching bytes |
| 1 | Date | characterString | M | UTC date of this index in YYYYMMDD, e.g. "20261013". For display only; it does not enter initRequest |
LocalRecordSegmentQueryParamsStructure Type
The input comes from the already downloaded index file, not a time window.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Timestamps | list[uint32] | M | The timestamp in the index entries, one or more. An empty list is an invalid parameter. |
The response member LocalRecordSegment SHALL have the same length and order as the requested Timestamps. Each entry is a FileDescriptorStructure.
LocalRecordQuery Response Command Structure Type
QueryLocalRecordType echoes the value in the request and decides which member the result list appears in.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Status | StatusCodeEnum8 | M | SUCCESS means the query succeeded and the result list may be empty. INVALID_COMMAND means the parameters are invalid. INVALID_IN_STATE means the storage is unavailable. DYNAMIC_CONSTRAINT_ERROR means the cursor has been invalidated |
| 1 | Type | QueryLocalRecordTypeEnum8 | M | Echoes the value in the request |
| 2 | Index | list[LocalRecordIndexEntryStructure] | C | Appears when QueryLocalRecordType=LocalRecordIndex |
| 3 | Segment | list[FileDescriptorStructure] | C | Appears when QueryLocalRecordType=LocalRecordSegment. One-to-one with the Timestamps request |
| 4 | NextCursor | uint16 | O | Index query only. The entry index of the first entry of the next page; an omitted value means the query has finished |
| 5 | TotalCount | uint16 | M | Returned by both queries. For the index query it is the number of matched entries in the time range, unaffected by Cursor and MaxCount; for the segment query it is the number of entries in this Timestamps request |
Trait Definitions
CloudClipRecordingType Trait (Cloud Clip Recording Type)
Indicates the recording type of the triggered cloud short video (clip). Value 0 = default (unspecified), 1 = recording (general event), 22 = related event (triggered by other sensors/devices), 27 = security related event (for example, home security alarm). This feature can be read, written, and proactively reported by the device.
| Trait ID | Code |
|---|
| 0x4FE9 | CloudClipRecordingType |
Parameters
SupportLocalVideoDownload Trait (Local Video Download Support)
Indicates whether the device supports downloading local videos from the SD card through the App.
| Trait ID | Code |
|---|
| 0x4FC1 | SupportLocalVideoDownload |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
LocalPlaybackStatus Trait (Local Playback Status)
Playback status and playback position.
| Trait ID | Code |
|---|
| 0x5243 | LocalPlaybackStatus |
Parameters
Reporting timing: when the status changes. When reporting on aqara.control, SessionId is omitted; when reporting via COIP or reading, SessionId is included.
Command Definitions
LocalPlaybackControl Command (Local Playback Control)
Playback control of the local SD card playback session (StreamUsage=LocalPlayback).
Parameters
LocalPlaybackControl Command Structure
Response
LocalPlaybackControlResponse Command Structure, with Status values:
| Status | Meaning |
|---|
SUCCESS | The command was accepted |
INVALID_IN_STATE | The session is not a playback session |
INVALID_COMMAND | Op is invalid or a parameter is missing. When arriving from COIP without SessionId, this value is also taken |
NOT_FOUND | SessionId is not an active session, or Timestamp cannot be mapped to a recording position. When the DataChannel carries a SessionId inconsistent with that channel, this value is also taken |
Processing
- When arriving from
aqara.control, SessionId is omitted and the session is the playback session to which that channel belongs. Carrying an inconsistent SessionId -> return NOT_FOUND. When arriving from COIP, SessionId SHALL be carried; if omitted -> return INVALID_COMMAND.
Pause and Play belong to one category, and only the last one of the same category is kept; Seek is one category; Speed is one category. Overwritten commands are no longer reported, but each command has its own response.- After
Op=Seek takes effect, SHALL send a key frame from the new position.
LocalRecordQuery Command (Local Recording Query)
Queries the local recording index and resolves the timestamp values in the index into recording file descriptors. This Command belongs to the Playback Function and is exchanged via InvokeCommand on the aqara.control of the playback session.
- Request OpCode
0x008D. objectIdentifier carries the object hosting the Playback Function. propertyIdentifier is the Command ID of this Command. propertyValue is the LocalRecordQuery Command Structure. source is the same as other Commands.
- Response OpCode
0x038D. propertyValue is the LocalRecordQuery Response Command Structure, and member 0 is Status. Invalid parameters, unavailable storage, and invalidated cursors all stay in this ComplexACK.
With QueryLocalRecordType=LocalRecordIndex, the member LocalRecordIndex is used, which is bounded (MaxCount + Cursor) and one-question-one-answer with no progress notifications. With QueryLocalRecordType=LocalRecordSegment, the member LocalRecordSegment is used, without a cursor: the request gives which timestamps, and the response returns the file descriptors in the same order. Both queries return TotalCount.
Parameters
LocalRecordQuery Command Structure
Response
LocalRecordQuery Response Command Structure
See Downloading the Local Recording Index File and Downloading Local Recording Files for the flows.
Pagination applies only to LocalRecordIndex. The range of LocalRecordSegment is the Timestamps in the request.
| Dimension | Parameters | Answer |
|---|
| Range | The timestamp range of LocalRecordIndex (StartTimestamp / EndTimestamp) | Which days to query the index for |
| Pagination | MaxCount / Cursor | How many index entries this response carries. TotalCount is the number of entries in the whole range |
Cursor and NextCursor are entry indexes into the matched results, starting from 0, not time. The App SHALL only echo the NextCursor of the previous response, and SHALL NOT compute it from Date or timestamps by itself.TotalCount is returned by both queries. For the index query it is the number of matched entries in the time range; for the segment query it is the number of entries in this Timestamps request. With circular overwrite, a later page of an index query can differ from the previous page. Whether the query is finished is determined by NextCursor.- One response SHALL NOT exceed the limit of a single carried message. Beyond the given
MaxCount, the device SHALL keep converging according to this limit.
- An omitted
NextCursor means the query has finished; an empty LocalRecordIndex with a NextCursor is legal (that page was filtered out).
- When the cursor is invalidated, SHALL return
Status = DYNAMIC_CONSTRAINT_ERROR and the App restarts the query from the beginning.
- During pagination, circular recording may have overwritten old data, and entries may be duplicated or missing. The device SHOULD keep the result consistent within the cursor lifetime; if it cannot, the App deduplicates by
fileDesignator.
- Repeated queries of the hole-refetching kind SHOULD follow a minimum interval (500 ms is used for index queries in production).
CloudRecording (Cloud Recording)
Introduction
Controls the master switch of cloud recording, determining whether video content is uploaded to cloud storage.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x010B | CloudRecording | Cloud recording |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
CloudRecordingEnable Trait (Cloud Video Recording Master Enable)
The master switch to enable or disable event cloud recording.
| Trait ID | Code |
|---|
| 0x5026 | CloudRecordingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
CameraSettings (More Settings)
Introduction
Provides extended camera configurations, such as periodic snapshot upload, RTSP streaming, and advanced feature switches.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x010C | CameraSettings | More settings |
Trait
Command
This Function does not contain any Commands.
Data Types
PeriodicSnapshotIntervalEnum8 Type
This enumeration defines the valid values of the Present Value for the PeriodicSnapshotInterval Trait.
| Value | Name | Description |
|---|
| 0x00 | Auto | Auto |
| 0x01 | Minutes10 | 10 minutes |
| 0x02 | Minutes30 | 30 minutes |
| 0x03 | Minutes60 | 60 minutes |
| 0x04 | Minutes120 | 120 minutes |
| 0x05 | Minutes240 | 240 minutes |
ClientKeepAliveReqEnum8 Type
This enumeration defines the valid values of the Present Value for the ClientKeepAliveReq Trait.
| Value | Key | Chinese Name | Description |
|---|
| 0x01 | KeepAlive | Keep-alive request | Client keep-alive request. |
Trait Definitions
PeriodicSnapshotUploadEnable Trait (Periodic Snapshot Upload Enable)
Enables or disables periodic snapshot upload to the cloud. When PeriodicSnapshotInterval is implemented, the capture interval is configured by that Trait; when it is not implemented, the behavior of uploading one frame every 10 minutes is maintained.
| Trait ID | Code |
|---|
| 0x5028 | PeriodicSnapshotUploadEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
PeriodicSnapshotInterval Trait (Periodic Snapshot Interval)
Device-side periodic snapshot capture interval. It can be configured and takes effect after PeriodicSnapshotUploadEnable is enabled, replacing the fixed interval of capturing one frame every 10 minutes. 0 means the device decides the interval automatically; non-zero values execute the interval specified by the enumeration. The default is 0, and it is readable, writable, and reportable.
| Trait ID | Code |
|---|
| 0x5249 | PeriodicSnapshotInterval |
Parameters
CameraRTSPEnable Trait (Camera RTSP Enable)
Indicates the RTSP (Real Time Streaming Protocol) enable switch configuration of the camera. When enabled, the live video stream can be accessed through the RTSP protocol; when disabled, RTSP access is forbidden.
| Trait ID | Code |
|---|
| 0x4F91 | CameraRTSPEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraRTSPURL Trait (Camera RTSP URL)
Indicates the RTSP (Real Time Streaming Protocol) URL of the camera, used to access the live video stream through the RTSP protocol. This property returns a JSON object whose keys are resolution identifiers (such as "360p", "720p", "1080p", "4mp") and whose values are the corresponding complete RTSP URL strings. Example format: {"360p": "rtsp://192.168.1.109:8554/360p","720p": "rtsp://192.168.1.109:8554/720p","1080p": "rtsp://192.168.1.109:8554/1080p","4mp": "rtsp://192.168.1.109:8554/4mp"}
| Trait ID | Code |
|---|
| 0x4F90 | CameraRTSPURL |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RV | O |
ClientKeepAliveReq Trait (Client Keep-Alive Request)
A keep-alive request sent by the client (APP) to a low-power device to prevent the device from sleeping during the setup process. Upon receiving it, the device should reset the sleep timer.
| Trait ID | Code |
|---|
| 0x5171 | ClientKeepAliveReq |
Parameters
VideoAutoBrightSupport Trait (Video Auto Brightness Support)
Video auto brightness support. Used to identify whether the device supports automatically adjusting video brightness. 0 = not supported, 1 = supported.
| Trait ID | Code |
|---|
| 0x5180 | VideoAutoBrightSupport |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RV | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
IrcutThreshold Trait (IR-Cut Switch Threshold)
IR-Cut switch threshold. Used to control the switching of the infrared filter.
| Trait ID | Code |
|---|
| 0x5181 | IrcutThreshold |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 50 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0007 | Default Value | uint8 | | 50 | RW | O |
Command Definitions
This Function does not contain any Commands.
AIDetection (AI Detection)
Introduction
Performs AI-driven image and audio analysis to achieve event detection, content recognition, and intelligent alerts.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x010D | AIDetection | AI detection |
Trait
Command
This Function does not contain any Commands.
Data Types
LensObstructionDetectedEnum8 Type
This enumeration defines the valid values of the Present Value for the LensObstructionDetected Trait.
| Value | Name | Description |
|---|
| 0x01 | Detected | Lens obstruction detected |
LensObstructionTimePeriodTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the LensObstructionTimePeriod Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | starttime | characterString | M | Start time, in HH:MM format (24-hour). |
| 1 | endtime | characterString | M | End time, in HH:MM format (24-hour). |
| 2 | repeat | array[uint32] | M | A weekday repeat flag with a fixed length of 7, in order from Sunday to Saturday; 1 means active, 0 means inactive. |
LensObstructionBitmaskRegionTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the LensObstructionBitmaskRegion Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | detect_region | characterString | M | A bitmask in hexadecimal string form, where each bit corresponds to a grid cell. |
| 1 | effective_bits | int32 | M | The number of valid bits in the bitmask; bits beyond this number should be ignored. |
LensObstructionSensitivityEnum8 Type
This enumeration defines the valid values of the Present Value for the LensObstructionSensitivity Trait.
| Value | Name | Description |
|---|
| 0x00 | Lowest | Minimum |
| 0x01 | Low | Low |
| 0x02 | Medium | Medium |
| 0x03 | High | High |
| 0x04 | Highest | Maximum |
Trait Definitions
LensObstructionDetected Trait (Lens Obstruction Detection Event)
An event Trait indicating that the camera lens is obstructed (partially or completely). When the device detects lens obstruction, it reports this Trait with a value of 1.
| Trait ID | Code |
|---|
| 0x507C | LensObstructionDetected |
Parameters
LensObstructionPushEnable Trait (Lens Obstruction Push Enable)
Enables or disables push notifications for lens obstruction events. When enabled, the user will receive an alert when the lens is obstructed.
| Trait ID | Code |
|---|
| 0x4FE0 | LensObstructionPushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
LensObstructionTimePeriod Trait (Lens Obstruction Detection Time Period)
Defines the time period during which lens obstruction detection is active. The schedule configuration structure contains three fields: starttime, endtime, and repeat. starttime and endtime are strings in "HH:MM" format (24-hour), ranging from "00:00" to "23:59", defining the start and end times of the active period. If they are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of unsigned 8-bit integers with a length of 7, whose index order corresponds to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. A value of 1 means the working day is active, and 0 means it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FDF | LensObstructionTimePeriod |
Parameters
LensObstructionEnable Trait (Lens Obstruction Enable)
Enables or disables the lens obstruction detection function. When enabled, the camera monitors whether the lens is partially or completely obstructed and can trigger events, recordings, or notifications accordingly.
| Trait ID | Code |
|---|
| 0x4FDE | LensObstructionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
LensObstructionRecordEnable Trait (Lens Obstruction Record Enable)
Enables or disables local recording when lens obstruction is detected.
| Trait ID | Code |
|---|
| 0x4FFC | LensObstructionRecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
LensObstructionInterval Trait (Lens Obstruction Detection Interval)
The time interval (in seconds) between consecutive lens obstruction detection triggers.
| Trait ID | Code |
|---|
| 0x4FFD | LensObstructionInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint16 | | 180 | RVW | O |
| 0x0002 | Maximum Value | uint16 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint16 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint16 | | 180 | RW | O |
LensObstructionSensitivity Trait (Lens Obstruction Detection Sensitivity)
This Trait is used to configure the sensitivity level of lens obstruction detection. The valid values are 0, 1, 2, 3, and 4, corresponding to minimum, low, medium, high, and maximum sensitivity, respectively. Higher sensitivity makes the function more responsive to trigger conditions (for example, detecting weak signals or small targets more easily); lower sensitivity requires more obvious triggers to respond.
| Trait ID | Code |
|---|
| 0x4FFB | LensObstructionSensitivity |
Parameters
LensObstructionBitmaskRegion Trait (Lens Obstruction Region Setting)
Represents the configuration of the lens obstruction detection region. The region configuration is defined based on a grid mask. It contains two fields: detect_region (hexadecimal string) and effective_bits (integer). Each bit in the hexadecimal string corresponds to a grid cell (for example, dividing the picture into 24 cells). A bit value of 1 means detection or recognition is enabled for the corresponding cell, and 0 means it is disabled. The bit arrangement follows a predefined order (for example, from left to right or from the most significant bit to the least significant bit). The effective_bits field specifies the number of actually valid bits in the hexadecimal string, allowing the string to keep a fixed length while only the first N bits are meaningful. For example, "FF" means 8 consecutive bits are all 1. If effective_bits is 32, all 32 bits are valid; if it is 24, only the first 24 bits are valid.
| Trait ID | Code |
|---|
| 0x5191 | LensObstructionBitmaskRegion |
Parameters
AIVideoSummaryEnable Trait (AI Video Summary Enable)
Enables or disables AI video summary generation. AI extracts key moments (events) and composites them into a short video summary.
| Trait ID | Code |
|---|
| 0x4FC3 | AIVideoSummaryEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AIVideoSearchEnable Trait (AI Video Search Enable)
Enables or disables the AI video search function. When enabled, the user can search recordings by object type (such as person, vehicle, package).
| Trait ID | Code |
|---|
| 0x4FC2 | AIVideoSearchEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
VideoSettings (Video Settings)
Introduction
Manages image processing and picture presentation, including image quality, watermark, privacy masking, night vision, and fill light linkage.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x010E | VideoSettings | Video settings |
Trait
Command
| Command ID | Code | Name | Conformance |
|---|
| 0x9D3E | WhiteLightToggle | White light status toggle control | O |
Data Types
ImageFlipModeEnum8 Type
This enumeration defines the valid values of the Present Value for the ImageFlipMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | HorizontalFlip | Horizontal flip |
| 0x02 | VerticalFlip | Vertical flip |
| 0x03 | HorizontalVerticalFlip | Horizontal and vertical flip |
InfraredNightVisionSettingEnum8 Type
This enumeration defines the valid values of the Present Value for the InfraredNightVisionSetting Trait.
| Value | Name | Description |
|---|
| 0x00 | AlwaysOff | Always off |
| 0x01 | AlwaysOn | Always on |
| 0x02 | Auto | Auto switch |
| 0x03 | WarmColorFullColor | Warm light full color |
PowerFrequencyEnum8 Type
This enumeration defines the valid values of the Present Value for the PowerFrequency Trait.
| Value | Name | Description |
|---|
| 0x00 | 50Hz | 50Hz |
| 0x01 | 60Hz | 60Hz |
EventLightingModeEnum8 Type
This enumeration defines the valid values of the Present Value for the EventLightingMode Trait.
| Value | Name | Description |
|---|
| 0x00 | Steady | Steady |
| 0x01 | Blink | Blink |
VideoBrightnessRangeTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the VideoBrightnessRange Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Mode | uint8 | M | Brightness adjustment mode: 0 = automatic, 1 = manual. |
| 1 | ColorBrightness | uint16 | O | Color video brightness percentage, range 1-100; should be provided in manual mode. |
| 2 | MonoBrightness | uint16 | O | Black-and-white video brightness percentage, range 1-100; should be provided in manual mode. |
WhiteLightToggle Command Structure Type
Parameter structure of the WhiteLightToggle Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
Trait Definitions
AIDetectionBoxEnable Trait (Display Detection Box Enable)
Enables or disables drawing AI detection bounding boxes (such as people, pets) in the live preview.
| Trait ID | Code |
|---|
| 0x5019 | AIDetectionBoxEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
HdrEnable Trait (HDR Enable)
Enables or disables the HDR (High Dynamic Range) function. When enabled, the device improves image quality in backlit or high-contrast scenes, preserving highlight and shadow details for a clearer and more natural picture.
| Trait ID | Code |
|---|
| 0x5000 | HdrEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
VideoCorrectionEnable Trait (Video Correction Enable)
Turns lens distortion correction on/off. When enabled, the device applies distortion correction to straighten the curved edges caused by the wide-angle lens (improving image geometry but possibly cropping the field of view).
| Trait ID | Code |
|---|
| 0x4FD0 | VideoCorrectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Specifies the format string for displaying the date and time in the OSD watermark. Uses strftime-compatible format specifiers (for example, %Y for year, %m for month, %d for day, %H for hour, %M for minute, %S for second).
| Trait ID | Code |
|---|
| 0x4FCE | OSDTimeFormatSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
ImageFlipMode Trait (Image Flip)
Controls whether the video picture is vertically flipped (180 deg rotation). When set to Flip (1), the picture is upside down, suitable for ceiling-mounted or inverted installation scenarios; when set to Normal (0), the picture orientation is standard.
| Trait ID | Code |
|---|
| 0x4FCF | ImageFlipMode |
Parameters
OSDWatermarkEnable Trait (OSD Time Watermark Enable)
Controls whether a timestamp is overlaid on the live preview and recordings. When enabled, the current date and time are displayed at the specified position of the video picture, helping viewers accurately identify when an event occurred.
| Trait ID | Code |
|---|
| 0x4FCB | OSDWatermarkEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
InfraredNightVisionSetting Trait (Night Vision Setting)
Sets the night vision mode of the camera. AlwaysOff: IR cut and illuminator off; AlwaysOn: IR cut on (black-and-white) and IR LED on; Auto: switches according to ambient light; WarmColorFullColor: uses warm white light for full-color night vision.
| Trait ID | Code |
|---|
| 0x4FCA | InfraredNightVisionSetting |
Parameters
PrivacyMaskRegions Trait (Privacy Mask Region)
Defines the mask regions used to protect privacy in the video frame. Its value is a structure containing visible and regions fields. visible is a boolean or integer (0 or 1), indicating whether to display the outlines of the mask regions in the live preview (for debugging or confirmation; it does not affect the actual masking effect). regions is an array of up to 4 mask objects. Each mask object contains color and rect. color is an integer (decimal), representing the RGB color of the mask block (for example, the decimal form of 0xRRGGBB, with the high byte as red, the middle byte as green, and the low byte as blue). rect is an array of four integers specifying the bounding rectangle: left coordinate, top coordinate, width, and height. The coordinate origin is at the top-left corner of the image, with the X axis increasing to the right and the Y axis increasing downward. This configuration applies to both the live video and the recording stream, and the masking is executed on the device side to ensure that privacy-sensitive content cannot be restored.
| Trait ID | Code |
|---|
| 0x5018 | PrivacyMaskRegions |
Parameters
PowerFrequency Trait (Power Frequency)
Sets the power line frequency to avoid flicker (50Hz or 60Hz).
| Trait ID | Code |
|---|
| 0x5017 | PowerFrequency |
Parameters
LogoWatermarkEnable Trait (Logo Watermark Enable)
Enables or disables the video brand logo watermark overlay. When enabled, the device embeds a fixed logo image in the video files.
| Trait ID | Code |
|---|
| 0x4FB0 | LogoWatermarkEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
WhiteLightDuration Trait (White Light Duration)
Sets the duration that the white light (fill light) stays on after being triggered. A value of 0 means it stays on continuously (always on). Values from 1 to 1800 represent the number of seconds it stays on before automatically turning off.
| Trait ID | Code |
|---|
| 0x4FDB | WhiteLightDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 1800 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 30 | RW | O |
EventLightingMode Trait (Event-Triggered Lighting Mode)
Defines the behavior of the indicator/illumination light when the device detects an event. Steady: the light stays steadily on; Blink: the light blinks repeatedly.
| Trait ID | Code |
|---|
| 0x4FDA | EventLightingMode |
Parameters
LightingTimePeriod Trait (Lighting Time Period)
Defines the scheduled plan for the active period of the event-triggered lighting function. The schedule configuration structure contains three fields: starttime, endtime, and repeat. starttime and endtime are strings in "HH:MM" format (24-hour), ranging from "00:00" to "23:59", defining the start and end times of the active period. If they are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of unsigned 8-bit integers with a length of 7, whose index order corresponds to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. A value of 1 means the working day is active, and 0 means it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x4FBF | LightingTimePeriod |
Parameters
LightUpWhenEventDetected Trait (Light Up When Event Detected)
Turns on the white light for 20 seconds when an event (such as motion or person detection) is detected during the scheduled period. Used as a visual deterrent or for illumination.
| Trait ID | Code |
|---|
| 0x4FBE | LightUpWhenEventDetected |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
WhiteLightOnOff Trait (White Light Switch)
Controls the master switch of the white fill light. Toggling changes the current state.
| Trait ID | Code |
|---|
| 0x5014 | WhiteLightOnOff |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
WhiteLightBrightness Trait (White Light Brightness Setting)
Sets the white light brightness level, ranging from 1% to 100%.
| Trait ID | Code |
|---|
| 0x5016 | WhiteLightBrightness |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 1.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
VideoBrightnessRange Trait (Video Brightness Range Setting)
Configures the brightness parameters of color (daytime) and black-and-white (nighttime) video, and supports both automatic and manual adjustment modes.
| Trait ID | Code |
|---|
| 0x50E0 | VideoBrightnessRange |
Parameters
Command Definitions
WhiteLightToggle Command
This Command is used to perform the "White Light Status Toggle Control" operation.
Parameters
WhiteLightToggle Command Structure
CameraWorkMode (Camera Work Mode)
Introduction
Defines the camera power consumption strategy and work modes, adapting to different power supply types and usage scenarios.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x010F | CameraWorkMode | Camera work mode |
Trait
Command
This Function does not contain any Commands.
Data Types
CamWorkModeEnum8 Type
This enumeration defines the valid values of the Present Value for the CamWorkMode Trait.
| Value | Name | Description |
|---|
| 0x00 | PowerSaving | Power saving mode |
| 0x01 | SuperPowerSaving | Super power saving mode |
| 0x02 | MainsPower | Mains power mode |
| 0x03 | AOV | Smart monitoring mode (AOV) |
Trait Definitions
ActiveWakeupInterval Trait (Active Wake-Up Interval)
Configures the active wake-up interval of the battery-powered camera when operating in AOV (Always-On Video) smart monitoring mode. The device wakes up periodically at this interval (in seconds) to capture frames for event detection. For example, setting it to 3 means the camera wakes up every 3 seconds to check for motion or events.
| Trait ID | Code |
|---|
| 0x4FD9 | ActiveWakeupInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 3 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 65535 | R | O |
| 0x0003 | Minimum Value | uint32 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 3 | RW | O |
CamWorkMode Trait (Camera Work Mode)
Defines the working mode of the camera in terms of power consumption and functionality. PowerSaving: reduces performance to extend battery life; SuperPowerSaving: maximum power saving with limited functionality; MainsPower: full performance operation under continuous power supply (AC/DC); AOV: Always-On Video low-power smart monitoring mode.
| Trait ID | Code |
|---|
| 0x4FD8 | CamWorkMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | CamWorkModeEnum8 | | 0 | RVW | O |
| 0x0006 | Supported Value | list[CamWorkModeEnum8] | | | R | O |
| 0x0007 | Default Value | uint8 | | 0 | RW | O |
AOVRecordingEnable Trait (AOV Recording Enable)
Enables or disables the AOV (Always-On Video) recording function. When enabled, the device records continuously to ensure that key moments are not missed.
| Trait ID | Code |
|---|
| 0x4FD6 | AOVRecordingEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
RangeTestMode Trait (Enter Ranging Test Mode)
Enables the ranging test mode for configuring the camera detection distance. In this mode, the device emits a prompt (such as flashing the white light three times) when a target is detected, indicating the effective range of the current distance setting.
| Trait ID | Code |
|---|
| 0x4FD3 | RangeTestMode |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
AudioSettings (Audio Settings)
Introduction
Controls audio capture and output, adjusting parameters such as recording mute and system prompt volume.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0110 | AudioSettings | Audio settings |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
RecordingMuteEnable Trait (Silent Recording Enable)
Determines whether audio is recorded together with the video. When set to 1 (muted), the recording file does not save audio; when set to 0, audio is included.
| Trait ID | Code |
|---|
| 0x4FD1 | RecordingMuteEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Volume Trait (Volume)
Indicates or sets the speaker volume of the camera device (such as for two-way voice). The value is usually expressed as a percentage (0 to 100) or a device-defined numeric range.
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
QuickReplyTotalCapacity Trait (Custom Quick Reply Total Capacity)
Custom quick reply total capacity. Used to record the total capacity limit of all audio files saved by the user to the device among custom quick replies/custom ringtones, in MB.
| Trait ID | Code |
|---|
| 0x5182 | QuickReplyTotalCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 6 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 100 | R | O |
| 0x0003 | Minimum Value | uint8 | | 0 | R | O |
| 0x0007 | Default Value | uint8 | | 6 | RW | O |
QuickReplyPresetVoice Trait (Quick Reply Preset Voice)
Quick reply preset voice. Used to identify the language and index of the preset quick reply voice.
| Trait ID | Code |
|---|
| 0x5183 | QuickReplyPresetVoice |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
CameraPrivacySecurity (Camera Privacy and Security)
Introduction
Focuses on the camera privacy policy, including low-power security and privacy protection capabilities such as scheduled sleep.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0111 | CameraPrivacySecurity | Camera privacy and security |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
ScheduledSleepTimePeriod Trait (Scheduled Sleep Time Period)
Defines the scheduled plan for the period during which the device should enter sleep mode. The schedule configuration structure contains three fields: starttime, endtime, and repeat. starttime and endtime are strings in "HH:MM" format (24-hour), ranging from "00:00" to "23:59", defining the start and end times of the active period. If they are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of unsigned 8-bit integers with a length of 7, whose index order corresponds to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. A value of 1 means the working day is active, and 0 means it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x501B | ScheduledSleepTimePeriod |
Parameters
ScheduledSleepEnable Trait (Scheduled Sleep Enable)
Enables or disables the scheduled sleep mode.
| Trait ID | Code |
|---|
| 0x501A | ScheduledSleepEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
CameraNotifications (Camera Notifications)
Introduction
Manages event notification policies, supporting notification types, scheduled periods, filtering rules, and importance level settings.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0112 | CameraNotifications | Camera notifications |
Trait
Command
This Function does not contain any Commands.
Data Types
CameraNotificationTypeEnum8 Type
This enumeration defines the valid values of the Present Value for the CameraNotificationType Trait.
| Value | Name | Description |
|---|
| 0x01 | EventNotification | Event notification |
| 0x02 | AIVideoSummary | AI video summary notification |
Trait Definitions
CameraAdvancedEventNotificationSettings Trait (Camera Advanced Event Notification Settings)
Configures the advanced event set for which the camera sends notifications. The value is a string composed of event type numbers separated by vertical bars (|), for example "39 | 40 | 111 | 108". Each number corresponds to a specific event type listed below. Only events whose numbers are included in the string trigger notifications. Value Event Description (English)
1 Motion detection
2 Human form
3 Cat or dog present
4 Human wandering
5 Doorbell pressed
6 Tampering alarm
7 Family member recognized
8 Stranger recognized
9 Abnormal crying
10 Crying
11 Coughing
12 Alarm sound
13 Dog barking
14 Lens blocked
15 Package detected
16 Package disappeared
17 Vehicle present
32 Baby crib
33 Baby stroller
38 Toy car
39 Mask/face covering
40 Mouth and nose covered
46 Holding a phone
48 Person fallen
50 Person climbing
53 Person smoking
56 Wearing a hat
58 Dog
59 Cat
60 Drinking water
61 Eating
62 Using the toilet
63 Animal
64 Pet
65 Bird
66 Bear
67 Brown bear
68 Squirrel
69 Rabbit
70 Deer
71 Reindeer
| Trait ID | Code |
|---|
| 0x4FC9 | CameraAdvancedEventNotificationSettings |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
CameraAdvancedEventNotificationEnable Trait (Camera Advanced Event Notification Enable)
Enables or disables advanced event notifications (such as detailed AI event alerts).
| Trait ID | Code |
|---|
| 0x5012 | CameraAdvancedEventNotificationEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraNotificationSchedulePeriods Trait (Camera Notification Schedule - Periods)
Defines the scheduled plan for the periods in which notifications are allowed. The schedule configuration structure contains three fields: starttime, endtime, and repeat. starttime and endtime are strings in "HH:MM" format (24-hour), ranging from "00:00" to "23:59", defining the start and end times of the active period. If they are equal, the period covers the whole day. When starttime is less than endtime, the period is within the same day; when starttime is greater than endtime, the period crosses midnight, starting from starttime on the active day and ending at endtime on the next day. repeat is an array of unsigned 8-bit integers with a length of 7, whose index order corresponds to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. A value of 1 means the working day is active, and 0 means it is inactive. All times are based on the device's current time zone.
| Trait ID | Code |
|---|
| 0x5010 | CameraNotificationSchedulePeriods |
Parameters
CameraFilterUnimportantNotifications Trait (Camera Filter Unimportant Notifications Enable)
Enables or disables the filtering of unimportant notifications to reduce distractions.
| Trait ID | Code |
|---|
| 0x5011 | CameraFilterUnimportantNotifications |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraNotificationScheduleEnable Trait (Camera Notification Schedule Enable)
Enables or disables the notification schedule function.
| Trait ID | Code |
|---|
| 0x500F | CameraNotificationScheduleEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
CameraNotificationType Trait (Camera Notification Type)
Specifies the type of notifications to receive: event notifications or AI video summary notifications.
| Trait ID | Code |
|---|
| 0x500E | CameraNotificationType |
Parameters
CameraEventImportanceLevel Trait (Camera Event Importance Level)
Sets the minimum importance level for event notifications. Only events with level >= this value trigger notifications.
| Trait ID | Code |
|---|
| 0x5013 | CameraEventImportanceLevel |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 2 | RVW | O |
| 0x0002 | Maximum Value | uint8 | | 5 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint8 | | 2 | RW | O |
PicturePushEnable Trait (Picture Push Enable)
Picture push enable. Controls whether a captured picture is attached to alarm messages for push. When set to 1 (on), the device pushes the current captured picture together with the alarm message to the user when an alarm is triggered; when set to 0 (off), the alarm message does not include a picture. The default value is 0.
| Trait ID | Code |
|---|
| 0x516A | PicturePushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
NASStorage (NAS Storage)
Introduction
Integrates with Network Attached Storage (NAS), providing binding, policy configuration, transfer interval, and status management.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0113 | NASStorage | NAS storage |
Trait
Command
Data Types
NASServerBindingStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the NASServerBindingStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Unbound | Unbound |
| 0x01 | Bound | Bound successfully |
NASWorkModeEnum8 Type
This enumeration defines the valid values of the Present Value for the NASWorkMode Trait.
| Value | Name | Description |
|---|
| 0x00 | TranscodeFromSD | Transfer from local storage card |
| 0x01 | DirectUpload | Upload directly to NAS |
NASVerificationResultEnum8 Type
This enumeration defines the valid values of the Present Value for the NASVerificationResult Trait.
| Value | Name | Description |
|---|
| 0x00 | Failed | Verification failed |
| 0x01 | Success | Verification successful |
NASStatusEnum8 Type
This enumeration defines the valid values of the Present Value for the NASStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | Normal | Normal |
| 0x01 | Transferring | Transferring |
| 0x02 | Paused | Transfer paused |
| 0x03 | Clearing | Clearing videos |
| 0x04 | Error | Error |
DeleteNASServer Command Structure Type
Parameter structure of the DeleteNASServer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | enum8 | M | Status; default value is 0. |
NASClearHistoryVideos Command Structure Type
Parameter structure of the NASClearHistoryVideos Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Type | enum8 | M | Command type. |
Trait Definitions
NASServerBindingStatus Trait (NAS Server Binding Status)
Indicates the binding status between the device and the NAS server. Value 0 means unbound (not connected or not configured), value 1 means bound (successfully connected and authenticated).
| Trait ID | Code |
|---|
| 0x507B | NASServerBindingStatus |
Parameters
NASLastWriteTimestamp Trait (NAS Last Write Timestamp)
Indicates the Unix timestamp (in milliseconds, without time zone) of the last successful write to NAS storage. The device records this timestamp when it finishes writing video files or any data to the NAS.
| Trait ID | Code |
|---|
| 0x4FE4 | NASLastWriteTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 18446744073709551615 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint64 | | 0 | RW | O |
SetNASSharedFolder Trait (Set Shared Folder)
Sets the shared folder path used for NAS storage.
| Trait ID | Code |
|---|
| 0x5025 | SetNASSharedFolder |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | | | RVW | O |
NASSharedFoldersList Trait (Get Shared Folder List)
Retrieves the list of shared folders on the NAS as a JSON array.
| Trait ID | Code |
|---|
| 0x5024 | NASSharedFoldersList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array | | | RV | O |
NASServersList Trait (Get NAS Server List)
Retrieves the list of configured NAS servers as an array.
| Trait ID | Code |
|---|
| 0x5023 | NASServersList |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | array | | | RV | O |
NASStorageDuration Trait (NAS Storage Duration)
The retention duration of videos on the NAS (in seconds).
| Trait ID | Code |
|---|
| 0x502C | NASStorageDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 2592000 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 2592000 | RW | O |
NASTransferInterval Trait (NAS Transfer Interval)
The time interval for transferring videos to the NAS (in seconds).
| Trait ID | Code |
|---|
| 0x502B | NASTransferInterval |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 86400 | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 86400 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 60 | RW | O |
NASStorageEnable Trait (NAS Storage Enable)
Enables or disables NAS video storage.
| Trait ID | Code |
|---|
| 0x5021 | NASStorageEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
NASWorkMode Trait (NAS Work Mode)
Specifies the NAS storage mode: transfer from the SD card or direct upload.
| Trait ID | Code |
|---|
| 0x5022 | NASWorkMode |
Parameters
NASVerificationResult Trait (NAS Verification Result)
The result of the last NAS connection verification.
| Trait ID | Code |
|---|
| 0x5020 | NASVerificationResult |
Parameters
SetNASServers Trait (Set NAS Server)
Configures the parameters required for the device to connect to a NAS server. It contains three parameters: host (characterString, the address of the NAS server, which can be an IP address, hostname, or UNC path), user (characterString, the username used for NAS authentication), and password (characterString, the password corresponding to the username). After receiving this command, the device attempts to connect to the specified NAS server using the provided credentials and returns the connection result (success or failure).
| Trait ID | Code |
|---|
| 0x501E | SetNASServers |
Parameters
NASStatus Trait (NAS Status)
The current status of NAS video storage.
| Trait ID | Code |
|---|
| 0x501F | NASStatus |
Parameters
Command Definitions
DeleteNASServer Command
Represents the operation of unbinding the NAS server.
Parameters
DeleteNASServer Command Structure
NASClearHistoryVideos Command
This Command is used to perform the "Clear NAS History Videos" operation.
Parameters
NASClearHistoryVideos Command Structure
Repeater (Wi-Fi Repeater)
Introduction
Manages Wi-Fi repeater capabilities, including keep-alive, repeater link information, network diagnostics, and connection status with the gateway.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0114 | Repeater | Wi-Fi repeater |
Trait
Command
This Function does not contain any Commands.
Data Types
KeepAliveRepeaterInfoTraitPresentValueStructure Type
This structure defines the field layout of the Present Value for the KeepAliveRepeaterInfo Trait.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Info | characterString | M | JSON string containing information such as the alive host/port, hotspot credentials (SSID, passphrase), and link type. |
Trait Definitions
KeepAliveRepeaterInfo Trait (Keep-Alive and Repeater Link Information)
Provides keep-alive and repeater link information between low-power devices (such as battery cameras) and their base station/gateway. The value is a JSON string containing details such as the alive host and port, hotspot credentials (SSID and passphrase), and link type.
| Trait ID | Code |
|---|
| 0x5069 | KeepAliveRepeaterInfo |
Parameters
SupportedHubCapability Trait (Supported Hub Capability Set)
This property reports, in bitmask form, the core functional features of the gateway as a smart home hub. Each bit represents a specific capability (such as local automation, data storage, AI support). Upper-layer applications use it to discover and adapt to advanced device features, enabling differentiated experiences.
bit 0: Supports gateway basic functions (such as creating gateway clusters)
bit 1: Has the local automation module ha_driven
bit 2: Supports the gateway local data storage function NAS
bit 3: Supports SAAS
bit 4: Supports local AI
bit 5: Supports LAN APP control
bit 6: Supports running Aqara Studio
bit 7: Supports Aqara Studio logic function blocks
bit 8 to 31: Reserved
| Trait ID | Code |
|---|
| 0x4F55 | SupportedHubCapability |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
Command Definitions
This Function does not contain any Commands.
TamperProtection (Tamper Protection)
Introduction
Provides physical security protection, detecting and responding to tampering behaviors such as illegal removal and forced disassembly, with alarm and recording linkage support.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0115 | TamperProtection | Tamper protection |
Trait
Command
This Function does not contain any Commands.
Data Types
AntiTamperAlertEventEnum8 Type
This enumeration defines the valid values of the Present Value for the AntiTamperAlertEvent Trait.
| Value | Name | Description |
|---|
| 0x01 | TamperDetected | Removal alarm |
Trait Definitions
AntiTamperAlertEvent Trait (Forced Disassembly Alarm Event)
Reports this event when the device detects that it has been illegally disassembled or removed from its installation position.
| Trait ID | Code |
|---|
| 0x50DA | AntiTamperAlertEvent |
Parameters
AntiTamperAlertEnable Trait (Forced Disassembly Alarm Enable)
Turns the anti-tamper alarm function on or off.
| Trait ID | Code |
|---|
| 0x50DB | AntiTamperAlertEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
AntiTamperAlertPushEnable Trait (Forced Disassembly Alarm Push Enable)
Turns push notifications for the forced disassembly alarm on or off.
| Trait ID | Code |
|---|
| 0x50DC | AntiTamperAlertPushEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
AntiTamperAlertRecordEnable Trait (Forced Disassembly Alarm Record Enable)
Turns automatic recording triggered by the forced disassembly alarm on or off.
| Trait ID | Code |
|---|
| 0x50DD | AntiTamperAlertRecordEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 1 | RVW | O |
| 0x0007 | Default Value | boolean | | 1 | RW | O |
Command Definitions
This Function does not contain any Commands.
SmileDetection (Smile Detection)
Introduction
Recognizes smiles in the picture and reports events, supporting enabling/disabling control of the smile recognition capability.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0116 | SmileDetection | Smile detection |
Trait
Command
This Function does not contain any Commands.
Data Types
SmileDetectionEventEnum32 Type
This enumeration defines the valid values of the Present Value for the SmileDetectionEvent Trait.
| Value | Name | Description |
|---|
| 0x01 | HappyMoment | Happy moment detected |
Trait Definitions
SmileDetectionEvent Trait (Smile Detection Event)
Represents a smile event detected by the camera. When a smile is recognized, the device reports the corresponding event value.
| Trait ID | Code |
|---|
| 0x50CD | SmileDetectionEvent |
Parameters
SmileDetectionEnable Trait (Smile Detection Enable)
Enables or disables the smile recognition capability of the camera. When enabled, the video stream is analyzed and smile events are reported.
| Trait ID | Code |
|---|
| 0x50CE | SmileDetectionEnable |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | boolean | | 0 | RVW | O |
| 0x0007 | Default Value | boolean | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
CameraAVStreamManagement (Camera Audio/Video Stream Management)
Introduction
The Camera AV Stream Management Function defines the audio/video stream management capabilities of Aqara cameras, supporting stream allocation and capability queries required for WebRTC live streaming and local SD card recording playback.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0126 | CameraAVStreamManagement | Camera audio/video stream management |
Trait
Command
Data Types
VideoCodecEnum8 Type
This enumeration defines the valid values of the video codec.
| Value | Name | Description |
|---|
| 0x00 | H264 | Advanced Video Coding (H.264) |
| 0x01 | HEVC | High Efficiency Video Coding (H.265) |
| 0x02 | VVC | Versatile Video Coding (H.266) |
| 0x03 | AV1 | AOMedia Video 1 |
AudioCodecEnum8 Type
This enumeration defines the valid values of the audio codec.
| Value | Name | Description |
|---|
| 0x00 | OPUS | Open source IETF standard codec |
| 0x01 | AAC-LC | Advanced Audio Coding-Low Complexity |
TwoWayTalkSupportTypeEnum8 Type
This enumeration defines the valid values of the two-way intercom support type.
| Value | Name | Description |
|---|
| 0x00 | NotSupported | Two-way intercom not supported |
| 0x01 | HalfDuplex | Half duplex |
| 0x02 | FullDuplex | Full duplex |
StreamUsageEnum8 Type
This enumeration defines the valid values of the audio/video stream usage.
| Value | Name | Description |
|---|
| 0x00 | Internal | Internal use, not available for WebRTC allocation |
| 0x01 | Recording | Recording use (cloud clip / Push, etc., not SD card playback) |
| 0x02 | Analysis | Analysis use |
| 0x03 | LiveView | Live streaming use |
| 0xF0 | LocalPlayback | Playback of the device's unique local SD card recording file |
Note: 0x04-0xEF is reserved for future Matter standard extensions. LocalPlayback indicates the playback encoding channel usage; the device has only one local recording file, and the App does not need to specify the source clip.
StatusCodeEnum8 Type
This enumeration defines the valid values of the Command response status codes of the CameraAVStreamManagement Function.
| Value | Name | Description |
|---|
| 0x00 | SUCCESS | Success |
| 0x01 | NOT_FOUND | Not found |
| 0x02 | INVALID_IN_STATE | Invalid state |
| 0x03 | INVALID_COMMAND | Invalid command |
| 0x04 | DYNAMIC_CONSTRAINT_ERROR | Dynamic constraint error |
| 0x05 | RESOURCE_EXHAUSTED | Resource exhausted |
| 0x06 | ALREADY_EXISTS | Already exists |
VideoResolutionStructure Type
This structure defines the field layout of the video resolution.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Width | uint16 | M | Width (pixels). |
| 1 | Height | uint16 | M | Height (pixels). |
VideoSensorParamsStructure Type
This structure defines the field layout of the video sensor parameters.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | SensorWidth | uint16 | M | Sensor width (pixels). |
| 1 | SensorHeight | uint16 | M | Sensor height (pixels). |
| 2 | MaxFPS | uint16 | M | Maximum frame rate (fps). |
RateDistortionTradeOffPointsStructure Type
This structure defines the field layout of the rate-distortion trade-off reference points.
AudioCapabilitiesStructure Type
This structure defines the field layout of the microphone capabilities.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | MaxNumberOfChannels | uint8 | M | Maximum number of channels. |
| 1 | SupportedCodecs | list[AudioCodecEnum8] | M | Supported audio codecs. |
| 2 | SupportedSampleRates | list[uint32] | M | Sample rate (Hz). |
| 3 | SupportedBitDepths | list[uint8] | M | Bit depth. |
VideoStreamStructure Type
This structure defines the field layout of an allocated video stream.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | VideoStreamID | uint16 | M | Video stream ID; referenced by WebRTC VideoStreams. |
| 1 | StreamUsage | StreamUsageEnum8 | M | Stream usage. |
| 2 | VideoCodec | VideoCodecEnum8 | M | Codec. |
| 3 | MinFrameRate | uint16 | M | Minimum frame rate (fps). |
| 4 | MaxFrameRate | uint16 | M | Maximum frame rate (fps). |
| 5 | MinResolution | VideoResolutionStructure | M | Minimum resolution. |
| 6 | MaxResolution | VideoResolutionStructure | M | Maximum resolution. |
| 7 | MinBitRate | uint32 | M | Minimum bit rate (bps). |
| 8 | MaxBitRate | uint32 | M | Maximum bit rate (bps). |
| 9 | KeyFrameInterval | uint16 | M | Key frame interval (ms). |
| 10 | ReferenceCount | uint8 | M | Current reference count; cannot be deallocated when >0. |
AudioStreamStructure Type
This structure defines the field layout of an allocated audio stream.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | AudioStreamID | uint16 | M | Audio stream ID; referenced by WebRTC AudioStreams. |
| 1 | StreamUsage | StreamUsageEnum8 | M | Stream usage. |
| 2 | AudioCodec | AudioCodecEnum8 | M | Codec. |
| 3 | ChannelCount | uint8 | M | Number of channels. |
| 4 | SampleRate | uint32 | M | Sample rate (Hz). |
| 5 | BitRate | uint32 | M | Bit rate (bps). |
| 6 | BitDepth | uint8 | M | 8/16/24/32. |
| 7 | ReferenceCount | uint8 | M | Current reference count. |
CAVSMVideoStreamAllocate Command Structure Type
Request parameter structure of the CAVSMVideoStreamAllocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | StreamUsage | StreamUsageEnum8 | M | Stream usage (Recording, Analysis, LiveView, LocalPlayback). |
| 1 | VideoCodec | VideoCodecEnum8 | M | Video codec. |
| 2 | MinFrameRate | uint16 | M | Minimum frame rate (fps). |
| 3 | MaxFrameRate | uint16 | M | Maximum frame rate (fps). |
| 4 | MinResolution | VideoResolutionStructure | M | Minimum resolution. |
| 5 | MaxResolution | VideoResolutionStructure | M | Maximum resolution. |
| 6 | MinBitRate | uint32 | M | Minimum bit rate (bps). |
| 7 | MaxBitRate | uint32 | M | Maximum bit rate (bps). |
| 8 | KeyFrameInterval | uint16 | M | Key frame interval (ms). |
CAVSMVideoStreamAllocateResponse Command Structure Type
Response parameter structure of the CAVSMVideoStreamAllocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | StatusCodeEnum8 | M | Processing status. |
| 1 | VideoStreamID | uint16 | M | Allocated video stream ID. |
CAVSMVideoStreamDeallocate Command Structure Type
Request parameter structure of the CAVSMVideoStreamDeallocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | VideoStreamID | uint16 | M | Video stream ID to be released. |
CAVSMVideoStreamDeallocateResponse Command Structure Type
Response parameter structure of the CAVSMVideoStreamDeallocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | StatusCodeEnum8 | M | Processing status. |
CAVSMAudioStreamAllocate Command Structure Type
Request parameter structure of the CAVSMAudioStreamAllocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | StreamUsage | StreamUsageEnum8 | M | Stream usage (Recording, Analysis, LiveView, LocalPlayback). |
| 1 | AudioCodec | AudioCodecEnum8 | M | Audio codec. |
| 2 | ChannelCount | uint8 | M | Number of channels. |
| 3 | SampleRate | uint32 | M | Sample rate (Hz). |
| 4 | BitRate | uint32 | M | Bit rate (bps). |
| 5 | BitDepth | uint8 | M | Bit depth (8/16/24/32). |
CAVSMAudioStreamAllocateResponse Command Structure Type
Response parameter structure of the CAVSMAudioStreamAllocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | StatusCodeEnum8 | M | Processing status. |
| 1 | AudioStreamID | uint16 | M | Allocated audio stream ID. |
CAVSMAudioStreamDeallocate Command Structure Type
Request parameter structure of the CAVSMAudioStreamDeallocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | AudioStreamID | uint16 | M | Audio stream ID to be released. |
CAVSMAudioStreamDeallocateResponse Command Structure Type
Response parameter structure of the CAVSMAudioStreamDeallocate Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | StatusCodeEnum8 | M | Processing status. |
CAVSMSetStreamPriorities Command Structure Type
Request parameter structure of the CAVSMSetStreamPriorities Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | StreamPriorities | list[StreamUsageEnum8] | M | Priority list in descending order; contains only values from CAVSMSupportedStreamUsages. |
CAVSMSetStreamPrioritiesResponse Command Structure Type
Response parameter structure of the CAVSMSetStreamPriorities Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | StatusCodeEnum8 | M | Processing status. |
Trait Definitions
CAVSMMaxConcurrentEncoders Trait
Maximum number of concurrent hardware video encoders.
| Trait ID | Code |
|---|
| 0x511D | CAVSMMaxConcurrentEncoders |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint8 | | 4 | RV | M |
| 0x0002 | Maximum Value | uint8 | | 255 | R | O |
| 0x0003 | Minimum Value | uint8 | | 1 | R | O |
CAVSMMaxEncodedPixelRate Trait
Maximum encoded pixel rate (pixels/second).
| Trait ID | Code |
|---|
| 0x511E | CAVSMMaxEncodedPixelRate |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 60 | RV | M |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 1 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
CAVSMVideoSensorParams Trait
Sensor size and frame rate capabilities.
| Trait ID | Code |
|---|
| 0x511F | CAVSMVideoSensorParams |
Parameters
CAVSMRateDistortionTradeOffPoints Trait
Minimum bit rate reference points for each codec/resolution.
| Trait ID | Code |
|---|
| 0x5120 | CAVSMRateDistortionTradeOffPoints |
Parameters
CAVSMMicrophoneCapabilities Trait
Microphone capabilities.
| Trait ID | Code |
|---|
| 0x5121 | CAVSMMicrophoneCapabilities |
Parameters
CAVSMTwoWayTalkSupport Trait
Two-way intercom mode.
| Trait ID | Code |
|---|
| 0x5122 | CAVSMTwoWayTalkSupport |
Parameters
CAVSMMaxNetworkBandwidth Trait
Maximum total network bandwidth for media streams (bps).
| Trait ID | Code |
|---|
| 0x5123 | CAVSMMaxNetworkBandwidth |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 100 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 4294967295 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
CAVSMSupportedStreamUsages Trait
The list of Stream Usages supported by the device.
| Trait ID | Code |
|---|
| 0x5125 | CAVSMSupportedStreamUsages |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[StreamUsageEnum8] | | | RV | M |
CAVSMAllocatedVideoStreams Trait
List of allocated video streams.
| Trait ID | Code |
|---|
| 0x5126 | CAVSMAllocatedVideoStreams |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[VideoStreamStructure] | | | RV | O |
CAVSMAllocatedAudioStreams Trait
List of allocated audio streams.
| Trait ID | Code |
|---|
| 0x5127 | CAVSMAllocatedAudioStreams |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[AudioStreamStructure] | | | RV | O |
CAVSMStreamUsagePriorities Trait
Stream Usage priorities (Index 0 is the highest).
| Trait ID | Code |
|---|
| 0x5128 | CAVSMStreamUsagePriorities |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[StreamUsageEnum8] | | | RV | M |
Command Definitions
CAVSMVideoStreamAllocate Command
Allocates a video encoding stream. On success, the device SHALL Report the updated CAVSMAllocatedVideoStreams.
Parameters
CAVSMVideoStreamAllocate Command Structure
Response
CAVSMVideoStreamAllocateResponse Command Structure
After receiving this Command, SHALL validate the request parameters and process them according to the following rules.
Parameter Validation
| Parameter | Validation Rule | Failure Status |
|---|
| StreamUsage | SHALL be Recording, Analysis, LiveView, or LocalPlayback; SHALL exist in CAVSMStreamUsagePriorities and CAVSMSupportedStreamUsages | INVALID_IN_STATE |
| VideoCodec | SHALL be a codec supported by the device | DYNAMIC_CONSTRAINT_ERROR |
| MinFrameRate | SHALL satisfy 1 <= MinFrameRate <= MaxFrameRate | DYNAMIC_CONSTRAINT_ERROR |
| MaxFrameRate | SHALL >= 1; for LiveView/Recording/Analysis SHALL <= CAVSMVideoSensorParams.MaxFPS; for LocalPlayback MAY validate against the frame rate capability of the local recording file | DYNAMIC_CONSTRAINT_ERROR |
| MinResolution | Width and Height SHALL >= 1; SHALL <= MaxResolution; SHALL not exceed sensor capabilities | DYNAMIC_CONSTRAINT_ERROR |
| MaxResolution | Width and Height SHALL >= 1; SHALL <= the width/height of CAVSMVideoSensorParams | DYNAMIC_CONSTRAINT_ERROR |
| MinBitRate | SHALL satisfy 1 <= MinBitRate <= MaxBitRate | DYNAMIC_CONSTRAINT_ERROR |
| MaxBitRate | SHALL >= 1; MAY reference the minimum bit rate of the corresponding Codec/Resolution in CAVSMRateDistortionTradeOffPoints | DYNAMIC_CONSTRAINT_ERROR |
| KeyFrameInterval | SHALL satisfy 0 <= KeyFrameInterval <= 65500 | DYNAMIC_CONSTRAINT_ERROR |
StreamUsage not in CAVSMStreamUsagePriorities -> return INVALID_IN_STATE.- Any parameter exceeding the table above or device capabilities -> return
DYNAMIC_CONSTRAINT_ERROR.
- An exactly matching stream already exists in
CAVSMAllocatedVideoStreams -> return the existing VideoStreamID (SUCCESS).
- Insufficient resources such as encoder count, encoded pixel rate, or network bandwidth (refer to
CAVSMMaxConcurrentEncoders, CAVSMMaxEncodedPixelRate, CAVSMMaxNetworkBandwidth) -> return RESOURCE_EXHAUSTED.
- Validation passed -> allocate a new
VideoStreamID, append it to CAVSMAllocatedVideoStreams, and Report.
CAVSMVideoStreamDeallocate Command
Releases a video encoding stream. On success, the device SHALL Report the updated CAVSMAllocatedVideoStreams.
Parameters
CAVSMVideoStreamDeallocate Command Structure
Response
CAVSMVideoStreamDeallocateResponse Command Structure
After receiving this Command, SHALL validate the VideoStreamID and process it according to the following rules.
Parameter Validation
| Parameter | Validation Rule | Failure Status |
|---|
| VideoStreamID | SHALL exist in CAVSMAllocatedVideoStreams | NOT_FOUND |
| VideoStreamID | The ReferenceCount of the corresponding stream SHALL be 0 | INVALID_IN_STATE |
| VideoStreamID | The StreamUsage of the corresponding stream SHALL not be Internal | DYNAMIC_CONSTRAINT_ERROR |
VideoStreamID does not exist -> return NOT_FOUND.ReferenceCount > 0 (still referenced by WebRTC sessions, etc.) -> return INVALID_IN_STATE.StreamUsage=Internal -> return DYNAMIC_CONSTRAINT_ERROR.- Validation passed -> release the video stream, remove it from
CAVSMAllocatedVideoStreams, and Report.
CAVSMAudioStreamAllocate Command
Allocates an audio encoding stream. On success, the device SHALL Report the updated CAVSMAllocatedAudioStreams.
Parameters
CAVSMAudioStreamAllocate Command Structure
Response
CAVSMAudioStreamAllocateResponse Command Structure
After receiving this Command, SHALL validate the request parameters and process them according to the following rules.
Parameter Validation
| Parameter | Validation Rule | Failure Status |
|---|
| StreamUsage | SHALL be Recording, Analysis, LiveView, or LocalPlayback; SHALL exist in CAVSMStreamUsagePriorities and CAVSMSupportedStreamUsages | INVALID_IN_STATE |
| AudioCodec | For LiveView/Recording/Analysis SHALL be a value in CAVSMMicrophoneCapabilities.SupportedCodecs; for LocalPlayback MAY validate against the encoding of the local recording file | DYNAMIC_CONSTRAINT_ERROR |
| ChannelCount | SHALL satisfy 1 <= ChannelCount <= 8, and <= CAVSMMicrophoneCapabilities.MaxNumberOfChannels | DYNAMIC_CONSTRAINT_ERROR |
| SampleRate | SHALL >= 1 and belong to CAVSMMicrophoneCapabilities.SupportedSampleRates | DYNAMIC_CONSTRAINT_ERROR |
| BitRate | SHALL >= 1 | DYNAMIC_CONSTRAINT_ERROR |
| BitDepth | SHALL be 8, 16, 24, or 32, and belong to CAVSMMicrophoneCapabilities.SupportedBitDepths | DYNAMIC_CONSTRAINT_ERROR |
StreamUsage not in CAVSMStreamUsagePriorities -> return INVALID_IN_STATE.- Any audio parameter outside the supported range of
CAVSMMicrophoneCapabilities -> return DYNAMIC_CONSTRAINT_ERROR.
- An exactly matching stream already exists in
CAVSMAllocatedAudioStreams -> return the existing AudioStreamID (SUCCESS).
- Insufficient resources -> return
RESOURCE_EXHAUSTED.
- Validation passed -> allocate a new
AudioStreamID, append it to CAVSMAllocatedAudioStreams, and Report.
CAVSMAudioStreamDeallocate Command
Releases an audio encoding stream. On success, the device SHALL Report the updated CAVSMAllocatedAudioStreams.
Parameters
CAVSMAudioStreamDeallocate Command Structure
Response
CAVSMAudioStreamDeallocateResponse Command Structure
After receiving this Command, SHALL validate the AudioStreamID and process it according to the following rules.
Parameter Validation
| Parameter | Validation Rule | Failure Status |
|---|
| AudioStreamID | SHALL exist in CAVSMAllocatedAudioStreams | NOT_FOUND |
| AudioStreamID | The ReferenceCount of the corresponding stream SHALL be 0 | INVALID_IN_STATE |
| AudioStreamID | The StreamUsage of the corresponding stream SHALL not be Internal | DYNAMIC_CONSTRAINT_ERROR |
AudioStreamID does not exist -> return NOT_FOUND.ReferenceCount > 0 -> return INVALID_IN_STATE.StreamUsage=Internal -> return DYNAMIC_CONSTRAINT_ERROR.- Validation passed -> release the audio stream, remove it from
CAVSMAllocatedAudioStreams, and Report.
CAVSMSetStreamPriorities Command
Sets the Stream Usage priorities. On success, the device SHALL Report CAVSMStreamUsagePriorities.
Parameters
CAVSMSetStreamPriorities Command Structure
Response
CAVSMSetStreamPrioritiesResponse Command Structure
After receiving this Command, SHALL validate the StreamPriorities and process them according to the following rules.
Parameter Validation
| Parameter | Validation Rule | Failure Status |
|---|
| StreamPriorities | CAVSMAllocatedVideoStreams and CAVSMAllocatedAudioStreams SHALL both be empty | INVALID_IN_STATE |
| StreamPriorities | Every value in the list SHALL exist in CAVSMSupportedStreamUsages | DYNAMIC_CONSTRAINT_ERROR |
| StreamPriorities | The list SHALL have no duplicates; Index 0 is the highest priority | ALREADY_EXISTS |
- Any allocated audio/video stream exists -> return
INVALID_IN_STATE.
- The list contains values outside
CAVSMSupportedStreamUsages -> return DYNAMIC_CONSTRAINT_ERROR.
- The list contains duplicate
StreamUsage -> return ALREADY_EXISTS.
- Validation passed -> update
CAVSMStreamUsagePriorities and Report.
WebRTC (WebRTC Transport)
Introduction
The WebRTC Transport Function defines the WebRTC signaling interface between the Client and the Server, covering live streaming (LiveView) and local SD card recording playback (LocalPlayback) sessions. The Client submits signaling to the Server via Aqara Spec Command, and the Server returns processing results and signaling events via Response and Report; both parties transmit bidirectional media over WebRTC (P2P/TURN). Local playback assumes the Server has only one local recording file, which can be played back directly without specifying a source clip ID.
WebRTC and CAVSM Dependencies
WebRTC sessions depend on CameraAVStreamManagement to provide allocated audio/video streams. Before initiating WebRTCProvideOffer to create a new session or WebRTCSolicitOffer, the Client SHALL obtain the VideoStreamID and AudioStreamID required for this session; WebRTC signaling negotiation does not replace stream allocation.
- The Client SHALL query CAVSMMicrophoneCapabilities, CAVSMVideoSensorParams, CAVSMRateDistortionTradeOffPoints, CAVSMAllocatedAudioStreams and CAVSMAllocatedVideoStreams to obtain the audio/video capabilities and the list of allocated streams.
- The Client SHALL determine the audio/video stream parameters based on the above capabilities and the requirements of this session. Audio parameters include
AudioCodec, ChannelCount, SampleRate, BitDepth, and BitRate; the codec, channel count, sample rate, and bit depth SHALL satisfy the microphone capability constraints. Video parameters include VideoCodec, frame rate, resolution range, bit rate range, and key frame interval; the resolution and frame rate SHALL satisfy the constraints of CAVSMVideoSensorParams, the VideoCodec and resolution tier SHALL be selected according to the Codec and Resolution of CAVSMRateDistortionTradeOffPoints, and the bit rate MAY reference the MinBitRate of the corresponding tier. For fixed resolution, both MinResolution and MaxResolution are set to the selected tier; when multi-tier switching is required, they are set to the lower and upper bounds of the required tier range, respectively.
- The Client SHALL determine, based on the
StreamUsage of this session and the determined audio/video parameters, whether the list already contains a reusable audio stream and video stream; if a matching stream already exists, reuse its ID and skip the corresponding Allocate step.
- When no matching video stream exists, the Client SHALL call CAVSMVideoStreamAllocate with the determined video parameters; when no matching audio stream exists, the Client SHALL call CAVSMAudioStreamAllocate with the determined audio parameters.
- The Client SHALL wait for the allocation of all required streams to succeed and obtain the stream IDs from the responses, then initiate the WebRTC session; if any required stream allocation fails, it SHALL NOT continue connection establishment using the result of that failed allocation.
- The Client SHALL fill the obtained video stream IDs into
VideoStreams and the audio stream IDs into AudioStreams. The referenced streams SHALL have been allocated on the Server, and their StreamUsage SHALL be consistent with this session; when only one medium is used, only the stream IDs of the corresponding type need to be prepared and carried.
The following pre-interactions apply to both LiveView and LocalPlayback; when only one medium is used, skip the capability query, parameter selection, list query, and matching and allocation steps for the other medium.
Interaction Flow
Interaction Roles
This section uniformly uses Client and Server to describe interactions without distinguishing specific access topologies.
- Client: the side that requests and receives media and initiates control, collectively representing the App and the cloud.
- Server: the side that provides media and handles requests, collectively representing the gateway and the camera.
The Client and Server complete signaling interactions through Aqara Spec Command / Response / Report and transmit bidirectional media over WebRTC (P2P/TURN). Internal forwarding and protocol conversion within each side are not expanded in the flow diagrams.
WebRTCProvideOffer Flow
The Client first completes the CameraAVStreamManagement pre-interaction, then generates and submits the SDP Offer; the Server returns the Answer.
WebRTCSolicitOffer Flow
The Client first completes the CameraAVStreamManagement pre-interaction. This flow applies to scenarios such as wake-up from standby; the Server delivers the Offer deferred, and the Client then submits the Answer.
Resolution Switching
The Client SHALL use the WebRTCSetResolution Command to switch one VideoStreamID bound to this session to the target resolution.
Switching Conditions
VideoStreamID SHALL be a StreamUsage=LiveView stream bound to this session, and the MinResolution of that stream SHALL be less than MaxResolution.- The target
Resolution SHALL fall between the MinResolution and MaxResolution of that stream, and SHALL be one of the tiers in CAVSMRateDistortionTradeOffPoints.
- Playback sessions with
StreamUsage=LocalPlayback do not support resolution switching.
Switching Flow and Result
This flow assumes a WebRTC session has been established with a video stream that supports resolution switching bound, and applies to both connection methods, the WebRTCProvideOffer Flow and the WebRTCSolicitOffer Flow.
Resolution switching:
- The Client sends
WebRTCSetResolution, carrying VideoStreamID and the target Resolution.
- The Server validates the request per the WebRTCSetResolution Command definition and returns a success or failure response.
- After returning
SUCCESS, the Server SHALL switch the target stream to the specified resolution, keeping VideoStreamID and SSRC unchanged; the new resolution starts from a new IDR, and the IDR carries the new SPS. After the new-tier IDR is sent, the current resolutions being sent for each video stream of this session SHALL be reported via WebRTCStreamResolution, and the target stream SHALL be at the specified resolution.
- When the request fails, the Server SHALL return the corresponding non-
SUCCESS status and keep the original resolution; it SHALL NOT return SUCCESS and then keep the original tier on the grounds that the target-tier IDR was not observed.
If the target is the current resolution and no switching is in progress, the Server SHALL return SUCCESS and immediately report WebRTCStreamResolution once.
Each WebRTCStreamResolution report SHALL carry the complete video stream resolution list of this session, and the other unaffected streams keep their original values. The Client SHALL confirm the actual resolution based on the reported values.
Local SD Card Recording Playback
This section only defines the establishment of playback sessions. The Server maintains only one local recording file; the Client initiates a LocalPlayback session to play back that file, without carrying a source clip identifier. Playback control and recording queries are in Playback.
Playback Session Establishment Flow
Note: With StreamUsage=LocalPlayback, MetadataEnabled=true SHALL be set so that the DataChannel can be opened on this PeerConnection. Resolution, playback control, and recording queries within the session go through InvokeCommand on aqara.control; recording file bytes go through the file transfer business interaction protocol on aqara.download. Definitions of playback control, recording index, and recording file download are in Playback. Carriage is via DataChannel.
Function Identification
Processing Logic
| Function ID | Code | Name |
|---|
| 0x001D | WebRTC | WebRTC transport |
Trait
The Server uses the following Traits for reporting.
Command
The Client uses the following Commands for requests.
Data Types
WebRTCStatusCodeEnum8 Type
This enumeration defines the valid response status code values for the Commands of the WebRTC Function; it is independent of the status code definitions of other Functions.
| Value | Name | Description |
|---|
| 0x00 | SUCCESS | Success |
| 0x01 | NOT_FOUND | Not found |
| 0x02 | INVALID_IN_STATE | Invalid state |
| 0x03 | INVALID_COMMAND | Invalid command |
| 0x04 | DYNAMIC_CONSTRAINT_ERROR | Dynamic constraint error |
| 0x05 | RESOURCE_EXHAUSTED | Resources exhausted |
| 0x06 | ALREADY_EXISTS | Already exists |
SignalingEventTypeEnum8 Type
This enumeration defines the valid values of the signaling event types in the WebRTCSignalingEvent Trait.
| Value | Name | Description |
|---|
| 0x00 | Offer | After WebRTCSolicitOffer (especially DeferredOffer) |
| 0x01 | Answer | After WebRTCProvideOffer |
| 0x02 | ICE | Trickle ICE |
| 0x03 | End | Camera ends the session |
WebRTCEndReasonEnum8 Type
This enumeration defines the valid values of the WebRTC session end reasons.
| Value | Name | Description |
|---|
| 0x00 | ICEFailed | Failed to establish media connection |
| 0x01 | ICETimeout | ICE timeout |
| 0x02 | UserHangup | User hang-up |
| 0x03 | UserBusy | Remote busy |
| 0x04 | Replaced | Replaced |
| 0x05 | NoUserMedia | No local media device |
| 0x06 | InviteTimeout | Offer/Answer timeout |
| 0x07 | AnsweredElsewhere | Answered by another device |
| 0x08 | OutOfResources | Insufficient resources |
| 0x09 | MediaTimeout | Media timeout |
| 0x0A | LowPower | Low battery |
| 0x0B | PrivacyMode | Privacy mode |
| 0x0C | UnknownReason | Unknown |
This enumeration defines the valid values of the actual media transport methods.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown or not determined |
| 0x01 | P2P | End-to-end direct connection |
| 0x02 | TURN | Via TURN relay |
SessionStatusEventEnum8 Type
This enumeration defines the valid values of the status event types in the WebRTCSessionStatus Trait.
| Value | Name | Description |
|---|
| 0x00 | MediaConnected | Media channel established; reports the actual streaming method |
| 0x01 | SessionEnded | Session ended; reports streaming statistics and disconnect reason |
ICEServerStructure Type
This structure defines the field layout of the ICE server configuration.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | URLs | list[characterString] | M | List of stun:/turn:/stuns:/turns: URLs. |
| 1 | Username | characterString | O | TURN username. |
| 2 | Credential | characterString | O | TURN credential. |
| 3 | CAID | uint16 | O | TLS root certificate ID for turns/stuns. |
ICECandidateStructure Type
This structure defines the field layout of the ICE candidate.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Candidate | characterString | M | RFC 8839 candidate-attribute. |
| 1 | SDPMid | characterString | M | sdpMid. |
| 2 | SDPMLineIndex | uint16 | M | m= line index. |
ExtensionOptionsStructure Type
Extension options for configuring the timeout values of each WebRTC connection establishment phase and other extension parameters. The Struct as a whole and each field are optional; when a field is not carried, the gateway SHALL use implementation defaults. Options not supported by the downstream Matter WebRTC protocol are interpreted and executed by the gateway on the Aqara Spec side.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | ICECollectionTimeout | uint32 | O | ICE candidate collection timeout (ms). |
| 1 | TLSConnectTimeout | uint32 | O | TLS connection timeout (ms); applicable to TURN/TURNS. |
| 2 | InviteTimeout | uint32 | O | Offer/Answer signaling exchange timeout (ms). |
| 3 | DeferredOfferTimeout | uint32 | O | Deferred offer wait timeout (ms); applicable to WebRTCSolicitOffer. |
| 4 | ICENegotiationTimeout | uint32 | O | ICE connectivity check timeout (ms). |
| 5 | MediaTimeout | uint32 | O | Media channel establishment timeout (ms). |
SessionStructure Type
This structure defines the field layout of the WebRTC session.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | SessionId | uint16 | M | Corresponding WebRTC SessionID. |
| 1 | StreamUsage | StreamUsageEnum8 | M | Stream usage; definition see CameraAVStreamManagement. |
| 2 | MetadataEnabled | boolean | M | Metadata DataChannel switch. |
| 3 | VideoStreams | list[uint16] | M | List of VideoStreamIDs. |
| 4 | AudioStreams | list[uint16] | M | List of AudioStreamIDs. |
SignalingEventStructure Type
This structure defines the field layout of the signaling event.
SessionStatusStructure Type
Session status report structure. The gateway Reports based on the route selection result of the WebRTC media stack and the session lifecycle; when the downstream Matter protocol has no corresponding capability, the gateway aggregates and reports it.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | SessionId | uint16 | M | WebRTC SessionID. |
| 1 | EventType | SessionStatusEventEnum8 | M | Status event type. |
| 2 | MediaTransport | MediaTransportEnum8 | M | Actual streaming method (P2P / TURN). |
| 3 | DurationMs | uint32 | O | Streaming duration (ms). |
| 4 | VideoFrameCount | uint32 | O | Total number of received video frames. |
| 5 | DisconnectReason | WebRTCEndReasonEnum8 | O | Disconnect reason. |
| 6 | SignalingDurationMs | uint32 | O | Signaling interaction duration (ms); from session initiation to media channel establishment. |
Note: When EventType=MediaConnected, SHALL carry MediaTransport and SignalingDurationMs; when EventType=SessionEnded, SHALL carry DurationMs, MediaTransport, VideoFrameCount, and DisconnectReason, and MAY carry SignalingDurationMs.
WebRTCSolicitOffer Command Structure Type
Request parameter structure of the WebRTCSolicitOffer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | InitiatorData | characterString | O | Initiator data; used to correlate requests and replies before the SessionId is generated; maximum 32 bytes. |
| 1 | StreamUsage | StreamUsageEnum8 | M | Stream usage. |
| 2 | ICEServers | list[ICEServerStructure] | O | ICE server list (up to 10). |
| 3 | ICETransportPolicy | characterString | O | ICE policy (all or relay). |
| 4 | MetadataEnabled | boolean | O | Metadata DataChannel switch. |
| 5 | VideoStreams | list[uint16] | O | List of VideoStreamIDs (1 to 16); SHALL be carried when video is used and SHALL reference the streams allocated for this StreamUsage, see CameraAVStreamManagement pre-interaction. |
| 6 | AudioStreams | list[uint16] | O | List of AudioStreamIDs (1 to 16); SHALL be carried when audio is used and SHALL reference the streams allocated for this StreamUsage, see CameraAVStreamManagement pre-interaction. |
| 7 | ExtensionOptions | ExtensionOptionsStructure | O | Extension options. |
WebRTCSolicitOfferResponse Command Structure Type
Response parameter structure of the WebRTCSolicitOffer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | WebRTCStatusCodeEnum8 | M | Processing status; definition see WebRTCStatusCodeEnum8. |
| 1 | InitiatorData | characterString | O | Echoes the InitiatorData from the request. |
| 2 | SessionId | uint16 | O | SHALL be carried with the allocated session ID when Status=SUCCESS; SHALL be omitted on failure. |
| 3 | DeferredOffer | boolean | O | Whether the Offer is delivered with a delay; SHALL be carried when Status=SUCCESS; SHALL be omitted on failure. |
WebRTCProvideOffer Command Structure Type
Request parameter structure of the WebRTCProvideOffer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | InitiatorData | characterString | O | Initiator data; used to correlate requests and replies before the SessionId is generated; maximum 32 bytes. |
| 1 | SessionId | uint16 | O | Session ID; absent means a new session, present means re-offer. |
| 2 | SDP | characterString | M | SDP Offer. |
| 3 | StreamUsage | StreamUsageEnum8 | O | Stream usage; required when creating a new session. |
| 4 | ICEServers | list[ICEServerStructure] | O | ICE server list (up to 10). |
| 5 | ICETransportPolicy | characterString | O | ICE policy. |
| 6 | MetadataEnabled | boolean | O | Metadata DataChannel switch. |
| 7 | VideoStreams | list[uint16] | O | List of VideoStreamIDs (1 to 16); SHALL be carried when video is used and SHALL reference the streams allocated for this StreamUsage, see CameraAVStreamManagement pre-interaction. |
| 8 | AudioStreams | list[uint16] | O | List of AudioStreamIDs (1 to 16); SHALL be carried when audio is used and SHALL reference the streams allocated for this StreamUsage, see CameraAVStreamManagement pre-interaction. |
| 9 | ExtensionOptions | ExtensionOptionsStructure | O | Extension options. |
WebRTCProvideOfferResponse Command Structure Type
Response parameter structure of the WebRTCProvideOffer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | WebRTCStatusCodeEnum8 | M | Processing status. |
| 1 | InitiatorData | characterString | O | Echoes the InitiatorData from the request. |
| 2 | SessionId | uint16 | O | SHALL be carried with the new or updated session ID when Status=SUCCESS; SHALL be omitted on failure. |
WebRTCProvideAnswer Command Structure Type
Request parameter structure of the WebRTCProvideAnswer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | SessionId | uint16 | M | Session ID. |
| 1 | SDP | characterString | M | SDP Answer. |
WebRTCProvideAnswerResponse Command Structure Type
Response parameter structure of the WebRTCProvideAnswer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | WebRTCStatusCodeEnum8 | M | Processing status. |
| 1 | SessionId | uint16 | M | Session ID. |
WebRTCProvideICECandidates Command Structure Type
Request parameter structure of the WebRTCProvideICECandidates Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | SessionId | uint16 | M | Session ID. |
| 1 | ICECandidates | list[ICECandidateStructure] | M | List of local ICE candidates. |
WebRTCProvideICECandidatesResponse Command Structure Type
Response parameter structure of the WebRTCProvideICECandidates Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | Status | WebRTCStatusCodeEnum8 | M | Processing status. |
| 1 | SessionId | uint16 | M | Session ID. |
WebRTCEndSession Command Structure Type
Request parameter structure of the WebRTCEndSession Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | SessionId | uint16 | M | Session ID. |
| 1 | Reason | WebRTCEndReasonEnum8 | M | End reason. |
WebRTCTalk Command Structure Type
The request structure of WebRTCTalk.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Enabled | boolean | M | Turn talk on or off. true opens talk, false closes talk |
| 1 | SessionId | uint16 | O | Carried over COIP to specify the session to open or close talk on. Omitted on DataChannel; the session is determined by that channel |
WebRTCTalkResponse Command Structure Type
The response structure of WebRTCTalk.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Status | WebRTCStatusCodeEnum8 | M | Command execution result; see the command definition for values |
WebRTCSetResolution Command Structure Type
The request structure of WebRTCSetResolution.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | VideoStreamID | uint16 | M | The video stream ID to switch |
| 1 | Resolution | VideoResolutionStructure | M | The target resolution |
| 2 | SessionId | uint16 | O | Carried over COIP to specify the session. Omitted on DataChannel; the session is determined by that channel |
WebRTCSetResolutionResponse Command Structure Type
The response structure of WebRTCSetResolution.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | Status | WebRTCStatusCodeEnum8 | M | Command execution result; see the command definition for values |
StreamResolutionStructure Type
One record corresponds to one session; as many entries as VideoStreamID streams bound to the session appear in the list.
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | SessionId | uint16 | M | WebRTC session ID, see SessionStructure. When the same VideoStreamID is referenced by multiple sessions, each session reports it separately |
| 1 | VideoStreams | list[VideoStreamResolutionStructure] | M | The resolution currently being sent on each stream of this session, in the same order as the VideoStreams in WebRTCProvideOffer |
VideoStreamResolutionStructure Type
| Struct Member Index | Field Name | Type | Mandatory | Description |
|---|
| 0 | VideoStreamID | uint16 | M | Video stream ID |
| 1 | Resolution | VideoResolutionStructure | M | The resolution currently being sent on this stream |
Trait Definitions
WebRTCCurrentSessions Trait
List of currently active WebRTC sessions.
| Trait ID | Code |
|---|
| 0x5129 | WebRTCCurrentSessions |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[SessionStructure] | | | RV | M |
WebRTCSignalingEvent Trait
Signaling events generated by the camera.
| Trait ID | Code |
|---|
| 0x512A | WebRTCSignalingEvent |
Parameters
WebRTCSessionStatus Trait
Session status and streaming statistics.
| Trait ID | Code |
|---|
| 0x512B | WebRTCSessionStatus |
Parameters
The gateway SHALL Report this Trait at the following moments:
- Media channel established and route selection completed (
EventType=MediaConnected): report SessionId, the actual MediaTransport (P2P or TURN), and SignalingDurationMs.
- Session ended (
EventType=SessionEnded): report DurationMs, MediaTransport, VideoFrameCount, and DisconnectReason.
WebRTCStreamResolution Trait
Reports the resolution currently being sent on each video stream of each session.
| Trait ID | Code |
|---|
| 0x5244 | WebRTCStreamResolution |
Parameters
Reporting timing: each report carries the whole list of that session, not only the stream that changed.
- The IDR of a new resolution of one stream has been sent -> that stream appears in the new list with the new tier.
- A request failed -> keep the original resolution; do not trigger a resolution change report because of that failed request.
- The target is already the current resolution and there is no switch in progress -> return
SUCCESS and report the current resolution immediately.
- Other unaffected streams in the same session appear in the same list with their original values.
Path: the Server SHALL send it on the session's aqara.control with ProtocolID 0x00, OpCode 0x018A (UnconfirmedCOVNotificationMultiple); the Trait's Present Value SHALL be updated synchronously, and it MAY additionally be reported through the Report path.
Command Definitions
WebRTCSolicitOffer Command
The Client SHALL first complete the CameraAVStreamManagement pre-interaction, and then request the Server to initiate a WebRTC Offer. When DeferredOffer=true, the subsequent Offer is delivered via the Report WebRTCSignalingEvent, and the App then sends WebRTCProvideAnswer.
Parameters
WebRTCSolicitOffer Command Structure
Response
WebRTCSolicitOfferResponse Command Structure
WebRTCProvideOffer Command
Submits an SDP Offer to establish or update a WebRTC session. Before creating a new session, the Client SHALL complete the CameraAVStreamManagement pre-interaction. On success, the camera sends an Answer through Matter, and the gateway Reports WebRTCSignalingEvent(Answer).
Parameters
WebRTCProvideOffer Command Structure
Response
WebRTCProvideOfferResponse Command Structure
When StreamUsage=LocalPlayback:
- SHALL set
MetadataEnabled=true.
VideoStreams / AudioStreams SHALL be CAVSM allocated stream IDs with StreamUsage=LocalPlayback.- The Server SHALL have a readable local recording file; otherwise return
INVALID_IN_STATE or NOT_FOUND.
- The Server SHALL play back the single local recording file, starting from the beginning of the file or a resume position defined by the implementation.
WebRTCProvideAnswer Command
Submits an SDP Answer to complete the WebRTC signaling negotiation.
Parameters
WebRTCProvideAnswer Command Structure
Response
WebRTCProvideAnswerResponse Command Structure
WebRTCProvideICECandidates Command
Submits local Trickle ICE candidates.
Parameters
WebRTCProvideICECandidates Command Structure
Response
WebRTCProvideICECandidatesResponse Command Structure
WebRTCEndSession Command
Ends a WebRTC session.
Parameters
WebRTCEndSession Command Structure
WebRTCTalk Command
Session-level talk switch. The Server allows only one session to have talk open at a time. The InvokeCommand forwarded by COIP and the InvokeCommand on this session's aqara.control use the same WebRTCTalk Command Structure. Request OpCode 0x008D, response OpCode 0x038D.
Parameters
WebRTCTalk Command Structure
Response
WebRTCTalk Response Command Structure, where Status takes the following values:
| Status | Description |
|---|
SUCCESS | The SessionId has been opened and occupied, or closed and released. It also succeeds when the session is already in the target state. |
NOT_FOUND | SessionId is not an active session. When it arrives from the DataChannel, a mismatch with the session to which that channel belongs also takes this value. |
INVALID_IN_STATE | The Server does not support talk, or the session is not LiveView. |
INVALID_COMMAND | Enabled is missing. When it arrives from COIP without SessionId, this value is also taken. |
RESOURCE_EXHAUSTED | Talk is already occupied by another session, and the SessionId cannot be opened. |
Processing
- When it arrives from
aqara.control without SessionId, the session is the one to which that channel belongs. A carried inconsistent SessionId -> return NOT_FOUND. When it arrives from COIP, SessionId SHALL be carried; omission -> return INVALID_COMMAND.
Enabled=true and not yet occupied -> this session occupies, return SUCCESS.- Opening again when this session has already occupied -> return
SUCCESS; it does not constitute a second occupation.
- Opening when another session has already occupied -> return
RESOURCE_EXHAUSTED. This session stays closed and does not preempt.
- The occupant sends
Enabled=false -> release, return SUCCESS.
- A non-occupant sends
Enabled=false -> return SUCCESS; the occupant is not released.
- The occupant's
WebRTCEndSession, its DataChannel closing, or the PeerConnection ending -> release the occupation.
WebRTCSetResolution Command
Switches one VideoStreamID bound to this session to the target resolution. The switch does not change the SSRC; the new resolution starts from the new IDR of that stream, and the IDR carries the new SPS. After returning SUCCESS, the Server SHALL complete the switch to the specified resolution, and the actual resolution is reported by WebRTCStreamResolution; on request failure, a non-SUCCESS status is returned and the original resolution is kept.
Parameters
WebRTCSetResolution Command Structure
Response
WebRTCSetResolutionResponse Command Structure, where Status takes the following values:
| Status | Description |
|---|
SUCCESS | The request succeeds; the Server SHALL switch to the specified resolution. When the target is already the current resolution, keep it and report immediately. |
NOT_FOUND | SessionId is not an active session, or the target ID is not in this session. A SessionId carried on the DataChannel that is inconsistent with that channel also takes this value. |
INVALID_IN_STATE | This stream cannot be switched (MinResolution = MaxResolution, non-LiveView, playback session). |
INVALID_COMMAND | The target resolution exceeds the Min/Max of that ID, or is not a tier of the capability set. When it arrives from COIP without SessionId, this value is also taken. |
RESOURCE_EXHAUSTED | The command queue is full. |
Validation and Processing
- When it arrives from
aqara.control without SessionId, the session is the one to which that channel belongs. A carried inconsistent SessionId -> return NOT_FOUND. When it arrives from COIP, SessionId SHALL be carried; omission -> return INVALID_COMMAND.
VideoStreamID SHALL be a stream bound to this session with StreamUsage=LiveView; the MinResolution of that ID SHALL be less than MaxResolution.- The target resolution SHALL fall between the
MinResolution and MaxResolution of that ID, and SHALL be a tier of CAVSMRateDistortionTradeOffPoints.
- The target is already the current resolution and there is no switch in progress -> return
SUCCESS and report WebRTCStreamResolution once immediately.
- The request is executable -> return
SUCCESS; the Server SHALL complete the switch and report WebRTCStreamResolution after the new IDR at the specified resolution is sent.
- The request is not executable -> return the corresponding non-
SUCCESS status and keep the original resolution.
- Requests on the same stream SHALL be processed in order; SHALL NOT override a switch that has returned
SUCCESS but has not yet completed. When the command queue is full, return RESOURCE_EXHAUSTED.
DataChannel
The transport, channels, messages, and file transfer binding of the in-session DataChannel are described in DataChannel.
DataChannel
Overview
This section defines the Trait, Command, and carrier on the DataChannel within a WebRTC session. These Trait and Command still belong to the WebRTC Function, and Command IDs share the same table as cloud signaling. In-session commands and states are InvokeCommand and UnconfirmedCOVNotificationMultiple with ProtocolID 0x00, sent and received on aqara.control, without passing through the cloud. File bytes use the file transfer business interaction protocol (ProtocolID 0x02). Fields, OpCodes, and interactions follow that protocol; this section does not define another set.
Transport
The transport stack of the WebRTC DataChannel (RFC 8831) is SCTP over DTLS over ICE. One m=application is one SCTP association. There are two Data Channels on this association. Each Data Channel is bidirectional, with one SCTP stream in each direction, and the two streams use the same stream id.
| Layer | Role | Meaning for this binding |
|---|
| ICE | Hole punching or relay (P2P / TURN) | Shares one candidate pair and one connection with audio/video |
| DTLS | Encryption and identity | Shares the same certificate as audio/video; a=setup decides active / passive |
| SCTP | Reliable, ordered, message-oriented (RFC 4960) | This binding depends directly on it |
| DCEP (RFC 8832) | Opens channels on the association | label, Channel Type, and Priority live here and do not enter the SDP |
Reliability and ordering are guaranteed by SCTP. File transfer reuses this delivery and does not add its own acknowledgment, retransmission, or whole-file checksum. Integrity is borne by DTLS. CoAP Type and Message ID do not carry acknowledgment. The request order of blocks is described in blockRequest. Only the Requestor can cancel, as described in abortRequest.
Channels
A WebRTC session has at most one m=application. This media description carries one SCTP association, and the association runs on the same DTLS. There are two Data Channels (RFC 8831) on the association. Each Data Channel is bidirectional, with one SCTP stream in each direction, the same stream id, and the name is the DCEP Label:
| label | Purpose | Channel Type | Priority | Content-Format |
|---|
aqara.control | Business commands and responses, device status notifications. Recording queries and tier switching, and playback are also on this Data Channel | 0x00 reliable ordered | 1024 | 50 (JSON) |
aqara.download | Fetch file bytes according to the file transfer business interaction protocol | 0x00 reliable ordered | 128 | 60 (CBOR) |
The ProtocolID is selected by which allocated business protocol a message in the session belongs to, and no separate protocol is defined per Data Channel:
| ProtocolID | Business protocol family | Carrier in this session |
|---|
0x00 | Aqara data model business interaction protocol | InvokeCommand (including recording queries) and UnconfirmedCOVNotificationMultiple |
0x02 | File transfer business interaction protocol | Carries file fetching only |
The OpCodes of 0x00 follow the data model: the high byte is the PDU Type and the low byte is the Service Choice. This binding does not add such OpCodes.
| OpCode | PDU Type | Service name | Description |
|---|
0x008D | Confirmed-Request | InvokeCommand | In-session business command. propertyIdentifier is the Command ID and propertyValue is the command request parameters |
0x038D | ComplexACK | InvokeCommand | Command response. propertyValue is the command response structure, member 0 is Status |
0x018A | Unconfirmed-Request | UnconfirmedCOVNotificationMultiple | Device actively reports WebRTCStreamResolution and LocalPlaybackStatus |
0x02 uses the function numbers of the file transfer protocol itself. Fields and interactions are described in the definitions linked in the table below; this section does not define another set.
| OpCode | Function name | Description |
|---|
0x0000 / 0x0001 | initRequest / initResponse | Establish the transfer |
0x0002 / 0x0003 | blockRequest / blockResponse | Pull by range in batches; each block response carries blockCounter and data |
0x0004 / 0x0005 | EOFRequest / EOFResponse | The requestor confirms that the last block has been processed |
0x0006 / 0x0007 | abortRequest / abortResponse | The requestor cancels |
0x0008 | errorResponse | Business failure. The data model Error PDU is not used |
| label | Carrier | OpCode | Direction | Typical messages |
|---|
aqara.control | InvokeCommand (ProtocolID 0x00) | 0x008D / 0x038D | App -> Device / back | WebRTCSetResolution, WebRTCTalk, LocalPlaybackControl, LocalRecordQuery |
aqara.control | UnconfirmedCOVNotificationMultiple (ProtocolID 0x00) | 0x018A | Device -> App | WebRTCStreamResolution, LocalPlaybackStatus |
aqara.download | File transfer (ProtocolID 0x02) | 0x0000-0x0008 | App requests, device responds | init, block, EOF, abort, error |
The table above specifies which type of message uses which label:
- The same CoAP message SHALL NOT appear on two labels.
- The two Data Channels are each ordered and do not queue on each other; control messages are not queued behind file blocks. They share this one SCTP association, the same DTLS / ICE, and the same congestion window, and SHALL NOT each open an
m=.
- The App creates labels after
WebRTCProvideOffer (negotiated=false). The device collects them in onDataChannel by label; labels that do not match SHALL be ignored. Before DATA_CHANNEL_OPEN of a label completes, the App SHALL NOT send messages on that label.
- When the App is the offerer, the stream id of label
aqara.control is 0, and label aqara.download is 2.
- The Channel Type of both Data Channels is
0x00 (DATA_CHANNEL_RELIABLE), and the Reliability Parameter SHALL be 0. Other Channel Types SHALL NOT be used.
- The Content-Format of label
aqara.control SHALL be 50. Label aqara.download SHALL be 60. File blocks are octetString and SHALL NOT be Base64-encoded into JSON.
- Recording queries are
LocalRecordQuery on label aqara.control. The bytes of the index file and recording files go over label aqara.download.
Messages
One SCTP user message (PPID = 53) SHALL carry exactly one complete CoAP message. This binding fixes the CoAP header to Type=NON, Message ID=0. The message diagrams in the file transfer protocol body are written for reliable transport with Length; OpCode and Payload are the same, see the file transfer business interaction protocol.
SCTP User Message (PPID = 53)
└─ CoAP Message
├─ Version: 1
├─ Type: NON
├─ Code: 0.02 POST / allowed response Codes
├─ Message ID: 0
├─ Token
├─ Options
├─ Payload Marker: 0xFF
└─ Payload
Type SHALL be NON. CON, ACK, and RST SHALL NOT be used.Message ID SHALL be 0. Both sides SHALL ignore it and SHALL NOT use it for deduplication or correlation.- Requests and responses SHALL be correlated through
Token. The Token length SHALL be 1-8 bytes and SHALL NOT repeat on the same connection at the same time.
- Messages that do not require a response SHALL use an empty
Token.
- One SCTP user message SHALL NOT carry multiple CoAP messages; one CoAP message SHALL NOT span multiple SCTP user messages.
| Name | Option ID | Appearance | Value in this binding |
|---|
| Uri-Path | 11 | M | Two Options, values in order coip, interaction |
| Content-Format | 12 | M | aqara.control is 50; aqara.download is 60 |
| Accept | 17 | C | Requests with a payload SHALL carry it. The value for aqara.download is described in the file transfer encoding rules |
| InteractionVersion | 2048 | M | 0 |
| SourceDeviceID | 2052 | O | SHALL be omitted |
| DestinationDeviceID | 2056 | O | SHALL be omitted |
| ProtocolID | 2064 | M | 0x00 or 0x02 |
| OpCode | 2072 | M | See the OpCode table of Channels; SHALL use the shortest uint encoding |
| PayloadEncryption | 2076 | M | 0 |
| Scenario | Sender | Receiver |
|---|
| Business commands (including recording queries) | Code 0.02, non-empty Token | 2.04 Changed, echoing the same Token |
| File transfer | Code 0.02, non-empty Token | 2.04 Changed, echoing the same Token. Interactions follow the OpCode master table |
| Resolution and playback status reports | Code 0.02, empty Token, OpCode 0x018A | No CoAP response |
| Business failure of data model commands | - | Stays in the ComplexACK of InvokeCommand, member 0 is Status |
| Business failure of file transfer | - | errorResponse, not StatusCodeEnum8 |
The structure encoding of aqara.control is a JSON Object, with member keys being the decimal strings of member indices. The encoding of aqara.download is described in the file transfer encoding rules. Mandatory JSON members that are semantically nullable are encoded as null when empty and SHALL NOT omit the key. LocalRecordQuery's QueryLocalRecordType indicates the kind, and only the member it points to appears: LocalRecordIndex or LocalRecordSegment.
SDP and DCEP
m=application has only the following lines in both the Offer and the Answer. ICE candidates, a=setup, and the fingerprint are shared with audio/video. The mid of this m= goes into the session-level a=group:BUNDLE.
Offer (App):
m=application 9 UDP/DTLS/SCTP webrtc-datachannel
c=IN IP4 0.0.0.0
a=mid:2
a=sctp-port:5000
a=setup:actpass
a=ice-ufrag:offerufrag
a=ice-pwd:offericepwd0123456789abcd
a=fingerprint:sha-256 AA:BB:CC:DD
Answer (Device):
m=application 9 UDP/DTLS/SCTP webrtc-datachannel
c=IN IP4 0.0.0.0
a=mid:2
a=sctp-port:5000
a=setup:passive
a=ice-ufrag:answerufrag
a=ice-pwd:answericepwd0123456789abcd
a=fingerprint:sha-256 EE:FF:00:11
When the device does not accept this m=, it writes port 0 and adds a=inactive. The session is still established normally, only without a DataChannel. Tier switching, queries, and file transfer are all unavailable, and media is still sent at the broadcast resolution.
label, Channel Type, and Priority are not written into the SDP; they are opened on the association by RFC 8832 (WebRTC Data Channel Establishment Protocol). When the App is the offerer, stream ids are even.
The format of DATA_CHANNEL_OPEN is in Section 5.1 of RFC 8832:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Type | Channel Type | Priority |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reliability Parameter |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Label Length | Protocol Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
\ /
| Label |
/ \
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
\ /
| Protocol |
/ \
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The format of DATA_CHANNEL_ACK is in Section 5.2 of RFC 8832:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Type |
+-+-+-+-+-+-+-+-+
The App sends one DATA_CHANNEL_OPEN for each Data Channel. The first column of the table is the value of the Label field:
| label | Priority | stream id | Message (hex) |
|---|
aqara.control | 1024 | 0 | 03 00 04 00 00 00 00 00 00 0D 00 00 + 61 71 61 72 61 2E 63 6F 6E 74 72 6F 6C |
aqara.download | 128 | 2 | 03 00 00 80 00 00 00 00 00 0E 00 00 + 61 71 61 72 61 2E 64 6F 77 6E 6C 6F 61 64 |
Values in this binding: Message Type 0x03, Channel Type 0x00 (DATA_CHANNEL_RELIABLE), Reliability Parameter 0, Protocol Length 0, and Protocol empty. Priority, Label Length, and Label are in the table above. The Message Type of DATA_CHANNEL_ACK is 0x02. a=max-message-size is not written; the default single SCTP user message is 65536 bytes. The stream id is not in the OPEN message body. The App sends this OPEN on the stream id of that Data Channel, and both directions use the same stream id.
Only after the device receives DATA_CHANNEL_OPEN of a label and returns DATA_CHANNEL_ACK does it consider that label available. Before that, the App SHALL NOT send messages on that label. m=application, DTLS, and the SCTP association are not established again per label. Messages are isolated by label, see Channels.
Channel Reporting Trait
Channel Command Command
The Commands currently supported on label aqara.control. The specifications are in the DataChannel channel command table of WebRTC and the corresponding Command definitions.
File Transfer Binding
The App is the Requestor and the device is the Provider. The entries of LocalRecordQuery give FileDescriptorStructure. The field meanings follow the dependency section of the file transfer business interaction protocol and are written into initRequest as-is. Encoding follows the file transfer encoding rules.
- Label
aqara.download carries only ProtocolID 0x02. The device does not proactively send bytes on that label; currently only the requestor pulls.
- Only one unfinished
transferId exists on that label at a time. A second initRequest returns Busy (errorResponse).
- Block request order, last block, and cancellation follow blockRequest, EOFRequest, and abortRequest.
- This binding defines the "secure session" as the DTLS session of this PeerConnection.
transferId is unique and non-zero within that session. When WebRTCEndSession, the DataChannel closes, or DTLS ends, unfinished transfers are invalidated and both sides release resources.
- Card removal, circular overwrite, or read failures are not separately cancelled by the device. The result is shown on the current batch or the next request via errorResponse.
- Media types are not in the file transfer protocol. mp4 and the original index format are decided by the business object.
- When negotiating
maxBlockSize, reserve space for CoAP encapsulation and CBOR overhead, see the file block message of the file transfer protocol. The CBOR Map of blockResponse also carries the current block number blockCounter; the encapsulation overhead varies with the CBOR encoding width of the block number and data length, and is no longer calculated as a fixed 25 bytes. The example uses maxBlockSize of 32768.
SO2 (Sulfur Dioxide)
Introduction
Represents the monitoring functional domain for sulfur dioxide in the air, including but not limited to SO2 concentration measurement, whether SO2 is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0128 | SO2 | Sulfur dioxide |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x519F | SO2Density | Sulfur dioxide concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
SO2Density Trait (Sulfur Dioxide Concentration)
Represents the sulfur dioxide concentration in the air, used to evaluate irritant gas pollution levels and to assist in environmental safety monitoring and alarm determination. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x519F | SO2Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
NO2 (Nitrogen Dioxide)
Introduction
Represents the monitoring functional domain for nitrogen dioxide in the air, including but not limited to NO2 concentration measurement, whether NO2 is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0129 | NO2 | Nitrogen dioxide |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A0 | NO2Density | Nitrogen dioxide | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
NO2Density Trait (Nitrogen Dioxide)
Represents the nitrogen dioxide concentration in the air, which can be used to evaluate pollution levels related to combustion or exhaust, as well as air quality risks. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x51A0 | NO2Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
O3 (Ozone)
Introduction
Represents the monitoring functional domain for ozone in the air, including but not limited to O3 concentration measurement, whether O3 is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x012A | O3 | Ozone |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A1 | O3Density | Ozone concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
O3Density Trait (Ozone Concentration)
Represents the ozone concentration in the air, used to evaluate oxidative pollution levels and to assist in determining air exposure risks and purification needs. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x51A1 | O3Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
Introduction
Represents the monitoring functional domain for formaldehyde in the air, including but not limited to HCHO concentration measurement, whether formaldehyde is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x012B | Formaldehyde | Formaldehyde |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A3 | HCHODensity | Formaldehyde concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
HCHODensity Trait (Formaldehyde Concentration)
Represents the formaldehyde concentration in the air, used to monitor renovation pollution risks and to assist in determining whether continuous ventilation or purification treatment is needed. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x51A3 | HCHODensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
O2 (Oxygen)
Introduction
Represents the monitoring functional domain for oxygen in the environment, including but not limited to O2 concentration measurement, hypoxia/hyperoxia determination, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x012C | O2 | Oxygen |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A4 | O2Density | Oxygen | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
O2Density Trait (Oxygen)
Represents the oxygen volume fraction in the air, used to determine the oxygen supply level of the environment and to assist in evaluating safety in enclosed spaces or special scenarios. Unit: %vol.
| Trait ID | Code |
|---|
| 0x51A4 | O2Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 21 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 21 | RW | O |
Command Definitions
This Function does not contain any Commands.
Chlorine (Chlorine Gas)
Introduction
Represents the monitoring functional domain for chlorine gas in the air, including but not limited to Cl2 concentration measurement, whether chlorine gas is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x012D | Chlorine | Chlorine gas |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A5 | Cl2Density | Chlorine gas concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
Cl2Density Trait (Chlorine Gas Concentration)
Represents the chlorine gas concentration in the air, used to monitor the risk of leakage of highly irritant gas and to support safety alarms. Unit: mg/m^3.
| Trait ID | Code |
|---|
| 0x51A5 | Cl2Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 1000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
HydrochloricAcid (Hydrochloric Acid)
Introduction
Represents the monitoring functional domain for hydrochloric acid gas in the air, including but not limited to HCl concentration measurement, whether hydrochloric acid gas is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x012E | HydrochloricAcid | Hydrochloric acid |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A6 | HClDensity | Hydrochloric acid concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
HClDensity Trait (Hydrochloric Acid Concentration)
Represents the hydrochloric acid concentration in the air, which can be used to monitor acidic irritant gas pollution and environmental safety risks. Unit: mg/m^3.
| Trait ID | Code |
|---|
| 0x51A6 | HClDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 1000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
HydrogenSulfide (Hydrogen Sulfide)
Introduction
Represents the monitoring functional domain for hydrogen sulfide in the air, including but not limited to H2S concentration measurement, whether hydrogen sulfide is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x012F | HydrogenSulfide | Hydrogen sulfide |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A7 | H2SDensity | Hydrogen sulfide concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
H2SDensity Trait (Hydrogen Sulfide Concentration)
Represents the hydrogen sulfide concentration in the air, used to monitor toxic and harmful gas risks and to assist in ventilation and alarm linkage. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x51A7 | H2SDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
Ammonia (Ammonia Gas)
Introduction
Represents the monitoring functional domain for ammonia gas in the air, including but not limited to NH3 concentration measurement, whether ammonia gas is detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0130 | Ammonia | Ammonia gas |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51A8 | NH3Density | Ammonia gas concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
NH3Density Trait (Ammonia Gas Concentration)
Represents the ammonia gas concentration in the air, used to evaluate irritant gas pollution levels and to assist in determining leaks or environmental anomalies. Unit: ug/m^3.
| Trait ID | Code |
|---|
| 0x51A8 | NH3Density |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 9999.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
WaterQuality (Water Quality)
Introduction
Represents the monitoring functional domain for water quality, covering but not limited to the measurement and status determination of water quality parameters such as water hardness, turbidity, pH, TDS (total dissolved solids), residual chlorine, and dissolved oxygen, as well as sensor status and exceedance alarm capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0131 | WaterQuality | Water quality |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
WaterHardness Trait (Water Hardness)
Represents the water hardness level, usually reflecting the calcium and magnesium ion content in water, and can be used to determine scaling risks and water treatment needs. Unit: ppm.
| Trait ID | Code |
|---|
| 0x51AB | WaterHardness |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
WaterTurbidity Trait (Water Turbidity)
Represents the degree of turbidity of the water body, which can be used to determine the level of suspended particle impurities and water cleanliness. Unit: NTU.
| Trait ID | Code |
|---|
| 0x51AC | WaterTurbidity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 4000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
NitrogenOxides (Nitrogen Oxides)
Introduction
Represents the monitoring functional domain for nitrogen oxides in the air, including but not limited to NOx concentration measurement, whether nitrogen oxides are detected, exceedance alarms, and sensor status capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0132 | NitrogenOxides | Nitrogen oxides |
Trait
| Trait ID | Code | Name | Conformance |
|---|
| 0x51AF | NOxDensity | Nitrogen oxides concentration | M |
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
NOxDensity Trait (Nitrogen Oxides Concentration)
Represents the nitrogen oxides concentration in the air, used to evaluate combustion pollution levels and air quality risks. Unit: mg/m^3.
| Trait ID | Code |
|---|
| 0x51AF | NOxDensity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 1000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
LiquidLevel (Liquid Level)
Introduction
Represents the monitoring functional domain for the liquid level in containers or pipelines, including but not limited to liquid level height measurement, liquid storage volume determination, replenishment/drainage demand analysis, and high/low liquid level risk warning capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0133 | LiquidLevel | Liquid level |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
LiquidLevelHeight Trait (Liquid Level Height)
Represents the actual height of the liquid surface in a container or pipeline, used to determine liquid storage volume, replenishment/drainage needs, and high/low liquid level risks. Unit: m.
| Trait ID | Code |
|---|
| 0x51EC | LiquidLevelHeight |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
Noise
Introduction
Represents the monitoring functional domain for environmental noise, including but not limited to noise level measurement, whether the noise exceeds the standard, peak noise, and average noise capabilities.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0134 | Noise | Noise |
Trait
This Function does not contain any Traits.
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
This Function does not contain any Traits.
Command Definitions
This Function does not contain any Commands.
HeatMeter (Heat Metering)
Introduction
Represents the comprehensive management of cooling/heating metering functions in heating/cooling supply systems, covering the measurement and reporting of parameters such as instantaneous heat flow, instantaneous cold flow, accumulated heat value, accumulated cold value and their fractional parts, for energy metering, energy efficiency analysis, and billing.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0135 | HeatMeter | Heat metering |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
InstantaneousColdFlow Trait (Instantaneous Cold Flow)
Represents the rate of cooling energy transferred at the current moment, which can be used to determine the real-time cooling supply capacity and cold load changes of the system. Unit: m^3/s.
| Trait ID | Code |
|---|
| 0x51BD | InstantaneousColdFlow |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
InstantaneousHeatFlow Trait (Instantaneous Heat Flow)
Represents the rate of heat energy transferred at the current moment, which can be used to determine the real-time heating intensity and load changes of the system. Unit: GJ/h.
| Trait ID | Code |
|---|
| 0x51C1 | InstantaneousHeatFlow |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 100000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
Boiler
Introduction
Represents the monitoring and control functional domain for boiler equipment operation status, covering the measurement, setting, and reporting of parameters such as exhaust temperature, fire adjustment, load output, combustion timing, and ignition count, for boiler combustion control, energy efficiency analysis, and safety monitoring.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0136 | Boiler | Boiler |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
SupplyWaterPressure Trait (Supply Water Pressure)
Represents the pipeline pressure on the supply side of the boiler, used to determine whether the supply circuit is stable and whether there is abnormal pressure. Unit: MPa.
| Trait ID | Code |
|---|
| 0x51E1 | SupplyWaterPressure |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
ReturnWaterPressure Trait (Return Water Pressure)
Represents the pipeline pressure on the return side of the boiler, used to determine the operating status of the return circuit and changes in the system pressure differential. Unit: MPa.
| Trait ID | Code |
|---|
| 0x51E2 | ReturnWaterPressure |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
SupplyWaterTemperature Trait (Supply Water Temperature)
Represents the temperature of the medium output by the boiler supply circuit, used to determine the heating output level and the current supply operating condition. Unit: degC.
| Trait ID | Code |
|---|
| 0x51E3 | SupplyWaterTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
ReturnWaterTemperature Trait (Return Water Temperature)
Represents the temperature of the medium returning through the boiler return circuit, used to analyze the return operating condition and the heat exchange effect of the system. Unit: degC.
| Trait ID | Code |
|---|
| 0x51E4 | ReturnWaterTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
ExhaustTemperature Trait (Exhaust Temperature Value)
Represents the boiler exhaust gas temperature, used to determine the combustion heat exchange effect, exhaust losses, and whether there is an abnormal thermal state. Unit: degC.
| Trait ID | Code |
|---|
| 0x51E5 | ExhaustTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
TargetTemperatureDifferential Trait (Target Temperature Differential Value)
Represents the supply/return temperature differential setpoint adopted by the boiler control target, used to guide load regulation and thermal balance control. Unit: degC.
| Trait ID | Code |
|---|
| 0x51E6 | TargetTemperatureDifferential |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RVW | O |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
MinimumFireRate Trait (Minimum Fire Rate)
Represents the minimum combustion output boundary allowed for boiler operation, used to limit the stable combustion range under low-load operation. Unit: %.
| Trait ID | Code |
|---|
| 0x51E7 | MinimumFireRate |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
MaximumFireRate Trait (Maximum Fire Rate)
Represents the maximum combustion output boundary allowed for boiler operation, used to limit the output ceiling under high-load operation. Unit: %.
| Trait ID | Code |
|---|
| 0x51E8 | MaximumFireRate |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
TimeToMaximumLoadSetting Trait (Time to Maximum Load Setting)
Represents the set time allowed for the boiler to rise from the current state to maximum load, used to control the load-up speed and thermal shock. Unit: h.
| Trait ID | Code |
|---|
| 0x51E9 | TimeToMaximumLoadSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RVW | O |
| 0x0002 | Maximum Value | float | | 1000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
AccumulatedCombustionTime Trait (Accumulated Combustion Time)
Represents the accumulated combustion operating time of the boiler, which can be used for maintenance, life assessment, and operating statistics analysis. Unit: h.
| Trait ID | Code |
|---|
| 0x51EA | AccumulatedCombustionTime |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 240000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
IgnitionCount Trait (Ignition Count)
Represents the cumulative ignition count of the boiler, used to analyze start/stop frequency, burner usage intensity, and maintenance needs.
| Trait ID | Code |
|---|
| 0x51EB | IgnitionCount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | | 0 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 1000000 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
| 0x0007 | Default Value | uint32 | | 0 | RW | O |
Command Definitions
This Function does not contain any Commands.
ControlCabinet (Control Cabinet)
Introduction
Represents the monitoring and control functional domain for control cabinet equipment, covering the measurement, setting, and reporting of parameters such as frequency feedback, cooling water temperature actual value and setpoint, temperature differential setting, and manual frequency setpoint, for cooling water system control, frequency adjustment, and operation monitoring.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0137 | ControlCabinet | Control cabinet |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
FrequencyFeedback Trait (Frequency Feedback)
Represents the variable-frequency operation feedback frequency collected by the device. Unit: Hz.
| Trait ID | Code |
|---|
| 0x51DA | FrequencyFeedback |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
CoolingWaterActualTemperature Trait (Cooling Water Temperature Actual Value)
Represents the actual cooling water temperature monitored by the control cabinet, used to determine the current operating condition and temperature control effect of the cooling circuit. Unit: degC.
| Trait ID | Code |
|---|
| 0x51DB | CoolingWaterActualTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
CoolingWaterTemperatureSetpoint Trait (Cooling Water Temperature Setpoint)
Represents the target cooling water temperature used by the control cabinet for temperature control adjustment, used to determine the control target and start/stop strategy of the cooling circuit. Unit: degC.
| Trait ID | Code |
|---|
| 0x51DC | CoolingWaterTemperatureSetpoint |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 26 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 26 | RW | O |
TemperatureDifferentialSetting Trait (Temperature Differential Setting)
Represents the temperature differential threshold used by the control cabinet temperature control strategy, used to determine when to perform adjustment, start/stop, or linkage actions after a certain differential is reached. Unit: degC.
| Trait ID | Code |
|---|
| 0x51DD | TemperatureDifferentialSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RVW | O |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
ManualFrequencySetpoint Trait (Manual Frequency Setpoint)
Represents the target operating frequency sent to the control cabinet in manual mode, used to manually specify the variable-frequency output level. Unit: Hz.
| Trait ID | Code |
|---|
| 0x51DE | ManualFrequencySetpoint |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
Command Definitions
This Function does not contain any Commands.
Compressor
Introduction
Represents the monitoring and control functional domain for compressor equipment operation status, covering the measurement, setting, and reporting of parameters such as temperature, pressure, current, voltage, power, humidity, speed, opening degree, operating time, and cooling capacity, for refrigeration system control, energy efficiency analysis, and safety monitoring.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0138 | Compressor | Compressor |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
CoolingCapacityPercentage Trait (Cooling Capacity Percentage)
Represents the current cooling output of the compressor as a percentage of the rated capacity, used to determine the device load level and capacity adjustment status.
| Trait ID | Code |
|---|
| 0x51C2 | CoolingCapacityPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
AverageLineCurrent Trait (Average Line Current)
Represents the average operating current of the three-phase lines of the compressor, used to evaluate the electrical load level and operating load changes. Unit: A.
| Trait ID | Code |
|---|
| 0x51C3 | AverageLineCurrent |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 10000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
ChilledWaterInletTemperature Trait (Chilled Water Inlet Temperature)
Represents the water temperature entering the chilled water circuit of the compressor, used to determine the evaporator-side load and inlet operating condition. Unit: degC.
| Trait ID | Code |
|---|
| 0x51C4 | ChilledWaterInletTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
ChilledWaterOutletTemperature Trait (Chilled Water Outlet Temperature)
Represents the water temperature leaving the chilled water circuit of the compressor, used to determine the cooling output effect and outlet operating condition. Unit: degC.
| Trait ID | Code |
|---|
| 0x51C5 | ChilledWaterOutletTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
EvaporatorRefrigerantTemperature Trait (Evaporator Refrigerant Temperature)
Represents the refrigerant temperature inside the evaporator, used to determine the evaporation heat exchange state and the operating condition of the refrigeration cycle. Unit: degC.
| Trait ID | Code |
|---|
| 0x51C6 | EvaporatorRefrigerantTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
ChilledEvaporatorRefrigerantPressure Trait (Chilled Evaporator Refrigerant Pressure)
Represents the refrigerant pressure on the evaporator side, used to determine the evaporation operating condition, refrigerant state, and whether the system is running normally. Unit: kPa.
| Trait ID | Code |
|---|
| 0x51C7 | ChilledEvaporatorRefrigerantPressure |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 5000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
CoolingWaterInletTemperature Trait (Cooling Water Inlet Temperature)
Represents the water temperature entering the cooling water circuit of the compressor, used to determine the condenser-side heat dissipation conditions and inlet operating condition. Unit: degC.
| Trait ID | Code |
|---|
| 0x51C8 | CoolingWaterInletTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
CoolingWaterOutletTemperature Trait (Cooling Water Outlet Temperature)
Represents the water temperature leaving the cooling water circuit of the compressor, used to determine the condenser-side heat dissipation effect and outlet operating condition. Unit: degC.
| Trait ID | Code |
|---|
| 0x51C9 | CoolingWaterOutletTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
CondenserRefrigerantTemperature Trait (Condenser Refrigerant Temperature)
Represents the refrigerant temperature inside the condenser, used to determine the condensation heat exchange state and the efficiency of the refrigeration cycle. Unit: degC.
| Trait ID | Code |
|---|
| 0x51CA | CondenserRefrigerantTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | M |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
CondenserRefrigerantPressure Trait (Condenser Refrigerant Pressure)
Represents the refrigerant pressure on the condenser side, used to determine the high-pressure side operating condition, heat dissipation state, and operating risks. Unit: kPa.
| Trait ID | Code |
|---|
| 0x51CB | CondenserRefrigerantPressure |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | M |
| 0x0002 | Maximum Value | float | | 5000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
VFDCoolingRefrigerantFlowPercentage Trait (VFD Cooling Refrigerant Flow Percentage)
Represents the ratio of the refrigerant flow in the VFD cooling circuit to the design value, used to determine whether the VFD cooling capacity is sufficient. Unit: %.
| Trait ID | Code |
|---|
| 0x51CC | VFDCoolingRefrigerantFlowPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
VFDSpeedPercentage Trait (VFD Speed Percentage)
Represents the ratio of the current VFD speed to the rated speed, which can be used to determine the variable-speed output level of the compressor and the operating load state under frequency conversion. Unit: %.
| Trait ID | Code |
|---|
| 0x51CD | VFDSpeedPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
GuideVaneOpeningPercentage Trait (Guide Vane Opening Percentage)
Represents the ratio of the current opening degree of the compressor guide vanes, which can be used to determine the capacity adjustment range and intake control state. Unit: %.
| Trait ID | Code |
|---|
| 0x51CE | GuideVaneOpeningPercentage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
RectifierTemperature Trait (Rectifier Temperature)
Represents the operating temperature of the rectifier, used to monitor the thermal state of power electronic components and assist in determining whether heat dissipation is normal. Unit: degC.
| Trait ID | Code |
|---|
| 0x51CF | RectifierTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
CompressorOilTemperature Trait (Compressor Oil Temperature)
Represents the current temperature of the compressor lubricating oil, used to determine the lubrication and heat dissipation condition; abnormal oil temperature may affect equipment life and operating safety. Unit: degC.
| Trait ID | Code |
|---|
| 0x51D0 | CompressorOilTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 150.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
CompressorOilPressure Trait (Compressor Oil Pressure)
Represents the lubricating oil pressure of the compressor, used to determine whether the lubrication system has properly established an oil film and maintains safe operation. Unit: kPa.
| Trait ID | Code |
|---|
| 0x51D1 | CompressorOilPressure |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
DischargeTemperature Trait (Discharge Temperature)
Represents the gas temperature at the discharge end of the compressor, used to determine the thermal state of the compression process and whether there is an overheating risk. Unit: degC.
| Trait ID | Code |
|---|
| 0x51D2 | DischargeTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
CompressorBearingTemperature Trait (Compressor Bearing Temperature)
Represents the working temperature of the compressor bearing, used to monitor mechanical friction, lubrication effectiveness, and bearing health status. Unit: degC.
| Trait ID | Code |
|---|
| 0x51D3 | CompressorBearingTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
MotorCoilTemperature Trait (Motor Coil Temperature)
Represents the temperature of the compressor drive motor coil, used to determine the motor thermal load and insulation operating risks. Unit: degC.
| Trait ID | Code |
|---|
| 0x51D4 | MotorCoilTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
AverageLineVoltage Trait (Average Line Voltage)
Represents the average operating voltage of the three-phase lines of the compressor, used to evaluate power supply quality and voltage stability. Unit: V.
| Trait ID | Code |
|---|
| 0x51D5 | AverageLineVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 220 | RV | O |
| 0x0002 | Maximum Value | float | | 500.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.01 | R | O |
| 0x0007 | Default Value | float | | 220 | RW | O |
LinePower Trait (Line Power)
Represents the current line input power of the compressor, which can be used to evaluate the device power consumption level and operating load changes. Unit: W.
| Trait ID | Code |
|---|
| 0x51D6 | LinePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 0 | RW | O |
VFDDeviceHumidity Trait (VFD Device Humidity)
Represents the ambient humidity around the VFD device, used to determine whether the electrical environment has condensation, moisture, or insulation risks. Unit: %.
| Trait ID | Code |
|---|
| 0x51D7 | VFDDeviceHumidity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 1.0 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
InverterTemperature Trait (Inverter Temperature)
Represents the operating temperature of the inverter, used to monitor the thermal state of power devices and assist in determining heat dissipation and load conditions. Unit: degC.
| Trait ID | Code |
|---|
| 0x51D8 | InverterTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 25 | RV | O |
| 0x0002 | Maximum Value | float | | 300.0 | R | O |
| 0x0003 | Minimum Value | float | | -50.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 25 | RW | O |
OutletWaterTemperatureSetpoint Trait (Outlet Temperature Setpoint)
Represents the outlet water temperature setpoint given to the compressor, used to adjust the chilled water outlet control target and influence the cooling regulation strategy. Unit: degC.
| Trait ID | Code |
|---|
| 0x51D9 | OutletWaterTemperatureSetpoint |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 26 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 26 | RW | O |
Command Definitions
This Function does not contain any Commands.
CoolingPump (Cooling Pump)
Introduction
Represents the monitoring and control functional domain for cooling pump equipment, covering the measurement, setting, and reporting of parameters such as frequency feedback, manual frequency setpoint, frequency upper/lower limits, and operating time, for frequency adjustment, operation monitoring, and energy consumption management of the cooling water circulation system.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x0139 | CoolingPump | Cooling pump |
Trait
Command
This Function does not contain any Commands.
Data Types
This Function has no custom data types.
Trait Definitions
FrequencyFeedback Trait (Frequency Feedback)
Represents the variable-frequency operation feedback frequency collected by the device. Unit: Hz.
| Trait ID | Code |
|---|
| 0x51DA | FrequencyFeedback |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RV | M |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
ManualFrequencySetting Trait (Manual Frequency Setpoint)
Represents the target operating frequency set for the cooling pump in manual mode, used to manually specify the motor speed and flow level. Unit: Hz.
| Trait ID | Code |
|---|
| 0x51E0 | ManualFrequencySetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 50 | RVW | O |
| 0x0002 | Maximum Value | float | | 100.0 | R | O |
| 0x0003 | Minimum Value | float | | 0.0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
| 0x0007 | Default Value | float | | 50 | RW | O |
Command Definitions
This Function does not contain any Commands.
Buzzer
Introduction
Represents the control functional domain of the device buzzer, used to play or stop the buzzer sound, supporting the setting of playback volume and duration; applicable to scenarios such as doorbell notifications, alarm reminders, and operation feedback.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x013A | Buzzer | Buzzer |
Trait
Command
Data Types
BuzzerPlayStatusEnum8 Type
This enumeration defines the playback states of the PlayBuzzer Command.
| Value | Name | Description |
|---|
| 0x00 | Stopped | Stopped |
| 0x01 | Playing | Playing |
BuzzerPlayVolumeEnum8 Type
This enumeration defines the playback volumes of the PlayBuzzer Command.
| Value | Name | Description |
|---|
| 0x01 | Low | Low volume |
| 0x02 | Medium | Medium volume |
| 0x03 | High | High volume |
PlayBuzzer Command Structure Type
Parameter structure of the PlayBuzzer Command.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | PlayStatus | BuzzerPlayStatusEnum8 | M | Playback state; default value is 0. Stopped indicates stopping the currently playing buzzer sound; Playing indicates starting playback. |
| 1 | PlayVolume | BuzzerPlayVolumeEnum8 | O | Playback volume; default value is 2. |
| 2 | PlayDuration | uint32 | O | Playback duration (seconds), in the range 1 to 4294967295 with a step of 1; default value is 5. |
Trait Definitions
Command Definitions
PlayBuzzer Command
Controls the device to play or stop the buzzer sound. PlayStatus is a required field that specifies the playback state: PLAYING (Playing) indicates starting playback, and STOPPED (Stopped) indicates stopping playback. During playback, PlayVolume can be used to set the volume and PlayDuration to set the playback duration; PlayDuration greater than 0 means playing for the specified number of seconds. When PlayStatus is STOPPED, PlayVolume, PlayDuration, and all other optional parameters SHALL be omitted, and the device will stop the currently playing buzzer sound.
Parameters
PlayBuzzer Command Structure
GasMetering (Gas Metering)
Introduction
GasMetering provides gas metering-related capabilities, including the gas calorific value and the conversion coefficient from operating-condition volume to standard volume, to support energy conversion and standardized conversion of gas usage.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x013B | GasMetering | Gas metering |
Trait
Command
This Function does not contain any Commands.
Data Types
GasCalorificValueTraitPresentValueStructure Type
This structure defines the field layout of the Present Value of the GasCalorificValue Trait.
| Member Index | Field Name | Type | Required | Minimum | Maximum | Step | Default | Description (Unit) |
|---|
| 0 | CalorificValue | float | M | 0 | 100 | 0.01 | 38.5 | Calorific value of the standard-volume gas, configured by the gas source/server side. Unit: MJ/m^3 (megajoules per standard cubic meter). |
| 1 | ReferenceTemperature | float | O | -50 | 50 | 0.1 | 15.0 | Combustion reference temperature corresponding to the calorific value. Unit: deg C. |
| 2 | ReferencePressure | float | O | 50 | 150 | 0.001 | 101.325 | Reference pressure corresponding to the calorific value. Unit: kPa. |
Trait Definitions
GasCalorificValue Trait
The gas calorific value represents the heat (energy) contained in a unit volume of gas, used to convert the volume consumption of gas into energy consumption. It is usually provided in the form of a higher heating value, that is, the heat released by the complete combustion of a unit standard volume of gas under standard reference conditions. This value is a gas property parameter, affected by the gas source composition and the reference temperature/pressure, and is usually configured by the gas company or the cloud; the gas meter performs the volume-to-energy conversion accordingly.
| Trait ID | Code |
|---|
| 0x51F5 | GasCalorificValue |
Parameters
GasVolumeFactor Trait
The gas volume conversion coefficient represents the coefficient (Volume Conversion Factor, VCF) for converting the gas volume measured by the gas meter under operating conditions (actual temperature, pressure) into the volume under standard reference conditions. It is defined as the volume under standard reference conditions divided by the volume under operating conditions. This coefficient integrates corrections for temperature, pressure, compressibility factor, and other factors, and is usually calculated by a volume corrector or the cloud and then delivered; the gas meter performs the standardized volume conversion accordingly.
| Trait ID | Code |
|---|
| 0x51F6 | GasVolumeFactor |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | | 1.0 | RV | M |
| 0x0002 | Maximum Value | float | | 2 | R | O |
| 0x0003 | Minimum Value | float | | 0.5 | R | O |
| 0x0005 | Step Value | float | | 0.00001 | R | O |
Command Definitions
This Function does not contain any Commands.
EnergyStorage (Energy Storage)
Introduction
EnergyStorage is used to describe the dedicated state and energy metering capabilities of battery energy storage systems, including battery-side state of charge, capacity, charge/discharge power, cumulative charge/discharge energy, and battery health status. SOC (State of Charge) is measured or estimated by the BMS (Battery Management System). The backup battery used by the device itself to maintain controller operation does not belong to this Function; it SHALL use PowerSource.
The charge/discharge power and energy in this Function take the battery DC terminal as the metering boundary. The AC-side power/energy of the PCS (Power Conversion System) and the import/export data at the grid interconnection point belong to EnergyManagement or ElectricityMetering and, being affected by power conversion losses, SHALL not be directly equated with the battery-side metering values.
Rated capacity, usable capacity, SOC allowable range, maximum charge/discharge power, and SOH are all optional capabilities and are not required for every energy storage device. Consumers can estimate the currently available energy only when both a trustworthy, valid, and sufficiently fresh StateOfCharge and the current UsableEnergyCapacity exist; RatedEnergyCapacity, SOH, or power limits cannot replace either of them. The calculation rules are described in EnergyManagement.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x013C | EnergyStorage | Energy storage |
Trait
Command
This Function does not contain any Commands.
Trait Definitions
StorageOperationModeEnum8 Type
This enumeration defines the operating modes of the energy storage device.
| Value | Name | Description |
|---|
| 0x00 | RapidCharging | Fast charge |
| 0x01 | Charging | Charge |
| 0x02 | Discharging | Discharge |
| 0x03 | Standby | Standby |
| 0x04 | Test | Test |
| 0x05 | Automatic | Automatic |
| 0x06 | Restart | Restart |
| 0x07 | EffectiveCapacityRecalculation | Usable capacity recalculation |
| 0x08 | Other | Other |
StateOfCharge Trait
State of Charge (SOC) represents the percentage estimate of the currently available energy of the energy storage battery relative to the current available full charge capacity, measured or estimated by the BMS. SOC of 0% indicates reaching the BMS-configured discharge floor, and 100% indicates reaching the BMS-configured charge ceiling; it does not represent the absolute chemical empty/full state of the cells, nor does it directly represent the remaining kWh available to the load. The SOC reported by the device MUST conform to this definition; when its meaning, validity, or freshness cannot be confirmed, it MUST NOT be used as a trustworthy SOC for derivation. Unit %, accuracy 0.1%. Used for energy management interface display, charge/discharge strategies, and low-battery determination. When the device temporarily cannot determine SOC, the value SHALL be marked as unavailable rather than falsely reported as 0%.
| Trait ID | Code |
|---|
| 0x51F9 | StateOfCharge |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-100 % | No fixed default; report the current BMS value | RV | M |
| 0x0002 | Maximum Value | float | | No fixed default; optionally report the device-allowed SOC ceiling | R | O |
| 0x0003 | Minimum Value | float | | No fixed default; optionally report the device-allowed SOC floor | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
StoredEnergy Trait
The remaining stored energy represents the energy currently stored in the battery, in kWh; it is an absolute energy value, not a state-of-charge percentage or usable capacity. When reported directly by the device, the effective measured value of the device SHALL be used. Consumers may estimate it as UsableEnergyCapacity x StateOfCharge / 100 only when StateOfCharge is trustworthy and UsableEnergyCapacity is currently valid; the rated capacity SHALL NOT be used in place of the usable capacity, and missing or invalid inputs SHALL NOT be treated as 0.
| Trait ID | Code |
|---|
| 0x520A | StoredEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 kWh | No fixed default; report the current value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
ACChargeCapacity Trait
The AC charge usable capacity represents the effective energy capacity available for charging under the device-defined AC-side metering boundary, in W·h; it SHALL NOT be confused with the battery DC-side rated capacity or usable capacity.
| Trait ID | Code |
|---|
| 0x520B | ACChargeCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | No fixed default; report the device value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACDischargeCapacity Trait
The AC discharge usable capacity represents the effective energy capacity available for discharging under the device-defined AC-side metering boundary, in W·h; it is not equivalent to the battery-side usable capacity.
| Trait ID | Code |
|---|
| 0x520C | ACDischargeCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | No fixed default; report the device value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACChargeableCapacity Trait
The AC chargeable capacity represents the energy that can still be charged under the current AC-side metering boundary, in W·h.
| Trait ID | Code |
|---|
| 0x520D | ACChargeableCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | No fixed default; report the device value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACDischargeableCapacity Trait
The AC dischargeable capacity represents the energy that can still be discharged under the current AC-side metering boundary, in W·h.
| Trait ID | Code |
|---|
| 0x520E | ACDischargeableCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | No fixed default; report the device value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACChargeableEnergy Trait
The AC chargeable energy represents the additional charging energy the device allows under the current conditions, in W·h.
| Trait ID | Code |
|---|
| 0x520F | ACChargeableEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | No fixed default; report the device value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACDischargeableEnergy Trait
The AC dischargeable energy represents the additional discharging energy the device allows under the current conditions, in W·h.
| Trait ID | Code |
|---|
| 0x5210 | ACDischargeableEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | No fixed default; report the device value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACCumulativeChargeEnergy Trait
The AC-side cumulative charge energy represents the non-negative cumulative value within the current counter generation, in W·h; the metering boundary of this quantity is defined by the energy storage device and SHALL NOT be confused with the battery DC-side CumulativeChargeEnergy. Counter generation rules are described in EnergyManagement.
| Trait ID | Code |
|---|
| 0x5211 | ACCumulativeChargeEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACCumulativeDischargeEnergy Trait
The AC-side cumulative discharge energy represents the non-negative cumulative value within the current counter generation, in W·h; the metering boundary of this quantity is defined by the energy storage device and SHALL NOT be confused with the battery DC-side CumulativeDischargeEnergy. Counter generation rules are described in EnergyManagement.
| Trait ID | Code |
|---|
| 0x5212 | ACCumulativeDischargeEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACRatedEnergy Trait
The AC rated energy represents the nominal energy capacity on the AC side of the device, in W·h; its conversion relationship with the battery DC-side rated capacity is determined by the product specification.
| Trait ID | Code |
|---|
| 0x5213 | ACRatedEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
StorageRatedVoltage Trait
The energy storage rated voltage represents the nominal operating voltage of the energy storage device, in V.
| Trait ID | Code |
|---|
| 0x5214 | StorageRatedVoltage |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 V | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
StorageChargeDischargePower Trait
The instantaneous charge/discharge power is expressed as a single signed value, in W; positive indicates charging, negative indicates discharging, and zero indicates no power flow. It SHALL NOT be metered redundantly on the same boundary together with the separately reported battery-side ChargePower and DischargePower.
| Trait ID | Code |
|---|
| 0x5215 | StorageChargeDischargePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | -5000000-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | -5000000 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ACChargingAmountSetting Trait
The AC charge energy setting represents the target charge energy allowed on the AC side of the device, in W·h.
| Trait ID | Code |
|---|
| 0x5216 | ACChargingAmountSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | 0-999999999 W·h | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 999999999 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
ACDischargingAmountSetting Trait
The AC discharge energy setting represents the target discharge energy allowed on the AC side of the device, in W·h.
| Trait ID | Code |
|---|
| 0x5217 | ACDischargingAmountSetting |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | 0-999999999 W·h | No fixed default; report the current setting | RVW | O |
| 0x0002 | Maximum Value | uint32 | | 999999999 | R | O |
| 0x0003 | Minimum Value | uint32 | | 0 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
BatteryType Trait
The battery type represents the battery category identifier reported by the device, using a text value to preserve the category name given by the device; it is not used to indicate battery status.
| Trait ID | Code |
|---|
| 0x5218 | BatteryType |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | characterString | Device-defined category name | No fixed default | RV | O |
StorageOperationMode Trait
The energy storage operating mode represents the operating mode set on the device and is read-write.
| Trait ID | Code |
|---|
| 0x522E | StorageOperationMode |
Parameters
WorkingStorageOperationMode Trait
The actual energy storage operating mode represents the operating mode currently being executed by the device; its enumeration values use the same definitions as the set mode.
| Trait ID | Code |
|---|
| 0x522F | WorkingStorageOperationMode |
Parameters
RatedEnergyCapacity Trait
The rated capacity represents the manufacturer-nominal battery energy capacity, in kWh. This value is a product specification parameter, usually given under the battery rated test conditions; it is not the remaining energy corresponding to the current SOC, nor does it equal the currently usable capacity after deducting the BMS protection range. It is used for product specification display and system capacity planning.
| Trait ID | Code |
|---|
| 0x51FA | RatedEnergyCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0.001-1000000 kWh | No fixed default; determined by the product specification | RV | M |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0.001 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
UsableEnergyCapacity Trait
The usable capacity represents the energy capacity available for charging and discharging under the current BMS operating boundaries, in kWh. This value may vary with temperature, SOH, protection strategies, or operating conditions; implementations SHALL use the current estimated value of the device usable capacity and SHALL NOT confuse it with the manufacturer-nominal RatedEnergyCapacity. It is used for scheduling charge/discharge and estimating dispatchable energy.
| Trait ID | Code |
|---|
| 0x51FB | UsableEnergyCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 kWh | No fixed default; report the current BMS value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
CumulativeChargeEnergy Trait
The cumulative charge energy represents the cumulative electrical energy flowing into the battery within the current counter generation, with the metering boundary at the battery DC terminal. This is a non-negative cumulative value, in W·h, and is not offset by the discharge energy. It is used to analyze the battery charging process and cyclic energy throughput; to calculate round-trip efficiency, ensure that the charge and discharge energy cover the same battery-side boundary and statistics period. Device restarts SHALL NOT clear readings or generations; resets, uncompensated rollbacks, and meter replacements MUST increment the Counter Generation.
| Trait ID | Code |
|---|
| 0x51FC | CumulativeChargeEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
CumulativeDischargeEnergy Trait
The cumulative discharge energy represents the cumulative electrical energy flowing out of the battery within the current counter generation, with the metering boundary at the battery DC terminal. This is a non-negative cumulative value, in W·h, independent of the cumulative charge energy. It is used to analyze the battery discharge process, energy utilization, and cycle statistics; device restarts SHALL NOT clear readings or generations; resets, uncompensated rollbacks, and meter replacements MUST increment the Counter Generation.
| Trait ID | Code |
|---|
| 0x51FD | CumulativeDischargeEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
ChargePower Trait
The charge power represents the active power currently flowing into the battery, with the metering boundary at the battery DC terminal, in W. This value is always non-negative; it reports 0 when there is no charging. It is reported separately from DischargePower to avoid the charge/discharge meaning varying by vendor when a single signed value is used. It is used for real-time monitoring and charge power scheduling.
| Trait ID | Code |
|---|
| 0x51FE | ChargePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | No fixed default; optionally report the maximum charge power supported by the device | R | O |
| 0x0003 | Minimum Value | float | | No fixed default; optionally report the minimum charge power supported by the device | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
DischargePower Trait
The discharge power represents the active power currently flowing out of the battery, with the metering boundary at the battery DC terminal, in W. This value is always non-negative; it reports 0 when there is no discharging. It is reported separately from ChargePower. It is used for real-time monitoring and dispatchable discharge power calculation.
| Trait ID | Code |
|---|
| 0x51FF | DischargePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | No fixed default; optionally report the maximum discharge power supported by the device | R | O |
| 0x0003 | Minimum Value | float | | No fixed default; optionally report the minimum discharge power supported by the device | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
StateOfHealth Trait
The battery health (SOH) represents the battery health state, ranging from 0-100%. For interoperability, it is defined as the percentage of the current usable energy capacity relative to the initial usable energy capacity defined by the manufacturer; 100% indicates the same as that baseline, and a lower value indicates usable capacity degradation. If the device calculates it by another algorithm, the product documentation MUST explain this, and SOH values from different algorithms SHALL NOT be directly compared. It is used to evaluate battery degradation and maintenance status. Unit %, accuracy 0.1%.
| Trait ID | Code |
|---|
| 0x5200 | StateOfHealth |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-100 % | No fixed default; report the current BMS value | RV | O |
| 0x0002 | Maximum Value | float | | 100 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
Command Definitions
This Function does not contain any Commands.
ElectricityMetering (Electricity Metering)
Introduction
ElectricityMetering is used to describe the metering capabilities of electricity meters and the point of common coupling (PCC), including measurement points, directional real-time active power, demand, and time-of-use cumulative energy. This Function supplements the general electrical measurement capabilities of EnergyManagement; meters used for grid settlement or home energy management SHALL also implement EnergyManagement to report general electrical data such as imported/exported cumulative active energy.
This Function targets metering at the grid connection point (PCC). The import direction of the PCC is from the grid to the user side, and the export direction is from the user side to the grid. Power may use signed values to indicate direction, while imported and exported energy and time-of-use energy are accumulated separately with non-negative counters. The rate numbers of time-of-use registers are defined by the meter/rate plan; categories such as Peak and OffPeak serve only as general classifications and cannot replace a specific rate plan.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x013D | ElectricityMetering | Electricity metering |
Trait
If CurrentDemand or MaximumDemand exists, DemandIntervalDuration and DemandCalculationMethod MUST also exist; if MaximumDemand exists, MaximumDemandTimestamp and DemandPeriodStartTimestamp MUST exist. This allows consumers to determine the demand averaging window, the calculation method, and the billing period to which the maximum value belongs.
Command
This Function does not contain any Commands. The maximum demand billing period is determined by the meter or its rate configuration; this Function provides the period start time and the end time of the maximum demand interval, and does not define a Command to remotely reset the demand counter.
Data Types
MeteringPointTypeEnum8 Type
This enumeration identifies the metering location of the electricity meter. PCC is currently defined to distinguish user-side import/export from generation-side metering.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown or not configured |
| 0x01 | GridConnectionPoint | Point of common coupling (PCC) between the grid and the user energy system |
TariffCategoryEnum8 Type
This enumeration provides generic rate period classifications for time-of-use registers. The actual rate numbers and their applicable times are determined by the meter/rate plan; the enumeration categories are used only for display and coarse-grained aggregation.
| Value | Name | Description |
|---|
| 0x00 | Unspecified | Unspecified category |
| 0x01 | OffPeak | Off-peak period or low rate period |
| 0x02 | Shoulder | Shoulder period or intermediate rate period |
| 0x03 | Peak | Peak period or high rate period |
| 0x04 | CriticalPeak | Critical peak or special high rate period |
DemandCalculationMethodEnum8 Type
This enumeration identifies the calculation method of the demand integration interval. The device MUST provide this item when reporting demand, and MUST NOT report Unknown together with a valid demand result, to prevent consumers from mixing fixed-interval and sliding-interval results.
| Value | Name | Description |
|---|
| 0x00 | Unknown | Unknown or not configured |
| 0x01 | FixedBlock | Fixed block; average power calculated over consecutive non-overlapping intervals |
| 0x02 | RollingWindow | Rolling window; average power calculated over a continuously moving time window |
TariffEnergyRegisterStructure Type
This structure describes the identity of a rate register and its imported/exported cumulative active energy. Directions not measured by the device may be omitted; the same rate register ID MUST be unique and stable within one meter endpoint.
| Member Index | Field Name | Type | Required | Minimum | Maximum | Step | Unit | Default | Description |
|---|
| 0 | TariffRegisterId | uint8 | M | 1 | 16 | 1 | None | None | Rate register identifier, unique within this meter endpoint. The specific time period semantics are determined by the meter rate plan. |
| 1 | TariffCategory | TariffCategoryEnum8 | O | 0 | 4 | 1 | None | 0 | Generic rate category. Use Unspecified when no generic category corresponds. |
| 2 | ImportedActiveEnergy | float | O | 0 | 1000000000000 | 0.1 | W·h | None | Cumulative active energy imported from the grid under this rate register, a non-negative cumulative value; when the implementation cannot guarantee continuous logical accumulation and precise differences are required, it MUST be provided together with ImportedCounterGeneration. |
| 3 | ExportedActiveEnergy | float | O | 0 | 1000000000000 | 0.1 | W·h | None | Cumulative active energy exported to the grid under this rate register, a non-negative cumulative value; when the implementation cannot guarantee continuous logical accumulation and precise differences are required, it MUST be provided together with ExportedCounterGeneration. |
| 4 | ImportedCounterGeneration | uint32 | O | 0 | 4294967295 | 1 | None | 0 | When the implementation cannot guarantee continuous logical accumulation and precise differences are required, it MUST be provided if ImportedActiveEnergy exists; counter generation rules are described in EnergyManagement. |
| 5 | ExportedCounterGeneration | uint32 | O | 0 | 4294967295 | 1 | None | 0 | When the implementation cannot guarantee continuous logical accumulation and precise differences are required, it MUST be provided if ExportedActiveEnergy exists; counter generation rules are described in EnergyManagement. |
Each structure SHALL contain at least one of ImportedActiveEnergy or ExportedActiveEnergy. The data type is a list of up to 16 TariffEnergyRegisterStructure; an empty list indicates that the device currently provides no time-of-use register data.
Trait Definitions
GridActivePower Trait
The grid active power represents the current net active power at the PCC, in W, using a signed value: positive indicates importing from the grid (purchasing), negative indicates exporting to the grid (feeding), and zero indicates the current net power is near zero. This value is the net of the import power and the export power, and does not represent the instantaneous power of each direction separately; directional cumulative quantities SHALL use CurrentForwardTotalActiveEnergy and CurrentReverseTotalActiveEnergy in EnergyManagement. It is used for energy flow display, PV self-consumption/feed-in status determination, and energy management strategies.
| Trait ID | Code |
|---|
| 0x5201 | GridActivePower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | -5000000-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | -5000000 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
MeteringPointType Trait
The metering point type represents the measurement boundary of the electricity meter. When set to GridConnectionPoint, the import/export and active power signs of this Function are defined according to the PCC direction. When the metering location is unknown, report Unknown and do not infer the boundary from the device model. It is used to prevent incorrectly comparing grid connection point energy with generator or battery-side energy.
| Trait ID | Code |
|---|
| 0x5202 | MeteringPointType |
Parameters
DemandIntervalDuration Trait
The demand interval represents the length of the integration interval used to calculate the current demand and the maximum demand, in seconds. Demand is the average imported active power within this interval; this field describes the averaging window length, not the reporting interval. 15 minutes (900 seconds) is a common default integration period, and meters may still configure other periods according to local billing rules. It is used to interpret demand data and perform cross-device comparisons.
| Trait ID | Code |
|---|
| 0x5203 | DemandIntervalDuration |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint32 | 60-3600 s | 900 | RV | O |
| 0x0002 | Maximum Value | uint32 | | 3600 | R | O |
| 0x0003 | Minimum Value | uint32 | | 60 | R | O |
| 0x0005 | Step Value | uint32 | | 1 | R | O |
CurrentDemand Trait
The current demand represents the average imported active power within the current demand integration interval, in W, non-negative. When the interval is not yet complete, the device may report the interval average up to the current moment, but it MUST be calculated consistently; consumers SHALL understand its time window through DemandIntervalDuration. Export power is not included in the imported demand. It is used for real-time observation of billing demand growth trends and is not equivalent to the instantaneous net power of GridActivePower.
| Trait ID | Code |
|---|
| 0x5204 | CurrentDemand |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
MaximumDemand Trait
The maximum demand represents the maximum of the average imported active power over all demand integration intervals within the current billing period, in W, non-negative. It is not an instantaneous power peak and does not include export demand. The billing period is determined by the meter/rate plan, and its start time is reported through DemandPeriodStartTimestamp; the maximum is recalculated when a new billing period begins. The end time of the interval in which the maximum occurred is reported through MaximumDemandTimestamp. It is used for demand charge assessment and peak load analysis within the billing period.
| Trait ID | Code |
|---|
| 0x5205 | MaximumDemand |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | 0 | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
MaximumDemandTimestamp Trait
The maximum demand timestamp represents the end time of the demand interval in which the current recorded MaximumDemand occurred, as a UTC (Coordinated Universal Time) Unix epoch (from 1970-01-01T00:00:00Z) millisecond timestamp. A value of 0 indicates that the device has not yet recorded a valid maximum demand time. This timestamp, together with DemandIntervalDuration, identifies the complete integration interval that produced the maximum demand, and is used for bill verification and load event analysis.
| Trait ID | Code |
|---|
| 0x5206 | MaximumDemandTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | 0-253402300799999 ms | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 253402300799999 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint64 | | 1 | R | O |
DemandPeriodStartTimestamp Trait
The billing period start timestamp represents the start time of the billing period to which the current MaximumDemand belongs, as a UTC (Coordinated Universal Time) Unix epoch (from 1970-01-01T00:00:00Z) millisecond timestamp. The billing period boundary is determined by the meter billing calendar or rate plan; the maximum demand SHALL be recalculated when the period starts. A value of 0 indicates that the device has not provided a period start time. It is used to determine the statistics scope of the maximum demand and to avoid directly comparing values from different billing periods.
| Trait ID | Code |
|---|
| 0x5207 | DemandPeriodStartTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | 0-253402300799999 ms | 0 | RV | O |
| 0x0002 | Maximum Value | uint64 | | 253402300799999 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint64 | | 1 | R | O |
TariffEnergyRegisters Trait
The time-of-use energy register represents the imported and/or exported active energy accumulated separately by rate register in the meter. Each register has a stable and unique TariffRegisterId; the specific rate schedule, seasonal, and holiday rules of the register are configured by the meter or an external rate plan, and this Trait does not transmit the rate calendar. The category enumeration provides only coarse-grained labels and SHALL NOT be used to replace rate IDs or to calculate charges from it. Each energy value is a non-negative cumulative value, in W·h; device restarts SHALL NOT cause logical cumulative values to roll back. When the implementation cannot guarantee continuous logical accumulation and precise differences are required, a corresponding generation field MUST be provided for each direction. Counter generation rules are described in EnergyManagement. It is used for critical-peak/shoulder/off-peak statistics, time-of-use billing, and demand-side energy analysis.
| Trait ID | Code |
|---|
| 0x5208 | TariffEnergyRegisters |
Parameters
DemandCalculationMethod Trait
The demand calculation method represents the window method used by the meter to calculate demand. FixedBlock divides continuous time into non-overlapping fixed intervals; RollingWindow uses a continuously sliding window. This method MUST be used together with DemandIntervalDuration to interpret CurrentDemand and MaximumDemand; units do not apply. It is used to ensure that the demand calculation basis of different meters is clear.
| Trait ID | Code |
|---|
| 0x5209 | DemandCalculationMethod |
Parameters
BranchCircuitMeasurementStructure Type
This structure represents the metering data of one distribution circuit. The channel identifier is unique and stable within the device; metering directions or instantaneous power fields not provided by the device may be omitted.
| Structure Member Index | Field Name | Type | Required | Description |
|---|
| 0 | ChannelId | uint16 | M | Distribution circuit channel number, unique and stable within the same device. |
| 1 | ImportedActiveEnergy | float | O | Circuit forward cumulative energy, non-negative value, in W·h; provide it together with the field ImportedCounterGeneration when generation is needed. |
| 2 | ExportedActiveEnergy | float | O | Circuit reverse cumulative energy, non-negative value, in W·h; provide it together with the field ExportedCounterGeneration when generation is needed. |
| 3 | ActivePower | float | O | Circuit instantaneous active power, in W; positive indicates import/consumption, negative indicates export/reverse power flow. |
| 4 | ImportedCounterGeneration | uint32 | O | When continuous logical accumulation cannot be guaranteed and precise differences are required, it MUST be provided if ImportedActiveEnergy is provided. Rules are described in EnergyManagement. |
| 5 | ExportedCounterGeneration | uint32 | O | When continuous logical accumulation cannot be guaranteed and precise differences are required, it MUST be provided if ExportedActiveEnergy is provided. Rules are described in EnergyManagement. |
BranchCircuitMeasurements Trait
The branch circuit measurement data represents the cumulative imported/exported energy and instantaneous active power of each circuit in the distribution panel. The Present Value is a list of BranchCircuitMeasurementStructure; channel numbers MUST be unique and stable within the device, and each list item SHALL contain at least one measurement value. If ECHONET Lite provides raw counts in device cumulative energy units, the conversion SHALL first convert to W·h by the device unit and then write to the corresponding structure field.
| Trait ID | Code |
|---|
| 0x523F | BranchCircuitMeasurements |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | list[BranchCircuitMeasurementStructure] | According to the number of circuits supported by the device | [] | RV | O |
Command Definitions
This Function does not contain any Commands.
PowerGeneration (Power Generation)
Introduction
PowerGeneration is used to represent the rated output capability and generation operating state of power generation equipment, and provides gas consumption, load-side electricity usage, and heat recovery data for fuel cells and gas cogeneration equipment. The grid connection state is represented by EnergyManagement/SystemInterconnectionStatus. The instantaneous generation power and cumulative generation energy reuse EnergyManagement/GeneratedActivePower and EnergyManagement/CumulativeGeneratedActiveEnergy; this Function does not change their metering boundary conventions.
Function Identifier
| Function ID | Code | Name |
|---|
| 0x013E | PowerGeneration | Power generation |
Trait
Command
This Function does not contain any Commands. Until the value semantics of generation settings and scheduled generation states are clarified, no corresponding control interface is defined.
Data Types
PowerGenerationStatusEnum8 Type
This enumeration defines the current operating state of the power generation device.
| Value | Name | Description |
|---|
| 0x00 | Stopped | Stopped |
| 0x01 | Starting | Starting |
| 0x02 | Generating | Generating |
| 0x03 | Stopping | Stopping |
| 0x04 | Idling | Standby |
Trait Definitions
RatedGenerationPower Trait
The rated generation power represents the nominal maximum output power of the power generation device, in W.
| Trait ID | Code |
|---|
| 0x5230 | RatedGenerationPower |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-5000000 W | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 5000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
PowerGenerationStatus Trait
The generation state represents the current operating stage of the power generation device.
| Trait ID | Code |
|---|
| 0x5231 | PowerGenerationStatus |
Parameters
CumulativeGasConsumption Trait
The cumulative gas consumption represents the volume of gas consumed within the current counter generation, in m^3; device restarts SHALL NOT clear readings or generations, and counter resets, uncompensated rollbacks, or meter replacements MUST increment the Counter Generation. Counter generation rules are described in EnergyManagement.
| Trait ID | Code |
|---|
| 0x5233 | CumulativeGasConsumption |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 m^3 | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.001 | R | O |
RecoveredWaterTemperature Trait
The heat recovery water temperature represents the water temperature in the heat recovery system of the power generation device, in deg C.
| Trait ID | Code |
|---|
| 0x5236 | RecoveredWaterTemperature |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | -50-150 deg C | No fixed default; report the current value | RV | O |
| 0x0002 | Maximum Value | float | | 150 | R | O |
| 0x0003 | Minimum Value | float | | -50 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
RemainingHotWaterAmount Trait
The remaining hot water volume represents the volume of hot water currently available in the hot water storage device, in L.
| Trait ID | Code |
|---|
| 0x5237 | RemainingHotWaterAmount |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 L | No fixed default; report the current value | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
HotWaterTankCapacity Trait
The hot water tank capacity represents the nominal storage volume of the tank, in L.
| Trait ID | Code |
|---|
| 0x5238 | HotWaterTankCapacity |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000 L | No fixed default; determined by the product specification | RV | O |
| 0x0002 | Maximum Value | float | | 1000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |
PowerGenerationRequestTimestamp Trait
The generation request time represents the generation request moment recorded by the power generation device, as a UTC Unix epoch millisecond timestamp; 0 indicates that the device has not provided a valid moment. When converting an external time representation to this format, its time zone semantics SHALL be followed; when the time or time zone cannot be determined, it MUST NOT be guessed.
| Trait ID | Code |
|---|
| 0x523E | PowerGenerationRequestTimestamp |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | uint64 | 0-253402300799999 ms | No fixed default; report the device-recorded value | RV | O |
| 0x0002 | Maximum Value | uint64 | | 253402300799999 | R | O |
| 0x0003 | Minimum Value | uint64 | | 0 | R | O |
| 0x0005 | Step Value | uint64 | | 1 | R | O |
CumulativeSoldEnergy Trait
The cumulative sold energy represents the cumulative active energy sold externally by the power generation device, in W·h. Its metering boundary is determined by the selling metering point of the power generation device and is not equivalent to the total device generation; when the implementation cannot guarantee continuous logical accumulation and precise differences are required, the Counter Generation SHALL also be reported, with generation change rules described in EnergyManagement.
| Trait ID | Code |
|---|
| 0x5239 | CumulativeSoldEnergy |
Parameters
| Parameter ID | Name | Type | Constraint | Default | Access | Conformance |
|---|
| 0x0001 | Present Value | float | 0-1000000000000 W·h | 0 | RV | O |
| 0x0010 | Counter Generation | uint32 | 0-4294967295 | 0 | R | O |
| 0x0002 | Maximum Value | float | | 1000000000000 | R | O |
| 0x0003 | Minimum Value | float | | 0 | R | O |
| 0x0005 | Step Value | float | | 0.1 | R | O |