Bluetooth LE 设备授权

本文档主要介绍生产测试SDK接口参考消息，包括主要功能，接口函数和回调函数。

概述

蓝牙生产测试SDK是基于涂鸦私网络通信协议、蓝牙设备固件通信库两部分组成。其中。涂鸦网络通信库用于于涂鸦云的通信。主要包括账号登录、获取授权码信息、模块授权、授权校验、授权日志上传等功能。蓝牙设备固件通信库包括基于涂鸦蓝牙设备通信协议的模块产测功能，包括进入产测、授权信息读写、按键测试、信号强度测试等功能。

SDK下载地址

• Demo
• SDK

目录结构

    ├─TuyaCloudLib
    │      BouncyCastle.Crypto.dll
    │      Newtonsoft.Json.dll
    │      TuyaCloudIfLib.dll
    │      TuyaCloudIfLib.xml
    │      RleaseNote.txt
    └─Communication
    │      Tuya.Module.ProtocolServer.dll
    │      Tuya.Core.dll
    │      Tuya.Module.BottomCommunication.dll
    │      Newtonsoft.Json.dll

• TuyacloudLib目录的内容为和涂鸦云通讯的库文件
• Communication目录下的内容为和设备固件通信库文件

主要库介绍

涂鸦网络通信库接口介绍

接口	说明
SetUrlSftVer	设置涂鸦云工作环境
UserLogin	账号登录
TokenAuth	授权
GetTokenInfo	获取Token信息
TokenAuthValidate	授权有效性校验
AddAuthLog	添加授权日志

涂鸦蓝牙设备固件通信库接口总览

接口	说明
CommunicationServerBuilder.UseSerialPort	设置蓝牙通信服务串口信息
CommunicationServerBuilder.Start	启动蓝牙通信服务
CommunicationServerBuilder.Stop	停止蓝牙通信服务
CommunicationServerBuilder.EnterPcbaTestMode	进入测试模式
CommunicationServerBuilder.WriteConfigInfo	写入固件授权信息
CommunicationServerBuilder.ReadConfigInfo	读取固件授权信息

流程说明

本部分内容为涂鸦产测授权SDK主要是要部分的相关设置、接口调用流程。

串口测试整体流程

串口测试主要包括账号登录、授权码信息获取、固件烧录、进入测试模式、固件版本校验、授权等部分。测试开始前需确保涂鸦账号、授权码Token正确无误。

设置涂鸦云工作环境

用于设置涂鸦云的工作模式，设置软件版本信息等。

登录账号

账号登录为使用涂鸦云授权的前提，账号密码需向涂鸦注册。登录成功后方可使用涂鸦云相关功能。

授权信息
授权码信息部分作用为根据涂鸦提供授权码获取授权码配置的相关信息，如固件下载链接、固件版本信息以及其他相关测试的配置等。

固件烧录
固件烧录部分为模块固件烧录功能，可根据具体情况取舍。

进入产测模式

调用程序通过串口连接待测设备，调用蓝牙设备固件通信库进入产测模式接口，根据通信协议返回正确数据后，固件进入产测成功，可以进行后续通信。如进入产测失败，则无法进行后续流程。

固件版本比较

此部分主要作用为确保固件中运行的固件版本与授权码中配置的固件信息一致，确保设备批次或烧录结果无误。方法为调用固件通信库接口将获取到的相关信息与授权码中相关信息进行校验。

授权

授权部分为设备向涂鸦云注册授权，只有授权通过后才可与涂鸦云进行正确连接。本部分涉及云端通信库授权、授权校验、添加授权日志等接口，涉及到蓝牙设备固件通信库中写入设备授权信息、读取设备授权信息接口。此部分授权通通过后授权测试结束。如授权失败，可能会造成整机产测无法进入。授权部分中除读写授权配置信息可使用自有通信协议外，云端通信库授权接口调用不可缺少、省略，否则都可能会造成后续流程失败。

授权流程

本部分介绍授权详细流程，其中涉及云端通信库、蓝牙设备固件通信库相关接口。

授权前准备

