WebSocket
一、WebSocket 概述
WebSocket 是 HTML5 下一种新的协议（本质上是一个基于 TCP 的协议），它实现了浏览器与服务器之间的全双工通信，能够节省服务器资源和带宽，达到实时通讯的目的。WebSocket 协议通过握手机制，允许客户端和服务器之间建立一个类似 TCP 的连接，从而方便它们之间的通信。
- 在线聊天应用：允许用户实时发送和接收消息，而无需页面刷新或轮询服务器。
- 实时协作应用：支持多用户实时编辑文档或共享白板等场景。
- 实时游戏：允许多个玩家之间进行实时的游戏交互。
- 实时数据展示：用于显示实时数据，如股票市场变化、天气预报更新等。
- 实时通知和提醒：用于向用户发送实时的通知消息，如新邮件提醒、社交媒体通知等。
- 在线会议和视频通话：支持实时的音视频通信。
二、准备硬件环境
参考：硬件环境清单第二章节内容，准备以及组装好硬件环境。
三、软件环境
3.1 合宙模组相关
“凡事预则立，不预则废。”在详细阐述本功能示例之前，我们需先精心筹备好以下软件环境。
1. Luatools工具；
2. 内核固件文件（底层core固件文件）：LuatOS-SoC_V2002_Air780EP；参考项目使用的内核固件；
3. luatos需要的脚本和资源文件
脚本和资源文件右键点我,另存为,下载完整压缩文件包
lib脚本文件：使用Luatools烧录时，勾选 添加默认lib 选项，使用默认lib脚本文件；
准备好软件环境之后，接下来查看如何烧录项目文件到Air780EP核心板，将本篇文章中演示使用的项目文件烧录到Air780EP核心板中。
3.2 LLCOM配置
3.2.1 LLCOM 工具设置：初始配置
3.2.2 数据发送前的配置
四、WebSocket 加密通讯的概述
本小节教你怎么使用 LuatOS脚本语言，就可以让合宙 4G 模组连接上一个 WebSocket 服务器，并且模组和服务器之间实现数据的交互！
4.1 本教程实现的功能定义：
- 4G 模组插卡开机后，连接上 WebSocket 服务器；
- 这是个测试服务, 当 4G 模组发送的是 json,且 action=echo,就会回显所发送的内容
- 发送内容是 wsc:send((json.encode({action="echo", msg=os.date()})))
4.2 文章内容引用
- Air780EP 开发板软硬件资料 ： Air780EP 产品手册
- websocket 函数接口不做详细介绍，可通过此链接查看具体介绍：websocket - 网络接口 - LuatOS 文档
4.3 核心脚本代码详解
4.3.1 websocket 客户端创建
-- ws 普通链接不加密
wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
--加密链接 wss 表示加密，
wsc = websocket.create(nil, "wss://echo.airtun.air32.cn/ws/echo")
4.3.2 设置额外的 headers
-- table形式
wsc:headers({Auth="Basic ABCDEFGG"})
-- 字符串形式
wsc:headers("Auth: Basic ABCDERG\r\n")
4.3.3 设置自动重连机制
wsc:autoreconn(true, 3000) -- 自动重连机制
4.3.4 注册 websocket 回调
wsc:on(function(wsc, event, data, fin, optcode)
--[[
event的值有:
conack 连接服务器成功,已经收到websocket协议头部信息,通信已建立
recv 收到服务器下发的信息, data, payload 不为nil
sent send函数发送的消息,服务器在TCP协议层已确认收到
disconnect 服务器连接已断开
其中 sent/disconnect 事件在 2023.04.01 新增
]]
-- data 当事件为recv是有接收到的数据
-- fin 是否为最后一个数据包, 0代表还有数据, 1代表是最后一个数据包
-- optcode, 0 - 中间数据包, 1 - 文本数据包, 2 - 二进制数据包
-- 因为lua并不区分文本和二进制数据, 所以optcode通常可以无视
-- 若数据不多, 小于1400字节, 那么fid通常也是1, 同样可以忽略
log.info("wsc", event, data, fin, optcode)
-- 显示二进制数据
-- log.info("wsc", event, data and data:toHex() or "", fin, optcode)
if event == "conack" then -- 连接websocket服务后, 会有这个事件
log.info("WebSocket connect succeed!")
sys.publish("wsc_conack")----连接成功发布"wsc_conack"
end
end)
4.3.5 连接服务器
wsc:connect()
-- 等待conack是可选的
sys.waitUntil("wsc_conack")------等待连接成功 并订阅到 "wsc_conack"
4.3.6 发布消息
-- 定期发业务ping也是可选的, 但为了保存连接, 也为了继续持有wsc对象, 这里周期性发数据
while true do
wsc:send((json.encode({action="echo", msg=os.date()})))
sys.wait(15000)
-- 发送二进制帧, 2023.06.21 之后编译的固件支持
-- wsc:send(string.char(0xA5, 0x5A, 0xAA, 0xF2), 1, 1)
end
4.3.7 websocket 客户端关闭(关闭后资源释放无法再使用)
wsc:close()
4.4 成果演示与深度解析：视频 + 图文全面展示
4.4.1 成果运行精彩呈现
4.4.2 演示视频生动展示
4.4.3 完整实例深度剖析
PROJECT = "airtun"
VERSION = "1.0.0"
-- sys库是标配
_G.sys = require("sys")
-- _G.sysplus = require("sysplus")
-- Air780EP的AT固件默认会为开机键防抖, 导致部分用户刷机很麻烦
if rtos.bsp() == "EC618" and pm and pm.PWK_MODE then
pm.power(pm.PWK_MODE, false)
end
-- 报错信息自动上报到平台,默认是iot.openluat.com
-- 支持自定义, 详细配置请查阅API手册
-- 开启后会上报开机原因, 这需要消耗流量,请留意
if errDump then
errDump.config(true, 600)
end
local wsc = nil
sys.taskInit(function()
sys.waitUntil("IP_READY") -- 等待联网成功
-- 这是个测试服务, 当发送的是json,且action=echo,就会回显所发送的内容
-- 加密TCP链接 wss 表示加密
wsc = websocket.create(nil, "wss://echo.airtun.air32.cn/ws/echo")
-- 这是另外一个测试服务, 能响应websocket的二进制帧
-- wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo2")
-- 以上两个测试服务是Java写的, 源码在 https://gitee.com/openLuat/luatos-airtun/tree/master/server/src/main/java/com/luatos/airtun/ws
if wsc.headers then
wsc:headers({Auth="Basic ABCDEGG"})
end
wsc:autoreconn(true, 3000) -- 自动重连机制
wsc:on(function(wsc, event, data, fin, optcode)
--[[
event的值有:
conack 连接服务器成功,已经收到websocket协议头部信息,通信已建立
recv 收到服务器下发的信息, data, payload 不为nil
sent send函数发送的消息,服务器在TCP协议层已确认收到
disconnect 服务器连接已断开
其中 sent/disconnect 事件在 2023.04.01 新增
]]
-- data 当事件为recv是有接收到的数据
-- fin 是否为最后一个数据包, 0代表还有数据, 1代表是最后一个数据包
-- optcode, 0 - 中间数据包, 1 - 文本数据包, 2 - 二进制数据包
-- 因为lua并不区分文本和二进制数据, 所以optcode通常可以无视
-- 若数据不多, 小于1400字节, 那么fid通常也是1, 同样可以忽略
log.info("wsc", event, data, fin, optcode)
-- 显示二进制数据
-- log.info("wsc", event, data and data:toHex() or "", fin, optcode)
if event == "conack" then -- 连接websocket服务后, 会有这个事件
log.info("WebSocket connect succeed!")
sys.publish("wsc_conack")
end
end)
wsc:connect()
-- 等待conack是可选的
sys.waitUntil("wsc_conack")
--local stat = wsc:ready()
-- 定期发业务ping也是可选的, 但为了保存连接, 也为了继续持有wsc对象, 这里周期性发数据
while true do
wsc:send((json.encode({action="echo", msg=os.date()})))
sys.wait(15000)
-- 发送二进制帧, 2023.06.21 之后编译的固件支持
-- wsc:send(string.char(0xA5, 0x5A, 0xAA, 0xF2), 1, 1)
end
wsc:close()
wsc = nil
end)
-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后后面不要加任何语句!!!!!
五、WebSocket-UART 透传的概述
在某些应用场景下，可能需要将 WebSocket 接收到的数据通过 UART 串口发送到其他设备，或者将 UART 串口接收到的数据通过 WebSocket 发送到服务器。这通常需要通过一个中间层或网关设备来实现数据的转换和传输。
5.1 本教程实现的功能定义：
- 4G 模组插卡开机后，连接上 WebSocket 服务器；
- 本小节教你怎么使用 LuatOS脚本语言，就可以让合宙 4G 模组通过 Uart1 透传数据发送到 WebSocket 服务器，并且模组和服务器之间实现数据的交互！
5.2 文章内容引用
- Air780EP 开发板软硬件资料 ： Air780EP 产品手册
- websocket 函数接口不做详细介绍，可通过此链接查看具体介绍：websocket - 网络接口 - LuatOS 文档
5.3 核心脚本代码详解
5.3.1 websocket 客户端创建
-- ws 普通链接不加密
wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
--加密链接 wss 表示加密，
wsc = websocket.create(nil, "wss://echo.airtun.air32.cn/ws/echo")
5.3.2 设置额外的 headers
-- table形式
wsc:headers({Auth="Basic ABCDEFGG"})
-- 字符串形式
wsc:headers("Auth: Basic ABCDERG\r\n")
5.3.3 设置自动重连机制
wsc:autoreconn(true, 3000) -- 自动重连机制
5.3.4 注册 websocket 回调
wsc:on(function(wsc, event, data, fin, optcode)
--[[
event的值有:
conack 连接服务器成功,已经收到websocket协议头部信息,通信已建立
recv 收到服务器下发的信息, data, payload 不为nil
sent send函数发送的消息,服务器在TCP协议层已确认收到
disconnect 服务器连接已断开
其中 sent/disconnect 事件在 2023.04.01 新增
]]
-- data 当事件为recv是有接收到的数据
-- fin 是否为最后一个数据包, 0代表还有数据, 1代表是最后一个数据包
-- optcode, 0 - 中间数据包, 1 - 文本数据包, 2 - 二进制数据包
-- 因为lua并不区分文本和二进制数据, 所以optcode通常可以无视
-- 若数据不多, 小于1400字节, 那么fid通常也是1, 同样可以忽略
log.info("wsc", event, data, fin, optcode)
-- 显示二进制数据
-- log.info("wsc", event, data and data:toHex() or "", fin, optcode)
if event == "conack" then -- 连接websocket服务后, 会有这个事件
log.info("WebSocket connect succeed!")
sys.publish("wsc_conack")----连接成功发布"wsc_conack"
end
end)
5.3.5 连接服务器
wsc:connect()
-- 等待conack是可选的
sys.waitUntil("wsc_conack")------等待连接成功 并订阅到 "wsc_conack"
5.3.6 串口初始化
本文示例：串口使用 MAIN_UART(uart1)
--初始化
local uartid = 1 -- 根据实际设备选取不同的uartid
uart.setup(
uartid,--串口id
115200,--波特率
8,--数据位
1--停止位
)
5.3.7 接收 UART 消息
uart.on(uartid, "receive", function(id, len)
while true do
local len = uart.rx(id, uart_rx_buff) -- 接收串口收到的数据，并赋值到uart_rx_buff
if len <= 0 then -- 接收到的字节长度为0 则退出
break
else
uart_rx_buff:seek(0)
uart_rx_buff_data = uart_rx_buff:read(len)
Sbuf = len
log.info("UART接收的数据包",uart_rx_buff_data)
break
end
end
end)
5.3.8 发布消息
if Sbuf > 0 then
log.info("发送到服务器数据，长度",Sbuf)
log.info("UART发送到服务器的数据包 ",uart_rx_buff_data)
log.info("UART发送到服务器的数据包类型 ",type(uart_rx_buff_data))
if uart_rx_buff_data == '"echo"' then -- 连接收到串口发送的"echo" ，会进行数据发送
log.info("UART透传成功 进行数据发送")
wsc:send(json.encode({action="echo", msg=os.date()})) ---发送数据
end
end
5.3.9 websocket 客户端关闭(关闭后资源释放无法再使用)
wsc:close()
5.4 成果演示与深度解析：视频 + 图文全面展示
5.4.1 成果运行精彩呈现
5.4.2 演示视频生动展示
5.4.3 完整实例深度剖析
PROJECT = "Websocket_demo"
VERSION = "1.0.0"
-- sys库是标配
_G.sys = require("sys")
-- _G.sysplus = require("sysplus")
-- Air780EP的AT固件默认会为开机键防抖, 导致部分用户刷机很麻烦
if rtos.bsp() == "EC618" and pm and pm.PWK_MODE then
pm.power(pm.PWK_MODE, false)
end
if wdt then
--添加硬狗防止程序卡死，在支持的设备上启用这个功能
wdt.init(9000)--初始化watchdog设置为9s
sys.timerLoopStart(wdt.feed, 3000)--3s喂一次狗
end
-- 报错信息自动上报到平台,默认是iot.openluat.com
-- 支持自定义, 详细配置请查阅API手册
-- 开启后会上报开机原因, 这需要消耗流量,请留意
if errDump then
errDump.config(true, 600)
end
local tx_buff = zbuff.create(1024) -- 发送至WebSocket服务器的数据
local uart_rx_buff = zbuff.create(1024) -- 串口接收到的数据
local uartid = 1 -- 根据实际设备选取不同的uartid
Sbuf = 0
--初始化
uart.setup(
uartid,--串口id
115200,--波特率
8,--数据位
1--停止位
)
local wsc = nil
sys.taskInit(function()
sys.waitUntil("IP_READY") -- 等待联网成功
-- 这是个测试服务, 当发送的是json,且action=echo,就会回显所发送的内容
-- 加密TCP链接 wss 表示加密
wsc = websocket.create(nil, "wss://echo.airtun.air32.cn/ws/echo")
-- 这是另外一个测试服务, 能响应websocket的二进制帧
-- wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo2")
-- 以上两个测试服务是Java写的, 源码在 https://gitee.com/openLuat/luatos-airtun/tree/master/server/src/main/java/com/luatos/airtun/ws
if wsc.headers then
wsc:headers({Auth="Basic ABCDEGG"})
end
wsc:autoreconn(true, 3000) -- 自动重连机制
wsc:on(function(wsc, event, data, fin, optcode)
--[[
event的值有:
conack 连接服务器成功,已经收到websocket协议头部信息,通信已建立
recv 收到服务器下发的信息, data, payload 不为nil
sent send函数发送的消息,服务器在TCP协议层已确认收到
disconnect 服务器连接已断开
其中 sent/disconnect 事件在 2023.04.01 新增
]]
-- data 当事件为recv是有接收到的数据
-- fin 是否为最后一个数据包, 0代表还有数据, 1代表是最后一个数据包
-- optcode, 0 - 中间数据包, 1 - 文本数据包, 2 - 二进制数据包
-- 因为lua并不区分文本和二进制数据, 所以optcode通常可以无视
-- 若数据不多, 小于1400字节, 那么fid通常也是1, 同样可以忽略
log.info("wsc", event, data, fin, optcode)
-- 显示二进制数据
-- log.info("wsc", event, data and data:toHex() or "", fin, optcode)
if event == "conack" then -- 连接websocket服务后, 会有这个事件
log.info("WebSocket connect succeed!")
sys.publish("wsc_conack")
end
end)
wsc:connect()
sys.waitUntil("wsc_conack")
uart.on(uartid, "receive", function(id, len)
while true do
while true do
local len = uart.rx(id, uart_rx_buff) -- 接收串口收到的数据，并赋值到uart_rx_buff
if len <= 0 then -- 接收到的字节长度为0 则退出
break
else
uart_rx_buff:seek(0)
uart_rx_buff_data = uart_rx_buff:read(len)
Sbuf = len
log.info("UART接收的数据包",uart_rx_buff_data)
break
end
end
end)
if Sbuf > 0 then
log.info("发送到服务器数据，长度",Sbuf)
log.info("UART发送到服务器的数据包 ",uart_rx_buff_data)
log.info("UART发送到服务器的数据包类型 ",type(uart_rx_buff_data))
if uart_rx_buff_data == '"echo"' then -- 连接收到串口发送的"echo" ，会进行数据发送
log.info("UART透传成功 进行数据发送")
wsc:send(json.encode({action="echo", msg=os.date()})) ---发送数据
end
end
Sbuf = 0
uart_rx_buff:del() -- 清除串口buff的数据长度
sys.wait(1000)
end
wsc:close()
wsc = nil
end)
-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后后面不要加任何语句!!!!!
六、总结
- WebSocket 加密确保了数据在传输过程中的安全性，防止被窃取或篡改；而 WebSocket 透传则指数据在不改变内容的情况下，通过 WebSocket 协议进行传输，通常涉及中间层或网关设备的数据格式转换与传递
- Air780EP 作为一款 4G 模组，支持 WebSocket 协议，并可通过 Luatools 等工具进行调试和固件管理。在 Air780EP 上实现 WebSocket 加密通讯，通常需要使用 SSL/TLS 等加密协议来确保数据传输的安全性。
七、常见问题
- websocket 服务器的连接地址,格式为 ws(或 wss)://xxx 开头
- websocket 需要在任务中启动,带自动重连,支持心跳协议
- websocket 心跳包，建议 180 秒
- 注意 串口发送过去的数据是 字符格式，这里进行对比时注意 echo的类型 if uart_rx_buff_data == '"echo"'
八、扩展
在 WebSocket 中，WS 和 WSS 代表两种不同的连接类型，它们分别具有以下特点：
8.1 WS（WebSocket）
- 含义：表示非安全的 WebSocket 连接，即没有加密的 WebSocket 通信。
- 端口：默认情况下，WebSocket 的 WS 协议使用 80 端口。
- 使用场景：适用于不需要数据加密的场景，或者在安全性要求不高的环境中使用。然而，对于敏感数据或需要保护通信内容的情况，WS 可能不是最佳选择。
8.2 WSS（WebSocket Secure）
- 含义：表示安全的 WebSocket 连接，即在 TLS（传输层安全协议）之上的 WebSocket 通信。WSS 相当于 HTTPS 在 WebSocket 中的应用，提供了数据加密和完整性验证等安全功能。
- 端口：默认情况下，WSS 协议使用 443 端口，这是大多数网站用于 HTTPS 通信的标准端口。
- 使用场景：适用于需要保护通信内容、防止数据窃取或篡改的场景。WSS 是处理敏感数据或进行安全通信时的推荐选择。
给读者的话
本篇文章由
永仔开发；本篇文章描述的内容，如果有错误、细节缺失、细节不清晰或者其他任何问题，总之就是无法解决您遇到的问题；
请登录合宙技术交流论坛，点击文档找错赢奖金-Air780EP-LuatOS-软件指南-网络驱动-WebSocket通信；
用截图标注+文字描述的方式跟帖回复，记录清楚您发现的问题；
我们会迅速核实并且修改文档；
同时也会为您累计找错积分，您还可能赢取月度找错奖金！