Network services

Lua RTOS has support for the following network services:

• SNTP
• HTTP/HTTPS
• Telnet
• Captive DNS
• MDNS

SNTP

This service can be used by the programmer for get the current time from a NTP server and update the internal Lua RTOS clock with this time.

For start this service:

-- Setup and start an ethernet connection
net.en.setup()
net.en.start()

-- Sync Lua RTOS clock with an NTP server
net.service.sntp.start()

The net.service.sntp.start accepts an optional argument to set the NTP server name to use. If this argument is not provided the NTP server name is set to "pool.ntp.org".

For stop this service:

net.service.sntp.stop()

HTTP/HTTPS

This service can be started to serve files via the http:// and https:// protocol. For security reasons the document root is configured at compile time. If a http request doesn't point to a file but a directory then that directory is searched for a file named index.lua or index.html. If one of those is found the file is served, if none is found a directory listing is generated. So if you don't want a folder listing e.g. in /images make sure you got an empty index.html there. If a file is requested that ends on .lua then that file is being executed as a dynamic lua page before it is served to the client.

To start this service:

-- Setup and start an ethernet connection
net.en.setup()
net.en.start()

-- Start HTTP server
net.service.http.start()

-- Start the HTTP server on a non-standard port
net.service.http.start(81)

-- Start the HTTP Server with HTTPS on port 443
net.service.http.start(80, 443, "/path/to/certificate.pem", "/path/to/privatekey.pem")

-- Start the HTTP Server with HTTPS on port 443 but do not serve HTTP
net.service.http.start(0, 443, "/path/to/certificate.pem", "/path/to/privatekey.pem")

To stop this service:

net.service.http.stop()

To check the status of this service:

net.service.http.running()

Variables available to dynamic lua pages:

http_method -- this is one of GET / POST / HEAD
http_uri -- contains the requested URI
http_request -- contains the post or get data sent with the request
http_cookies -- contains the cookies sent with the request
http_language -- contains the client's accept-language
http_agent -- containsthe client's user agent
http_port -- contains the server's port used
http_secure -- this is whether the connection was done securely with ssl "1" or insecure with http only "0"
http_remote_addr -- contains the client's ip address
http_remote_port -- contains the client's port used
http_script_name -- contains the /path/to/filename.lua of the lua script being executed

Telnet

This service can be started to serve content via a simple telnet-like protocol. The client connects to the server and sends one or more commands. The server can send one or more responses per command. For each single command the client sends, a user-supplied lua callback-function will be executed - see below.

To start this service:

-- this function is called for each command received from the client
function telnet_receive(client, command)
	-- the parameter 'client' contains the client's IP address
	local print = net.service.telnet.print
	print("you entered: "..command.."\n") --note: this is sent directly to the client
end

if net.service.telnet then
	net.service.telnet.start(23, telnet_receive)
end

To stop this service:

net.service.telnet.stop()

To check the status of this service:

net.service.telnet.running()

Extended use possibilities:

By using this service, it's easy to resemble various "telnet-like" clear-text protocols like, e.g. AVR-NET-IO For more information about AVR-NET-IO see http://www.gtkdb.de/index_18_1032.html for a description of the protocol and the original hardware that it was designed for.

Captive DNS

This service can be started to serve fake DNS answers to queries from other devices. That is useful if the Lua RTOS device creates a wifi AP and clients need to connect to the device e.g. to configure the actual wifi settings via a web browser. The Captive DNS service helps by automatically redirecting all name resolution to the Lua RTOS device's local ip in the same way as standard Captive Wifi logon portals do. Instead of providing a website with an "accept" button as usual captive portals (do for legal reasons) the Lua RTOS device can use the HTTP service with lua scripts to e.g. present a Lua RTOS device configuration form. For most operating systems the form will open automatically on the client device once it has connected to the AP.

To start this service:

-- Setup and start an ethernet connection
net.en.setup()
net.en.start()

-- Start HTTP server
net.service.http.start()

-- Start the Captive DNS service
net.service.captivedns.start()

To stop this service:

net.service.captivedns.stop()

To check the status of this service:

net.service.captivedns.running()

MDNS

This service adds support for Multicast DNS. MDNS service is configured on a per-interface basis.

net.service.mdns.start([hostname [, instancename]])

To start this service:

net.service.mdns.start("ESP32")

To stop this service:

net.service.mdns.stop()

To check the status of this service:

net.service.mdns.running()

To find a device by hostname:

results = net.service.mdns.resolvehost(hostname [, timeout_seconds])

To find a device by service type:

service = "_http"
protocol = "_tcp"
results = net.service.mdns.findservice(service, protocol [, timeout_seconds])

To make the Lua RTOS device itself advertise a service:

service = "_http"
protocol = "_tcp"
port = 80
instancename = "ESP WebServer"
net.service.mdns.addservice(service, protocol, port [, instancename [, txt_table]])

To make the Lua RTOS device itself no longer advertise a previously added service:

service = "_http"
protocol = "_tcp"
net.service.mdns.removeservice(service, protocol)