授权开始前需确认登录流程是否成功，以及Token相关信息获取无误。除此之外需自行创建序列号SN用于测试，SN的作用为识别授权设备身份，以方便后续整机测试获取Mac正常。SN的要求为独立不重复，且每个SN使用后不可重复授权(包括授权失败的情况)。

授权接口调用

参数为SN、授权码、mac地址(根据情况传入)、软件版本信息。调用成功后云端会返回授权接口会返回分配的mac、uuid、accessKey等信息，此信息用于写入固件设置固件相关参数。

注：

1. mac是否传入根据具体需求判断。

1. 如使用涂鸦分配mac，生成Token时需设置相关信息。此情况下，调用授权接口无需传入mac地址，授权接口会返回授权的mac参数。
2. 如使用模块中已有的的mac地址，Token中不可配置分配mac。调用接口前需读取正确的mac地址，再将此mac作为参数传入到授权接口中。对于这种情况，授权接口返回的mac与传入的mac相同。如Token设置了分配mac，但以模块mac作为参数授权，此时授权的mac为云端分配mac，接口返回mac也为云端返回mac，不是模块真实mac地址。

2. 授权错误、缺失或授权SN重复使用，授权接口会返回无法授权的错误信息。

向固件写入授权信息

此处如使用涂鸦蓝牙设备固件通信库，需确保蓝牙通信服务开启成功、进入产测模式成功。根据进入产测返回结果确定授权信息是否需要写入产品ID，同时写入设备信息的参数还包括调用授权接口返回的uuid、mac、accessKey以及是否为整机产测信息。调用向固件写入授权信息接口后，等待串口返回写入结果。

读取固件授权信息

读取固件授权信息即为读取上步骤中写入的授权信息，此方法用于校验授权信息写入是否成功。返回信息包括mac、uuid、accessKey以及根据情况返回的Pid。

固件信息校验

用于比对写入、读出固件授权信息是否一致，确保授权无误。

授权信息校验

调用授权接口并校验固件授权信息后，可确保写入固件授权信息与授权信息一致，此时需进行授权校验确保授权成功。参数包括Token、SN、uuid、mac、accessKey、软件版本信息等。

以上步骤除读写固件授权信息可使用自有协议外，其余流程(包括使用涂鸦蓝牙设备固件通信协议的情况)必须确保返回成功方可进行下一项的调用，否则会导致授权失败。如SN已被授权接口使用过，无论后续流程是否成功，都不可再使用同一个SN重复授权。

涂鸦网络通信函数说明

设置涂鸦云工作环境 SetUrlSftVer

功能说明(Summary)
此接口用于选择涂鸦云的工作环境和设置调用SDK的应用程序的名称和版本信息。调用此接口后，每次调用涂鸦网络通信接口时，调用参数中自动附带应用程序的名称和版本信息。
函数原型

void SetUrlSftVer(string sftVer, string sftIdentity, _LoginUrlType urlType = _LoginUrlType.Release)  

参数说明（Parameters）

参数名称	说明
sftVer	调用SDK的软件的版本号
sftIdentity	调用SDK的软件名称
urlType	涂鸦云工作环境，默认为线上环境

返回值（Return Values）

返回值	说明
无	无
注意点(Notes)
urlType 必须为_LoginUrlType.Release，否则可能导致产品授权无效。

账号登录 UserLogin

功能说明(Summary)
此接口实现涂鸦云账号登录，实现用户身份验证。账号和密码可以联系项目经理申请。每个客户需要单独申请账号和密码，不同的账号拥有不同的权限范围和使用范围。绝大部分涂鸦网络通信接口都需要账号登录后才能访问。

函数原型

UserLoginRspParas UserLogin(UserLoginReqParas ReqParas, string apiVer = "1.0")  

参数说明（Parameters）

参数名称	说明
ReqParas	账号登录请求参数，UserLoginReqParas类型的对象
apiVer	API版本，默认为1.0

返回值（Return Values）

返回值	说明
UserLoginRspParas的对象	包含登录返回成功信息，以及错误信息等

授权 ProdTokenAuth

功能说明(Summary)

此接口上传产品的信息如mac,SN,token等信息到涂鸦云，校验通过后返回授权秘钥等信息，完成设备的授权。未经授权或授权失败的设备可能无法连接到涂鸦云。
函数原型

