接入概述

设备接入主要是开发者要实现设备与云平台进行连接、数据交互（上报、透传）、命令控制等过程。 目前平台提供多种接入协议类型供选择，分别是TCP、MQTT、TCP透传、HTTP等，通信网络可以是常见的3G/4G、WIFI、以太网口等；
设备接入的方案可以是下图中的任何一种:
再实现设备接入之前，需要完成以下设备创建的步骤：

之后根据所创建项目的协议类型选择相应硬件进行开发，记录下设备标识与传输密钥。
下面分别针对TCP、MQTT、TCP透传、HTTP等协议进行说明：

接入安全鉴权

1.鉴权方式

2.普通鉴权方式

普通鉴权直接以SecretKey做为传输密钥与云端建立连接，无访问时间控制、安全性低，但资源占用少。

                
    TCP协议   wxString key="a5528869647040b4a88bb61dcb566e32"; 
                

                
    MQTT协议  String clientID = "mydevice";
              String userName = "50015";
              String password = "a5528869647040b4a88bb61dcb566e32"; 
                

3.安全鉴权方式

鉴权机制优势：

• 避免核心密钥网络中直接传输，从而避免核心密钥在传输中泄露
• 通过包含由非可逆算法生成的签名的token来进行身份认证，即使token被窃取，攻击者也无法通过token反向获得核心密钥
• 鉴权参数token具有用户自定义的过期时间属性，可从时间维度降低被攻击/仿冒的风险

token的组成：

token由以上5个参数值组成，每个参数值以"&"字符相连组合，如
mtqqdevice1&50046&md5&1566276142807&B8ABEAE97F97C80C3CE7593F9ECDA63D

