Connectivity Using Custom Protocol (Data Parsing)

Last Updated on : 2024-06-20 04:20:21download

This topic provides examples of data parsing for TuyaLink-based devices.

Before you start, you can familiarize yourself with Data Parsing.

Overview

A sample of the data parsing script with examples is provided for your reference.

Device-side development

For more information, see Messaging With Custom Format.

Script template

The default script template provided by the Tuya Developer Platform contains the function definitions for upstream and downstream communication.


/**
*
* After the cloud receives data from a device, this function converts the custom format data into TuyaLink JSON data.
* @param {array} rawData  An array of raw data. For example, [0x10,0xFF,0x01,0x02].
* @returns {object}  After conversion, the function returns the result object that should include the following properties:
* msgType: The message type.
* payload: The message payload.
* Example of the returned data:
* {
*     "msgType":"thing.property.report",
*     "payload":{
*         "msgId":"100001",
*         "time":1636625851737,
*         "data":{
*             "color":{
*                 "value":"RED",
*                 "time":1636625851737
*             }
*         }
*     }
* }
*/
 function rawDataToTyLink(rawData) {



 }



/**
*
* Before the cloud sends data to a device, this function converts the TuyaLink JSON data to the custom format data.
* @param {object} tylinkData  After conversion, the data object sent from the cloud to the device should include the following properties:
* msgType: The message type.
* payload: The message payload.
* Example:
* {
*     "msgType":"thing.property.set",
*     "payload":{
*         "msgId":"1000324923",
*         "time":1636625851737,
*         "data":{"color":"BLUE"}
*     }
* }
* @returns {array}  Returns an array of custom format data, for example, [0x12,0xEF,0x03,0x12].
*/
function tyLinkToRawData(tylinkData) {



}

Script examples

Example 1: Smart colored light

Create a product.

Log in to the Tuya Developer Platform. Choose Lighting > Light Source. Choose TuyaLink for the smart mode and then Custom for Data Protocol. For more information about the detailed processes of product creation, see Create Products.
Define functions.

In the Function Definition tab, click Add and add the desired functions to build a virtual device model.

For more information, see Function Definition.

Write the script.