TokenAuthRsp TokenAuth(TokenAuthReq ReqParas, string apiVer = "1.0")

参数说明（Parameters）

参数名称	说明
ReqParas	授权请求参数
apiVer	api版本，默认为1.0

返回值（Return Values）

返回值	说明
TokenAuthRsp类型的对象	包含接口操作成功结果、错误信息、授权信息等。

获取Token信息 GetTokenInfo

功能说明(Summary)
用于获取Token绑定信息
函数原型

GetTokenInfoRspParas GetTokenInfo(GetTokenInfoReqParas ReqParas, string apiVer = "1.0")

参数说明（Parameters）

参数名称	说明
ReqParas	授权请求参数
apiVer	api版本，默认为1.0

返回值（Return Values）

返回值	说明
GetTokenInfoRspParas 类型的对象	查询Token信息获取返回结果

授权校验 ProdTokenAuthValidate

功能说明(Summary)
用于校验授权有效性，授权必须要通过授权有效性校验。
函数原型

TokenAuthValidateRsp TokenAuthValidate(TokenAuthValidateReq ReqParas, string apiVer = "1.0")

参数说明（Parameters）

参数名称	说明
ReqParas	授权校验请求参数
apiVer	api版本，默认为1.0

返回值（Return Values）

返回值	说明
TokenAuthValidateRsp类型的对象	TokenAuthValidateRsp类型的对象，包含授权有效性校验结果

添加授权日志 AddAuthLog

功能说明(Summary)
授权完成后添加授权日志到涂鸦云。
函数原型

AddAuthLogRspParas AddAuthLog(AddAuthLogReqParas ReqParas, string apiVer = "1.0")

参数说明（Parameters）

参数名称	说明
ReqParas	添加授权日志请求参数
apiVer	api版本，默认为1.0

返回值（Return Values）

返回值	说明
AddAuthLogRspParas的对象	包含接口操作成功结果、错误信息等。

涂鸦网络通信库类说明

涂鸦云端运行环境枚举 _LoginUrlType

enum _LoginUrlType
{
	Release = 0,	//线上环境，默认
	Preview = 1,  //预发环境
	Daily = 2     //日常环境
}

账号登录请求参数 UserLoginReqParas

public class UserLoginReqParas
{
	public string username;  //用户名，必填
	public string password;  //密码,必填  
	public string token;     //token,非必填
}

登录权限数据

public class PermissionsData
{
	public string permissionCode;  // 登录权限码
	public string permissionName;  // 登录权限名称
}

账号登录返回结果

public class UserLoginResult
{
	public string sessionId;                 // 登录session id
	public List<PermissionsData> permissions; // 登录权限数据列表
}

账号登录返回参数 UserLoginRspParas

public class UserLoginRspParas{
	public bool success;        //接口执行结果，成功为true，失败为false
	public string errorMsg;      // 错误信息
	public string errorCode;     //错误码
	public string status;         // 操作状态，包含一些特定的错误信息或状态
	public long t;              //接口调用时间
	public UserLoginResult result; // 账号登录返回结果
}

授权请求参数 TokenAuthReq

public class TokenAuthReq    
{
    public string sn ;      //产品序列号
    public string tokenId ;  //激活码
    public string sftVersion ;//软件版本号
    public string muid ;    //乐鑫芯片的muid，其他芯片传空字符串
    public string mac ;     // 产品的mac地址
    public string chipId ;   // 加密芯片的芯片ID，无加密芯片传空串
}

授权结果 TokenAuthResult

public class TokenAuthResult
{
	public string uuid;       //模块uuid
	public string mac;       //授权的mac
	public string accessKey;  //授权秘钥
}

授权请求返回结果 TokenAuthRsp

public class TokenAuthRsp{
    public bool success; //接口执行结果，成功为true，失败为false
    public string errorMsg; //错误信息
	public string errorCode; //错误代码
	public string status;    //操作状态
	public long t; //接口调用时间戳
    public TokenAuthResult result; //授权结果只有串口执行结果为true的时候有意义
}

获取Token信息请求参数 GetTokenInfoReqParas

