Skip to main content

Command Codes

APIUnbindWiFiSubdevice​

Reports successful unbinding of a Wi-Fi child device. The device reports to the cloud that a Wi-Fi child device has been successfully unbound (removed) from this device or its bridge management.

Parameters​

This Command has no parameters.

APICheckCarDataConsistency​

Vehicle recognition data consistency verification request. The device reports summary information for its locally stored vehicle recognition feature database to the cloud, requests comparison and receives differences (vehicle data to add or delete), to keep the vehicle database synchronized.

Parameters​

This Command has no parameters.

APIBindWiFiSubdevice​

Reports successful binding of a Wi-Fi child device. The device reports to the cloud that a Wi-Fi child device (such as a Wi-Fi camera or smart plug) has been successfully bound to the home network and user account through this device or its bridging capability.

Parameters​

This Command has no parameters.

APIOperateBridgedDevice​

Bridged device operation command. The cloud sends a command through the gateway to a device acting as a bridge (for example, a multifunction gateway or repeater), instructing it to perform a specific operation (for example, on/off or configuration) on its connected or managed child devices.

Parameters​

This Command has no parameters.

APIDeviceCameraCall​

Call request initiated by a device (such as a camera). When a camera or other device detects a specific event (such as a doorbell press or motion detection), it proactively sends an audio/video call or push-notification request to the cloud for the user to answer or view.

Parameters​

This Command has no parameters.

APIOperateCameraUp​

Camera upstream operation request. The device proactively sends a request to the cloud for a special camera operation, such as requesting cloud AI analysis of a video clip, applying for a temporary increase in cloud storage quota, or reporting a self-check exception.

Parameters​

This Command has no parameters.

APIIssueTokenForWebRTCCall​

WebRTC device call-token issuance request. When a WebRTC-enabled video device (such as a camera) needs to establish peer-to-peer audio/video calling or streaming, it requests that the cloud issue a temporary security token on its behalf for authentication and session establishment.

Parameters​

This Command has no parameters.

APIOperateCameraDown​

Camera downstream operation command. The cloud sends specific control commands to a camera device, such as pan-tilt control, adding or recalling presets, face-database management, and cruise settings.

Parameters​

This Command has no parameters.

APIGetSignallingServerAddress​

Signaling server address retrieval request. The device queries the cloud for a list of currently available signaling server addresses to support P2P connection negotiation for devices using real-time communication protocols such as WebRTC.

Parameters​

This Command has no parameters.

APIReportCameraExtEvents​

Camera extended business event report. The device reports to the cloud extended events generated by the camera that go beyond basic state changes (for example, intelligent recognition results, abnormal-behavior alerts, and scene-analysis events), for advanced applications and AI analysis.

Parameters​

This Command has no parameters.

APICheckFaceDataConsistency​

Face recognition data consistency verification request. The device reports summary information for its locally stored face recognition feature database to the cloud, requests comparison and receives differences (face data to add or delete), to keep the face database synchronized.

Parameters​

This Command has no parameters.

APIUnbindHubDown​

Hub downstream unbinding command. The cloud commands the Hub to execute the unbinding process from the current user account, typically including resetting network settings, clearing user data, and preparing for binding by a new user.

Parameters​

This Command has no parameters.

APIUploadDeviceInfo​

Device information update report. The device reports changes to attribute information for itself or its managed child devices (such as name changes, location adjustments, or icon updates), requesting the cloud to update the device profile synchronously.

Parameters​

This Command has no parameters.

APIReportDeviceResponse​

Device command execution response report. After executing a control or query command issued by the cloud, the device reports the specific response result it returned (including success, failure, and detailed data), completing the command interaction loop.

Parameters​

This Command has no parameters.

APIGetSubdeviceConfig​

Child device detailed configuration query request. The gateway queries the cloud for detailed configuration information for a specified child device.

Parameters​

This Command has no parameters.

APICheckHubDataConsistency​

Hub data consistency verification command. The cloud proactively requests that the Hub compare the summary of its stored data with the cloud.

Parameters​

This Command has no parameters.

APICheckHubLocalSync​

Hub local information bidirectional synchronization verification request. The Hub proactively sends a verification request to the cloud, compares its local information summary with the cloud, detects and corrects inconsistencies, and ensures data integrity.

Parameters​

This Command has no parameters.

APIGetLoginRandomCode​

Device login nonce retrieval request. During device login or authentication, the device requests a nonce from the cloud to construct security credentials that protect against replay attacks.

Parameters​

This Command has no parameters.

APIGetRandomJoinCode​

Five-tuple child-device network-entry random-code retrieval request. Under the five-tuple security framework, the gateway requests a one-time random join code from the cloud for a new child device preparing to join the network, ensuring the security and uniqueness of the network-entry process.

Parameters​

This Command has no parameters.

APIClearHubConfig​

Hub system configuration clearing command. The cloud commands the Hub to clear specified system configuration and restore it to the factory-default or empty state.

Parameters​

This Command has no parameters.

APISyncDataCloudToHub​

Cloud-to-Hub batch data synchronization command. The cloud sends data packets to the Hub to batch-synchronize non-real-time business data such as user configurations, device relationships, and scene rules, ensuring that the Hub can restore its complete service state after being offline or initialized.

Parameters​

This Command has no parameters.

APIReportSubdeviceModel​

Child-device data-model information report. After discovering a new child device or upgrading child-device firmware, the gateway reports its complete supported data-model definitions (functions, properties, commands, and events) to the cloud, to update the device capability database and generate the UI dynamically.

Parameters​

This Command has no parameters.

APIClearLocalData​

Hub local data clearing command. The cloud commands the Hub to clear specific types of, or all, user data and configurations (such as scenes and device bindings) that were synchronized from the cloud and stored locally, typically for account switching or data reset.

Parameters​

This Command has no parameters.

APINotifyConfigChange​

Hub configuration change notification command. The cloud notifies the Hub that part of its configuration has changed in the cloud, requiring the Hub to proactively retrieve the latest configuration or prepare to apply new configuration, thereby actively pushing changes.

Parameters​

This Command has no parameters.

APIGetVoiceFileUrl​

Voice prompt file URL retrieval request. The gateway requests from the cloud the download URL or configuration information for voice prompt files (such as alarm sounds or greetings), for local playback.

Parameters​

This Command has no parameters.

APIDisableSubdeviceJoining​

Child-device network-entry mode disable command. The cloud commands the gateway to immediately exit pairing/discovery mode for new child devices and resume normal operation.

Parameters​

This Command has no parameters.

APIAskOtherHubToken​

Request for another gateway's security token. In scenarios requiring cross-gateway collaboration or access, the gateway requests from the cloud the security token of another specified gateway to establish secure direct or indirect communication with it.

Parameters​

This Command has no parameters.

APISubdeviceKeepAlive​

Child-device online heartbeat report. Periodically or when a child device's status changes, the gateway reports the online status (heartbeat) of its managed child devices to the cloud, allowing the cloud to monitor device liveness and update the online indicator in the device list.

Parameters​

This Command has no parameters.

APIBindBleDeviceToHub​

Bluetooth device binding to ZigBee Hub command.

Parameters​

This Command has no parameters.

APIReportHeartbeat​

Hub self online heartbeat report. The Hub periodically sends a heartbeat signal to the cloud, indicating that it itself (not a child device) is online and operating normally, so the cloud can monitor the Hub's liveness.

