Add read with timeout to uart driver

Adds a new uart:read/2 that takes a timeout parameter for reads. If no data is received during the
timeout period `timeout` is returned, and the listener is removed allowing for another read without
getting the `{error, ealready}` error tuple.

Closes #1446

Signed-off-by: Winford <winford@object.stream>

Author: UncleGrumpy

CHANGELOG.md

@@ -13,6 +13,7 @@ with nodejs and emscripten)
 - Added preliminary support for ESP32P4 (no networking support yet).
 - Added memory info in `out_of_memory` crash logs to help developers fix memory issues.
 - Added documentation and function specs for uart driver
+- Added `uart:read/2` with a timeout parameter.
 
 ### Fixed
 

libs/eavmlib/src/uart.erl

@@ -19,7 +19,7 @@
 %
 
 -module(uart).
--export([open/1, open/2, close/1, read/1, write/2]).
+-export([open/1, open/2, close/1, read/1, read/2, write/2]).
 
 -type peripheral() :: string() | binary().
 % The peripheral `Name' may be one of: `"UART0"' | `"UART1"' | `"UART2"' | `<<"UART0">>' | `<<"UART1">>' | `<<"UART2">>'.
@@ -104,6 +104,42 @@ close(Pid) when is_pid(Pid) ->
 read(Pid) when is_pid(Pid) ->
     port:call(Pid, read).
 
+%%-----------------------------------------------------------------------------
+%% @param   Pid of the uart port to be read
+%% @param   Timeout millisecond to wait for data to become available
+%% @returns `{ok, Data}', or `{error, Reason}'
+%% @doc     Read data from a UART port
+%%
+%%          This function will return any data that is available within the
+%%          timeout period to the process. After the timeout has expired a new
+%%          read command may be used regardless of whether the last read was
+%%          sent a payload.
+%%          Example:
+%%          ```
+%%          Data = case uart:read(Uart, 3000) of
+%%              {ok, Bin} -> Bin;
+%%              {error, timeout} -> <<"">>;
+%%              Error -> error_handler_fun(Uart, Error)
+%%          end,
+%%          '''
+%%          Any data sent to the esp32 over uart between reads with a timeout will
+%%          be lost, so be sure this is what you want. Most applications will want
+%%          a single process to read from UART and continue to listen until a payload
+%%          is received, and likely pass the payload off for processing and
+%%          immediately begin another read.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec read(Pid :: pid(), Timeout :: pos_integer()) ->
+    {ok, Data :: iodata()} | {error, _Reason :: term()}.
+read(Pid, Timeout) when is_pid(Pid) ->
+    case port:call(Pid, read, Timeout) of
+        {error, timeout} ->
+            port:call(Pid, cancel_read),
+            {error, timeout};
+        Result ->
+            Result
+    end.
+
 %%-----------------------------------------------------------------------------
 %% @param   Pid of the uart port to be written to
 %% @param   Data to be written to the given uart port

src/platforms/esp32/components/avm_builtins/uart_driver.c

@@ -103,6 +103,7 @@ static const AtomStringIntPair cmd_table[] = {
     { ATOM_STR("\x4", "read"), UARTReadCmd },
     { ATOM_STR("\x5", "write"), UARTWriteCmd },
     { ATOM_STR("\x5", "close"), UARTCloseCmd },
+    { ATOM_STR("\xB", "cancel_read"), UARTCancelCmd },
     SELECT_INT_DEFAULT(UARTInvalidCmd)
 };
 
@@ -394,6 +395,23 @@ static void uart_driver_do_read(Context *ctx, GenMessage gen_message)
     }
 }
 
+static void uart_driver_do_cancel_read(Context *ctx, GenMessage gen_message)
+{
+    struct UARTData *uart_data = ctx->platform_data;
+
+    safe_update_reader_data(uart_data, NO_READER, NO_REF);
+
+    term pid = gen_message.pid;
+    term ref = gen_message.ref;
+
+    if (UNLIKELY(memory_ensure_free_with_roots(ctx, TUPLE_SIZE(2), 1, &ref, MEMORY_CAN_SHRINK) != MEMORY_GC_OK)) {
+        ESP_LOGE(TAG, "[uart_driver_do_read] Failed to allocate space for return value");
+        globalcontext_send_message(ctx->global, term_to_local_process_id(pid), OUT_OF_MEMORY_ATOM);
+    }
+
+    port_send_reply(ctx, pid, ref, OK_ATOM);
+}
+
 static void uart_driver_do_write(Context *ctx, GenMessage gen_message)
 {
     GlobalContext *glb = ctx->global;
@@ -533,6 +551,11 @@ static NativeHandlerResult uart_driver_consume_mailbox(Context *ctx)
                 is_closed = true;
                 break;
 
+            case UARTCancelCmd:
+                TRACE("cancel_read\n");
+                uart_driver_do_cancel_read(ctx, gen_message);
+                break;
+
             default:
                 TRACE("uart: error: unrecognized command.\n");
         }