# 阿里云YAT对接协议

阿里的飞燕/启明星平台的识别码为：0x01。

#产品配置格式

模组连接飞燕或启明星平台时，需要烧录三元组，采用一机一码方式。三元组可以由庆科烧录，也可以由客户自己烧录。

pk: product key

ps: product secret

dn: device name（YAT固件蓝牙配网，dn为模组mac地址，字母用小写）

ds: device secret

id: product id 蓝牙配网必填，其他配网类型不需要设置

ap_ssid: softap ssid softap配网时的热点名称[可选]

fix_key: awss fix key [可选]

time_zone: 时区（单位ms）[可选]，设置时区后，通过0x24 查询UTC时间，模组会自动加上时区

Payload格式如下：

{
	"pk": "123",
	"ps": "456",
	"dn": "asd",
	"ds": "zxc",
	"id": "123",
  "ap_ssid": "mxchip",
  "fix_key": "fffff",
  "time_zone":"28800000"
}

#配网方式

飞燕平台配网方式：一键配网、设备热点配网、蓝牙配网。

启明星平台配网方式：一键配网。

格式如下：

MCU->WiFi

CMD

PAYLOAD

Cloud Code

Type

TimeOut

说明

0x13

0x00

0x00

2 Byte

EMW系列：一键配网

EMC系列：蓝牙配网

0x01

0x00

2 Byte

EMW系列：一键配网

EMC系列：蓝牙配网

0x01

2 Byte

一键配网

0x02

2 Byte

设备热点配网

0x03

2 Byte

蓝牙配网

0x11

2 Byte

一键配网,抢占式,配网超时后绑定关系不变

0x12

2 Byte

设备热点配网,抢占式,配网超时后绑定关系不变

0x13

2 Byte

蓝牙配网,抢占式,配网超时后绑定关系不变

#数据通信之JSON

如果选择MCU与WiFi模组的属性通信方式为JSON格式，由于飞燕平台数据分为：属性、事件、服务，需要MCU区分数据类型。

#属性上报

MCU->WiFi

CMD

PAYLOAD

说明

Type

JSON

JSON格式数据  n取值范围1~1023

0x27

0x01

n Byte

属性上报

WiFi->MCU

无

#事件上报

MCU->WiFi

CMD

PAYLOAD

说明

Type

EventID Length

EventID

JSON

JSON格式数据  n取值范围1~1020

0x27

0x02

1 Byte

n Byte

n Byte

事件上报

EventID Length: 事件ID长度

EventID：事件ID，string类型

WiFi->MCU

无

#属性下发

WiFi->MCU

CMD

PAYLOAD

说明

Type

JSON

JSON格式数据  n取值范围1~1023

0x27

0x01

n Byte

属性下发

MCU->WiFi

无

#服务下发

WiFi->MCU

CMD

PAYLOAD

说明

Type

ServiceID Len

ServiceID

JSON

JSON格式数据  n取值范围1~1023

0x27

0x03

1 Byte

n Byte

n Byte

服务下发

ServiceID Len: 服务ID长度

serviceID：服务ID，string类型

MCU->WiFi

无

#数据通信之JSON-TLV

注意： 该方案暂时不支持

#属性配置表规则

JSON-TLV模式的属性配置表存放在模组端

{
	"linkkit": {
		"services": [{
			"tag": 11,
			"identifier": "serviceID_1",
			"inputData": [{
				"tag": 1,
				"identifier": "char_value",
				"dataType": "char"
			}, {
				"tag": 2,
				"identifier": "enum_value",
				"dataType": "enum"
			}]
		}, {
			"tag": 12,
			"identifier": "serviceID_2"
		}],
		"properties": [{
			"tag": 1,
			"identifier": "bool_value",
			"dataType": "bool"
		}, {
			"tag": 2,
			"identifier": "enum_value",
			"dataType": "enum"
		}, {
			"tag": 3,
			"identifier": "char_value",
			"dataType": "char"
		}, {
			"tag": 4,
			"identifier": "int_value",
			"dataType": "int"
		}, {
			"tag": 5,
			"identifier": "float_value",
			"dataType": "float"
		}, {
			"tag": 6,
			"identifier": "text_value",
			"dataType": "text"
		}, {
			"tag": 7,
			"identifier": "struct_value",
			"dataType": "struct",
			"struct": [{
				"tag": 1,
				"identifier": "char_value",
				"dataType": "char"
			}, {
				"tag": 2,
				"identifier": "float_value",
				"dataType": "float"
			}]
		}],
		"events": [{
			"tag": 8,
			"identifier": "Error",
			"outputData": [{
				"tag": 1,
				"identifier": "ErrorCode",
				"dataType": "char"
			}]
		}]
	}
}

#TLV格式之服务下发

示例1： 服务 ID为 “serviceID_1”，服务内容如下:

{
	"char_value": 12,
	"enum_value": 5
}

