socket - Network Interface

Adapted Air780E/Air700E Air780EP/Air780EPV Air601 Air101/Air103 Air105 ESP32C3 ESP32S3

Tip

This library has its own demo,click this link to view the demo example of socket

Constant

constant	type	explanation
socket.ETH0	number	ETH0 with hardware stack, value is 5
socket.LWIP_ETH	number	An Ethernet card using the LWIP protocol stack, with a value 4
socket.LWIP_STA	number	WIFI STA using LWIP protocol stack, the value is 2
socket.LWIP_AP	number	WIFI AP using LWIP protocol stack, the value is 3
socket.LWIP_GP	number	Mobile cellular module using the LWIP protocol stack with a value 1
socket.USB	number	USB network card using LWIP protocol stack, value is 6
socket.LINK	number	LINK Event
socket.ON_LINE	number	ON_LINE Event
socket.EVENT	number	EVENT Event
socket.TX_OK	number	TX_OK Event
socket.CLOSED	number	CLOSED Event

socket.sntp(sntp_server)

This interface only supports Air780E/Air700E Air780EP/Air780EPV Air601 Air101/Air103 Air105 ESP32C3 ESP32S3

sntp Time synchronization

Parameters

Incoming Value Type	Explanation
string/table	sntp Server address optional
int	The serial number of the adapter can only be socket.ETH0 (external Ethernet),socket.LWIP_ETH (internal Ethernet),socket.LWIP_STA (STA with internal WIFI),socket.LWIP_AP (AP with internal WIFI),socket.LWIP_GP (GPRS with internal cellular network),socket.USB (external USB network card). if not filled in, the soc platform is preferred to have its own adapter capable of connecting to the external network. if there is still no adapter, select Last Registered Adapter

Return Value

None

Examples

socket.sntp()
--socket.sntp("ntp.aliyun.com") --custom sntp server address
--socket.sntp({"ntp.aliyun.com","ntp1.aliyun.com","ntp2.aliyun.com"}) --sntp Custom Server Address
--socket.sntp(nil, socket.ETH0) --sntp Custom Adapter Serial Number
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.ntptm()

timestamp after the network pair (ms level)

Parameters

None

Return Value

return value type	explanation
table	Data containing time information

Examples

-- This API was added on 2023.11.15
-- Note that this function is not valid until socket.sntp() is executed and the NTP time is obtained.
-- And it is the more accurate value after 2 sntp
-- The smaller the network fluctuation, the more stable the timestamp.
local tm = socket.ntptm()

-- The corresponding table contains multiple data, all of which are integer values.

-- Standard data
-- tsec Current seconds, starting from 1900.1.1 0:0:0, UTC time
-- tms  Current number of milliseconds
-- vaild Valid, true or nil

-- Debugging data, debugging, general users do not have to tube
-- ndelay Average network delay, in milliseconds
-- ssec The second offset of the system start time and 1900.1.1 0:0:0
-- sms The millisecond offset of the system startup time from 1900.1.1 0:0:0
-- lsec Local seconds counter, based on mcu.tick64()
-- lms Local milliseconds counter, based on mcu.tick64()

log.info("tm Data", json.encode(tm))
log.info("Timestamp", string.format("%u.%03d", tm.tsec, tm.tms))

---

socket.sntp_port(port)

Set the port number of the SNTP server

Parameters

Incoming Value Type	Explanation
int	port port number, default 123

Return Value

return value type	explanation
int	Returns the current port number

Examples

-- This function was added in 2024.5.17
-- In most cases, you do not need to set the port number of the NTP server, and the default 123 is sufficient.

---

socket.localIP(adapter)

Get Local ip

Parameters

Incoming Value Type

Explanation

int

The serial number of the adapter can only be socket.ETH0 (external Ethernet),socket.LWIP_ETH (internal Ethernet),socket.LWIP_STA (STA with internal WIFI),socket.LWIP_AP (AP with internal WIFI),socket.LWIP_GP (GPRS with internal cellular network),socket.USB (external USB network card). if not filled in, the soc platform is preferred to have its own adapter capable of connecting to the external network. if there is still no adapter, select Last Registered Adapter

Return Value

