From 33eae0c30d49bbe480056d0076dadc068633de63 Mon Sep 17 00:00:00 2001 From: Martin Lund Date: Sun, 28 Apr 2024 14:46:41 +0200 Subject: [PATCH] Update script API --- README.md | 84 ++++++++++++++++++++++++++++------------------------ man/tio.1.in | 11 ++++++- src/script.c | 10 ++----- 3 files changed, 59 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 3daa7fe..c182872 100644 --- a/README.md +++ b/README.md @@ -371,63 +371,71 @@ Tio suppots Lua scripting to easily automate interaction with the tty device. In addition to the Lua API tio makes the following functions available: ``` - expect(string, timeout) - Expect string - waits for string to match or timeout before continueing. +expect(string, timeout) + Expect string - waits for string to match or timeout before continueing. + Supports regular expressions. Special characters must be escaped with '\\'. + Timeout is in milliseconds, defaults to 0 meaning it will wait forever. - Supports regular expressions. Special characters must be escaped with '\\'. + Returns 1 on successful match, 0 on timeout, or -1 on error. - Timeout is in milliseconds, defaults to 0 meaning it will wait forever. + On successful match it also returns the match string as second return value. - send(string) - Send string. +send(string) + Send string. - modem_send(file, protocol) - Send file using x/y-modem protocol. + Returns number of bytes written on success or -1 on error. - Protocol can be any of XMODEM_1K, XMODEM_CRC, YMODEM. +modem_send(file, protocol) + Send file using x/y-modem protocol. - tty_search() - Search for serial devices. + Protocol can be any of XMODEM_1K, XMODEM_CRC, YMODEM. - Returns a table of number indexed tables, one for each serial device - found. Each of these tables contains the serial device information accessible - via the following string indexed elements "path", "tid", "uptime", "driver", - "description". +tty_search() + Search for serial devices. - Returns nil if no serial devices are found. + Returns a table of number indexed tables, one for each serial device + found. Each of these tables contains the serial device information accessible + via the following string indexed elements "path", "tid", "uptime", "driver", + "description". - exit(code) - Exit with code. + Returns nil if no serial devices are found. - high(line) - Set tty line high. +read(size, timeout) + Read from serial device. If timeout is 0 or not provided it will wait + forever until data is ready to read. - low(line) - Set tty line low. + Returns number of bytes read on success, 0 on timeout, or -1 on error. - toggle(line) - Toggle the tty line. +exit(code) + Exit with exit code. - sleep(seconds) - Sleep for seconds. +high(line) + Set tty line high. - msleep(ms) - Sleep for milliseconds. +low(line) + Set tty line low. - config_high(line) - Set tty line state configuration to high. +toggle(line) + Toggle the tty line. - config_low(line) - Set tty line state configuration to low. +sleep(seconds) + Sleep for seconds. - apply_config() - Apply tty line state configuration. +msleep(ms) + Sleep for miliseconds. - Using the line state configuration API instead of high()/low() will - help to make the lines physically switch as simultaneously as possible. - This may solve timing issues on some platforms. +config_high(line) + Set tty line state configuration to high. - Note: Line can be any of DTR, RTS, CTS, DSR, CD, RI +config_low(line) + Set tty line state configuration to low. + +apply_config() + Apply tty line state configuration. Using the line state configuration + API instead of high()/low() will help to make the lines physically switch as + simultaneously as possible. This may solve timing issues on some platforms. + +Note: Line can be any of DTR, RTS, CTS, DSR, CD, RI ``` ### 3.4 Configuration file diff --git a/man/tio.1.in b/man/tio.1.in index 75d05bb..87d5180 100644 --- a/man/tio.1.in +++ b/man/tio.1.in @@ -427,12 +427,15 @@ Expect string - waits for string to match or timeout before continueing. Supports regular expressions. Special characters must be escaped with '\\\\'. Timeout is in milliseconds, defaults to 0 meaning it will wait forever. -Returns 1 on successful match, 0 on timeout, or -1 on invalid regular expression. +Returns 1 on successful match, 0 on timeout, or -1 on error. On successful match it also returns the match string as second return value. .IP "\fBsend(string)" Send string. + +Returns number of bytes written on success or -1 on error. + .IP "\fBmodem_send(file, protocol)" Send file using x/y-modem protocol. @@ -448,6 +451,12 @@ following string indexed elements "path", "tid", "uptime", "driver", Returns nil if no serial devices are found. +.IP "\fBread(size, timeout)" +Read from serial device. If timeout is 0 or not provided it will wait forever +until data is ready to read. + +Returns number of bytes read on success, 0 on timeout, or -1 on error. + .IP "\fBexit(code)" Exit with exit code. .IP "\fBhigh(line)" diff --git a/src/script.c b/src/script.c index f998d40..571c58c 100644 --- a/src/script.c +++ b/src/script.c @@ -211,10 +211,6 @@ static int send(lua_State *L) } ret = write(device_fd, string, strlen(string)); - if (ret < 0) - { - tio_error_print("%s\n", strerror(errno)); - } lua_pushnumber(L, ret); @@ -281,7 +277,7 @@ static int read_string(lua_State *L) char *buffer = malloc(size); if (buffer == NULL) { - ret = -3; // Read buffer allocation failed + ret = -1; // Error goto error; } @@ -293,12 +289,12 @@ static int read_string(lua_State *L) ssize_t bytes_read = read_poll(device_fd, buffer, size, timeout); if (bytes_read < 0) { - ret = -1; // Read error + ret = -1; // Error goto error; } else if (bytes_read == 0) { - ret = -2; // Timeout + ret = 0; // Timeout goto error; }