TCP 设备接入指南

本文档介绍如何通过 TCP 协议 将设备安全接入到 Xlink 物联网平台，实现数据上报、命令下发等功能。
TCP（Transmission Control Protocol）是一种面向连接的、可靠的、基于字节流的传输层通信协议，适用于对数据完整性与顺序要求较高的设备通信场景。
Xlink 平台支持基于原始 TCP 协议的设备接入，并提供灵活的数据解析能力，以适配各种私有协议设备。

接入准备

创建产品
在云智易物联网平台中创建一个 产品（Product），这里以温湿度传感器为例。
定义物模型
进入产品管理页面，定义设备的物模型。平台提供大量标准物模型模板，也可自定义属性、事件与服务。
选择 TCP 协议接入方式 进入设备接入页面，选择自定义TCP直连接入方式。
连接信息 进入自定义TCP直连配置详情页，可以获取连接信息。

参数	说明	示例
服务器地址	TCP 接入服务器地址	`x-protocol-tcp.xlink.cn`
端口	TCP 通信端口，需要申请	`65533`

⚠️ TCP 接入不使用传统 MQTT 的 ClientID / Username / Password，而是通过首次通信数据包完成设备激活与绑定。

数据解析 TCP接入支持添加JS解析脚本，将设备自定义TCP数据转换为平台标准物模型数据，或将平台标准物模型主题数据转为设备自定义主题。
这里我们以一个简单的温湿度传感器的 TCP 协议为例： TCP 协议编码与格式

项目	说明
编码	UTF-8
协议类型	文本协议
一条消息	一行文本
消息类型	<MSG_TYPE> ，包括DATA、SET、ACK
行结束符	`\n`
字段分隔符	逗号 `,`
键值格式	`key=value`
消息格式	`<MSG_TYPE>,key1=value1,key2=value2`

TCP协议数据包示例：

# 属性上报消息
DATA,device_id=WSD00001,temp=36.5,hum=58.45,lat=113.25,lon=23.13

# 属性下发消息
SET,temp=xx.x,hum=xx.x

# 属性下发响应
ACK,code=0,msg=ok

按照上面的协议格式，我们进入解析脚本页面，添加解析脚本如下：

javascript

// 自定义实现：温湿度传感器TCP协议解析（仅attributes）
//设备属性上报解析
function up(content, context) {
    // 将hex字符串转换为实际内容字符串
    var contentStr = hexToString(content);
    contentStr = contentStr.replace(/\r\n/g, "").replace(/\n/g, "").trim();
    
    // 解析协议消息
    var parts = contentStr.split(",");
    var msgType = parts[0];
    
    var result = {
        "mac": "", // 设备MAC地址将从device_id中获取
        "state": "ONLINE", // 设备上下线，ONLINE,OFFLINE
        "time": Date.now(), // 当前时间戳
        "types": [
            "attributes"
        ], // 仅attributes
        "attributes": {} // 属性 参照管理台属性字段
    };
    
    if (msgType === "DATA") {
        // 解析DATA消息: DATA,device_id=xxx,device_name=xxx,temp=xx.x,hum=xx.x,lat=xx.xxxx,lon=xx.xxxx
        var data = {};
        for (var i = 1; i < parts.length; i++) {
            var keyValue = parts[i].split("=");
            if (keyValue.length === 2) {
                data[keyValue[0]] = keyValue[1];
            }
        }
        
        // 设置MAC地址
        if (data.device_id) {
            result.mac = data.device_id;
        }
        
        // 设置属性
        if (data.temp !== undefined) {
            result.attributes.temperature = parseFloat(data.temp);
        }
        if (data.hum !== undefined) {
            result.attributes.humidity = parseFloat(data.hum);
        }
        if (data.lat !== undefined && data.lon !== undefined) {
            // 地理位置格式为 [longitude, latitude, altitude]，海拔为可选
            result.attributes.position = [parseFloat(data.lon), parseFloat(data.lat), data.alt !== undefined ? parseFloat(data.alt) : null];
        }
    }
    
    return [result];
}

// hex字符串转字符串的辅助函数
function hexToString(hex) {
    var str = '';
    for (var i = 0; i < hex.length; i += 2) {
        var charCode = parseInt(hex.substr(i, 2), 16);
        str += String.fromCharCode(charCode);
    }
    return str;
}

