一、平台简介

使用天猫精灵IoT平台云对云接入，可将您智能家居产品快速接入天猫精灵音箱及AliGenie生态。

产品开发：将产品名称、型号、功能、语料和屏显功能及消息注册到平台，实现设备发现、设备控制、状态查询、状态上报、消息推送、场景联动
技能开发：将技能、OAuth服务、网关等信息注册到平台，实现云云用户账号互通
设备管理：针对注册至平台的产品，管理开发、审核、上架状态

相比于原有家居技能平台，升级的核心功能如下：

二、升级内容

2.1 产品和技能开发解耦：

新升级的平台，技能可单独上线和更新，归属于此技能的产品可逐一创建、开发、发布、更新，增加产品无需再修改逐个修改技能，详情见下方“三、接入流程-1.1 流程总览”

2.2 账号授权升级：

原有的天猫精灵App账号授权外，需完成5-8步的设置：

三方App设备配网绑定
精灵App技能查找
打开三方授权页面
三方账号账号输入，密码输入
三方账号授权绑定

2.3 设备发现升级

在技能授权绑定成功后，天猫精灵云会向厂商云发起获取用户在厂商云的已绑定的设备列表，2.0协议的发现设备请求协议如下。

{
    "header":{
        "namespace":"AliGenie.Iot.Device.Discovery",
        "name":"DiscoveryDevices",
      	//每个请求都会生成唯一的messageId，有问题反馈时附上messageId方便阿里技术支持同学排查日志
        "messageId":"1bd5d003-31b9-476f-ad03-71d471922820",
      	//标识使用2.0协议请求
        "payLoadVersion":2
    },
    "payload":{
      	//技能授权绑定时厂商云颁发给天猫精灵云的access token
        "accessToken":"access token"
    }
}

厂商云收到天猫精灵云的设备发现请求后，使用2.0协议格式返回该用户下支持2.0协议的所有设备。响应包体协议格式如下：

{
    "header":{
        "namespace":"AliGenie.Iot.Device.Discovery",
        "name":"DiscoveryDevicesResponse",
      	//天猫精灵发起的请求包体header里的messageId，有问题反馈时附上messageId方便阿里技术支持同学排查日志
        "messageId":"1bd5d003-31b9-476f-ad03-71d471922820",
       //标识使用2.0协议请求
        "payLoadVersion":2
    },
    "payload":{
        "devices":[
            {
                "deviceId":"34ea34cf2e63",
                /**
                 * 设备别名，
                 * 用户可以为该设备设置一个别名如"落地扇"
                 * 猫精支持的设备别名列表参考：https://open.bot.tmall.com/oauth/api/aliaslist
                 * 推荐使用猫精支持的设备别名，否则语音无法识别
                 * 非必填
                 */
                "deviceName":"落地扇",
              	/**
                 * 设备的品类英文名，如aircondition
                 * 猫精支持的品类列表参考：https://www.aligenie.com/doc/357554/eq19cg
                 * 必填
                 */
                "deviceType":"fan",
              	/**
                 * 品牌名称
                 * 必须是猫精平台支持的品牌名，注意！！！
                 * 必填
                 */
                "brand":"",
                /**
                 * 产品型号
                 * 必须与在猫精平台创建产品的型号一致，注意！！！
                 * 必填
                 */
                "model":"",
                /**
                 * 设备的位置
                 * 猫精支持的位置列表参考https://open.bot.tmall.com/oauth/api/placelist
                 * 推荐使用猫精支持的位置，否则语音无法识别
                 * 用户可以为该设备设置位置，如"客厅"
                 * 这时可以对天猫精灵说"打开客厅的落地扇"
                 * 选填
                 */
                "zone":"",
              	/**
                 * 设备的属性状态，参照设备对应的产品功能定义
                 * 非必填
                 **/
                "status":{
                    "powerstate":1,
                    "brightness":30
                },
                "extensions":{
                    "extension1":"",
                    "extension2":""
                }
            }
        ]
    }
}

2.0协议要求厂商返回的设备必须在天猫精灵IoT平台上创建相应的产品定义。厂商返回的设备信息中deviceType，

