socket - 网络接口

已适配 Air101/Air103 Air105 ESP32C3 ESP32S3 Air780E

小技巧

本库有专属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 Air105 ESP32C3 ESP32S3 Air780E

sntp时间同步

参数

传入值类型	解释
string/table	sntp服务器地址 选填

返回值

无

例子

socket.sntp()
--socket.sntp("ntp.aliyun.com") --自定义sntp服务器地址
--socket.sntp({"ntp.aliyun.com","ntp1.aliyun.com","ntp2.aliyun.com"}) --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)

---