//设备属性下发解析
function down(service, input, context) {
    var content = "";
    
    if (service === "device_attribute_set_service") {
        // 处理设备属性设置服务
        var temp = input.temperature;
        var hum = input.humidity;
        
        var params = [];
        if (temp !== undefined && temp !== null) {
            params.push("temp=" + parseFloat(temp));
        }
        if (hum !== undefined && hum !== null) {
            params.push("hum=" + parseFloat(hum));
        }
        
        if (params.length > 0) {
            content = "SET," + params.join(",");
        }
    }
    
    return [{
        "response": true, // true表示设备会响应此下发内容等待设备响应，false 表示设备不会响应此内容，翻译完下发设备后响应接口成功
        "response_timeout": 15, // 响应超时（秒）
        "content_type": "string", // base64, hex, string
        "content": content // 发送到设备的字符串内容
    }];
}

接入配置

这里以TCP调试助手为例介绍如何接入Xlink物联网平台。 TCP调试助手是一个开源工具，提供Windows、Mac和Linux版本。下载地址：
TCP-调试工具（Windows版-x64）
TCP-调试工具（Mac版-Intel）
TCP-调试工具（Mac版-AppleSilicon）
TCP-调试工具（Linux版-x64）
TCP-调试工具（Linux版-arm64）

连接 TCP 服务器
运行 TCP 调试工具，连接至 x-protocol-tcp.xlink.cn:65533。
上报属性（示例）
把上报属性的消息复制到TCP调试工具中，点击发送按钮。
查看设备状态
回到云智易物联网平台，由于前面已经配置了解析脚本，发送的消息会被平台自动解析为平台的属性。可以看到设备已经上线，并且属性已经上报成功。
属性下发 在设备详情页面，点击控制面板按钮，输入要下发的属性值，点击确定按钮。

TCP调试助手就能收到下发的控制消息，并发送响应消息。

总结

通过本文档，您已掌握如何将基于 TCP 协议的设备安全接入 Xlink 物联网平台。
TCP 接入方式适用于无法使用 MQTT 协议或已有成熟私有通信协议的设备场景。借助灵活的解析脚本机制，Xlink 平台可无缝对接各类文本或二进制协议，无需修改设备固件即可快速上云。

常见问题 FAQ

Q1：连接服务器后无任何响应，设备未上线？
A1：请确认以下几点：

设备是否发送了符合协议格式的首包数据（如 DATA,device_id=xxx,...）；
解析脚本是否已保存并启用；
device_id 是否与平台注册的设备 MAC 一致（平台以该字段识别设备身份）；
网络是否能正常访问 x-protocol-tcp.xlink.cn:65533（可使用 telnet 或 TCP 调试工具测试连通性）。

Q2：解析脚本报错或未生效？
A2：常见原因包括：

脚本语法错误（如缺少括号、分号），请使用在线 JS 校验工具检查；
hexToString 函数未正确处理非 ASCII 字符（若设备使用纯文本协议，确保发送的是 UTF-8 编码字符串对应的 HEX）；
返回结构不符合平台要求（如缺少 mac 字段或 attributes 结构错误）；
脚本未保存或未点击“启用”。

Q3：平台下发命令后，设备未收到？
A3：请检查：

是否在设备详情页的 控制面板 中正确填写了可写属性；
down() 函数是否根据服务名称（如 device_attribute_set_service）正确生成了下发内容；
TCP 连接是否仍处于活跃状态（设备掉线后无法接收下发）；
设备是否支持接收平台下发的数据（部分设备仅支持单向上报）。

Q4：如何支持设备主动下线？
A4：平台目前通过连接断开自动判定设备离线。若需设备主动通知下线，可在协议中定义特定消息（如 EVENT,type=offline），并在解析脚本中设置 "state": "OFFLINE"，但最终仍以 TCP 连接状态为准。

Q5：能否使用 TLS/SSL 加密 TCP 通信？
A5：支持。请联系 Xlink 技术支持申请 TLS 端口（如 65534），并在设备端使用 TLS 客户端连接。平台支持标准 TLS 1.2+ 协议，可配置证书校验策略。

Q6：设备上报频率过高，是否会被限流？
A6：平台对消息频率有一定限制（默认约 10 条/秒/设备）。若需高频上报，请联系技术支持调整配额，或优化协议合并多属性上报。

TCP 设备接入指南 ​

接入准备 ​

接入配置 ​

总结 ​

常见问题 FAQ ​

TCP 设备接入指南

接入准备

接入配置

总结

常见问题 FAQ