public class GetTokenInfoReqParas
{
	public string tokenId; //激活码
	public string type;   //授权类型“wifi”
	public string sftVersion; //软件版本
	public string softwareName; //软件名称
}

Token绑定信息 TokenInfo

public class TokenInfo
{
	public int amount; //授权总数
	public string firmwareConfigMd5; //配置文件md5校验码
	public string firmwareConfigUrl; //配置文件下载地址
	public string snPrefix; //sn的前缀
	public string firmwareChip; //固件芯片平台
	public string firmwareProtocolType; //固件协议类型
	public string productionFirmwareMd5; //生产固件md5校验码
	public string productionFirmwareUrl; //生产固件下载地址
	public bool supportFirmwareConfig; //是否支持oem配置
	public string productionSubFirmwareUrl; //子固件下载地址
	public string moduleModelChip; //模组芯片平台
	public string productId; //产品ID
	public string type; //激活码类型
	public string firmwareKey; //固件key
	public string macRule; //是否云端分配mac，“0”：不分配mac，“1”：分配mac
	public bool oem; //是否是oem固件
	public string countryCode; //国家码
	public string productionSubFirmwareMd5; //子固件md5校验码
	public string userareaFirmwareUrl; //用户区固件下载地址
	public string userareaFirmwareMd5; //用户区固件md5校验码
	public bool refreshUserarea; //是否刷新用户区固件
	public long effectiveTime; //激活码生效时间
	public int expires; //有效期
	public string id; //激活码
	public string productionId; //生产批号
	public bool test; //是否产测
	public int usedAmount; //已授权数量
	public string wifiHotspotName; //热点名称
	public string wifiPassword; //热点密码
	public string desc; //激活码描述信息
	public string manufacturer; //生产工厂
	public string productKey; //预留
	public string fingerprint; //固件名称
	public string firmwareVersion; //固件版本
	public int firmwareType; //预留
	public bool gpioTest; //预留
	public bool wifiTest; //预留
	public string baselineVersion; //预留
	public string flashRunSize; //flash大小，单位Mbits
}

授权请求返回结果

public class TokenAuthRsp
{
   	public bool success; //接口执行结果，成功为true，失败为false
	public string errorMsg; //错误信息
	public string errorCode; //错误码
	public string status; //操作状态，包含一些特定的错误信息或状态
	public long t; //接口调用时间戳
	public TokenAuthResult result; //授权结果数据
}

授权信息校验请求参数 ProdTokenAuthValidateReq

public class TokenAuthValidateReq    {
	public string tokenId ; //激活码
	public string sn; //产品序列号
	public string mac ; //mac地址
	public string uuid ; //授权产品uuid
	public string muid ; //产品芯片的id
	public string accessKey ; //授权秘钥
	public string wifiHotspotName ; //热点名称
	public string wifiPassword ; //热点密码
	public string chipId ; //加密芯片id
	public string sftVersion ; //软件版本
}

授权信息校验结果 TokenAuthValidateResult

public class TokenAuthValidateResult
{
	public bool result; //授权校验结果
	public string failureDepict; //失败原因描述信息
}

授权校验请求返回结果 TokenAuthValidateRsp

public class TokenAuthValidateRsp : BaseResponse
{
   	public bool success; //授权校验执行结果
	public string errorMsg; //错误信息
	public string errorCode; //错误码
	public string status; //操作状态，包含一些特定的错误信息或状态
	public long t; //时间戳
	public TokenAuthValidateResult result;  //  授权校验结果
}

授权日志信息 AuthLog

public class AuthLog
{
	public string hid; //wifi类授权为mac地址
	public string uuid; //授权uuid
	public string tokenId; //激活码
	public string sn; //产品sn
	public string activeTime; //时间戳
	public string firmwareInfo; //固件指纹，包含固件名称和版本
	public string gpio; //gpio测试结果“成功”或“失败”
	public string rssi; //wifi信号强度测试结果
	public int authStatus; //授权状态，1：成功 ，0：失败
	public string authDepict; //授权状态描述，“成功”或“失败”
	public string countryCode; //国家码
 }