brand，model必须与天猫精灵IoT平台上的产品信息定义相对应。如某个厂商在天猫精灵IoT平台上创建品牌为大*空调 D*IN,型号为AK-dfgfdg的空调产品，那么厂商云返回该产品对应的设备时，设备信息中deviceType取值为 aircondition，brand取值为大*空调 D*IN , mode取值为 AK-dfgfdg ，如下图所示。

brand，mode

2.4 设备列表更新通知

除了技能授权绑定时，天猫精灵云主动向厂商云获取用户的设备列表(2.3 设备发现升级)之外，厂商云可以在用户设备列表发生变动时（包括但不限于新增设备、删除设备、更新设备、状态变化等）通过alibaba.ailabs.iot.device.list.update.notify接口通知天猫精灵智能家居云端去重新获取该用户的设备列表,天猫精灵云会发起2.3 设备发现协议请求到厂商云获取设备列表。alibaba.ailabs.iot.device.list.update.notify接口接入流程参考文档链接

2.5 控制协议升级：

原有的aligenie.iot 1.0控制协议为对deviceId下发语音控制协议：

｛
  "header":{
      "namespace":"AliGenie.Iot.Device.Control",
      "name":"TurnOn",
      "messageId":"1bd5d003-31b9-476f-ad03-71d471922820",
      "payLoadVersion":1
   },
   "payload":{
       "accessToken":"access token",
       "deviceId":"34234",
       "deviceType":"XXX",
       "attribute":"powerstate",
       "value":"on",
       "extensions":{
          "extension1":"",
          "extension2":""
      }
    }
 ｝
 正常响应：
 ｛
  "header":{
      "namespace":"AliGenie.Iot.Device.Control",
      "name":"TurnOnResponse",
      "messageId":"1bd5d003-31b9-476f-ad03-71d471922820",
      "payLoadVersion":1
   },
   "payload":{
      "deviceId":"34234"
    }
 ｝
 异常响应：
 ｛
  "header":{
      "namespace":"AliGenie.Iot.Device.Control",
      "name":"ErrorResponse",
      "messageId":"1bd5d003-31b9-476f-ad03-71d471922820",
      "payLoadVersion":1
   },
   "payload":{
        "deviceId":"34234",
         "errorCode":"DEVICE_NOT_SUPPORT_FUNCTION",
         "message":"device not support"
    }
  ｝

升级后aligenie.iot 2.0协议按功能下发thing.attribute.set/thing.attribute.adjust和上报"thing.attribute.get"，支持多设备的组播下发。设备功能在产品创建时即完成注册。

2.5.1 设置设备属性值操作(2.0协议)

thing.attribute.set 代表设置值操作，发送给厂商的属性值就是目标值，厂商不需要换算直接把该值下发给设备。如用户对天猫精灵说"天猫精灵，开灯"，这时天猫精灵云发送给厂商云的协议如下：

用户：“天猫精灵，开灯”

发送给三方云请求中有这两个灯的deviceId，由deviceIds字段标识控制哪些设备

{
	"header": {
		"namespace": "AliGenie.Iot.Device.Control",
    //设置操作name字段值固定是thing.attribute.set
		"name": "thing.attribute.set",
		"messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
		"payLoadVersion": 2 //标识使用2.0协议控制设备
	},
	"payload": {
		"accessToken": "access token",
    //同一个productId下的设备控制是同一个请求下去
		"deviceIds": ["devId-34234","devId-abc","devId-1234","devId-5678"],
		"params": {
      //平台上灯对应的产品开关功能(标识符是powerstate)定义是枚举类型，取值有 关闭：0，打开：1 
			"powerstate": 1
		},
    // 扩展信息 与 具体业务有关,譬如博联零配设备用到extensions，或其他业务用到uuid
    "extensions":{
        "devId-34234":{},
      	"devId-abc":{},
      	"devId-1234":{},
    		"devId-5678":{},
      	"uuid":""
     }
	}
}

额外说明： params 是Map类型，语音控制每次控制只支持控制一个功能属性，但是有特殊某些场景或某厂商需求会要求每次控制把该设备支持的属性全部下发给设备(如红外设备))。

params里的key是该设备对应在天猫精灵IoT平台上创建的产品的功能定义里的功能标识符，value是该功能对应的取值定义，如某灯品类的产品功能定义如下：