Parameters​

This Command has no parameters.

APIGetInstallCode​

Five-tuple Install Code retrieval request. A device using the five-tuple security model requests its unique “Install Code” from the cloud for identity verification during the secure network-entry process.

Parameters​

This Command has no parameters.

APIReportPropertyExamination​

Debugging and diagnostic information 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.

Parameters​

This Command has no parameters.

APIBindSubdeviceWithSecurityCode​

Security-code-based five-tuple model child-device binding request. When a new gateway using the five-tuple authentication model binds a child device, it reports the child-device information and pre-shared security code to the cloud and requests that the cloud verify the security code's validity to complete secure binding.

Parameters​

This Command has no parameters.

APIStartHubProvisioning​

Hub network-entry configuration information delivery command. After a new Hub is powered on for the first time or reset, the cloud delivers the guidance information it needs to join the network, such as available server addresses, a configuration token, or initial configuration, guiding it to complete initialization.

Parameters​

This Command has no parameters.

APIReportHubLocalInfo​

Device local comprehensive information report. The device proactively reports local information to the cloud for overall status awareness and data backup.

Parameters​

This Command has no parameters.

APIUnsubscribeDeviceResource​

Device-initiated resource unsubscription request. The device (or its representing gateway) requests that the cloud stop pushing updates for one or more previously subscribed device resources.

Parameters​

This Command has no parameters.

APIReportHubLocalConfig​

Hub detailed local configuration report. The Hub proactively reports its detailed local system configuration to the cloud.

Parameters​

This Command has no parameters.

APICheckHubConfig​

Hub system configuration verification command. The cloud issues a command requiring the Hub to self-check its current system-level configuration and report the verification result or a configuration summary.

Parameters​

This Command has no parameters.

APIPushHubConfig​

Hub system configuration delivery command. The cloud delivers system-level configuration parameters or policy files to the Hub to update or initialize its operating environment, functional-module parameters, or connection strategy.

Parameters​

This Command has no parameters.

APIQueryDeviceResMultiExtGbk​

Device resource multi-value extended query request (GBK encoding). Request and response text data use GBK character encoding to be compatible with systems or devices requiring that encoding format.

Parameters​

This Command has no parameters.

APIReportExceptionLog​

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.

Parameters​

This Command has no parameters.

APINotifySubdeviceReadResult​

Asynchronous report of child-device proactive data read results. In response to the cloud's APITriggerSubdeviceRead command, after completing data reading from the target child device, the gateway asynchronously reports the read result (or timeout/failure status) to the cloud, completing this on-demand query loop.

Parameters​

This Command has no parameters.

APISubscribeDeviceResource​

Device-initiated resource subscription request. The device (or its representing gateway) requests that the cloud begin subscribing to changes to one or more device resources. When a resource value changes, the cloud proactively pushes an update.

Parameters​

This Command has no parameters.

APIReportCommandExecResult​

Cloud predefined instruction execution result report. After executing a cloud-delivered predefined function instruction through APIRunFunctionInstruction, the Hub reports the instruction's success/failure result, output data, or error details to the cloud.

Parameters​

This Command has no parameters.

APIGetWeatherData​

Weather data retrieval request. The device requests the current weather, forecast, and other meteorological information for a specified location from the cloud, for smart scene triggering or UI display.

Parameters​

This Command has no parameters.

APIConnectHub​

Hub network-entry request. The Hub uses the new network-entry protocol and process (version V1.0) to send a network-entry request to the cloud, submitting device credentials and network information to complete identity registration and network access.

Parameters​

This Command has no parameters.

APIUnbindHubUp​

Hub upstream unbinding request. The Hub proactively sends an unbinding request from the current user account to the cloud, typically triggered by the user.

Parameters​

This Command has no parameters.

APISyncTokenDown​

Device token synchronization downstream command. The cloud delivers the latest authorization token or other security credential for the user or device to the device, updating the authentication information it uses to communicate with the cloud or other services.

Parameters​

This Command has no parameters.

APIRefreshHubToken​

Five-tuple gateway token refresh request. When its current security token is about to expire, a gateway using the five-tuple authentication model requests a new valid token from the cloud to maintain secure communication with the cloud.

Parameters​

This Command has no parameters.

APIRpcDebugCommand​

Gateway remote procedure call (RPC) debugging command. The cloud sends a general RPC debugging command to the gateway to remotely run diagnostics, obtain internal status, test specific functions, or modify debugging parameters. It is an important tool for development and operations.

Parameters​

This Command has no parameters.

APISyncSubdeviceList​

Hub child-device list batch synchronization. The Hub reports to the cloud the complete list and basic information (ID, type, and status) of all child devices it manages, refreshing cloud records and ensuring an accurate device inventory.

Parameters​

This Command has no parameters.

APIRegisterDirectDevice​

Directly connected device re-network-entry registration request. A directly connected device (such as one connected through Wi-Fi Direct) requests restoration of network connectivity and services from the cloud.

Parameters​

This Command has no parameters.

APINotifyNoSubdevice​

No-child-device status notification command. The cloud notifies the gateway that, according to cloud records, no child device is currently bound under this account.

Parameters​

This Command has no parameters.

APIExecuteSubstituteCommand​

Hub request for cloud proxy command execution. When the Hub cannot execute a command directly due to permission, capability, or network limitations, it requests that the cloud proxy the command to the target device or service and return the result to the Hub.

Parameters​

This Command has no parameters.

APIRunFunctionInstruction​

Cloud predefined function instruction execution request. The cloud sends predefined function-instruction code or a script identifier to the Hub, requiring it to interpret and execute the corresponding complex logic or sequence of operations locally.

Parameters​

This Command has no parameters.

APIUnbindSubdeviceDown​

Child-device downstream unbinding command. The cloud sends a command to the gateway to remove (unbind) the specified child device from its management list. The gateway performs the local unbinding process and stops communicating with it.

Parameters​

This Command has no parameters.

APIUnbindSubdeviceUp​

Child-device upstream unbinding notification. The gateway proactively reports to the cloud that it has locally removed (unbound) a child device, requesting that the cloud update the device relationship and clean up related data.

Parameters​

This Command has no parameters.

APIEnableSubdeviceJoining​

Child-device network-entry mode enable command. The cloud commands the gateway to enter pairing/discovery mode, allowing new child devices (Zigbee, Bluetooth, and so on) to join the network for a specified duration or until it receives a stop command.

Parameters​

This Command has no parameters.

APIUploadLogFileEvent​

Log file upload event notification. The device notifies the cloud that log file upload has completed, triggering the cloud log processing workflow.

Parameters​

This Command has no parameters.

APIGetSubdeviceServiceConfig​

Child-device service configuration query request. The gateway queries the cloud for service configuration parameters required or recommended for a specific child device, such as connection strategy, data reporting frequency, and function-enablement recommendations.

Parameters​

This Command has no parameters.

APIQueryDeviceResMultiExt​

Device resource multi-value extended query request. The gateway requests that the cloud simultaneously query the current values of multiple resources (properties) for multiple devices or a single device, supporting extended query options for efficient batch data retrieval.

Parameters​

This Command has no parameters.

APITriggerSubdeviceRead​

Child-device proactive data-read trigger command. The cloud commands the gateway to immediately initiate a proactive data-read request to the specified child device (such as querying the latest sensor value) and asynchronously report the read result to the cloud, to obtain device status on demand.