添加授权日志返回结果 AddAuthLogReqParas

public class AddAuthLogReqParas
{
   	public AuthLog log; //授权日志数据集
}

添加授权日志返回结果 AddAuthLogRspParas

public class AddAuthLogRspParas{
	public bool success; //接口执行结果
	public string errorMsg; //错误信息
	public string errorCode; //错误代码
	public string status; //操作状态，包含一些特定的错误信息或状态
	public long t; //时间戳
}

涂鸦蓝牙设备固件通信函数说明

设置蓝牙通信服务串口信息 CommunicationServerBuilder.UseSerialPort

功能说明(Summary)
用于设置蓝牙通信服务串口、波特率信息。
函数原型

CommunicationServerBuilder UseSerialPort(ComPortParas paras)

参数说明（Parameters）

参数名称	说明
ComPortParas	串口信息设置参数

返回值（Return Values）

返回值	说明
CommunicationServerBuilder	无

启动蓝牙通信服务 CommunicationServerBuilder.Start

功能说明(Summary)
启动蓝牙设备串口通信服务。
函数原型

bool CommunicationServer.Start()

参数说明（Parameters）

参数名称	说明
无	无

返回值（Return Values）

返回值	说明
bool	启动通信结果 true:成功 false:失败

关闭蓝牙通信服务 CommunicationServerBuilder.Stop

功能说明(Summary)
关闭蓝牙设备串口通信服务。
函数原型

bool CommunicationServer.Stop()

参数说明（Parameters）

参数名称	说明
无	无

返回值（Return Values）

返回值	说明
bool	关闭通信结果 true:成功 false:失败

进入测试模式 CommunicationServerBuilder.EnterPcbaTestMode

功能说明(Summary)
向串口发送进入产测命令用以开启后续测试。
函数原型

bool EnterPcbaTestMode(out EnterTestModeRsp rsp, int sendRetryTimes = 1, int receiveRetryTimes = 50, int retryInterval = 100)

参数说明（Parameters）

返回值	说明
rsp	进入测试模式返回结果
sendRetryTimes	串口命令最大重发次数，默认1次
receiveRetryTimes	串口命令接收最大重试次数，默认50次
retryInterval	串口命令接收重试间隔时间，单位毫秒,默认100毫秒

返回值（Return Values）

返回值	说明
bool	进入测试模式命令发送结果

写入固件授权信息 CommunicationServerBuilder.WriteConfigInfo

功能说明(Summary)
通过串口向固件向设备写入授权信息。
函数原型

bool WriteConfigInfo(WriteConfigInfoReq req, out BaseRsp rsp, int sendRetryTimes = 
1, int receiveRetryTimes = 20, int receiveRetryInterval = 1000)

参数说明（Parameters）

返回值	说明
req	写入固件授权信息参数
rsp	写入固件授权信息返回结果
sendRetryTimes	串口命令最大重发次数，默认1次
receiveRetryTimes	串口命令接收最大重试次数，默认20次
retryInterval	串口命令接收重试间隔时间，单位毫秒,默认1000毫秒

返回值（Return Values）

返回值	说明
bool	写入授权信息命令发送结果

读取固件授权信息 CommunicationServerBuilder.ReadConfigInfo

功能说明(Summary)
通过串口读取固件授权信息。
函数原型

bool ReadConfigInfo(out GetModuleInformationRsp rsp, int sendRetryTimes = 1, int 
receiveRetryTimes = 6, int receiveRetryInterval = 1000)

参数说明（Parameters）

返回值	说明
rsp	读取的固件授权信息返回结果
sendRetryTimes	串口命令最大重发次数，默认1次
receiveRetryTimes	串口命令接收最大重试次数，默认6次
retryInterval	串口命令接收重试间隔时间，单位毫秒,默认1000毫秒

返回值（Return Values）

返回值	说明
bool	读取授权信息命令发送结果

涂鸦蓝牙设备固件通信库类说明

串口信息设置参数 ComPortParas