2.5.2 调节设备属性值操作(2.0协议)

thing.attribute.adjust 代表调值操作，发送给厂商的属性值就是步长值，厂商需要把该功能属性当前值加上步长值计算得到目标值再发送给设备。如用户对天猫精灵说"天猫精灵，灯亮度调高/调低20"，这时天猫精灵云发送给厂商云的协议如下：

{
    "header": {
        "namespace": "AliGenie.Iot.Device.Control",
        //调值操作name字段值固定是thing.attribute.adjust
        "name": "thing.attribute.adjust",  
        //messageId用于排查问题，厂商反馈问题需要天猫精灵技术支持时请提供messageId
        "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
        //协议版本号
        "payLoadVersion": 2  
    },
    "payload": {
        "accessToken": "access token",
       //同一个productId下的设备控制是同一个请求下去
        "deviceIds": ["devId-1234","devId-5678"],
        "params": {
            //表明要把devId-1234，devId-5678这几个设备的brightness功能值调高/调低20
            //假如devId-1234设备的brightness当前值是70，那么厂商云需计算本次操作的目标值(70+20=90),最后发送给设备的值是90；假如devId-5678设备的brightness当前值是45，那么厂商云需计算本次操作的目标值(45+20=65),最后发送给设备的值是65。
            //同理用户说"灯亮度调低20"，天猫精灵发送过来的是"brightness": -20，假如devId-1234设备的brightness当前值是70，那么厂商云需计算本次操作的目标值(70-20=50),最后发送给设备的值是50；假如devId-5678设备的brightness当前值是45，那么厂商云需计算本次操作的目标值(45-20=25),最后发送给设备的值是25。
            "brightness": 20 //20说明是调高操作；-20说明是调低操作
        },
    // 扩展信息 与 具体业务有关,譬如博联零配设备用到extensions，或其他业务用到uuid
    "extensions":{
        "devId-34234":{},
        "devId-abc":{},
        "devId-1234":{},
        "devId-5678":{},
        "uuid":""
     }
    }
}

2.5.3 设备控制响应协议格式

aligenie.iot 2.0协议控制设备支持设置设备属性值thing.attribute.set和调节属性值thing.attribute.adjust 两种操作类型。厂商云收到天猫精灵云发送的设备控制请求后，要返回每个设备的控制结果。控制设备响应协议格式如下：

正常返回：
 ｛
  "header":{
      "namespace":"AliGenie.Iot.Device.Control",
      "name":"CorrectResponse",
      "messageId":"1bd5d003-31b9-476f-ad03-71d471922820",
      "payLoadVersion":2
   },
   "payload":{
     	"deviceResponseList":[
        {
         "deviceId":"devId-34234",
         "errorCode":"SUCCESS",
         "message":"SUCCESS"
     	 },
       {
         "deviceId":"devId-abc",
         "errorCode":"SUCCESS",
         "message":"SUCCESS"
     	 },
        {
         "deviceId":"devId-1234",
          //说明devId-1234对应的设备不支持此功能
         "errorCode":"DEVICE_NOT_SUPPORT_FUNCTION",
         "message":"device not support"
     	 },
       {
         "deviceId":"devId-5678",
         //说明devId-5678对应的设备已离线
         "errorCode":"IOT_DEVICE_OFFLINE",
         "message":"device is offline"
     	 }
      ]
    }
  ｝

2.6 属性状态同步协议升级

当设备状态发生变化时，如设备从关闭状态变成打开，需要通过alibaba.ailabs.iot.cloud.device.report接口把设备状态同步给天猫精灵精灵云，以便设备状态及时在天猫精灵屏显终端准确呈现设备的状态变化，及语音查询状态变化。

设备属性状态同步接口参数描述如下：