return value type	explanation
string	It is usually an intranet ip or an extranet ip, depending on the operator’s allocation.
string	Network Mask
string	Gateway IP

Examples

sys.taskInit(function()
    while 1 do
        sys.wait(3000)
        log.info("socket", "ip", socket.localIP())
        -- Output example
        -- 62.39.244.10    255.255.255.255    0.0.0.0
    end
end)

---

socket.create(adapter, cb)

Apply for one on an adapted network card.socket_ctrl

Parameters

Incoming Value Type	Explanation
int	The serial number of the adapter can only be socket.ETH0 (external Ethernet),socket.LWIP_ETH (internal Ethernet),socket.LWIP_STA (STA with internal WIFI),socket.LWIP_AP (AP with internal WIFI),socket.LWIP_GP (GPRS with internal cellular network),socket.USB (external USB network card). if not filled in, the soc platform is preferred to have its own adapter capable of connecting to the external network. if there is still no adapter, select Last Registered Adapter
string	or function string is the taskName of the message notification, function it is a callback function, and if the firmware does not have a built-in sys_wait, it must be function

Return Value

None

Examples

None

---

socket.debug(ctrl, onoff)

Configure whether to open debug information

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl
boolean	true Turn on the debug switch

Return Value

return value type	explanation
nil	No return value

Examples

-- Turn on debugging information, which is turned off by default.
socket.debug(ctrl, true)

---

socket.config(ctrl, local_port, is_udp, is_tls, keep_idle, keep_interval, keep_cnt, server_cert, client_cert, client_key, client_password)

