socket - 网络接口#
已适配 Air101/Air103 Air601 Air105 ESP32C3 ESP32S3 Air780E/Air700E
小技巧
本库有专属demo,点此链接查看socket的demo例子
常量#
常量 |
类型 |
解释 |
---|---|---|
socket.ETH0 |
number |
带硬件协议栈的ETH0,值为5 |
socket.LWIP_ETH |
number |
使用LWIP协议栈的以太网卡,值为4 |
socket.LWIP_STA |
number |
使用LWIP协议栈的WIFI STA,值为2 |
socket.LWIP_AP |
number |
使用LWIP协议栈的WIFI AP,值为3 |
socket.LWIP_GP |
number |
使用LWIP协议栈的移动蜂窝模块,值为1 |
socket.USB |
number |
使用LWIP协议栈的USB网卡,值为6 |
socket.LINK |
number |
LINK事件 |
socket.ON_LINE |
number |
ON_LINE事件 |
socket.EVENT |
number |
EVENT事件 |
socket.TX_OK |
number |
TX_OK事件 |
socket.CLOSED |
number |
CLOSED事件 |
socket.sntp(sntp_server)#
本接口仅支持 Air101/Air103 Air601 Air105 ESP32C3 ESP32S3 Air780E/Air700E
sntp时间同步
参数
传入值类型 |
解释 |
---|---|
string/table |
sntp服务器地址 选填 |
int |
适配器序号, 只能是socket.ETH0(外置以太网),socket.LWIP_ETH(内置以太网),socket.LWIP_STA(内置WIFI的STA),socket.LWIP_AP(内置WIFI的AP),socket.LWIP_GP(内置蜂窝网络的GPRS),socket.USB(外置USB网卡),如果不填,优先选择soc平台自带能上外网的适配器,若仍然没有,选择最后一个注册的适配器 |
返回值
无
例子
socket.sntp()
--socket.sntp("ntp.aliyun.com") --自定义sntp服务器地址
--socket.sntp({"ntp.aliyun.com","ntp1.aliyun.com","ntp2.aliyun.com"}) --sntp自定义服务器地址
--socket.sntp(nil, socket.ETH0) --sntp自定义适配器序号
sys.subscribe("NTP_UPDATE", function()
log.info("sntp", "time", os.date())
end)
sys.subscribe("NTP_ERROR", function()
log.info("socket", "sntp error")
socket.sntp()
end)
socket.localIP(adapter)#
获取本地ip
参数
传入值类型 |
解释 |
---|---|
int |
适配器序号, 只能是socket.ETH0(外置以太网),socket.LWIP_ETH(内置以太网),socket.LWIP_STA(内置WIFI的STA),socket.LWIP_AP(内置WIFI的AP),socket.LWIP_GP(内置蜂窝网络的GPRS),socket.USB(外置USB网卡),如果不填,优先选择soc平台自带能上外网的适配器,若仍然没有,选择最后一个注册的适配器 |
返回值
返回值类型 |
解释 |
---|---|
string |
通常是内网ip, 也可能是外网ip, 取决于运营商的分配 |
string |
网络掩码 |
string |
网关IP |
例子
sys.taskInit(function()
while 1 do
sys.wait(3000)
log.info("socket", "ip", socket.localIP())
-- 输出示例
-- 62.39.244.10 255.255.255.255 0.0.0.0
end
end)
socket.create(adapter, cb)#
在某个适配的网卡上申请一个socket_ctrl
参数
传入值类型 |
解释 |
---|---|
int |
适配器序号, 只能是socket.ETH0(外置以太网),socket.LWIP_ETH(内置以太网),socket.LWIP_STA(内置WIFI的STA),socket.LWIP_AP(内置WIFI的AP),socket.LWIP_GP(内置蜂窝网络的GPRS),socket.USB(外置USB网卡),如果不填,优先选择soc平台自带能上外网的适配器,若仍然没有,选择最后一个注册的适配器 |
string |
or function string为消息通知的taskName,function则为回调函数,如果固件没有内置sys_wait,则必须是function |
返回值
无
例子
无
socket.debug(ctrl, onoff)#
配置是否打开debug信息
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
boolean |
true 打开debug开关 |
返回值
返回值类型 |
解释 |
---|---|
nil |
无返回值 |
例子
无
socket.config(ctrl, local_port, is_udp, is_tls, keep_idle, keep_interval, keep_cnt, server_cert, client_cert, client_key, client_password)#
配置network一些信息,
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
int |
本地端口号,小端格式,如果不写,则自动分配一个,如果用户填了端口号则需要小于60000, 默认不写 |
boolean |
是否是UDP,默认false |
boolean |
是否是加密传输,默认false |
int |
tcp keep live模式下的idle时间(秒),如果留空则表示不启用,如果是不支持标准posix接口的网卡(比如W5500),则为心跳间隔 |
int |
tcp keep live模式下的探测间隔时间(秒) |
int |
tcp keep live模式下的探测次数 |
string |
TCP模式下的服务器ca证书数据,UDP模式下的PSK,不需要加密传输写nil,后续参数也全部nil |
string |
TCP模式下的客户端ca证书数据,UDP模式下的PSK-ID,TCP模式下如果不需要验证客户端证书时,忽略,一般不需要验证客户端证书 |
string |
TCP模式下的客户端私钥加密数据 |
string |
TCP模式下的客户端私钥口令数据 |
返回值
返回值类型 |
解释 |
---|---|
boolean |
成功返回true,失败返回false |
例子
socket.config(ctrl, nil, nil ,true) --最普通的加密TCP传输,证书都不用验证的那种
socket.linkup(ctrl)#
等待网卡linkup
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了 |
boolean |
true已经linkup,false没有linkup,之后需要接收socket.LINK消息 |
例子
无
socket.connect(ctrl, ip, remote_port, need_ipv6_dns)#
作为客户端连接服务器
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
string |
or int ip或者域名,如果是IPV4,可以是大端格式的int值 |
int |
服务器端口号,小端格式 |
boolean |
域名解析是否要IPV6,true要,false不要,默认false不要,只有支持IPV6的协议栈才有效果 |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了,如果有异常,后续要close |
boolean |
true已经connect,false没有connect,之后需要接收socket.ON_LINE消息 |
例子
无
socket.discon(ctrl)#
作为客户端断开连接
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了 |
boolean |
true已经断开,false没有断开,之后需要接收socket.CLOSED消息 |
例子
无
socket.close(ctrl)#
强制关闭socket
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
返回值
无
例子
无
socket.tx(ctrl, data, ip, port, flag)#
发送数据给对端,UDP单次发送不要超过1460字节,否则很容易失败
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
string |
or user_data zbuff 要发送的数据 |
string |
or int 对端IP,如果是TCP应用则忽略,如果是UDP,如果留空则用connect时候的参数,如果是IPV4,可以是大端格式的int值 |
int |
对端端口号,小端格式,如果是TCP应用则忽略,如果是UDP,如果留空则用connect时候的参数 |
int |
发送参数,目前预留,不起作用 |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了,如果false,后续要close |
boolean |
true缓冲区满了,false没有满,如果true,则需要等待一段时间或者等到socket.TX_OK消息后再尝试发送,同时忽略下一个返回值 |
boolean |
true已经收到应答,false没有收到应答,之后需要接收socket.TX_OK消息, 也可以忽略继续发送,直到full==true |
例子
无
socket.rx(ctrl, buff, flag)#
接收对端发出的数据,注意数据已经缓存在底层,使用本函数只是提取出来,UDP模式下一次只会取出一个数据包
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
user_data |
zbuff 存放接收的数据,如果缓冲区不够大会自动扩容 |
int |
接收参数,目前预留,不起作用 |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了,如果false,后续要close |
int |
本次接收到数据长度 |
string |
对端IP,只有UDP模式下才有意义,TCP模式返回nil,注意返回的格式,如果是IPV4,1byte 0x00 + 4byte地址 如果是IPV6,1byte 0x01 + 16byte地址 |
int |
对端port,只有UDP模式下才有意义,TCP模式返回0 |
例子
无
socket.wait(ctrl)#
等待新的socket消息,在连接成功和发送数据成功后,使用一次将network状态转换到接收新数据
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了,如果false,后续要close |
boolean |
true有新的数据需要接收,false没有数据,之后需要接收socket.EVENT消息 |
例子
无
socket.listen(ctrl)#
作为服务端开始监听
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了,如果false,后续要close |
boolean |
true已经connect,false没有connect,之后需要接收socket.ON_LINE消息 |
例子
无
socket.accept(ctrl)#
作为服务端接收到一个新的客户端,注意,如果是类似W5500的硬件协议栈不支持1对多,则不需要第二个参数
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl,这里是服务器端 |
string |
or function or nil string为消息通知的taskName,function则为回调函数,和socket.create参数一致 |
返回值
返回值类型 |
解释 |
---|---|
boolean |
true没有异常发生,false失败了,如果false则不需要看下一个返回值了,如果false,后续要close |
user_data |
or nil 如果支持1对多,则会返回新的ctrl,自动create,如果不支持则返回nil |
例子
无
socket.release(ctrl)#
主动释放掉network_ctrl
参数
无
返回值
无
例子
无
socket.setDNS(adapter_index, dns_index, ip)#
设置DNS服务器
参数
传入值类型 |
解释 |
---|---|
int |
适配器序号, 只能是socket.ETH0,socket.STA,socket.AP,如果不填,会选择最后一个注册的适配器 |
int |
dns服务器序号,从1开始 |
string |
or int dns,如果是IPV4,可以是大端格式的int值 |
返回值
返回值类型 |
解释 |
---|---|
boolean |
成功返回true,失败返回false |
例子
socket.setDNS(socket.ETH0, 1, "114.114.114.114")
socket.sslLog(log_level)#
设置SSL的log
参数
传入值类型 |
解释 |
---|---|
int mbedtls |
log等级,0不打印,1只打印错误和警告,2大部分info,3及3以上详细的debug信息,过多的信息可能会造成内存碎片化 |
usage |
socket.sslLog(2) |
返回值
无
例子
无
socket.adapter(index)#
查看网卡适配器的联网状态
参数
传入值类型 |
解释 |
---|---|
int |
需要查看的适配器序号,可以留空会查看全部网卡,直到遇到IP READY的,如果指定网卡,只能是socket.ETH0(外置以太网),socket.LWIP_ETH(内置以太网),socket.LWIP_STA(内置WIFI的STA),socket.LWIP_AP(内置WIFI的AP),socket.LWIP_GP(内置蜂窝网络的GPRS),socket.USB(外置USB网卡) |
返回值
返回值类型 |
解释 |
---|---|
boolean |
被查看的适配器是否IP READY,true表示已经准备好可以联网了,false暂时不可以联网 |
int |
最后一个被查看的适配器序号 |
例子
-- 查看全部网卡,直到找到一个是IP READY的
local isReady,index = socket.adapter() --如果isReady为true,则index为IP READY的网卡适配器序号
--查看外置以太网(比如W5500)是否IP READY
local isReady,default = socket.adapter(socket.ETH0)
socket.remoteIP(ctrl)#
获取对端ip,必须在接收到socket.ON_LINE消息之后才可能获取到,最多返回4个IP。socket.connect里如果remote_port设置成0,则当DNS完成时就返回socket.ON_LINE消息
参数
传入值类型 |
解释 |
---|---|
user_data |
socket.create得到的ctrl |
返回值
返回值类型 |
解释 |
---|---|
string |
IP1,如果为nil,则表示没有获取到IP地址 |
string |
IP2,如果为nil,则表示没有IP2 |
string |
IP3,如果为nil,则表示没有IP3 |
string |
IP4,如果为nil,则表示没有IP4 |
例子
local ip1,ip2,ip3,ip4 = socket.remoteIP(ctrl)