{
    //技能id,厂商在天猫精灵IoT平台创建技能的id(必填)
    "skill_id":5**3,
  	//每次请求的消息id,由厂商云在发起每次请求时生成全局唯一消息id,方便问题定位排查 (必填)
    "message_id":"7309eeb8-3826-495c-9046-5ceed2c72aa7",
  	//设备id,表示当前同步的的该设备的状态 (必填)
    "device_id":"devId-abc",
  	//上报类型，1：属性上报 2：在离线上报 3：事件上报。这里是属性状态同步，因此固定为1。(必填)
    "report_type":1,
  	//设备所有属性的当前状态值组成的Map对象的Json字符串，参照设备对应的产品功能定义。(必填)
    "payload":"{\"powerstate\":1,\"brightness\":100}",
  	//协议版本号，现在是2.0协议
    "payload_version":2,
  	//账号类型（1：代表使用Oauth授权颁发给天猫精灵云的token换算成自己内部平台的用户信息；2：代表使用openUserId换算成自己内部平台的用户信息）。必填
  	//建议使用account_type=1
    "account_type":1,
  	//Oauth授权颁发给天猫精灵云的token。当account_type=1时，user_access_token必填。
    "user_access_token":"0d62************80cf",
   //Oauth授权颁发给天猫精灵云的open_id。当account_type=2时，open_user_id必填。
    "open_user_id":"502d***********e89b",
  	//保留业务字段,选填
    "extension":"",
  	//当前请求的时间戳，防止多个请求由于网络延迟原因，把同步状态值相互覆盖。（必填）
    "time_stamp":1614223850176
}

其中payload字段是该设备当前发生变化的属性及属性值构成的Map对象Json字符串。如设备id=devId-abc的设备在天猫精灵IoT平台上的产品功能定义如下：

重要：每次请求time_stamp必须赋值为当前请求的时间戳，当有并发有多个请求到达天猫精灵云时，天猫精灵云只保存time_stamp最大的一个请求，time_stamp小的或者重复的则不处理。

2.7 设备在线离线同步

当设备在线状态发生变化时，如设备从离线状态变成在线状态，需要通过alibaba.ailabs.iot.cloud.device.report接口把设备状态同步给天猫精灵精灵云，以便设备状态及时在天猫精灵屏显终端准确呈现设备的状态变化，及语音查询状态变化。

在线离线同步的接口参数与2.6 属性状态同步基本保持一致，除了report_type和payload字段的值有差异之外。接口参数描述如下：

{
    //技能id,厂商在天猫精灵IoT平台创建技能的id(必填)
    "skill_id":5**3,
  	//每次请求的消息id,由厂商云在发起每次请求时生成全局唯一消息id,方便问题定位排查 (必填)
    "message_id":"7309eeb8-3826-495c-9046-5ceed2c72aa7",
  	//设备id,表示当前同步的的该设备的状态 (必填)
    "device_id":"devId-abc",
  	//上报类型，1：属性上报 2：在离线上报 3：事件上报。这里是在线离线状态同步，因此固定为2。(必填)
    "report_type":2,
  	//设备在线离线状态值，key固定为onlinestate，online代表设备在线，offline代表设备离线
    "payload":"{\"onlinestate\":\"online\"}",
  	//协议版本号，现在是2.0协议
    "payload_version":2,
  	//账号类型（1：代表使用Oauth授权颁发给天猫精灵云的token换算成自己内部平台的用户信息；2：代表使用openUserId换算成自己内部平台的用户信息）。必填
  	//建议使用account_type=1
    "account_type":1,
  	//Oauth授权颁发给天猫精灵云的token。当account_type=1时，user_access_token必填。
    "user_access_token":"0d62************80cf",
   //Oauth授权颁发给天猫精灵云的open_id。当account_type=2时，open_user_id必填。
    "open_user_id":"502d***********e89b",
  	//保留业务字段,选填
    "extension":"",
  	//当前请求的时间戳，防止多个请求由于网络延迟原因，把同步状态值相互覆盖。（必填）
    "time_stamp":1614223850176
}

2.8 设备事件触发上报

当设备触发某个事件时，可以通过alibaba.ailabs.iot.cloud.device.report接口上报事件状态给天猫精灵云，天猫精灵云使用场景如下：

APP告知用户设备事件，如滤芯需要更换
触发天猫精灵消息播报，如TTS语音提醒
智能场景联动，如跨设备联动

设备事件上报的接口参数与2.6 属性状态同步基本保持一致，除了report_type和payload字段的值有差异之外。接口参数描述如下：