Configuration network some information，

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl
int	The local port number is in small endian format. If it is not written, one will be automatically assigned. If the user fills in the port number, it needs to be less than 60000. By default, it is not written
boolean	Whether it is UDP, default false
boolean	Whether it is encrypted transmission, default false
int	tcp keep live The idle time (in seconds) in the mode. If it is left blank, it means that it is not enabled. If it is a network card that does not support the standard posix interface (such as W5500), it is the heartbeat interval.
int	tcp keep live The probing interval in the mode (seconds）
int	tcp keep live Number of probes in mode
string	TCP The server ca certificate data in the mode and PSK in the UDP mode do not need to be encrypted and transmitted to write nil, and all subsequent parameters are also required.nil
string	TCP client ca certificate data in mode, PSK-ID in udp mode, and if you do not need to verify the client certificate in tcp mode, ignore, generally do not need to verify the client certificate
string	TCP Client private key encrypts data in mode
string	TCP Client private key password data in the mode

Return Value

return value type	explanation
boolean	Returns true on success and true on failure false

Examples

--The most common TCP transport
socket.config(ctrl)
--The most common encrypted TCP transmission, the kind of certificate without verification
socket.config(ctrl, nil, nil ,true)

---

socket.linkup(ctrl)

Wait for network card linkup

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to look at the next return value
boolean	true There is no linkup,false, and then you need to receive socket.LINK messages.

Examples

-- Judge whether it is connected to the Internet.
local succ, result = socket.linkup(ctrl)

---

socket.connect(ctrl, ip, remote_port, need_ipv6_dns)

Connect to the server as a client

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl
string	or int ip Or domain name, if it is IPV4, it can be int value in big-end format.
int	Server port number, little-end format
boolean	Does domain name resolution need IPV6,true yes, false no, default false no, only protocol stacks that support IPV6 have effect

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to look at the next return value, if there is an exception, follow-up close
boolean	true It has been connect,false is not connect, and socket.ON_LINE message needs to be received later.

Examples

local succ, result = socket.connect(ctrl, "netlab.luatos.com", 40123)

--[[
The code value of the common connection failure will be displayed in the log
-1 Low underlying memory
-3 Timeout
-8 Port already occupied
-11 Link not established
-13 Module Active Disconnect
-14 Server Active Disconnect
]]

---

socket.discon(ctrl)

Disconnect as client

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to look at the next return value
boolean	true Disconnected, false not disconnected, then need to receive socket.CLOSED message

Examples

local succ, result = socket.discon(ctrl)

---

socket.close(ctrl)

Force Close socket

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

return value type	explanation
nil	No return value

Examples

None

---

socket.tx(ctrl, data, ip, port, flag)

Send data to the opposite end, UDP should not send more than 1460 bytes at a time, otherwise it is easy to fail.

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl
string	or user_data zbuff Data to send
string	or int The opposite IP is ignored if it is TCP application, and if it is UDP, the parameter at connect time is used if it is left blank. if it is IPV4, it can be int value in big-end format.
int	The opposite-end slogan and small-end format are ignored if it is TCP application, and if it is UDP, the parameters at connect time are used if it is left blank.
int	Send parameter, currently reserved, does not work

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to see the next return value, if false, follow-up close
boolean	true The buffer is full, false is not full, if true, you need to wait for a period of time or wait for the socket.TX_ OK message before trying to send, while ignoring the next return value
boolean	true A reply has been received, false has not received a reply, and then you need to receive the socket.TX_ OK message, or you can ignore and continue sending full==true

Examples

local succ, full, result = socket.tx(ctrl, "123456", "xxx.xxx.xxx.xxx", xxxx)

---

socket.rx(ctrl, buff, flag, limit)

Receive the data sent by the opposite end, note that the data has been cached at the bottom layer, use this function only to extract, UDP mode will only take out one data packet at a time

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl
user_data	zbuff Store the received data, and automatically expand the capacity if the buffer is not enough.
int	Receiving parameter, currently reserved, does not work
int	Receive data length limit, if specified, only the first N bytes are taken. 2024.1.5 New

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to see the next return value, if false, follow-up close
int	Length of data received this time
string	The peer IP is meaningful only in UDP mode. TCP mode returns nil. Pay attention to the format of the return. If it is IPV4,1byte 0x 00 4byte address, if it is IPV6,1byte 0x 01 16byte address
int	The port on the opposite end, which is meaningful only in UDP mode and returned in TCP mode.0

Examples

-- Read data from the socket, ctrl is returned by socket.create, please refer demo/socket
local buff = zbuff.create(2048)
local succ, data_len, remote_ip, remote_port = socket.rx(ctrl, buff)

-- Limit Read Length, 2024.1.5 New
-- Attention
-- If it is UDP data, if the limit is less than the length of the UDP packet, only the first limit bytes will be taken and the remaining data will be discarded.
-- If it is TCP data, if there is any remaining data, it will not be discarded and can continue to be read..
-- New EVENT data is generated only when new data arrives. Data that has not been read will not trigger a new EVENT event.
local succ, data_len, remote_ip, remote_port = socket.rx(ctrl, buff, 1500)

-- Read buffer size, added in 2024.1.5. Note that the old version of firmware will report an error if it does not pass buff parameters.
-- For TCP data, the total length of the data to be read is returned here.
-- For UDP data, the length of a single UDP packet is returned here
local succ, data_len = socket.rx(ctrl)
if succ then
    log.info("Length of data to be charged", data_len)
end

---

socket.read(netc, len)

Read data (non-zbuff version)

Parameters

Incoming Value Type	Explanation
userdata	socket.create obtained ctrl
int	Limit the length of read data, optional, not to pass is to read all

Return Value

return value type	explanation
boolean	Read success or not
string	Data read, valid only if read successfully
string	The IP address of the other party is valid only when the reading is successful and UDP communication is performed.
int	Opposite port, valid only for read success and UDP traffic

Examples

-- This function was added in 2024.4.8 to easily read small data.
-- Please give priority to the socket.rx function, which is mainly used for flexible calls when the firmware does not contain the zbuff library.
local ok, data = socket.read(netc, 1500)
if ok and #data > 0 then
    log.info("Read data", data)
end

---

socket.wait(ctrl)

Wait for a new socket message. After the connection is successful and the data is sent successfully, use one time to switch the network state to receiving new data.

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to see the next return value, if false, follow-up close
boolean	true There is new data to receive, false no data, and then the socket.EVENT message needs to be received.

Examples

local succ, result = socket.wait(ctrl)

---

socket.listen(ctrl)

Start listening as a server

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to see the next return value, if false, follow-up close
boolean	true It has been connect,false is not connect, and socket.ON_LINE message needs to be received later.

Examples

local succ, result = socket.listen(ctrl)

---

socket.accept(ctrl)

As the server receives a new client, note that if the hardware protocol stack similar to W5500 does not support 1-to-many, the second parameter is not required.

Parameters

Incoming Value Type	Explanation
user_data	socket.create Get ctrl, here is the server side
string	or function or nil string is the taskName of the message notification, and the function is the callback function, which is the same as the socket.create parameter.

Return Value

return value type	explanation
boolean	true No exception occurred, false failed, if false, you don’t need to see the next return value, if false, follow-up close
user_data	or nil If 1-to-many is supported, a new ctrl will be returned, automatically create, if not supported, return nil

Examples

local succ, new_netc = socket.listen(ctrl, cb)

---

socket.state(ctrl)

Get the current state of the socket

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

return value type	explanation
int	or nil,If the input parameter is correct, return the value of the status, otherwise return nil
string	or nil,If the input parameters are correct, return the Chinese description of the status, otherwise return nil

Examples

local state, str = socket.state(ctrl)
log.info("state", state, str)
state    0    "Hardware Offline",
        1    "Offline",
        2    "Wait DNS",
        3    "Connecting",
        4    "TLS handshake in progress",
        5    "Online",
        6    "In listening",
        7    "Offline",
        8    "Unknown"

---

socket.release(ctrl)

Active release network_ctrl

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

None

Examples

-- It can no longer be used after release.
socket.release(ctrl)

---

socket.setDNS(adapter_index, dns_index, ip)

Set up the DNS server

Parameters

Incoming Value Type	Explanation
int	The adapter serial number can only be socket.ETH0,socket.STA,socket.AP. If it is not filled in, the last registered adapter will be selected.
int	dns Server sequence number, starting from 1
string	or int dns，If it is IPV4, it can be an int value in big-end format.

Return Value

return value type	explanation
boolean	Returns true on success and true on failure false

Examples

-- Set the DNS configuration for the default network adapter
socket.setDNS(nil, 1, "114.114.114.114")
-- Set up DNS configuration for your network adapter
socket.setDNS(socket.ETH0, 1, "114.114.114.114")

---

socket.sslLog(log_level)

Set log registration for SSL

Parameters

Incoming Value Type	Explanation
int	mbedtls log Grade

Return Value

return value type	explanation
nil	No return value

Examples

--[[
SSL/TLS log Level Description
0 Don't Print
1 Print errors and alarms only
2 Mostly info
3 and more than 3 detailed debug

Too much information can cause memory fragmentation
]]
-- Print most info logs
socket.sslLog(2)

---

socket.adapter(index)

Viewing the Networking Status of a NIC Adapter

Parameters

Incoming Value Type

Explanation

int

The serial number of the adapter to be viewed can be left blank and all network cards will be viewed until IP READY is encountered. If the network card is specified, it can only be socket.ETH0 (external Ethernet),socket.LWIP_ETH (internal Ethernet),socket.LWIP_STA (STA with internal WIFI),socket.LWIP_AP (AP with internal WIFI),socket.LWIP_GP (GPRS with internal cellular network),socket.USB (external USB network card）

Return Value

return value type	explanation
boolean	Whether the checked adapter is IP READY,true indicates that it is ready for networking, false temporarily cannot be networked
int	Last viewed adapter serial number

Examples

-- Check all network cards until you find one that is IP READY
local isReady,index = socket.adapter() --If the isReady is true, index is the NIC adapter serial number of IP READY
--Check if an external Ethernet (such as W5500)IP READY
local isReady,default = socket.adapter(socket.ETH0)

---

socket.remoteIP(ctrl)

Get peer ip

Parameters

Incoming Value Type	Explanation
user_data	socket.create obtained ctrl

Return Value

return value type	explanation
string	IP1，If the value is nil, the IP address is not obtained.
string	IP2，If nil, it means no IP2
string	IP3，If nil, it means no IP3
string	IP4，If nil, it means no IP4

Examples

-- Note: It can only be obtained after receiving the socket.ON_LINE message, returning up to 4 IP。
-- socket.connect If the remote_port is set to 0, the socket.ON_LINE message will be returned when DNS is completed.
local ip1,ip2,ip3,ip4 = socket.remoteIP(ctrl)

---