Parameters​

This Command has no parameters.

APIBindSubdeviceNoAuth​

Child-device binding request without authentication. In a specific mode (for example, local debugging or a trusted network), the Hub requests that the cloud bind a child device, declaring that strict security authentication (for example, five-fold verification) is bypassed.

Parameters​

This Command has no parameters.

APISetSubdeviceMixing​

Child-device combination and integration configuration command. The cloud commands the gateway to logically combine or integrate multiple independent physical child devices into a virtual composite device to enable unified control or complex scenes.

Parameters​

This Command has no parameters.

APICheckLocalSceneSync​

Local scene information synchronization verification request. The device reports summary information (such as IDs and versions) for all locally stored scenes to the cloud, requests a comparison, and receives a list of scenes that need to be updated or deleted to maintain bidirectional synchronization.

Parameters​

This Command has no parameters.

APIDownloadLocalScene​

Scene configuration localization synchronization command. The cloud delivers the complete definition of a user-created automation scene (trigger conditions and execution actions) to the device. The device stores it locally and is responsible for subsequent execution, making the scene available offline.

Parameters​

This Command has no parameters.

APIRunScene​

General scene execution command. The cloud sends a command to the device to immediately execute a specified preconfigured scene. The device parses the scene actions and controls local or child devices to perform the corresponding operations.

Parameters​

This Command has no parameters.

APIDeleteLocalScene​

Localized scene deletion command. The cloud commands the device to delete one or more specified synchronized scenes from local storage, typically for synchronization cleanup after a user deletes a scene in the cloud.

Parameters​

This Command has no parameters.

APIRunLocalScene​

Cloud-triggered local scene execution command. The cloud triggers an automation scene that is already stored and runs locally on the device, rather than a cloud-virtualized scene. On receipt, the device directly executes the local scene logic for a low-latency response.

Parameters​

This Command has no parameters.

APIDownloadCentralScene​

Central scene configuration localization synchronization command. For systems supporting multi-gateway hubs or edge computing, the cloud sends “central scene” configurations involving cross-gateway collaboration to gateways acting as hubs, enabling localized storage and distributed coordinated execution.

Parameters​

This Command has no parameters.

APIGetWakeupUrl​

Device remote wake-up service address retrieval request. The device queries the cloud for the wake-up server address or access Token of child devices that support remote wake-up, such as low-power devices, so they can be activated as needed.

Parameters​

This Command has no parameters.

APIInquiryCentralBroker​

Central message broker information query request. A hub acting as a central hub queries the cloud for information about the message broker server it should connect to, for inter-device communication and event distribution.

Parameters​

This Command has no parameters.

APIInquiryCentralEnableState Command​

Central function enable-state query request. The hub queries the cloud for the current enabled state (on or off) of its own “central hub function” for state synchronization or UI display.

Parameters​

This Command has no parameters.

APIHubPassthroughDataDown​

Hub passthrough data downstream channel. Through this general passthrough interface, the cloud sends raw data packets that do not require parsing by the Hub business layer; the Hub directly forwards them to connected specific end devices or services.

Parameters​

This Command has no parameters.

APIEnableCentralHubFunction​

Hub central gateway core function enable 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.

Parameters​

This Command has no parameters.

APIHubPassthroughDataUp​

Hub passthrough data upstream channel. Through this general passthrough interface, the Hub directly reports raw data packets received from connected devices to the cloud or a designated external service without business-layer parsing.

Parameters​

This Command has no parameters.

APIDeleteSecurityLocal​

Home security local configuration deletion command. The cloud commands the gateway to delete specified locally stored home security configurations, such as security scenes or device bindings, typically for configuration cleanup or reset.

Parameters​

This Command has no parameters.

APISyncSecurityLanInfo​

Home security LAN state synchronization command. The cloud delivers 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.

Parameters​

This Command has no parameters.

APICheckSecurityEnableConsistency​

Home security enable-state consistency verification request. The device queries and verifies with the cloud whether the recorded master switch state (on/off) of the home security function is consistent on both sides.

Parameters​

This Command has no parameters.

APIConfirmSecurityAlert​

Home security alert confirmation command. After the user confirms a device-reported home security alert, such as intrusion detection, through the cloud App, the cloud sends this confirmation command to the device. The device then stops pushing the alert and may update its local state.

Parameters​

This Command has no parameters.

APICheckSecurityConfigConsistency​

Home security configuration consistency verification request. The device actively requests that the cloud compare the detailed home security configurations stored by both sides, such as arming modes and linkage rules, to determine whether they are completely consistent, and return the comparison result.

Parameters​

This Command has no parameters.

APIEnableSecurity​

Home security function enable/disable command. The cloud issues a command to enable or disable the overall home security subsystem on the device.

Parameters​

This Command has no parameters.

APIRepairSecurityEnable​

Home security enable-state repair command. When the cloud detects that the device’s local security enable state is inconsistent with the cloud record, it issues this command to force the device’s local enable state to synchronize with the cloud-specified state, repairing state drift.

Parameters​

This Command has no parameters.

APIReportOtaDeviceListState​

OTA upgrade device list state report. The gateway reports to the cloud a summarized state list of all devices currently upgrading, awaiting an upgrade, or whose upgrade failed, allowing the cloud to centrally monitor upgrade batches.

Parameters​

This Command has no parameters.

APIReportOtaResult​

OTA upgrade final result report. After a child device firmware upgrade task is completed, whether successfully or unsuccessfully, the gateway reports the final result and details to the cloud, such as the successful version number or failure error code.

Parameters​

This Command has no parameters.

APIReportOtaProgress​

OTA upgrade progress report. The gateway reports the current progress of child device firmware upgrades to the cloud in real time, such as download percentage and flashing status, for display in the frontend UI.

Parameters​

This Command has no parameters.

APICancelOtaUpgrade​

Device OTA upgrade cancellation command. The cloud sends a command to the gateway to cancel the in-progress firmware upgrade task for a specified device.

Parameters​

This Command has no parameters.

APIInquiryFirmwareInfo​

Gateway firmware information query request. The gateway actively queries the cloud for a new firmware version applicable to itself and related metadata, such as the version number, release notes, and file size, to trigger its own OTA upgrade check.

Parameters​

This Command has no parameters.

APIUpgradeDeviceFirmware​

Child device firmware upgrade command delivery. The cloud sends the gateway an over-the-air (OTA) firmware upgrade command for a specified child device, such as Zigbee or Bluetooth, including firmware version and download URL information.

Parameters​

This Command has no parameters.

APILockPassthroughUpstream​

External application passthrough upstream information report (dedicated channel).

Parameters​

This Command has no parameters.

APILockPassthroughDownstream​

External application passthrough downstream command (dedicated channel). The cloud sends raw commands or data that bypass business-layer parsing through a dedicated passthrough channel reserved for a specific external application, forwarding them directly to a specified child device, such as a smart lock.

Parameters​

This Command has no parameters.

APIAssistDeviceCrypto​

Device data encryption/decryption assistance request. Due to security policy or capability limitations, the gateway requests the cloud to use a specified device’s key to encrypt or decrypt particular string data and return the result.

Parameters​

This Command has no parameters.

APIReportLockExtEvents​

