WebSocket

一、WebSocket 概述

WebSocket 是 HTML5 下一种新的协议（本质上是一个基于 TCP 的协议），它实现了浏览器与服务器之间的全双工通信，能够节省服务器资源和带宽，达到实时通讯的目的。WebSocket 协议通过握手机制，允许客户端和服务器之间建立一个类似 TCP 的连接，从而方便它们之间的通信。

• 在线聊天应用：允许用户实时发送和接收消息，而无需页面刷新或轮询服务器。
• 实时协作应用：支持多用户实时编辑文档或共享白板等场景。
• 实时游戏：允许多个玩家之间进行实时的游戏交互。
• 实时数据展示：用于显示实时数据，如股票市场变化、天气预报更新等。
• 实时通知和提醒：用于向用户发送实时的通知消息，如新邮件提醒、社交媒体通知等。
• 在线会议和视频通话：支持实时的音视频通信。

二、演示功能概述

本文使用 Air724UG 核心板，进行固件与脚本的烧录，连接 WebSocket 服务器，并且对脚本核心代码进行解析，以便开发者能快速了解 WebSocket 通信功能的使用。

三、准备硬件环境

“古人云：‘工欲善其事，必先利其器。’在深入介绍本功能示例之前，我们首先需要确保以下硬件环境的准备工作已经完成。”

3.1 Air724UG 开发板

准备一块 Air724UG-NFM 开发板，如下图所示：

点击链接购买：Air724UG-NFM 开发板淘宝购买链接 ；

此开发板的详细使用说明参考：Air724UG 产品手册 中的《EVB_Air724UG_AXX 开发板使用说明》，写这篇文章时最新版本的使用说明为：《EVB_Air724UG_A14 开发板使用说明》；开发板使用过程中遇到任何问题，可以直接参考这份使用说明文档。

3.2 SIM 卡

请准备一张可以正常上网的 SIM 卡，该卡可以是物联网卡或者您的个人手机卡。

特别提醒：请确保 SIM 卡未欠费且网络功能正常，以便顺利进行后续操作。

3.3 PC 电脑

请准备一台配备 USB 接口且能够正常上网的 Windows7 以及以上系统的电脑。

3.4 数据通信线

请准备一根用于连接 EVB_Air724UG_A14 开发板和 PC 电脑的数据线，该数据线将实现业务逻辑的控制与交互。

• USB 数据线：此数据线不仅用于为测试板供电，还用于查看数据日志。其一端为 Micro-B 接口（俗称老安卓口），用于连接 EVB_Air724UG_A14 开发板；另一端为标准 USB 接口，连接 PC 电脑。

3.5 组装硬件环境

3.5.1 请按照 SIM 卡槽上的指示方向正确插入 SIM 卡，务必确保插入方向正确，避免插反导致损坏！

通常，插入 SIM 卡的步骤如下：

• 将 SIM 卡槽的卡扣向 OPEN 的方向推，然后抬起。
• 将 SIM 卡对准卡槽形状，SIM 卡金属接触面朝下，再将卡口合上，朝 CLOSE 方向推，能够关上就说明 SIM 卡已经安装到位。

3.5.2 USB 数据线，连接电脑和 Air724UG 开发板：

1. 如下图，位于上方的 USB 接口（上方红框）直接用 micro USB 数据线连接 PC 供电。

2. 如下图，使用 USB 线缆，插入左侧的 USB 端口，将开发板左侧的电源拨动开关拨至“ON”。长按开机按钮 3 秒钟。

注意：A 所指示的框图区域，拨码开关 1 和 2 的位置需拨至上方与下图保持一致，以确保开发板能够正常工作。

3. 如下图，此时位置 1 的电源红灯会处于常亮，如果开发板是 AT 版本的固件，位置 2 的绿灯会闪烁（LUA 固件不带脚本时绿灯不亮）

四、准备软件环境

“凡事预则立，不预则废。”在详细阐述本功能示例之前，我们需先精心筹备好以下软件环境。

4.1 安装驱动程序