public class ComPortParas
{
	public string PortName; //串口号如“COM3”
	public int BaudRate ; //波特率
	public int DataBits ; //数据位
	public Parity Parity ; //奇偶校验
	public StopBits StopBits ; //停止位数
	public int ReadBufferSize ; //读缓存大小
	public int WriteBufferSize ; //写缓存大小
	public int ReadTimeout ; //读超时时间，单位毫秒
}

进入测试模式请求结果 EnterTestModeRsp

public class EnterTestModeRsp
{
	public bool IsNeedCheckFirmware ; //是否需要固件版本检测
	public bool IsNeedGetPidFromCloud ; //是否需要从云端获取pid写入设备
	public bool IsNeedReadUnigueCode ; //是否需要读取设备唯一码
}

写入设备固件信息 WriteConfigInfoReq

public class WriteConfigInfoReq
{
	public string AuthKey; //授权秘钥
	public string UUID; //授权uuid
	public string Mac; //授权mac
	public bool IsProductionTest; //是否为整机测试
}

写入设备信息(包括pid) WriteConfigInfoIncludeReq

public class WriteConfigInfoIncludeReq
{
	public string AuthKey; //授权秘钥
	public string UUID ; //授权uuid
	public string Mac ; //授权mac
	public bool IsProductionTest ; //是否为整机测试
	public string PID; //产品id
}

固件请求返回信息 BaseRsp

public class BaseRsp
{
	public bool Ret; //返回结果：true:成功 false:失败
}

固件授权信息读取结果 GetModuleInformationRsp

public class GetModuleInformationRsp
{
	public string auzKey ; //授权秘钥
	public string hid ; //硬件id，mac地址
	public string uuid ; //授权uuid
	public string mac ; //授权mac
	public string firmName ; //固件名称
	public string firmVer ; //固件版本
	public string prod_test ; //是否产测
	public string pid ; //产品id
}

获取授权信息示例代码（C#）

此代码进仅演示从涂鸦云端获取授权信息并完成授权校验的部分内容。（不包含写mac地址，写授权信息等其他功能）。

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using TuyaCloudIfLib;
using Newtonsoft.Json;
//1. Login**
UserLoginReqParas loginReq= new UserLoginReqParas();
loginReq.username = "******";
loginReq.password = "######";
UserLoginRspParas loginRsp= TuyaCloudIf.UserLogin(loginReq);
if (loginRsp.success == false)
       MessageBox.Show(loginRsp.errorMsg);
else
       MessageBox.Show("Login successfully !");

//2. Get token information
GetTokenInfoReqParas GetTokenReq = new GetTokenInfoReqParas();
GetTokenReq.tokenId= "XRVAygmzpvRZNxYN";
GetTokenInfoRspParas GetTokenRsp = TuyaCloudIf.GetTokenInfo(GetTokenReq);
if(GetTokenRsp.success == false)
     return false;

//3. Auth
TokenAuthReq AuthReq = new TokenAuthReq();
 AuthReq.sn = "sn0000000002";
AuthReq.mac = "ecfabc9a86f0";//mac read from module
AuthReq.sftVersion = "test_App";
AuthReq.muid = "009a86f0";// muid read from module
AuthReq.chipId = "";
AuthReq.tokenId = "XRVAygmzpvRZNxYN";
TokenAuthRsp AuthRsp= TuyaCloudIf.TokenAuth(AuthReq);
If(AuthRsp.success== false)
	return false;
//4. Auth validate
TokenAuthValidateReq ValidateReq = new TokenAuthValidateReq();
ValidateReq.accessKey = AuthRsp.result.accessKey;
ValidateReq.muid = "009a86f0";//read 
ValidateReq.sn = "sn0000000002";
ValidateReq.mac = AuthRsp.result.mac;
ValidateReq.tokenId = "XRVAygmzpvRZNxYN";
ValidateReq.uuid = AuthRsp.result.uuid;
ValidateReq.chipId = "";
ValidateReq.wifiHotspotName = "SmartLife";
ValidateReq.wifiPassword = "";
ValidateReq.sftVersion = "1.1";
TokenAuthValidateRsp ValidateRsp= TuyaCloudIf.TokenAuthValidate(ValidateReq);
if (!ValidateRsp.success)
	MessageBox.Show("Validate fail ！");
else
	MessageBox.Show("Validate successfully！");