{
    //技能id,厂商在天猫精灵IoT平台创建技能的id(必填)
    "skill_id":5**3,
  	//每次请求的消息id,由厂商云在发起每次请求时生成全局唯一消息id,方便问题定位排查 (必填)
    "message_id":"7309eeb8-3826-495c-9046-5ceed2c72aa7",
  	//设备id,表示当前同步的的该设备的状态 (必填)
    "device_id":"devId-abc",
  	//上报类型，1：属性上报 2：在离线上报 3：事件上报。这里是事件上报，因此固定为3。(必填)
    "report_type":3,
  	//上报设备触发的事件及参数，事件定义参照设备对应的产品功能里的事件定义。(必填)
    "payload":"{\"eventNameEn\":\"faultReportEvent\",\"params\":{\"errorCode\":149}}",
  	//协议版本号，现在是2.0协议
    "payload_version":2,
  	//账号类型（1：代表使用Oauth授权颁发给天猫精灵云的token换算成自己内部平台的用户信息；2：代表使用openUserId换算成自己内部平台的用户信息）。必填
  	//建议使用account_type=1
    "account_type":1,
  	//Oauth授权颁发给天猫精灵云的token。当account_type=1时，user_access_token必填。
    "user_access_token":"0d62************80cf",
   //Oauth授权颁发给天猫精灵云的open_id。当account_type=2时，open_user_id必填。
    "open_user_id":"502d***********e89b",
  	//保留业务字段,选填
    "extension":"",
  	//当前请求的时间戳，防止多个请求由于网络延迟原因，把同步状态值相互覆盖。（必填）
    "time_stamp":1614223850176
}

其中payload字段是该设备当前触发的事件及参数构成的Map对象Json字符串。如设备id=devId-abc的设备在天猫精灵IoT平台上的产品功能定义中事件定义如下：

事件上报的payload里的固定数据结构如下：

{
  	//eventNameEn字段指示当时上报的事件标识符，如故障上报在天猫精灵IoT平台上标识符是faultReportEvent
    "eventNameEn":"faultReportEvent",
  	//params是该事件定义的参数，故障上报事件在平台上定义有一个标识符为errorCode的参数
    "params":{
      	//参数的标识符及对应的值
        "errorCode":149
    }
}

2.9 新增屏显终端交互

除语音交互外，天猫精灵带屏终端智能家居升级，平台目前开放了天猫精灵手机App端的触屏交互，开发者可选择：

公版面板：
自定义面板：

带屏音箱及其他AliGenie生态设备敬请期待

2.10 新增设备触发的语音和App消息

新建产品的属性、事件，可作为状态或事件上报，定义天猫精灵音箱语音tts消息，及天猫精灵App消息

2.11 新增智能场景联动

新建产品的属性、事件，可作为状态或事件上报，定义天猫精灵智能场景触发条件。目前已开放

温湿度传感器：温度高于/低于，湿度高于/低于上报触发
门锁：开门通知

其余传感器等设备目前商家接入中，如有开放需求，请联系aligenie.iot@list.alibaba-inc.com

三方云App已设置好的场景模式，天猫精灵同步接入方案目前在设计中，敬请期待！

2.12 开放平台功能及交互升级

流程化产品开发向导

一站式线上调试平台

三、接入流程

3.1 流程总览

与原有家居技能平台不同，新的天猫精灵IoT平台在技能和产品上解耦，开发者可先完成技能开发和上线，然后逐一开发和维护技能账号下支持的产品型号

3.2 注册AliGenie开发者账号

登陆AliGenie开放平台官网，点击右上角“注册”

按指引完成淘宝企业账号注册

完成淘宝企业账号注册后，按账号名称和密码登陆天猫精灵IoT开放平台，则进入实名认证指引

勾选IoT合作方向，按指引完成实人认证、企业验证，提交后小二将在7个工作日内完成审核。

3.3 技能开发

新技能开发：请在技能开发中创建新技能，定义技能名称。按平台指引完成技能开发、发布和上架。详情见“技能开发”。

存量技能升级：请选择该技能，在技能发布流程中“更新”，按技能开发流程更新后提交发布和上架。详情见“存量技能开发”

3.4 产品开发

相较于原来的家居技能，IoT平台对产品型号的描述精确到Product ID粒度，开发者可定义硬件的功能

二、技能开发

2.1 新技能开发

2.2 存量技能升级

在原技能平台创建的技能需要在天猫精灵IoT平台进行确认升级支持2.0协议