You can try out the following code by copying it to the Script Debugging input box.

	/**
	*
	* The following example uses a smart colored light to show how data parsing works.
	*
	* ## Define a device model
	* {
	*    "code":"0asdlk234234",
	*    "name":"Smart Colored Light",
	*    "services":[
	*        {
	*            "properties":[
	*                {"abilityId":1, "code":"color",      "name":"Color", "typeSpec":{"type":"enum", "range":[ "RED", "GREEN", "BLUE" ] }},
	*                {"abilityId":2, "code":"brightness", "name":"Brightness", "typeSpec":{"type":"value", "min":0, "max":100, "step":1, "scale":0}},
	*                {"abilityId":3, "code":"switch",     "name":"On/Off", "typeSpec":{"type":"bool"}}
	*            ]
	*        }
	*    ]
	* }
	*
	* ## Define protocol format
	* +-----+---+---+---+---+---+---+---+---+---+---+---+---+-----+---+---+---+
	* |  \  | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 0 | 1 | 2 | 3 |  4  | 5 | 6 | 7 |
	* +-----+---+---+---+---+---+---+---+---+---+---+---+---+-----+---+---+---+
	* |  0  |    version    |      cmd      |             code                |
	* +-----+---------------+---------------+---------------+-----+---+---+---+
	* |  2  |                          property id                            |
	* +-----+-----------------------------------------------------------------+
	* |  4  |                          property value                         |
	* +-----+-----------------------------------------------------------------+
	*
	**/


	//~~~~~~~~~~~~~~~~~~~~~~~~~TuyaLink protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//
	var MSG_PROPERTY_SET 		= "thing.property.set";  		
	var MSG_PROPERTY_REPORT 	= "thing.property.report"; 		 	
	//~~~~~~~~~~~~~~~~~~~~~~~~~TuyaLink protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//


	//~~~~~~~~~~~~~~~~~~~~~~~~~Custom protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//
	var VERSION 				= 0x1;  // Protocol version
	var CMD_TYPE_SET 			= 0x1;	// Cloud sends a property update to the device.
	var CMD_TYPE_REPORT 		= 0x2;	// The device reports a property update to the cloud.

	var PROPERTY_COLOR		= 0x1;  // The ID of the color property.
	var PROPERTY_BRIGHTNESS = 0x2;	// The ID of the brightness property.
	var PROPERTY_SWITCH		= 0x3;  // The ID of the on/off property.

	var CODE_SUCCESS 	= 0;
	var CODE_ERROR 		= 1;

	var COLOR_TO_CODE = {"RED":0, "GREEN":1, "BLUE":2};  
	var CODE_TO_COLOR = {0:"RED", 1:"GREEN", 2:"BLUE"};  
	//~~~~~~~~~~~~~~~~~~~~~~~~~Custom protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//


	/**
	* 	Example 1: The cloud sends a color property setting to the device.
	*	Input parameters:
	*   	{"msgType":"thing.property.set", "payload":{"msgId":"15", "data":{"color":"BLUE"}}}
	*   Output data:
	*  		[0x11,0x00,0x00,0x01,0x00,0x02]
	*/
	function tyLinkToRawData(json) {
		// Encode data by message type.
		if(json.msgType == MSG_PROPERTY_SET) {
			return encodePropertySet(json.payload);
		}
	}


	/**
	* 	Example 1: The device reports data of the brightness property.
	*	Input parameters:
	*		[0x12,0x00,0x00,0x02,0x00,0x32]
	*   Output data:
	*  		{"msgType":"thing.property.report","payload":{"data":{"brightness":{"value":50}}}}
	*	
	*/
	function rawDataToTyLink(bytes) {
		var packet = decode(bytes);

		// Decode data by command type.
		if(packet.cmd == CMD_TYPE_REPORT) {
			return decodePropertyReport(packet);
		}
	}



	/** Encode the property setting message. */
	function encodePropertySet(json) {
		var data    = json.data;

		if(data.color !== undefined) {
			return encode(CMD_TYPE_SET, 0, PROPERTY_COLOR, COLOR_TO_CODE[data.color]);
		} else if (data.brightness !== undefined) {
			return encode(CMD_TYPE_SET, 0, PROPERTY_BRIGHTNESS, data.brightness);
		} else if (data.switch !== undefined) {
			return encode(CMD_TYPE_SET, 0, PROPERTY_SWITCH, data.switch ? 1 : 0);
		}
	}

	/** Encode the custom data packet. */
	function encode(cmd, code, proId, proVal) {
		var data = [];
		// 4-bit version number + 4-bit command type
		data = data.concat(encodeUint8(((VERSION << 4) & 0xF0) | (cmd & 0xF)));
		// 8-bit code
		data = data.concat(encodeUint8(code));
		if(proId != null) {
			// 16-bit property ID
			data = data.concat(encodeInt16(proId));
			// 16-bit property value
			data = data.concat(encodeInt16(proVal));
		}
		return data;
	}



	/** Decode the received property reporting. */
	function decodePropertyReport(packet) {
		var proId 	= packet.proId;
		var proVal 	= packet.proVal;

		var data = {"msgType": MSG_PROPERTY_REPORT,
					"payload":{"data":{}}}
		var payload = data.payload;
		if(proId == PROPERTY_COLOR) {
			payload.data.color = {"value": CODE_TO_COLOR[proVal]};
		} else if(proId == PROPERTY_BRIGHTNESS) {
			payload.data.brightness = {"value": proVal};
		} else if(proId == PROPERTY_SWITCH) {
			payload.data.switch = {"value": proVal == 1};
		}
		return data;
	}

	/** Decode custom data packet. */
	function decode(bytes) {
		var uint8RawData = new Uint8Array(bytes);
		var dataView 	 = new DataView(uint8RawData.buffer, 0);
		var packet		 = {};

		var header   	= dataView.getInt16(0);
		packet.version 	= (header & 0xF000) >> 12;
		packet.cmd 		= (header & 0x0F00) >> 8;
		packet.code 	= (header & 0x00FF);

		if(bytes.length > 2) {
			packet.proId = dataView.getInt16(2);
		}
		if(bytes.length > 4) {
			packet.proVal = dataView.getInt16(4);
		}
		return packet;
	}

	//~~~~~~~~~~~~~~~~~~~~~~~~~Useful methods~~~~~~~~~~~~~~~~~~~~~~~~~//

	function encodeUint8(value) {
		var uint8Array = new Uint8Array(1);
		var dv = new DataView(uint8Array.buffer, 0);
		dv.setUint8(0, value);
		return [].slice.call(uint8Array);
	}

	function encodeInt16(value) {
		var uint8Array = new Uint8Array(2);
		var dv = new DataView(uint8Array.buffer, 0);
		dv.setInt16(0, value);
		return [].slice.call(uint8Array);
	}
	function encodeInt32(value) {
		var uint8Array = new Uint8Array(4);
		var dv = new DataView(uint8Array.buffer, 0);
		dv.setInt32(0, value);
		return [].slice.call(uint8Array);
	}