Smart lock extended business event report. The device reports to the cloud extended events generated by a smart lock beyond basic state changes, such as records of a specific user unlocking the door, duress alerts, low-battery warnings, and tamper alerts.

Parameters​

This Command has no parameters.

Reboot​

Controls or reports the device restart state and can be used to monitor or trigger a device restart.

Parameters​

Reboot Command Structure

APIDownloadMusic​

Device music file download command. The cloud issues a command instructing the device to download audio files, such as ringtones or notification sounds, from a specified address to local storage for later playback.

Parameters​

This Command has no parameters.

APICheckLocalMusicSync​

Local music file information synchronization verification request. The device reports the list of locally stored music files, such as file names and MD5 hashes, to the cloud, requests a comparison, and receives a list of files that need synchronization through downloading or deletion to keep the cloud and local music libraries consistent.

Parameters​

This Command has no parameters.

APIDeleteMusic​

Device local music file deletion command. The cloud commands the device to delete one or more specified audio files from local storage.

Parameters​

This Command has no parameters.

APIPushMatterBindInfo​

Matter device network-joining/binding information delivery. The cloud sends the gateway network-joining permission, network credentials, or configuration information for a new Matter device, guiding and authorizing the device to join the local Matter network.

Parameters​

This Command has no parameters.

APIUnbindMatterDeviceDown​

Matter device unbinding command (downstream). The cloud sends a command to the gateway to remove (unbind) a specified Matter device from the home network. The gateway performs the local unbinding process and updates the network topology.

Parameters​

This Command has no parameters.

APIReportDeviceAqaraSpecModel​

Aqara Spec device Thing model detail report. During device onboarding, the gateway reports to the cloud the complete Thing model definition supported by a newly discovered Aqara Spec device, including functions, properties, and commands, for device capability registration and dynamic UI generation.

Parameters​

This Command has no parameters.

APISyncAqaraSpecDataToCloud​

Aqara Spec device resource data cloud synchronization. The gateway batch-synchronizes all current state data of local Aqara Spec devices, such as all property values, to the cloud. This is typically used for full-state recovery after initial device activation or network restoration.

Parameters​

This Command has no parameters.

APIGenNextMatterNodeId​

Matter network Node ID generation request. When preparing to assign a network identity to a new Matter device, the gateway requests that the cloud generate a globally unique, specification-compliant Node ID.

Parameters​

This Command has no parameters.

APIGenHomeMatterNoc​

Home Matter NOC certificate generation request. When establishing or managing a Matter Fabric, the gateway requests that the cloud generate or update a Matter Network Operational Certificate (NOC) for the current user’s home for secure authentication.

Parameters​

This Command has no parameters.

APIStartBindMatterDeviceToHub​

Aqara Spec device binding start. The gateway reports discovery of a new Aqara Spec device to the cloud and requests that the binding process begin. This is the first step of the multi-step device onboarding process.

Parameters​

This Command has no parameters.

APIUnbindMatterDeviceUP​

Matter device unbinding state report (upstream). The gateway reports to the cloud the result or state of a locally triggered Matter device unbinding event, ensuring that the cloud device list remains synchronized with the local network state.

Parameters​

This Command has no parameters.

APIQueryMatterJoinLimit​

Matter device network-joining limit policy query. Before allowing a new device to join the Matter network, the gateway queries the cloud whether the current home or gateway has reached its device limit or whether other network-joining restriction policies exist.

Parameters​

This Command has no parameters.

APICloudToPanelDownstream​

Cloud-to-panel downstream general command channel. The cloud uses this general interface to send various control, query, or configuration commands to a scene panel.

Parameters​

This Command has no parameters.

APIPanelUpstreamRequest​

Panel-to-cloud upstream general request channel. This general interface is used to initiate various requests to the cloud, such as retrieving weather, executing complex scenes, or reporting panel events.

Parameters​

This Command has no parameters.

APICheckPanelConfigConsistency​

Scene panel configuration consistency verification request. The device reports to the cloud summary information about the current configurations of all scene panels it manages, requests a comparison, and receives the differences to ensure synchronization between cloud and local panel configurations.

Parameters​

This Command has no parameters.

APISyncPositionDown​

Device location information downstream synchronization command. The cloud sends user-assigned location information, such as rooms and areas, to the device, ensuring that the device’s local device-to-location mapping is consistent with cloud settings.

Parameters​

This Command has no parameters.

APIPushPanelConfig​

Smart scene panel configuration delivery command. The cloud delivers smart scene panel configuration, physical or virtual, to the device, including button icons, backlight colors, and associated scene or device control logic.

Parameters​

This Command has no parameters.

APIReportLinkConsuming​

Network link latency probe 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.

Parameters​

This Command has no parameters.

APICheckLinkConsuming​

Network link latency probe command. The cloud sends a probe command to the device to measure round-trip time (RTT) between the cloud and the device, typically for network quality monitoring and diagnostics.

Parameters​

This Command has no parameters.

APIUnsubscribeIftttResChange​

Local automation rule request to unsubscribe from cloud resource changes. The gateway requests that the cloud stop pushing change notifications for previously subscribed specific resources.

Parameters​

This Command has no parameters.

APIEnableAutomation​

Local automation rule master switch control command. The cloud sends a command to globally enable or disable all automation rules (IFTTT scenes) stored and executed locally on the gateway, temporarily activating or deactivating them.

Parameters​

This Command has no parameters.

APIDeleteIftttLocal​

The cloud commands the gateway to delete specified IFTTT automation rules from its local storage.

Parameters​

This Command has no parameters.

APIPushCentralAutomation​

Central-level automation rule delivery command. The cloud provides complex automation rule configurations that require coordination across multiple hubs, or processing centralized by a hub acting as the central hub.

Parameters​

This Command has no parameters.

APIRunCloudAction​

Local automation-triggered cloud action execution request. When the conditions of a local automation rule on the gateway are met, this interface requests the cloud to perform actions that can only be completed in the cloud, such as sending notifications, calling Internet APIs, or updating a cloud database.

Parameters​

This Command has no parameters.

APIGetSunriseSunsetByLatLon​

Latitude-and-longitude-based sunrise and sunset time query request. The device queries the cloud for the specific sunrise and sunset times of the current day based on its latitude and longitude coordinates, enabling smart automation scenes related to natural light, such as “turn on lights at sunset.”

Parameters​

This Command has no parameters.

APIEnableCentralAutomation​

Central-level automation rule enable command. The cloud controls whether the central hub enables the central-level automation rules stored on it.

Parameters​

This Command has no parameters.

APIDeleteCentralAutomation​

Central-level automation rule deletion command. The cloud commands the hub acting as the central hub to delete specified central-level automation rules from its storage.

Parameters​

This Command has no parameters.

APIQueryIftttRes​

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, such as another home’s device state, weather data, or user mode.

Parameters​

This Command has no parameters.

APISubscribeIftttResChange​

Local automation rule request to subscribe to cloud resource changes. On behalf of local automation rules, the gateway subscribes to changes in one or more cloud resources. When those resources change in the cloud, the cloud notifies the gateway.

Parameters​

This Command has no parameters.

APIEnableIfttt​

The cloud sends a dedicated command to the gateway to control the overall enabled state of its IFTTT (If This Then That) automation function.

Parameters​

This Command has no parameters.

APIQueryHolidayList​

The device queries the cloud for the holiday list for a specified year and region.

Parameters​