1. 按照 3.5.2 节启动设备后，打开电脑的设备管理器，如果出现下图情况，需要安装驱动程序，Air724UG_USB 驱动下载地址：点击此处

2. 安装成功后打开设备管理器，会出现如下界面：

4.2 安装 Luatools 工具

想要烧录 AT 固件到 4G 模组中，需要用到合宙的强大的调试工具：Luatools；

下载地址：Luatools v3 下载调试工具。

Luatools 工具集具备以下几大核心功能：

• 一键获取最新固件：自动连接合宙服务器，轻松下载最新的合宙模组固件。
• 固件与脚本烧录：便捷地将固件及脚本文件烧录至目标模组中。
• 串口日志管理：实时查看模组通过串口输出的日志信息，并支持保存功能。
• 串口调试助手：提供简洁的串口调试界面，满足基本的串口通信测试需求。

Luatools 下载之后， 无需安装， 解压到你的硬盘，点击 Luatools_v3.exe 运行，出现如下界面，就代表 Luatools 安装成功了：

4.3 烧录代码

首先要说明一点： 脚本代码， 要和固件的 LuatOS-Air_V4030_RDA8910.pac 文件以及 lib 文件一起烧录。

4.3.1 找到烧录的固件文件

官网下载，底层 core 下载地址：Air724UG SDK&Demo

注意：本 demo 使用如图所示固件

4.3.2 找到烧录的脚本以及 lib 脚本

官网下载，烧录脚本以及 lib 脚本下载地址：Air724UG SDK&Demo

注意：本 demo 使用如图所示脚本包

4.4 新建项目

首先，确保你的 Luatools 的版本大于或者等于 3.0.6 版本。

在 Luatools 的左上角有版本显示，如图所示：

Luatools 版本没问题的话， 就点击 Luatools 右上角的“项目管理测试”按钮，如下图所示：

这时会弹出项目管理和烧录管理的对话框，如下图：

4.5 开始烧录

选择 724UG 板子对应的底层 core 和刚改的 main.lua 和 demo.lua 脚本文件以及 lib 文件夹下载到板子中。

点击下载后，下方显示下载成功即为下载成功。

五、WebSocket 通讯的概述

本小节教你怎么使用 luatos 脚本语言，就可以让合宙 4G 模组连接上一个 WebSocket 服务器。

5.1 本教程实现的功能定义：

4G 模组插卡开机后，连接上 WebSocket 服务器。

5.2 文章内同引用

• Air724UG 开发板软硬件资料：Air724UG 产品手册
• WebSocket 函数接口详细介绍：WebSocket 指南

5.3 核心脚本代码详解

5.3.1 创建 WebSocket 对象

local ws = websocket.new("wss://echo.airtun.air32.cn/ws/echo")

5.3.2 注册对应相关处理函数

这里注册了“open”，“message”，“send”，“close”，“error” 事件的处理函数，message|error|pong 形参是该方法需要的数据。

ws:on("open", function()
    ws:send("hello websocket server!")
end)
ws:on("message", function(msg)
    log.info("收到 websocket server 的消息:", msg)
end)
ws:on("sent", function()
    log.info("sent to websocket:", "发送消息已完成!")
end)
ws:on("error", function(msg)
    log.error("websocket error:", msg)
end)
ws:on("close", function(code)
    log.info("websocket closed,关闭码:", code)
end)

5.3.3 发送消息

每隔 2 秒，会向服务器发送一条固定消息。

sys.taskInit(function ()
    while true do
        sys.wait(2000)
        ws:send("www.openluat.com",true)
    end
end)

六、成果展示与完整解析

6.1 成果展示

6.2 完整解析

_--- 模块功能：websocket客户端_
_-- @module websocket_
_-- @author OpenLuat_
_-- @license MIT_
_-- @copyright OpenLuat.com_
_-- @release 2021.04.08_

_-- 引入必要的模块_
require "utils"          _-- 引入工具函数模块_
require "pm"             _-- 引入电源管理模块_
require "websocket"      _-- 引入WebSocket模块_