在技能列表页面找到需要升级支持2.0协议的技能，进入技能信息页面，勾选"协议升级"，点击保存即可。

保存后，该存量技能就打标支持2.0协议，这时开发者可以在该技能下创建产品，并开发和调试2.0协议。2.0协议开发调试通过后，可以提交技能发布审核(注意要调试通过才能提交发布上线)，如下图：

FQA:

Q:存量技能新老协议如何兼容?(这个技能之前已经支持1.0协议，并且已有线上用户在使用，现在该技能升级支持2.0协议，正在使用中的设备如何不受影响？)

A: 存量技能在升级支持2.0后(未发布上线)可以配置测试账号灰度名单进行开发和调试2.0协议，测试账号灰度名单配置流程如下图：

在技能列表页找到需要配置测试账号名单的技能，在点击"成员管理"进入技能权限管理页面；点击"添加成员"，在成员账号里输入待配置的测试账号，账号必须是天猫精灵APP注册过的账号(最好是手机号码或者淘宝昵称)。权限范围选择"线上真机开发联调/灰度测试"。点击"确认"保存既可。

配置了灰度用户后，当该用户请求"发现设备"时，天猫精灵云判断该用户是在灰度名单内，则会向厂商云先发起1.0的设备发现协议后也会发起2.0协议。不在灰度用户配置名单里的用户则只会发出1.0的设备发现协议。

厂商云需要判断哪些设备支持1.0协议则使用1.0协议格式返回这些设备，哪些设备支持2.0设备则使用2.0协议格式返回这些设备。例子如下：

天猫精灵云发出1.0发现设备协议，厂商云使用1.0协议返回支持1.0协议的设备：{

"header": {

"namespace": "AliGenie.Iot.Device.Discovery",

"name": "DiscoveryDevicesResponse",

"messageId": "1bd5d003-31b9-476f-ad03-71d471922820",

//1.0协议版本号，厂商返回请求响应的协议版本号必须与与精灵云发出的请求协议版本一致

"payLoadVersion":1

"payload": {

"devices": [{"deviceId":"34ea34cf2e63","deviceName":"单孔插座","deviceType":"outlet","zone":"","brand":"","model":"","icon":"https://git.cn-hangzhou.oss-cdn.aliyun-inc.com/uploads/aicloud/aicloud-proxy-service/41baa00903a71c97e3533cf4e19a88bb/image.png","properties":[{"name":"powerstate","value":"off"}],"actions":["TurnOn","TurnOff"],"extensions":{"extension1":"","extension2":""}}]

}

天猫精灵云发出2.0发现设备协议，厂商云使用2.0协议返回支持2.0协议的设备：

{

"header":{

"namespace":"AliGenie.Iot.Device.Discovery",

"name":"DiscoveryDevicesResponse",

"messageId":"1bd5d003-31b9-476f-ad03-71d471922820",

//2.0协议版本，厂商返回请求响应的协议版本号必须与与精灵云发出的请求协议版本一致

"payLoadVersion":2

"payload":{

"devices":[

{"deviceId":"662df8ehyui8","deviceName":"落地扇","deviceType":"fan","brand":"","model":"","zone":"","status":{"powerstate":1,"brightness":30},"extensions":{"extension1":"","extension2":""}}

]

}

如果厂商确认没有设备支持1.0/2.0协议则返回空列表既可，如：

{

    "header":{
       "namespace":"AliGenie.Iot.Device.Discovery",
       "name":"DiscoveryDevicesResponse",
       "messageId":"1bd5d003-31b9-476f-ad03-71d471922820",

//协议版本，厂商返回请求响应的协议版本号必须与与精灵云发出的请求协议版本一致

"payLoadVersion":1
},

    "payload":{
       "devices":[] //厂商确认该技能没有设备支持payLoadVersion指定的协议版本，则返回空列表
   }

}

设备控制天猫精灵云根据设备发现请求返回的设备知道该设备支持1.0协议还是支持2.0协议，就会下发相应版本的设备控制协议给厂商云。

存量技能在升级支持2.0并且已发布上线，绑定该技能的线上所有用户在发现设备时天猫精灵云均会向厂商云先发起1.0的设备发现协议后也会发起2.0协议。