This Command has no parameters.

APIPublishResourceChange​

Resource change event publication command. When the value of a cloud resource changes, the cloud proactively “publishes” this change event to local gateways subscribed to that resource, triggering their local automation rules.

Parameters​

This Command has no parameters.

APICheckLocalIftttSync​

Local automation rule information synchronization verification request. The gateway reports summary information about all locally stored IFTTT automation rules to the cloud, requests a comparison, and receives the differences to keep the cloud and local rule repositories consistent.

Parameters​

This Command has no parameters.

APIDownloadIftttLocal​

The cloud synchronizes user-created IFTTT automation rules to the gateway’s local storage so they can be triggered and executed locally under offline conditions.

Parameters​

This Command has no parameters.

Identify​

When written, starts or stops device self-identification.

Parameters​

Identify Command Structure

APIPushLightBoxConfig​

Light-box device configuration delivery command. The cloud delivers specific configurations for a smart light-box device (such as lighting effects, color schemes, and schedules) to the gateway, which then forwards them to or applies them on the target light-box device.

Parameters​

This Command has no parameters.

APIGetIrCode​

IR code raw-data retrieval request. The device requests the raw or waveform data of a specified IR code from the cloud for local transmission or verification.

Parameters​

This Command has no parameters.

APISaveLearnedIrKey​

Learned IR code key-binding save command. After 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 persist the binding in device storage.

Parameters​

This Command has no parameters.

APIQueryIrLearningCode​

Learned IR code information query request. The device requests that the cloud retrieve a list of all user-defined learned IR codes stored locally and their metadata (such as the bound appliance name and key name).

Parameters​

This Command has no parameters.

APIStartIrCodeLearning​

IR code learning mode start command. The cloud instructs the device to enter IR learning mode, preparing it to receive signals from the user's physical IR remote control and encode them into a digital format that can be stored and retransmitted.

Parameters​

This Command has no parameters.

APIGetIrCodeTarget​

IR code target-appliance information request. The device requests detailed information about the target appliance associated with a specific IR code (such as brand, model, and capabilities) from the cloud to enrich the user interface display.

Parameters​

This Command has no parameters.

APIQueryIrCodeLibrary​

IR code cloud-library query request. The device queries the cloud to determine whether a preset IR code library exists for an appliance of a specific brand and model, allowing users to add and control common appliances without manual learning.

Parameters​

This Command has no parameters.

APIGetIrCodeDownloadUrl​

IR code database download URL request. The device requests from the cloud a URL for downloading a complete or incremental IR code database file to update or initialize the offline code library.

Parameters​

This Command has no parameters.

APIDeleteLearnedIrCode​

Learned IR code deletion command. The cloud instructs the device to delete one or more IR remote-control codes that were previously learned and saved from its local storage.

Parameters​

This Command has no parameters.

APISendIrButtonPress​

Single IR code transmission command. The cloud instructs the device to use its IR transmitter to send a specific learned or preset IR code once to a target appliance (such as an air conditioner or television), simulating a single remote-control key press.

Parameters​

This Command has no parameters.

APISyncIrLearningCodes​

Bidirectional learned IR code synchronization request. The device reports summary information for all locally stored learned IR codes to the cloud and requests comparison and receipt of a difference list (codes to add or delete), so that the cloud and device IR code libraries eventually become consistent.

Parameters​

This Command has no parameters.

AddOrUpdateZigbeeNetwork​

This Command performs the "add or update Zigbee network" operation.

Parameters​

AddOrUpdateZigbeeNetwork Command Structure

AddOrUpdateZigbeeNetworkResponse​

This Command performs the "add or update Zigbee network response" operation.

Parameters​

AddOrUpdateZigbeeNetworkResponse Command Structure

ConfigStaticIPAddr​

The ConfigStaticIPAddr Command configures device network addressing information. Optional parameter AddressingMode: when set to 0, it switches to obtaining an IP address through DHCP (ignoring IPAddress, SubnetMask, PrimaryDNS, DefaultGateway, and SecondaryDNS); when set to 1, it switches to static IP mode and applies the preceding parameters; if this field is absent, static IP mode is used by default. Optional parameter InterfaceName (example: eth0) specifies the target interface; if it is not provided, the configuration applies to all network interfaces.

Parameters​

ConfigStaticIPAddr Command Structure

ConnectToHomeStation​

Represents a command for a WiFi Endpoint to connect to a Home Station.

Parameters​

ConnectToHomeStation Command Structure

ConnectToHomeStationResponse​

Home Station connection response.

Parameters​

ConnectToHomeStationResponse Command Structure

AddOrUpdateThreadNetwork​

This Command performs the "add or update Thread network" operation.

Parameters​

AddOrUpdateThreadNetwork Command Structure

AddOrUpdateThreadNetworkResponse​

This Command performs the "add or update Thread network response" operation.

Parameters​

AddOrUpdateThreadNetworkResponse Command Structure

TriggerZigbeeNetworkInfoUpload​

Triggers the gateway to report Zigbee network information for subsequent operations, such as enabling fast pairing of Zigbee devices based on the Zigbee network information.

Parameters​

TriggerZigbeeNetworkInfoUpload Command Structure

ScanWiFiNetworks​

This Command performs the "scan WiFi networks" operation.

Parameters​

This Command has no parameters.

ScanWiFiNetworksResponse​

This Command performs the "scan WiFi networks response" operation.

Parameters​

This Command has no parameters.

AddOrUpdateWiFiNetwork​

This Command performs the "add or update WiFi network" operation.

Parameters​

AddOrUpdateWiFiNetwork Command Structure

AddOrUpdateWiFiNetworkResponse​

This Command performs the "add or update WiFi network response" operation.

Parameters​

AddOrUpdateWiFiNetworkResponse Command Structure

APISyncConfiguration​

Bidirectional general-function configuration synchronization request. The device reports summaries of locally stored general-function configurations to the cloud and requests comparison and receipt of a difference list (configurations to push or delete), so that the cloud and device eventually become consistent.

Parameters​

This Command has no parameters.

APIWriteFunctionResource​

Multicast control command for general-function resources. The cloud uses multicast to send write-operation commands for specific general-function resources (such as virtual switches and counters), for example setting values or triggering actions, to one or more devices for batch control.

Parameters​

This Command has no parameters.

APIPushSubscribedResource​

Device-subscribed resource delivery command. Based on the resource types subscribed to by a device or its subdevices, the cloud delivers the corresponding resource configurations, status updates, or data streams to the device for real-time data delivery or configuration updates.

Parameters​

This Command has no parameters.

APIReportConfiguration​

Multicast reporting of general-function resources. The device reports the current values or summary information of a type of locally stored general-function resource (such as configurations or cached states) to the cloud through multicast or batch reporting for centralized monitoring and synchronization.

Parameters​

This Command has no parameters.

APIReportThingModelDetail​

Detailed Aqara new-device Thing model information report. For hubs or devices that support the Aqara device Thing model protocol, reports the detailed Thing model (objects, properties, and services) to the cloud.

Parameters​

This Command has no parameters.

APIGetConfiguration​

General-function configuration retrieval request. The device requests the latest configuration parameters or policy file for a specified functional module (such as specific sensor data-processing logic or device behavior rules) from the cloud.

Parameters​

This Command has no parameters.

APIDeleteConfiguration​