Debug the script.
1. Enter the script in the Script Debugging input box.
2. Choose Cloud Sends Data and Device Reports Data for Simulation Type to verify the script on cloud-to-device and device-to-cloud messaging respectively.
3. (Optional) Click Save to save the draft.
4. When the script is ready to go, click Run.
5. The Parsing Results are displayed on the right of the page. If the script is verified, click Release As Official Version.
6. Release the script.
  
  After a script goes live, it processes the bidirectional messaging for all connected devices under the current product.

Example 2: Smart IP camera

Create a product.

Log in to the Tuya Developer Platform. Choose IP Camera > Smart Camera. Choose TuyaLink for the smart mode and then Custom for Data Protocol.

For more information about the detailed processes of product creation, see Create Products.
Define functions.

In the Function Definition tab, click Add and add the desired functions to build a virtual device model.
For more information, see Function Definition.

Write the script.

You can try out the following code by copying it to the Script Debugging input box.

	/**
	*
	* The following example uses a smart camera that is defined with properties, events, and actions to show how data parsing works.
	* ## The device model of the smart camera
	* {
	*     "code":"0asdlk234234",
	*     "name":"Smart Camera",
	*     "services":[
	*         {
	*             "properties":[
	*                 {"abilityId":1, "code":"nightvision","name":"Infrared Night Vision", "accessMode":"rw", "typeSpec":{"type":"enum", "range":[ "OFF", "ON", "AUTO" ] }}
	*             ],
	*             "events":[
	*                 {"abilityId":2, "code":"fault",     "name":"Fault event", "outputParams":[{"code":"faultNumber", "name":"Fault No.", "typeSpec":{"type":"value", "min":0, "max":20, "step":1, "scale":0}} }]}
	*             ],
	*             "actions":[
	*             	  {"abilityId":3, "code":"ptzcontrol",  "name":"Pan-tilt rotation", "inputParams":[{"code":"direction", "typeSpec":{"type":"enum", "range":[ "UP", "DOWN", "LEFT","RIGHT" ]}}]
	*             ]
	*         }
	*     ]
	* }
	*
	* ## The smart camera protocol uses UTF-8 encoding. Fields are separated by a comma (,), as shown below.
	* <version>,<cmd>,<sub cmd>,<code>,<ack>,<msgId>,<timestamp>,<cmd args>
	**/

	//~~~~~~~~~~~~~~~~~~~~~~~~~TuyaLink protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//
	var MSG_PROPERTY_SET 		= "thing.property.set";  		
	var MSG_PROPERTY_SET_RES	= "thing.property.set.response"; 	
	var MSG_PROPERTY_REPORT 	= "thing.property.report"; 		 	
	var MSG_PROPERTY_REPORT_RES = "thing.property.report.response";
	var MSG_ACTION_EXECUTE 		= "thing.action.execute"; 		 	
	var MSG_ACTION_EXECUTE_RES 	= "thing.action.execute.response";
	var MSG_EVENT_TRIGGER 		= "thing.event.trigger"; 		 	
	var MSG_EVENT_TRIGGER_RES 	= "thing.event.trigger.response";
	//~~~~~~~~~~~~~~~~~~~~~~~~~TuyaLink protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//


	//~~~~~~~~~~~~~~~~~~~~~~~~~Custom protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//
	var VERSION 				= 0x1;  // Protocol version
	var CMD_PROPERTY_SET 		= 0x1;  // Set property		
	var CMD_PROPERTY_SET_RES	= 0x2;  // Respond to property setting	
	var CMD_PROPERTY_REPORT 	= 0x3;  // Report property	 	
	var CMD_PROPERTY_REPORT_RES = 0x4;  // Respond to property reporting
	var CMD_ACTION_EXECUTE 		= 0x5;  // Execute the received command	 	
	var CMD_ACTION_EXECUTE_RES 	= 0x6;  // Respond to command execution
	var CMD_EVENT_TRIGGER 		= 0x7;  // Trigger an event	 	
	var CMD_EVENT_TRIGGER_RES 	= 0x8;  // Respond to the event

	var SUB_CMD_NIGHT_VISION	= 0x1;  // Infrared night vision
	var SUB_CMD_FAULT 			= 0x2;	// Fault reporting
	var SUB_CMD_PTZ_CONRTOLR  	= 0x3;  // Pan-tilt rotation
	var SEPARATOR				= ','; 	// Field separator
	//~~~~~~~~~~~~~~~~~~~~~~~~~Custom protocol constants~~~~~~~~~~~~~~~~~~~~~~~~~//

	/**
	* 	Example 1: The cloud sends an infrared night vision setting to the device.
	*	Input parameters:
	*   	{"msgType":"thing.property.set", "payload":{"msgId":"1001", "sys":{"ack":1}, "time":1637114892287, "data":{"nightvision":"ON"}}}
	*   Output data:
	*  		[0x31,0x2c,0x31,0x2c,0x31,0x2c,0x30,0x2c,0x31,0x2c,0x31,0x30,0x30,0x31,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x37,0x2c,0x4f,0x4e]
	*
	* 	Example 2: The cloud responds to data reporting.
	*	Input parameters:
	*   	{"msgType":"thing.property.report.response", "payload":{"msgId":"1994", "time":1637114892287, "code":1000}}
	*   Output data:
	*  		[0x31,0x2c,0x34,0x2c,0x30,0x2c,0x31,0x30,0x30,0x30,0x2c,0x30,0x2c,0x31,0x39,0x39,0x34,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x37]
	*
	* 	Example 3: The cloud sends an action command to the device.
	*	Input parameters:
	*   	{"msgType":"thing.action.execute", "payload":{"msgId":"2011", "time":1637114892287, "data":{"actionCode":"ptzcontrol", "inputParams":{"direction":"UP"}}}}
	*   Output data:
	*  		[0x31,0x2c,0x35,0x2c,0x33,0x2c,0x30,0x2c,0x31,0x2c,0x32,0x30,0x31,0x31,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x37,0x2c,0x55,0x50]
	*
	* 	Example 4: The cloud responds to a reported event.
	*	Input parameters:
	*   	{"msgType":"thing.event.trigger.response", "payload":{"msgId":"2028","time":1637114892289, "code":0}}
	*   Output data:
	*  		[0x31,0x2c,0x38,0x2c,0x30,0x2c,0x30,0x2c,0x30,0x2c,0x32,0x30,0x32,0x38,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x39]
	*/
	function tyLinkToRawData(json) {
		if(json.msgType == MSG_PROPERTY_SET) {
			// Encode the property setting message.
			return encodePropertySet(json.payload);
		} else if(json.msgType == MSG_PROPERTY_REPORT_RES) {
			// Encode the response to property reporting.
			return encodeResponse(CMD_PROPERTY_REPORT_RES, json.payload);
		} else if(json.msgType == MSG_ACTION_EXECUTE) {
			// Encode the action command.
			return encodeActionExecute(json.payload);
		} else if(json.msgType == MSG_EVENT_TRIGGER_RES) {
			// Encode the response to a triggered event.
			return encodeResponse(CMD_EVENT_TRIGGER_RES, json.payload);
		}
	}



	/**
	* 	Example 1: The device reports infrared night vision property to the cloud.
	*	Input parameters:
			[0x31,0x2c,0x33,0x2c,0x31,0x2c,0x30,0x2c,0x31,0x2c,0x31,0x34,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x37,0x2c,0x4f,0x4e]
	*   Output data:
	*  		{"msgType":"thing.property.report","payload":{"msgId":"14", "time":1637114892287, "sys":{"ack":1}, "data":{"nightvision":{"value":"ON","time": 1637114892287}}}}
	*
	* 	Example 2: The device responds to the command of property setting.
	*	Input parameters:
	*   	[0x31,0x2c,0x32,0x2c,0x30,0x2c,0x30,0x2c,0x30,0x2c,0x31,0x35,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x37]
	*   Output data:
	*		{"msgType":"thing.property.set.response", "payload":{"msgId":"15",  "time":1637114892287, "code":0}}
	*  
	* 	Example 3: The device reports a fault event to the cloud.
	*	Input parameters:
	*   	[0x31,0x2c,0x37,0x2c,0x32,0x2c,0x30,0x2c,0x31,0x2c,0x31,0x36,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x37,0x2c,0x35]
	*   Output data:
	*		{"msgType":"thing.event.trigger", "payload":{"msgId":"16",  "time":1637114892287,"sys":{"ack":1}, "data":{"eventCode":"fault", "outputParams":{"faultNumber":5}}}}
	*  
	* 	Example 4: The device reports the result of action execution.
	*	Input parameters:
	*   	[0x31,0x2c,0x36,0x2c,0x30,0x2c,0x30,0x2c,0x30,0x2c,0x31,0x37,0x2c,0x31,0x36,0x33,0x37,0x31,0x31,0x34,0x38,0x39,0x32,0x32,0x38,0x37]
	*   Output data:
	*		{"msgType":"thing.action.execute.response", "payload":{"msgId":"17",  "time":1637114892287, "code":0}}
	*
	*/
	function rawDataToTyLink(bytes) {
		var packet = decode(bytes);
		if(packet.cmd == CMD_PROPERTY_REPORT) {
			// Decode the received property reporting.
			return decodePropertyReport(packet);
		} else if(packet.cmd == CMD_PROPERTY_SET_RES){
			// Decode the response to property setting.
			return decodePropertySetResponse(packet);
		} else if(packet.cmd == CMD_EVENT_TRIGGER){
			// Decode the triggered event.
			return decodeEventTrigger(packet);
		} else if(packet.cmd == CMD_ACTION_EXECUTE_RES){
			// Decode the response to action execution.
			return decodeActionExecuteRes(packet);
		}
	}



	/** Encode the property setting message. */
	function encodePropertySet(json) {
		var data = json.data;
		var sys = json.sys;
		if(data.nightvision !== undefined) {
			return encode(CMD_PROPERTY_SET, SUB_CMD_NIGHT_VISION, 0, (sys && sys.ack) ? 1 : 0, json.msgId, json.time, data.nightvision);
		}
	}

	/** Encode the response to property reporting. */
	function encodeResponse(cmdType, json) {
		return encode(cmdType, 0, json.code, 0, json.msgId, json.time);
	}

	/** Encode the action command. */
	function encodeActionExecute(json) {
		var data = json.data;
		if(data.actionCode == "ptzcontrol") {
			return encode(CMD_ACTION_EXECUTE, SUB_CMD_PTZ_CONRTOLR, 0, 1, json.msgId, json.time, data.inputParams.direction);
		}
	}

	/** Encode the custom data packet. */
	function encode(cmd, subCmd, code, ack, msgId, timestamp, cmdArgs) {
		var line = [VERSION].concat([].slice.call(arguments)).join(SEPARATOR);
		return encodeUtf8(line);
	}


	/** Decode the received property reporting */
	function decodePropertyReport(packet) {
		var msgId 	= packet.msgId;
		var subCmd 	= packet.subCmd;
		var args 	= packet.args;
		var time	= packet.timestamp;

		var result = {"msgType": MSG_PROPERTY_REPORT,
					"payload":{"msgId": msgId,
							"time":time,
							"data":{},
							"sys":{"ack":packet.ack}}}
		var params = result.payload.data;
		if(subCmd == SUB_CMD_NIGHT_VISION) {
			params.nightvision = {"value": args, "time": time};
		}
		return result;
	}

	/** Decode the response to property setting. */
	function decodePropertySetResponse(packet) {
		return {
				"msgType": MSG_PROPERTY_SET_RES,
				"payload":{"msgId": packet.msgId,
						"time": packet.timestamp,
						"code": packet.code}
			};
	}


	/** Decode the triggered event. */
	function decodeEventTrigger(packet) {
		var msgId 	= packet.msgId;
		var subCmd 	= packet.subCmd;
		var args 	= packet.args;
		var time	= packet.timestamp;

		var result = {"msgType": MSG_EVENT_TRIGGER,
					"payload":{"msgId": msgId,
							"time":time,
							"data":{},
							"sys":{"ack":packet.ack}}}
		var params = result.payload.data;
		params.eventTime = time;
		if(subCmd == SUB_CMD_FAULT) {
			params.eventCode = "fault";
			params.outputParams = {"faultNumber": parseInt(args)};
		}
		return result;
	}

	/** Decode the response to action execution. */
	function decodeActionExecuteRes(packet) {
		return {
				"msgType": MSG_ACTION_EXECUTE_RES,
				"payload":{"msgId": packet.msgId.toString(),
							"time":packet.timestamp,
						"code": packet.code}
			};
	}


	/** Decode custom data packet. */
	function decode(bytes) {
		var line = decodeUtf8(bytes);
		var fields = line.split(SEPARATOR);
		return {
			"version"	:parseInt(fields[0]),
			"cmd"		:parseInt(fields[1]),
			"subCmd"	:parseInt(fields[2]),
			"code"		:parseInt(fields[3]),
			"ack"		:fields[4] == "1" ? 1 : 0,
			"msgId"		:fields[5],
			"timestamp"	:parseInt(fields[6]),
			"args"		:fields[7]
		}
	}

	//~~~~~~~~~~~~~~~~~~~~~~~~~Useful methods~~~~~~~~~~~~~~~~~~~~~~~~~//

	function encodeUtf8(text) {
		const code = encodeURIComponent(text);
		const bytes = [];
		for (var i = 0; i < code.length; i++) {
			const c = code.charAt(i);
			if (c === '%') {
				const hex = code.charAt(i + 1) + code.charAt(i + 2);
				const hexVal = parseInt(hex, 16);
				bytes.push(hexVal);
				i += 2;
			} else bytes.push(c.charCodeAt(0));
		}
		return bytes;
	}

	function decodeUtf8(bytes) {
		var encoded = "";
		for (var i = 0; i < bytes.length; i++) {
			encoded += '%' + bytes[i].toString(16);
		}
		return decodeURIComponent(encoded);
	}

Debug the script.
1. Enter the script in the Script Debugging input box.
2. Choose Cloud Sends Data and Device Reports Data for Simulation Type to verify the script on cloud-to-device and device-to-cloud messaging respectively.
3. (Optional) Click Save to save the draft.
4. When the script is ready to go, click Run.
5. The Parsing Results are displayed on the right of the page. If the script is verified, click Release As Official Version.
6. Release the script.
  
  After a script goes live, it processes the bidirectional messaging for all connected devices under the current product.

Things to note

Be sure to read the script examples before you write a script.
A single script file cannot exceed 128 KB in size.

Prev DocGateway and Gateway Sub-Device Connectivity

Next DocDevice Management