由于飞燕平台服务只能单服务下发，所以根据上述属性配置表，第1个字节表示服务ID，第2、3、4个字节字节为占位符。

服务“serviceID_1”的字节流: 0B 01 01 02 01 05 01 01 0C 

说明：

0B 01 01 表示“Tag=11”，对应服务ID为“serviceID_1”，0B之后的01 01是占位符。

02 01 05 表示“Tag=2”，对应的服务“serviceID_1”中的“enum_value”，01表示数据长度为1，05表示数据内容为5。

01 01 0C 表示“Tag=1”，对应的服务“serviceID_1”中的“char_value”，01表示数据长度为1，0C表示数据内容为12。

示例2： 服务 ID为 “serviceID_2”，服务内容无

服务“serviceID_2”的字节流: 0C 01 01

说明：

0C 01 01 表示“Tag=12”，对应服务ID为“serviceID_2”，0C之后的01 01是占位符。

#TLV格式之属性下发

示例：属性下发内容

{
	"struct_value": {
		"char_value": 3,
		"float_value": 0.3
	},
	"text_value": "123",
	"bool_value": 1
}

属性下发字节流：07 0B 02 04 9A 99 99 3E 01 01 03 06 0431 32 33 00 01 01 01

说明：

07 0B 02 04 9A 99 99 3E 01 01 03 表示 “Tag=7”对应的属性“struct_value”，0B 表示嵌套型属性长度为11，02 04 9A 99 99 3E 表示 “Tag=2”,04 表示属性内容长度4，9A 99 99 3E表示0.3，01 01 00 03 表示 “Tag=1”,04 表示属性内容长度1，属性值为3.

06 04 31 32 33 00 表示“Tag=6”对应的属性“text_value”，04 表示属性值的长度为4，31 32 33 00 表示字符串“123”。

#TLV格式之事件上报

示例：上报事件‘ErrorCode=0’。

上报字节流：08 01 01 01 01 00。

说明：08 01 01，08表示 “Tag=8”对应的事件ID为:Error。01 01为占位符。01 01 00表示事件ID“Error”中，tag=1的ErrorCode，01 表示数据长度， 00表示数据位0.

#数据通信之RAW-TLV

#属性配置表规则

RAW-TLV模式的属性配置表存放在模组端。透传脚本有python编写 profile 为 list.

脚本：📎aliFY.py (opens new window)📎Tmail.js (opens new window)

修改 profile ，替换 ali.py中的 profile，上传至飞燕后台。

profile = [
  {"tag": 128, "identifier": "Error", "dataType": "eventOutputData", 
    "eventOutputData": [
      {"tag": 1, "identifier": "ErrorCode", "dataType": "uint8_t"}
    ]},
  {"tag": 144, "identifier": "SyncTime", "dataType": "serviceData", 
    "serviceInputData": [
      {"tag": 1, "identifier": "LocalTime", "dataType": "text"}
    ]},
  {"tag": 1, "identifier": "LightSwitch", "dataType": "uint8_t"},
  {"tag": 2, "identifier": "ColorTemperature", "dataType": "uint32_t"},
  {"tag": 3, "identifier": "Brightness", "dataType": "uint32_t"},
  {"tag": 4, "identifier": "LightMode", "dataType": "uint8_t"},
  {"tag": 5, "identifier": "HSVColor", "dataType": "struct", 
    "struct": [
      {"tag": 1, "identifier": "Hue", "dataType": "uint16_t"},
      {"tag": 2, "identifier": "Saturation", "dataType": "uint8_t"},
      {"tag": 3, "identifier": "Value", "dataType": "uint8_t"}
    ]},
  {"tag": 6, "identifier": "RSSI", "dataType": "int8_t"}]

RAW-TLV 数据上报与下发与 JSON-TLV 数据上报下发一致

#MCU OTA

#统一OTA版本号

打开MCU OTA功能，统一OTA版本号命名格式为 mcu-xxx-wifi-xxx （0<x<9），mcu-xxx 表示主控MCU OTA的版本，在MCU OTA时，更新此版本。wifi-xxx 表示WiFi模组的OTA版本，在模组OTA升级时，更新此版本号。

#OTA版本号检查

设备接收到OTA升级推送时，比较版本号区分是MCU OTA还是模组OTA升级

  1. 如果 mcu-xxx 有更新，则进入 MCU OTA 升级流程
  2. 如果 wifi-xxx 有更新，则进入 WiFi模组 OTA流程
  3. 如果 mcu-xxx 及 wifi-xxx 都有更新，则提示 OTA 版本号错误，现不支持MCU、模组同时OTA升级

更多MCU OTA，请参考： 阿里云MCU OTA协议 文档。

#文档更新记录

日期

说明

2022.11.4

新增抢占式配网

2022.11.23

新增awss fixkey的设置

更新时间: 2023/1/30 下午5:14:47

← 阿里云MCU OTA协议 →