Multicast deletion command for general-function configurations. The cloud issues a command requiring devices to delete one or more specified types of general configurations. This Command can be sent through multicast, affecting multiple qualifying gateways or devices simultaneously.

Parameters​

This Command has no parameters.

APIPushConfiguration​

Multicast delivery command for general-function configurations. The cloud delivers general-function configurations (such as device behavior rules and data-processing policies) to one or more devices. This Command can be sent through multicast to synchronize configurations across a batch of devices efficiently.

Parameters​

This Command has no parameters.

APIRequestCloudStorageResource​

Cloud-storage service resource configuration request. A device (typically a camera or similar device) requests from the cloud resource configuration information related to cloud video storage services, such as storage quotas, upload credentials, and recording schedules.

Parameters​

This Command has no parameters.

APIGetStudioBackupUploadUrl​

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.

Parameters​

This Command has no parameters.

APILoginByAuthCode​

Verification-code login request.

Parameters​

This Command has no parameters.

APIGetAuthCode​

User authentication-code retrieval request.

Parameters​

This Command has no parameters.

APIDeleteStudioBackup​

Studio cloud-backup deletion request. The gateway requests that the cloud delete a specified historical Studio backup file to free storage space or clean up old data.

Parameters​

This Command has no parameters.

APIGetPositionByDeviceId​

Query a room by device ID. When a gateway needs to organize a device list or perform room-level control, it queries the cloud for the name or ID of the room to which the specified device ID currently belongs.

Parameters​

This Command has no parameters.

APIGetStudioBackupInfo​

Studio cloud-backup information query request. The gateway queries the cloud for the list of Studio backup files already available for the current user or gateway and their metadata (such as backup time, size, and description), for restoration or backup management.

Parameters​

This Command has no parameters.

APIGetUserDeviceList​

User device-list retrieval request. The gateway requests from the cloud a list of all devices bound to the currently logged-in user account, including device IDs, names, types, and basic statuses; it is typically initiated during initialization, refresh, or management-interface operations.

Parameters​

This Command has no parameters.

APILoginByGuardCode​

Account-and-password login request.

Parameters​

This Command has no parameters.

APIReportStudioInfo​

Studio runtime information report. The gateway proactively reports information such as the runtime status, version, and configuration summary of the locally running Aqara Studio instance to the cloud for monitoring and statistical analysis.

Parameters​

This Command has no parameters.

APIConfirmStudioBackupSuccess​

Studio cloud-backup upload success confirmation. After a 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 process.

Parameters​

This Command has no parameters.

APIGetProxyServerInfo​

Proxy-server connection information query request. The gateway (or its Studio environment) requests an available proxy server address and configuration information from the cloud to establish a specific network connection (such as remote debugging or external service access).

Parameters​

This Command has no parameters.

ChangeTemperatureLevel​

Allows users to adjust the temperature to a preset level. Parameter Supported Values indicates the list of supported temperature levels.

Parameters​

ChangeTemperatureLevel Command Structure

ChangeTemperature​

ChangeTemperature allows users to specify and adjust the target temperature of a device or system.

Parameters​

ChangeTemperature Command Structure

ResetPresence​

The ResetPresence command resets the current presence-detection state of a device or space.

Parameters​

This Command has no parameters.

GoToMaxPositionPercentage​

This command requests that the device move to the maximum opening-percentage position (typically fully open or the device-defined maximum endpoint).

Parameters​

This Command has no parameters.

AutoControl​

