LuaSocket: Serial port support

From 70f7800986812ad0d1a5dd6f280f66fd2bf1dd12 Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Tue, 1 Sep 2026 10:00:21 +0200 Subject: docs: document socket.unix and socket.serial, fix stale/missing API references Pre-release documentation audit against master. Adds the two fully undocumented modules and closes gaps found by diffing every docs/*.html page against its corresponding source: - New docs/unix.html and docs/serial.html (socket.unix stream/dgram and socket.serial were never documented), linked from index.html, introduction.html, socket.html and reference.html. serial.html notes the current lack of a baud/parity/flow-control API and includes an os.execute+stty workaround example. Both note Windows is unsupported. - socket.html: document headers.setcanonic, point to unix/serial modules. - tcp.html: document getfamily, setpeername/setsockname aliases. - udp.html: document getfamily, getfd/setfd, dirty; document the ipv6-multicast-hops/ipv6-unicast-hops aliasing as current (known-buggy) behavior rather than the originally intended semantics. - http.html: correct redirect text (301/302/303/307/308, was 301/302 only); document MAXHEADERLINE/MAXHEADERSIZE. - dns.html: document getnameinfo. - ltn12.html: document source.rewind and BLOCKSIZE. - installation.html: fix stale "LuaSocket 3.0" sample output to 3.1.0. - reference.html: index every anchor added above plus new Unix/Serial blocks. --- docs/serial.html | 308 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 docs/serial.html (limited to 'docs/serial.html') diff --git a/docs/serial.html b/docs/serial.html new file mode 100644 index 0000000..8e123b0 --- /dev/null +++ b/docs/serial.html @@ -0,0 +1,308 @@ + + + + + + +LuaSocket: Serial port support + + + + + + + + + + + +

Serial port support

+ +

+The socket.serial module opens a serial device (e.g. +/dev/ttyUSB0) and exposes it through the same buffered, +timeout-aware send/receive interface used by +TCP and Unix domain +stream objects. +

+ +

+Note: This module is only built on Unix-like platforms (Linux, macOS, +BSD, Haiku). It is not available on Windows. +

+ +

+Serial port support is a separate module that must be required +explicitly. Unlike most other LuaSocket modules, it returns a +function directly — the constructor — rather than a +table of functions: +

+ +

+-- loads the socket.serial module; note this is the constructor itself
+local serial_open = require("socket.serial")
+
+-- open the device
+local port = assert(serial_open("/dev/ttyUSB0"))
+port:settimeout(1)
+assert(port:send("AT\r\n"))
+print(port:receive())
+port:close()
+

+ +

+Note: There is currently no API to configure the serial line itself +— baud rate, parity, data/stop bits or flow control. The device +is opened non-blocking with whatever settings the OS driver or a prior +external configuration (e.g. stty) left it in. This is a known +current limitation of the module, not a deliberate protection against +misuse; a future version may add a setoption-style API for these +settings the way tcp:setoption +does for TCP. +

+ +

+Until such an API exists, the workaround is to configure the line with +the platform's own stty utility (via os.execute) +before opening the device with socket.serial: +

+ +

+local serial_open = require("socket.serial")
+
+local dev = "/dev/ttyUSB0"
+
+-- Linux: stty -F <device> ...
+local ok = os.execute(string.format(
+    "stty -F %s 115200 cs8 -cstopb -parenb raw -echo", dev))
+
+-- macOS/BSD use -f instead of -F:
+-- os.execute(string.format("stty -f %s 115200 cs8 -cstopb -parenb raw -echo", dev))
+
+assert(ok, "failed to configure serial line with stty")
+
+local port = assert(serial_open(dev))
+port:settimeout(1)
+assert(port:send("AT\r\n"))
+print(port:receive())
+port:close()
+

+ +

+Note: raw -echo puts the line in raw mode, which matters for +LuaSocket's framing: without it, the TTY driver applies its own line +editing/echo, which can interfere with receive +patterns and send content. Adjust the +stty flags (baud rate, parity, stop bits, flow control) to match +your device; consult man stty for the full option set on your +platform, since flag names and defaults vary between Linux, macOS and the +BSDs. +

+ + + +

+port:close() +

+ +

+Closes a serial object. No further operations (except further calls to +close) are allowed on a closed object. +

+ +

+Note: Garbage-collected objects are automatically closed before +destruction. +

+ + + +

+port:dirty() +

+ +

+Check the read buffer status. +

+ +

+Returns true if there is any data in the read buffer, +false otherwise. +

+ +

+Note: This is an internal method, use at your own risk. +

+ + + +

+port:getfd() +

+ +

+Returns the underlying file descriptor associated to the object. +

+ +

+The descriptor. +

+ +

+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +

+ + + +

+port:getstats() +

+ +

+Returns accounting information on the port, useful for throttling of +bandwidth. Works exactly like +tcp:getstats. +

+ +

+The method returns the number of bytes received, the number of bytes +sent, and the age of the object in seconds. +

+ + + +

+port:receive([pattern [, prefix [, maxsize]]]) +

+ +

+Reads data from the serial port, according to the specified read +pattern. Works exactly like +tcp:receive, including the +*a/*l/number patterns and the +prefix/maxsize parameters. +

+ + + +

+port:send(data [, i [, j]]) +

+ +

+Sends data through the serial port. Works exactly like +tcp:send, including the optional +i/j substring selection. +

+ + + +

+port:setfd(fd) +

+ +

+Sets the underlying file descriptor associated to the object. The current +one is simply replaced, not closed, and no other change to the object +state is made. +

+ +

+No return value. +

+ +

+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +

+ + + +

+port:setstats(received, sent, age) +

+ +

+Resets accounting information on the port, useful for throttling of +bandwidth. Works exactly like +tcp:setstats. +

+ +

+The method returns 1 in case of success and nil otherwise. +

+ + + +

+port:settimeout(value [, mode]) +

+ +

+Changes the timeout values for the object. Works exactly like +tcp:settimeout, including the +'b' (block) and 't' (total) modes. +

+ + + +

+serial_open(path) +

+ +

+Opens the serial device at path and returns a serial object. +This is the value returned directly by require("socket.serial") +— there is no separate module table to index into, unlike +socket.unix.stream() or socket.tcp(). +

+ +

+Path is a string with the device path (e.g. +"/dev/ttyUSB0" or "/dev/ttyS0"). +

+ +

+In case of success, a new serial object is returned. In case of error, +the function returns nil, followed by an error message, +followed by the numeric errno value. +

+ + + + + + + -- cgit v1.2.3-55-g6feb