Device DPs

The data point (DP) is the abstraction of a smart device function, describing product functions and parameters.

DP definitions

• Identifier: the identification of a data point. An identifier is used for DP data transmission between the device and the cloud. Identifiers can contain letters, numbers, and underscores (_), and must start with a letter.

• DP name: the name of a function.

• Data type:

  Type	Parameter name	Description	Example
  Boolean	bool	Represent a binary variable value that is either true or false.	On/off control. Turn a device on or off.
  Value	value	Apply to the data that can be linearly adjusted.	Adjust the temperature, ranging from 20°C to 40°C.
  Enum	enum	A custom finite set of values.	Change the working level in terms of high, medium, and low.
  Fault	fault	Used to report DP failure. The device can only report the data when multiple faults occur.	Faults occur in the temperature sensor, motor, and more.
  String	string	Apply to DP data transmitted in the string format.	-
  Raw	raw	Transmit the data in the raw binary format. Raw data needs to be converted into data in the hexadecimal format.	-

• Data transfer type

  • Send and report: two-way data transmission between the device and the cloud.
  • Report only: one-way data transmission. Data can only be reported from the device.
  • Send only: one-way data transmission. Data can only be sent from the cloud.

Sample DPs

Take a lighting product as an example. The following table lists respective DPs.

Query DPs with cloud functions

You can query device DPs by calling cloud functions. If you have not deployed cloud functions, follow the instructions in Cloud Functions to deploy them.

• The following example shows how to query device DPs:

      import { request } from '../../utils/request';
      const params = {
          data: {
              action: "device.specifications",
              params: {
                  "device_id": "xxx" // The device ID.
              }
          }
      };
      request(params).then(res =>{
          console.log('res', res);
      }).catch(err => console.log('err', err))
  

• The following example shows the response:

  {
  	"category":"dj", // The category of the device.
  	"functions":[  // The array of DPs. Only one DP is displayed in this example.
  	{
  		"code":"switch_led",  // The identifier of the DP. It is used to send data.
  		"type":"Boolean", // The data type.
  		"values":"{}" // The properties of the DP.
  	},
  	]
  }
  

Send DP command

Based on the communication protocols supported by smart devices, WeChat mini programs support the following methods to send DP commands:

• Call device.control to send a command. This method is applicable to devices that can be directly connected to the internet, such as Wi-Fi locks, Wi-Fi speakers, and Wi-Fi-enabled multi-mode devices.
• Call WeChat’s native Bluetooth APIs to send a command. This method is applicable to Bluetooth devices that cannot be directly connected to the internet.

Method 1: Call device.control

For devices that can be directly connected to the internet, you can call cloud functions to send DP commands. If you have not deployed cloud functions, follow the instructions in Cloud Functions to deploy them.

The following example shows how to send a DP command:

const params = {
    data: {
        action: "device.control",
	// params: the parameters.
        params: {
            "device_id": "xxx", // The device ID.
	    "commands": [{ "code": "switch_led", "value": true }] // The DP command.
        }
    }
};
request(params).then(res =>{
    console.log('res', res); // A value of true indicates that the command is sent.
}).catch(err => console.log('err', err))

Method 2: Call WeChat’s native Bluetooth APIs

To send a DP command to control a Bluetooth device that cannot be directly connected to the internet, you must establish a Bluetooth connection between the device and the mobile phone. Then, call WeChat’s native Bluetooth APIs to send the DP command.

To help you quickly implement Bluetooth features for WeChat mini programs, Tuya provides the Bluetooth SDK. For more information, see WeChat Mini Program Bluetooth SDK.

Query device status

WeChat mini programs support device status query in any of the following methods:

• Call device.status.
• Push data through persistent connections over MQTT.
• Call WeChat’s native Bluetooth APIs to listen for data. This method is applicable to Bluetooth devices that cannot be directly connected to the internet.

Method 1: Call device.status

const params = {
    data: {
        action: "device.status",
	// params: the parameters.
        params: {
		"device_id": "xxx", // The device ID.
		"commands": [{ "code": "switch_led", "value": true }] // The DP command.
        }
    }
};

request(params).then(res =>{
    console.log('res', res); 
}).catch(err => console.log('err', err))

Response:

"result": [{ // The returned array contains all DP statuses.
		"code": "switch_led",
		"value": true
	}]

Method 2: Push data through persistent connections over MQTT

1. Create an MQTT connection in app.js file of the WeChat mini program.

   // Import the MQTT file.
   import wxMqtt from './utils/mqtt/wxMqtt'
   // Start the connection and listen for MQTT messages with the onLaunch lifecycle method.
   onLaunch: function () {
   
   	wxMqtt.connectMqtt()
   
   	wxMqtt.on('close', (errorMsg) => {
   	wxMqtt.connectMqtt()
   	console.log('errorMsg: mqttClose', errorMsg);
   	})
   
   	wxMqtt.on('error', (errorMsg) => {
   	wxMqtt.connectMqtt()
   	console.log('errorMsg: mqttError', errorMsg);
   	})
   
   }
   

2. Develop a listener for the target page.

   wxMqtt.on('message', (topic, newVal) => {
   console.log('message') // The listener data.
   })
   

Method 3: Call WeChat’s native Bluetooth APIs

For Bluetooth devices that cannot be directly connected to the internet, to query the device status, perform the following steps:

1. Create a Bluetooth connection channel between the device and mobile phone.
2. Call WeChat’s native Bluetooth APIs to listen for data reported by the device.
3. Parse device status data out of the reported data.

To help you quickly implement Bluetooth features for WeChat mini programs, Tuya provides the Bluetooth SDK. For more information, see WeChat Mini Program Bluetooth SDK.

FAQs

When is device.status called to query the device status?

When a page is initially opened or the device status has changes, call device.status to query the device status. You can also call it as needed.

How can I do if the MQTT connection is unstable?

1. In the case of putting the phone screen to sleep, switching between networks, or running WeChat mini programs in the background, disconnect from the mobile phone and reconnect to it.
2. Check whether the device is disconnected from the network.
3. Check whether the device reports data.

Why is a permission denial was returned after I made an API request to query device features?

Please check whether the same response occurs in other API requests. If this response has occurred only in the query of device features, it indicates that the device has not been standardized. You can also submit a ticket to request sending raw data.