token中sign参数的生成算法为：
需将clientId,projectId,method,timestamp四个参数值按固定排序依次拼接（参数间不需要任何拼接字符），再拼接上平台申请的SecretKey，使用method对应的签名算法加签。
假设clientId = mydevice，projectId = 50023， method = sha256， timestamp = 1566276142807，SecretKey=a5528869647040b4a88bb61dcb566eee，那么使用生成的sign参数如下：

                
 sign=sha256("mydevice50023sha2561566276142807a5528869647040b4a88bb61dcb566eee) 

 token="mydevice&50023&sha256&1566276142807&" + sign
                

TCP协议接入

1.协议介绍

请移步至“资料下载” -> TCP“设备接入协议”下载打开查看，协议定义了 连接请求、连接响应、 上报数据、上报数据确认、命令请求、命令响应、心跳请求、心跳响应等过程的报文格式；以JSON数据格式定义。 若您的设备是网关或手机类型的可以直接按照协议报文定义“数据结构体”，若是MCU、SOC类型的设备，可以做一些转化。
这里主要解讲采用SDK进入设备接入的过程

2.拷贝SDK，建立TCP连接

将SDK移植至网关/MCU/SOC等设备中，并开展和接入服务器的TCP连接。

TCP协议加入了SSL/TLS来提供物联网设备与云平台直接的安全通信功能，设备携带云平台提供的根证书；在使用8601端口建立TLS连接时，设备客户端既对NLECloud进行单向验证， 由此，便对中间人攻击带来了较高的要求。TLS单向验证大致流程如下：
云平台和设备从CA证书中心取得CA证书（也称根证书），云平台申请生成自已的私钥和证书，客户端用CA证书对云平台的证书进行验证，验证通过说明服务端是合法的，如果验证不过则不与云平台通信。 验证通过之后使用一对公钥和密钥进行加解密通信，中间的报文都是加密的。

3.设备与平台进行握手连接

使用记录好的“设备标识”和“传输密钥”做为参数，使用SDK中的对应函数组织TCP握手连接报文，发送到平台与之建立握手连接.
云平台支持"普通鉴权"或"安全鉴权"方式进行接入验证连接，详见 接入安全鉴权，以下为普通鉴权方式的代码示范：

    
        /* 根据协议定义连接请求的结构体 */
        con_req.msg_type = PACKET_TYPE_CONN_REQ; 
        con_req.device_id = "qiuzhb";
        con_req.key= "677abb3a5ff3456fb831c96482f11536";                //普通鉴权直接输入传输密钥
        con_req.ver = "V1.0";

        /* 利用SDK 中cloud.h 中 packet_msg 方法封包连接协议 */
        packet = packet_msg(&con_req);

        /*发送连接协议包数据*/
        ret = send_packet(sock, packet, strlen(packet), 0);

                

若握手连接成功，云端会发送响应成功信息，在设备管理中会看到一个在线标记： 若握手连接失败，云端也会发送响应失败信息，告诉失败原因。

4.传感数据上报

利用SDK中提供的接口函数，编写代码将数据上报到平台。 以C语言SDK为例，上传一组温度为30℃，湿度为80%RH的数据。

                
        //数据类型为1（JSON格式1字符串）
        post_req.msg_type = PACKET_TYPE_POST_DATA;
        post_req.msg_id++;
        post_req.data_type = 1;
        post_req.data = "{\
        \"nl_temperature\": \"23\",\
        \"nl_light\": 2000\
        }";
        post_req.data_len = strlen(post_req.data);
        packet = packet_msg(&post_req);
        if(packet == NULL){
	        MAIN_ERR("packet_msg JSON 1 error\n");
        }else{
	        MAIN_DBG("POST JSON 1 \n");
	        send_flag = 1;
        }

        /*发送包数据,上报传感数据*/
        if(send_flag){
	        ret = send_packet(sock, packet, strlen(packet), 0);
	        if(ret < 0){
		        MAIN_ERR("PACKET_TYPE_POST_DATA error\n");
	    }
	    free_packet_msg(packet);
	    send_flag = 0;
    }

                

5.查看上报的数据

1）设备管理->传感器管理->下发设备按钮右边下拉菜单点击“实时数据开”
2）设备管理->传感器管理->历史数据按钮

6.WebSocket连接

云平台支持基于WebSocket的TCP协议。您可以首先使用WebSocket建立连接，然后在WebSocket通道上，使用TCP协议进行通信，即TCP over WebSocket。
使用WebSocket方式进行连接，区别主要在TCP连接URL的协议和端口号，ws://ndp.nlecloud.com:8600， 连接代码示范如下：

                
        if ("WebSocket" in window)
        {
            var connected = false;
            ws = new WebSocket("ws://ndp.nlecloud.com:8600");
            ws.onopen = function (event) {

                connected = true;
                var strHTML = '';
                strHTML+='正在登录服务器...';
                strHTML+= GetFormattedTime();
                $('#log').prepend(strHTML);

                SendHandshakeMsg();

                setInterval(sendAlive, 55 * 1000);
            };

            ws.onmessage = function (event) {

                OnMessage(event);
            };

            ws.onerror = function (event)
            {
                if(!connected)
                {
                    var strHTML = '';
                    strHTML+='连接发生错误';
                    strHTML+= GetFormattedTime() ;
                    strHTML+='无法连接到云端，可能云端未启动！';
                    $('#log').prepend(strHTML);
                }
                else
                {
                    var strHTML = '';
                    strHTML+='通讯发生错误';
                    strHTML+= GetFormattedTime() ;
                    strHTML+= event.data ;
                    $('#log').prepend(strHTML);
                }

                ws.close();
                ws = null;
            };

            ws.onclose = function (event) {

                if(!connected)
                    return ;

                connected = false;

                var strHTML = '';

                strHTML+='设备离线';
                strHTML+= GetFormattedTime() ;
                strHTML+='系统消息：已与云端断开连接';
                $('#log').prepend(strHTML);
            };
        }
        else
            ShowTopCenterWarning("您的浏览器不支持websocket哦！" , 20000);

                

MQTT协议接入

1.协议介绍

请移步至“资料下载” -> “NLECloud MQTT协议”下载打开查看，协议定义了 连接请求、连接响应、 上报数据、上报数据确认、命令请求、命令响应、心跳请求、心跳响应等过程的报文格式；以JSON数据格式定义。

2.建立TCP连接

开展和接入服务器的TCP连接。

MQTTS在MQTT协议的基础上加入了SSL/TLS（在SSL/TLS上的MQTT）来提供物联网设备与云平台直接的安全通信功能，设备携带云平台提供的根证书；在使用8883端口建立TLS连接时，设备客户端既对NLECloud进行单向验证， 由此，便对中间人攻击带来了较高的要求。TLS单向验证大致流程如下：
云平台和设备从CA证书中心取得CA证书（也称根证书），云平台申请生成自已的私钥和证书，客户端用CA证书对云平台的证书进行验证，验证通过说明服务端是合法的，如果验证不过则不与云平台通信。 验证通过之后使用一对公钥和密钥进行加解密通信，中间的报文都是加密的。

3.设备与平台进行握手连接

使用记录好的“设备标识”和“传输密钥”做为参数，组织相应的CONNECT报文发送到平台进行握手，建立MQTT连接。 云平台支持"普通鉴权"或"安全鉴权"方式进行接入验证连接，详见 接入安全鉴权，以下为安全鉴权方式的代码示范：

设备创建时，平台为每个设备分配了唯一的传输密钥(SecretKey)，设备接入时需要使用 SecretKey 计算出的访问token 来进行访问安全认证， 设备可通过MQTT connnect报文进行连接，connect报文中三要素填写方法如下：

本例中，password = 经过SecretKey计算的token = clientId & username & method & timestamp & sign

• timestamp：表示访问过期时间戳 timestamp，当访问参数中的timestamp时间小于当前时间时，平台会认为访问参数过期从而拒绝该访问。
• method：表示签名算法类型。支持md5，sha1和sha256。
• sign：表示clientId,projectId,method,timestamp,secretKey五个参数值按固定排序依次拼接（参数间不需要任何拼接字符），使用method对应的签名算法加签。 详见 安全鉴权方式

若握手连接成功，云端会发送响应成功信息，在设备管理中会看到一个在线标记： 若握手连接失败，云端也会发送响应失败信息，告诉失败原因。

4.传感数据上报

组织相应的传感数据，通过MQTT“发送消息”协议进行数据上报。

5.查看上报的数据

1）设备管理->传感器管理->下发设备按钮右边下拉菜单点击“实时数据开”
2）设备管理->传感器管理->历史数据按钮

6.MQTT-WebSocket连接

云平台支持基于WebSocket的MQTT协议。您可以首先使用WebSocket建立连接，然后在WebSocket通道上，使用MQTT协议进行通信，即MQTT over WebSocket。
WebSocket可以使用ws和wss两种方式，ws就是普通的WebSocket连接，wss就是增加了TLS加密。如果使用wss方式进行安全连接，需要使用和TLS直连一样的根证书。 这边将重点将解ws，wss请移步到 MQTTS协议接入 节点。

使用WebSocket方式进行连接，区别主要在MQTT连接URL的协议和端口号，ws://mqtt.nlecloud.com:1883， 可以使用一些开源的mqttjs框架如mqttws31.js进行连接，如：

                 
        var hostname = 'mqtt.nlecloud.com',
            port = 1883,
            clientId = 'mydevice',
            timeout = 50000,
            keepAlive = 60000,
            cleanSession = false,
            ssl = false,
            userName = '50046',
            password = '1528a42fa64e4f42b6da07540eb0a97f',      //支持安全鉴权方式 详见 安全鉴权方式
            topic = '/sensor/datas',
            client = new Paho.MQTT.Client(hostname, port, clientId);
        //建立客户端实例
        var options = {
            invocationContext: {
                host: hostname,
                port: port,
                path: client.path,
                clientId: clientId
            },
            timeout: timeout,
            keepAliveInterval: keepAlive,
            cleanSession: cleanSession,
            useSSL: ssl,
            userName: userName,
            password: password,
            onSuccess: onConnect,
            onFailure: function (e) {
                console.log(e);
                s = "{time:" + new Date().Format("yyyy-MM-dd hh:mm:ss") + ", onFailure()}";
                console.log(s);
            }
        };
        client.connect(options);
        //连接服务器并注册连接成功处理事件
        function onConnect() {
            console.log("onConnected");
            s = "{time:" + new Date().Format("yyyy-MM-dd hh:mm:ss") + ", onConnected()}";
            console.log(s);
            start();
            //client.subscribe(topic);
        }

                

CoAP协议接入

1.协议介绍

请移步至“资料下载” -> “设备接入协议-CoAP”下载打开查看，协议定义了 设备认证、 上报数据、命令订阅/请求/响应等过程的报文格式。CoAP协议的详细分析可参考《COAP协议全面分析》

2.建立UDP连接

开展和接入服务器的UDP连接。

在CoAP协议的基础上加入了DTLS来提供物联网设备与云平台直接的安全通信功能，设备携带云平台提供的根证书；在使用5684端口建立DTLS连接时，设备客户端既对NLECloud进行单向验证， 由此，便对中间人攻击带来了较高的要求。

3.设备认证

使用记录好的“设备标识”和“传输密钥”做为参数。CoAP协议目前只支持"普通鉴权"验证接入，详见 接入安全鉴权。 设备首先需要发送设备认证请求报文与平台握手建立连接，请求报文格式如下：

POST /auth
Host: nbiot.nlecloud.com
Port: 5683
Accept: application/json
Content-Format: application/json 
payload: {"clientId":"coapdebugclient","Username":" 51*61*","Password":" b27e0595118f4d7cb******72277f7a9"}

设备鉴权成功后，返回结果状态码，同时返回token，该token为后面每次上传数据都需带上，示例：
{"ReturnCode":0, "token":"37hp01w1ssqomz8mdfzo001050****ad2b"}

4.数据上报

设备与服务器鉴权后，便可以进行传感数据的上报上传：

POST /topic/{clientId}/data
Host: nbiot.nlecloud.com
Port: 5683
Accept: application/json
Content-Format: application/json 
payload: {your_data}
CustomOptions: token

payload说明

"datas":
{
    "apitag1": "value1",
    "apitag2": value2,
    …
}

"datas":
{ 
    "apitag1":{"datetime1":"value1"},
    "apitag2": {"datetime2":"value2"},
    …
}

"datas":
[
    { 
        "apitag":"temperature",
        "datapoints":
        [{
            "dt":"2018-01-22 22:22:22",  //可选
            "value": 36.5  //数字浮点字符串
        }]
    },
    { 
        "apitag": "location",
        "datapoints":[…]
    },
    { … }
]

消息上行成功后，返回成功状态码。

5.命令订阅/请求/响应

5.1.客户端命令订阅(client)->(server)

大致原理如下，利用CoAP扩展的订阅/发布协议，客户端通过GET请求 （设置Option的Oberser值为0）向服务端订阅一个是否有新命令的主题，当服务端检测到有新命令时，通知客户端，客户端在该请求的Respond中编写接收命令和业务逻辑，订阅请求如下：

POST /topic/{clientId}/cmd
Host: nbiot.nlecloud.com
Port: 5683
Accept: application/json
CustomOptions: token 
Oberser: 0

5.2.服务端命令请求(server)->(client)

客户端命令订阅成功后，服务端下发命令（如控制某个传感器的开关），客户端会在上次订阅请求的Response中接收到命令，命令报文格式如下:
{"t": 5,"cmdid": “123456789”, "apitag":"rgb_open","data":{ 见下表说明 } }

5.2.服务端命令请求(server)->(client)

客户端处理好命令后，会上传处理结果给服务端，通用消息类型NON POST请求上传数据资源：

POST /topic/{clientId}/data
Host: nbiot.nlecloud.com
Port: 5683
Accept: application/json
Content-Format: application/json 
payload: {your_data}
CustomOptions: token

payload说明

TCP透传协议接入

1.协议介绍

请移步至“资料下载” -> TCP透传“设备接入协议”下载打开查看。
NLECloud支持用户通过TCP透传的方式上传数据和下发命令，为任何基于TCP通信设备接入NLECloud提供了可行性。 TCP透传具有较高自由度，它允许用户自定义协议，并根据用户定义的脚本完成与其他协议的交互。

• 长连接
• 支持Lua脚本嵌入
• 高灵活性

2.接入说明

步骤1：创建项目 首先需要您在此平台创建一个属于您的项目(如何创建项目？)， 如您还未拥有平台账号，可查看注册帮助 步骤2：创建设备 在项目下添加通讯协议为TCP透传的设备，并添加相关的传感设备，具体操作可移步这里 步骤3：上传脚本 通过点击下图中提示的脚本上传图标
进入如下图所示窗口实现上传操作，可下载平台提供的脚本demo，根据demo中的说明并参照文档的Lua脚本规范进行用户自定义处理，然后再将最终的脚本文件上传到平台 步骤4：发送握手请求 设备向平台发送握手请求，若成功建立连接,可以看到平台上的设备在线状态： 握手报文示例：

{
    "t": 1,                                     --固定标识，指明握手请求
    "device": "P123456789",                     --设备标识
    "key":"9861d43a0733415ab5424ee7d0f1c685",   --传输密钥
    "ver":"v1.1"                                --客户端拟定的版本号
}

Modbus协议接入

1.协议介绍

请移步至“资料下载” -> Modbus“设备接入协议”下载打开查看。
NLECloud支持用户通过Modbus协议的方式采集数据和下发命令，为任何基于Modbus通信设备接入NLECloud提供了可行性。 Modbus通讯协议是一种工业现场总线通讯协议，在工业自动化控制中应用较多，可以实现工业数据采集与控制等功能。 MODBUS 是一个请求/应答协议，并且提供功能码规定的服务。MODBUS 功能码是 MODBUS 请求/应答 PDU（协议数据单元） 的元素。

• 长连接协议
• 物联网云平台作为Modbus主机，周期性下发命令
• 自动将终端上报的数据转化为传感数据值
• 可灵活配置采集公式

2.接入说明

步骤1：创建项目 首先需要您在此平台创建一个属于您的项目(如何创建项目？)， 如您还未拥有平台账号，可查看注册帮助 步骤2：创建设备 在项目下添加通讯协议为Modbus的设备，并添加modbus的传感设备，具体操作可移步这里 步骤4：发送握手请求 设备向平台发送握手请求（以字节形式发送设备Mac码）进行鉴权，若成功建立连接,可以看到平台上的设备在线状态。
设备登录成功后，服务器不会返回数据，如果登录失败，服务器会主动断开连接。 握手成功后 平台会根据用户创建传感设备的设定周期性的下发采集指令来获取数据。 当设备处于空闲的时候，为了保持与平台的连接不断开，需要定期发送心跳包，以确保网络连接不断开。其中时间间隔须小于3分钟。 握手报文示例：

9C A5 25 A9 7A 2A

HTTP协议接入

1.协议介绍

HTTP协议接入主要是采用RESTful风格的"添加传感数据"API接口实现上报数据，不需要建立“连接请求”等过程；在云端添加好传感器后即可直接以JSON格式进行数据的上报。 以下为具体的步骤：

2.获取AccessToken

使用你的帐号与密码请求帐号登录接口“http://api.nlecloud.com/users/login”，请求的数据包为： 请求成功后会返回AccessToken：

3.传感数据添加

带上AccessToken请求“http://api.nlecloud.com/devices/{deviceId}/datas”,{deviceId}替换为真实的设备ID

4.查看添加的数据

1）设备管理->传感器管理->下发设备按钮右边下拉菜单点击“实时数据开”
2）设备管理->传感器管理->历史数据按钮