module(..., package.seeall) _-- 定义模块_

_-- 创建 websocket 对象，连接到指定的WebSocket服务器_
local ws = websocket.new("wss://echo.airtun.air32.cn/ws/echo")

_-- 设置WebSocket连接成功时的回调函数_
ws:on("open", function()
    ws:send("hello websocket server!") _-- 连接成功后发送消息_
end)

_-- 设置收到消息时的回调函数_
ws:on("message", function(msg)
    log.info("收到 websocket server 的消息:", msg) _-- 记录收到的消息_
end)

_-- 设置消息发送完成时的回调函数_
ws:on("sent", function()
    log.info("sent to websocket:", "发送消息已完成!") _-- 记录发送完成的消息_
end)

_-- 设置WebSocket错误时的回调函数_
ws:on("error", function(msg)
    log.error("websocket error:", msg) _-- 记录错误信息_
end)

_-- 设置WebSocket关闭时的回调函数_
ws:on("close", function(code)
    log.info("websocket closed,关闭码:", code) _-- 记录关闭码_
end)

_-- 启动WebSocket任务进程，设置栈大小为180字节_
sys.taskInit(ws.start, ws, 180)

_-- 启动一个定时任务，定期发送消息到WebSocket服务器_
sys.taskInit(function ()
    while true do
        sys.wait(2000) _-- 每2秒等待一次_
        ws:send("www.openluat.com", true) _-- 发送指定消息，true表示这是一个响应_
    end
end)

_-- 启动一个定时器，每10秒打印内存使用情况和可用空间_
sys.timerLoopStart(function()
    log.info("打印占用的内存:", _G.collectgarbage("count")) _-- 打印当前占用的RAM（单位KB）_
    log.info("打印可用的空间", rtos.get_fs_free_size()) _-- 打印剩余FLASH存储空间（单位Byte）_
end, 10000)

七、总结

• Air724UG 作为一款 4G 模组，支持 WebSocket 协议，并可通过 Luatools 等工具进行调试和固件管理。
• WebSocket 使得客户端和服务器之间的数据交换变得更加简单，允许服务端主动向客户端推送数据。

八、常见问题

• websocket 服务器的连接地址,格式为 ws(或 wss)://xxx 开头
• websocket 需要在任务中启动,带自动重连,支持心跳协议
• websocket 心跳包，建议 180 秒

九、扩展

在 WebSocket 中，WS 和 WSS 代表两种不同的连接类型，它们分别具有以下特点：

9.1 WS（WebSocket）

• 含义：表示非安全的 WebSocket 连接，即没有加密的 WebSocket 通信。
• 端口：默认情况下，WebSocket 的 WS 协议使用 80 端口。
• 使用场景：适用于不需要数据加密的场景，或者在安全性要求不高的环境中使用。然而，对于敏感数据或需要保护通信内容的情况，WS 可能不是最佳选择。

9.2 WSS（WebSocket Secure）

• 含义：表示安全的 WebSocket 连接，即在 TLS（传输层安全协议）之上的 WebSocket 通信。WSS 相当于 HTTPS 在 WebSocket 中的应用，提供了数据加密和完整性验证等安全功能。
• 端口：默认情况下，WSS 协议使用 443 端口，这是大多数网站用于 HTTPS 通信的标准端口。
• 使用场景：适用于需要保护通信内容、防止数据窃取或篡改的场景。WSS 是处理敏感数据或进行安全通信时的推荐选择。

给读者的话

本篇文章由永仔开发；

本篇文章描述的内容，如果有错误、细节缺失、细节不清晰或者其他任何问题，总之就是无法解决您遇到的问题；

请登录合宙技术交流论坛，点击文档找错赢奖金-Air724UG-LuatOS-WebSocket通信；

用截图标注+文字描述的方式跟帖回复，记录清楚您发现的问题；

我们会迅速核实并且修改文档；

同时也会为您累计找错积分，您还可能赢取月度找错奖金！