This command requests that the device perform a product-defined automatic control action (such as 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.

Parameters​

This Command has no parameters.

GoToPositionPercentage​

This Command performs the "go to a specified opening percentage" operation.

Parameters​

GoToPositionPercentage Command Structure

GoToMinPositionPercentage​

This command requests that the device move to the minimum opening-percentage position (typically fully closed or the device-defined minimum endpoint).

Parameters​

This Command has no parameters.

StopMotion​

This Command performs the "stop" operation.

Parameters​

This Command has no parameters.

Toggle​

This Command performs the "on/off" operation.

Parameters​

This Command has no parameters.

On​

This Command performs the "turn on" operation.

Parameters​

This Command has no parameters.

Off​

This Command performs the "turn off" operation.

Parameters​

This Command has no parameters.

SendIRCode​

This Command performs the "send infrared command" operation.

Parameters​

SendIRCode Command Structure

ClearActivePreset​

This Command performs the "clear active preset" operation.

Parameters​

This Command has no parameters.

SetActivePreset​

This Command performs the "set active preset" operation.

Parameters​

SetActivePreset Command Structure

Pause​

This Command performs the "pause" operation.

Parameters​

This Command has no parameters.

Stop​

This command requests that the device stop its current operation.

Parameters​

This Command has no parameters.

Play​

This Command performs the "play" operation.

Parameters​

This Command has no parameters.

PlaySpecificList​

This Command performs the "play list" operation.

Parameters​

This Command has no parameters.

Rewind​

This Command performs the "rewind" operation.

Parameters​

This Command has no parameters.

FastForward​

This Command performs the "fast-forward" operation.

Parameters​

This Command has no parameters.

MediaPlaybackCommand​

MediaPlaybackCommand represents media playback commands and is applicable to playback operations for various types of media, including music, video, audiobooks, and radio.

Parameters​

MediaPlaybackCommand Command Structure

Next​

This Command performs the "next" operation.

Parameters​

This Command has no parameters.

Previous​

This Command performs the "previous" operation.

Parameters​

This Command has no parameters.

StartOver​

This Command performs the "restart playback" operation.

Parameters​

This Command has no parameters.

SelectInput​

This Command performs the "select playback source" operation.

Parameters​

SelectInput Command Structure

ChangeToMode​

ChangeToMode is used to set the device mode.

Parameters​

ChangeToMode Command Structure

ResetCondition​

ResetCondition represents resetting the filter cartridge.

Parameters​

This Command has no parameters.

UnboltDoor​

Open the door—retract the deadbolt and latch bolt.

Parameters​

UnboltDoor Command Structure

SetWeekDaySchedule​

This Command performs the "set weekly schedule" operation.

Parameters​

SetWeekDaySchedule Command Structure

QuietUnlockDoor​

This Command performs the "silent unlock" operation.

Parameters​

This Command has no parameters.

GetYearDaySchedule​

This Command performs the "get yearly schedule" operation.

Parameters​

GetYearDaySchedule Command Structure

ClearWeekDaySchedule​

This Command performs the "clear weekly schedule" operation.

Parameters​

ClearWeekDaySchedule Command Structure

GetUser​

This Command performs the "get user" operation.

Parameters​

This Command has no parameters.

UnlockDoor​

This Command performs the "unlock" operation.

Parameters​

UnlockDoor Command Structure

SetYearDaySchedule​

This Command performs the "set yearly schedule" operation.

Parameters​

SetYearDaySchedule Command Structure

GetWeekDaySchedule​

This Command performs the "get weekly schedule" operation.

Parameters​

GetWeekDaySchedule Command Structure

LockDoor​

This Command performs the "lock" operation.

Parameters​

LockDoor Command Structure

ClearYearDaySchedule​

This Command performs the "clear yearly schedule" operation.

Parameters​

ClearYearDaySchedule Command Structure

QuietLockDoor​

This Command performs the "silent lock" operation.

Parameters​

This Command has no parameters.

GoHome​

The Vacuum GoHome command instructs the robot vacuum to return to its charging dock or base station.

Parameters​

This Command has no parameters.

Start​

Start.

Parameters​

This Command has no parameters.

Resume​

Resume.

Parameters​

This Command has no parameters.

Open​

Open command.

Parameters​

This Command has no parameters.

Close​

Close command.

Parameters​

This Command has no parameters.

StartCleaning​

This Command performs the "start cleaning" operation.

Parameters​

This Command has no parameters.

PauseCleaning​

This Command performs the "pause cleaning" operation.

Parameters​

This Command has no parameters.

ContinueCleaning​

This Command performs the "continue cleaning" operation.

Parameters​

This Command has no parameters.

StopCleaning​

This Command performs the "stop cleaning" operation.

Parameters​

This Command has no parameters.

EnableCharging​

EnableCharging Command (enable charging command).

Parameters​

This Command has no parameters.

DisableCharging​

DisableCharging Command (disable charging command).

Parameters​

This Command has no parameters.

SelfTestRequest​

SelfTestRequest represents an alarm self-test.

Parameters​

This Command has no parameters.

PreviewEffect​

This command requests that the device preview a scene using the supplied EffectData without saving it. Users can preview a scene before adding or updating a user-defined scene.

Effect on Receipt​

After receiving this command, the device shall validate the encoding validity of EffectData and support for the action type.

  • If validation succeeds: the device shall enter preview mode and execute the corresponding scene effect, and shall not write it to persistent storage.
  • If validation fails: the device shall return a semantic status indicating an invalid parameter or data format.

During preview, EffectOperationState shall indicate Previewing; after it ends, it shall return to idle or an implementation-defined state.

Parameters​

PreviewEffect Command Structure

UpdateUserDefinedEffect​

This command requests that the device update an existing user-defined scene. Only scenes of the UserDefined type can be updated.

Effect on Receipt​

After receiving this command, the device shall first validate EffectID and the validity of the data content.

  • If validation succeeds: the device shall update the corresponding scene data while retaining the scene ID.
  • If EffectID does not exist: it shall return a semantic "scene does not exist" error.
  • If the target is a BuiltIn scene: it shall return a semantic error indicating that a non-user-defined scene cannot be updated.

Parameters​

UpdateUserDefinedEffect Command Structure

RemoveUserDefinedEffect​

This command requests that the device remove an existing user-defined scene. Only scenes of the UserDefined type can be removed; BuiltIn scenes cannot be removed.

Effect on Receipt​

After receiving this command, the device shall validate that EffectID exists and belongs to the UserDefined scope.

  • If validation succeeds: the device shall delete the scene record and update the UserDefinedEffects list.
  • If EffectID does not exist: it shall return a semantic "scene does not exist" error.
  • If the target is a BuiltIn scene: it shall return a semantic error indicating that a non-user-defined scene cannot be deleted.

Parameters​

RemoveUserDefinedEffect Command Structure

GetEffectData​

This command requests that the device return the scene data for the specified EffectID. Clients can use it to read stored scene data, for example, for display, backup, or editing.

Effect on Receipt​

After receiving this command, the device shall validate whether EffectID exists in the BuiltIn or UserDefined list.

  • If validation succeeds: the device shall return the corresponding EffectData.
  • If validation fails: it shall return a semantic "invalid scene ID" or "scene does not exist" error.

Parameters​

GetEffectData Command Structure

StartEffect​

This command requests that the device start the specified lighting effect.

The target EffectID shall exist in the BuiltInEffects or UserDefinedEffects list.

Parameters​

StartEffect Command Structure

AddUserDefinedEffect​

This command requests that the device add a new user-defined scene. The new scene is of the UserDefined type.

Effect on Receipt​

After receiving this command, the device shall validate the length of EffectName and the format of EffectData.

  • If validation succeeds and capacity is available: the device shall allocate a new UserDefined EffectID, save the scene, and update UserDefinedEffects.
  • If the current count reaches MaxUserDefinedEffects: it shall return a semantic "scene count has reached the limit" error.
  • If the name or data is invalid: it shall return a semantic parameter-error status.

Parameters​

AddUserDefinedEffect Command Structure

StopPreview​

This command requests that the device stop the currently running scene preview and resume normal window-covering operation.

Effect on Receipt​

After receiving this command, the device shall stop the current preview scene and return to the regular control state.

  • If a preview scene is currently active: it shall terminate the preview and switch EffectOperationState back to idle or a device-defined stable state.
  • If no preview scene is currently active: the device may return a semantic "no active preview" status, or return a successful no-op according to the implementation.

This Command has no parameters.

PreviewTransition​

This command requests that the device preview a transition effect using the supplied parameters. Before submitting, users can view the light's on/off transition behavior under the specified timing and curve settings.

This command is used to preview the combined visual effects of On/Off transition time, dimming curve, and initial brightness.

Parameters​

PreviewTransition Command Structure

StepBrightness​

This command performs stepped brightness adjustment without changing the light's On/Off state.

Effect on Receipt​

When Size = 0, the command has no effect and shall return INVALID_COMMAND.

When Size ≠ 0, the device shall change brightness in the step direction:

  • Up: increase CurrentLevel by Size, or stop when the device's maximum level is reached; if the boundary is reached early, the transition duration shall be shortened proportionally.
  • Down: decrease CurrentLevel by Size, or stop when the device's minimum level is reached; if the boundary is reached early, the transition duration shall be shortened proportionally.

Parameters​

StepBrightness Command Structure

SetBrightness​

This command sets the target brightness without changing the light's On/Off state.

Effect on Receipt​

After receiving this command, the device shall transition continuously from the current brightness to the target value specified by Level.

  • The transition duration shall preferentially use Time in the command.
  • When Time is absent, the device transition-duration configuration shall be used; if no configuration is available, the transition shall complete at the fastest speed achievable by the device.

If the device does not support variable-rate transitions, it may ignore the transition-duration field.

Parameters​

SetBrightness Command Structure

StepBrightnessWithOnOff​

This command performs stepped brightness adjustment with On/Off coupling.

When brightness falls near the minimum level, the device may update the On/Off state in accordance with the coupling semantics.

Effect on Receipt​

After receiving this command, the device shall first perform brightness stepping according to the semantics of StepBrightness:

  • When Size = 0, the command has no effect and shall return INVALID_COMMAND.
  • When Size ≠ 0, update CurrentLevel according to the step direction and step size; if the device's permitted minimum or maximum boundary is reached, stop at the boundary and shorten the actual transition duration proportionally.

In addition to the above behavior, this command shall also perform On/Off coupling:

  • If the command effect causes CurrentLevel to be greater than the device's minimum level, OnOff at the same endpoint shall be set to TRUE (On).
  • If the command effect causes CurrentLevel to reach the device's minimum level, OnOff at the same endpoint shall be set to FALSE (Off).

Parameters​

StepBrightnessWithOnOff Command Structure

SetBrightnessWithOnOff​

This command sets the target brightness with On/Off coupling.

Compared with SetBrightness, this command can also affect the On/Off state while setting brightness.

Effect on Receipt​

After receiving this command, the device shall first transition continuously from the current brightness to the target brightness according to the semantics of SetBrightness.

  • The transition duration shall preferentially use Time in the command.
  • When Time is absent, the device transition-duration configuration shall be used; if no configuration is available, the transition shall complete at the fastest speed achievable by the device.

In addition to the above behavior, this command shall also perform On/Off coupling:

  • If the command effect causes CurrentLevel to be greater than the device's minimum level, OnOff at the same endpoint shall be set to TRUE (On).
  • If the command effect causes CurrentLevel to reach the device's minimum level, OnOff at the same endpoint shall be set to FALSE (Off).

Parameters​

SetBrightnessWithOnOff Command Structure

MoveToXYColor​

This command sets the XY color.

After execution, the device shall switch ColorMode to XY mode.

Effect on Receipt​

After receiving this command, the device shall 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 shall match the TransitionTime field. The transition path in color space is not mandated; the shortest path in CIE xyY space (which can be considered a "straight-line" path) is recommended.

Parameters​

MoveToXYColor Command Structure

MoveToHueSaturationBrightness​

This command simultaneously sets Hue/Saturation and brightness.

It is typically equivalent to issuing MoveToHueAndSaturation and MoveToLevelWithOnOff together.

Effect on Receipt​

After receiving this command, the device shall first switch ColorMode to HSV and continuously transition from the current Hue/Saturation to the target values; it shall simultaneously perform brightness and On/Off coupling according to the semantics of MoveToLevelWithOnOff.

Parameters​

MoveToHueSaturationBrightness Command Structure

MoveToHueAndSaturation​

This command sets Hue and Saturation.

After execution, the device shall switch ColorMode to HSV mode.

Effect on Receipt​

After receiving this command, the device shall switch ColorMode to HSV mode and transition continuously from the current Hue/Saturation to the target Hue/Saturation.

The transition duration shall match the TransitionTime field. The transition path is not mandated; the shortest path in color space is recommended.

Parameters​

MoveToHueAndSaturation Command Structure

MoveToColorTemperatureBrightness​

This command simultaneously sets color temperature and brightness.

It is typically equivalent to issuing MoveToColorTemperature and MoveToLevelWithOnOff together.

Effect on Receipt​

After receiving this command, the device shall first perform the color-temperature transition according to the semantics of MoveToColorTemperature (switching ColorMode to ColorTemperature), and perform brightness and On/Off coupling according to the semantics of MoveToLevelWithOnOff.

If the target color temperature is outside the device's physical capability range, it shall be clamped to the minimum or maximum color temperature reachable by the device.

Parameters​

MoveToColorTemperatureBrightness Command Structure

MoveToXYColorBrightness​

This command simultaneously sets the XY color and brightness.

It is typically equivalent to issuing MoveToColor and MoveToLevelWithOnOff together.

Effect on Receipt​

After receiving this command, the device shall first set the target XY color according to the semantics of MoveToXYColor (switching ColorMode to XY) and move continuously to the target color over the transition time; it shall simultaneously set the target brightness and handle On/Off coupling according to the semantics of MoveToLevelWithOnOff.

The color transition path is not mandated; the shortest path in CIE xyY space is recommended.

Parameters​

MoveToXYColorBrightness Command Structure

MoveToColorTemperature​

This command sets the color temperature.

After execution, the device shall switch ColorMode to ColorTemperature mode.

Effect on Receipt​

After receiving this command, the device shall set ColorMode (if implemented) to ColorTemperature mode and transition continuously from the current color temperature to the target color temperature.

The transition duration shall match the TransitionTime field. As defined by this mode, the color-temperature transition path follows the Black Body Line.

If the target value is below the device's physical minimum color temperature (Mired) or above its physical maximum color temperature (Mired), it shall be clamped to the physical minimum or maximum value, respectively, as the final target.

Parameters​

MoveToColorTemperature Command Structure

StepColorTemperature​

This command performs incremental color-temperature adjustment by step size.

Effect on Receipt​

When StepSize = 0, the command has no effect and shall return INVALID_COMMAND.

When StepSize > 0, the device shall set ColorMode (and the corresponding enhanced mode, if implemented) to ColorTemperature mode and perform one color-temperature change in the direction specified by StepMode:

  • Up: increase Mired (that is, decrease the Kelvin color temperature).
  • Down: decrease Mired (that is, increase the Kelvin color temperature).

The stepping operation shall stop when a device-permitted boundary, whether a configured or physical boundary, is reached.

Parameters​

StepColorTemperature Command Structure

PanTiltDirectionControl​

This Command performs the "pan-tilt direction control" operation.

Parameters​

PanTiltDirectionControl Command Structure

StopMotion​

This Command performs the "stop" operation.

Parameters​

This Command has no parameters.

RotationControl​

This command requests that the device perform rotation control in the specified direction.

The device shall perform rotation in consideration of the current angle boundaries, resolution, and mechanical constraints, stopping at a boundary when necessary.

Parameters​

RotationControl Command Structure

GoToPositionRotationPercentage​

The GoToPositionRotationPercentage command sets a window-covering device's target tilt position to the percentage specified in the command. TargetPositionRotationPercentage shall be set to RotationPercentage; after completion, CurrentPositionRotationPercentage shall be set to the percentage specified in the command.

Effect on Receipt​

After receiving this command, the device shall constrain RotationPercentage to its supported range and write it to TargetPositionRotationPercentage.

The device shall drive the tilt movement; after reaching the target, it shall update CurrentPositionRotationPercentage. If mechanical boundaries prevent it from fully reaching the target, it shall stop at the reachable boundary and report the actual position.

Parameters​

GoToPositionRotationPercentage Command Structure

StepPosition​

This command requests that the device perform relative position stepping.

The sign of Size determines the step direction; the device shall clamp the target value within the controllable range and execute it at the available resolution.

Effect on Receipt​

After receiving this command, the device shall calculate the relative target position using 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 successful no-op according to the implementation, or return a semantic invalid-parameter error.

If Time is provided, the device shall perform the transition over that duration; otherwise, it shall use the device's default strategy. If the result of the calculation exceeds a boundary, it shall be clamped to the minimum or maximum reachable position.

Parameters​

StepPosition Command Structure

GoToPositionPercentage​

This Command performs the "go to specified open/close percentage" operation.

Parameters​

GoToPositionPercentage Command Structure

GoToMinPositionPercentage​

This command requests that the device move to the minimum open/close percentage position (typically corresponding to fully closed or the device-defined minimum endpoint).

Parameters​

This Command has no parameters.

GoToMaxPositionPercentage​

This command requests that the device move to the maximum open/close percentage position (typically corresponding to fully open or the device-defined maximum endpoint).

Parameters​

This Command has no parameters.

AutoControl​

This command requests that the device perform a product-defined automatic control action, such as switching between preset targets.

The specific strategy is defined by the device implementation; clients can trigger it in conjunction with the current state and configuration.

Parameters​

This Command has no parameters.

TriggerWarning​

This Command performs the "trigger alarm" operation.

Parameters​

TriggerWarning Command Structure

SelfTestRequest​

SelfTestRequest represents an alarm self-test.

Parameters​

This Command has no parameters.

RemoveOneMatterManufacturer​

This Command performs the "Matter Bridge removes one Matter ecosystem platform" operation.

Parameters​

This Command has no parameters.

RemoveAllMatterManufacturer​

This Command performs the "Matter Bridge removes all Matter ecosystem platforms" operation.

Parameters​

This Command has no parameters.

Toggle​

This Command performs the "On/Off" operation.

Parameters​

This Command has no parameters.