pybricks.tools: Add read_input_byte() function.

This adds a new non-blocking function to read one byte from stdin. This
is needed since there is no other way to read from stdin on the Move
hub. It is also useful on other hubs as it eliminates the need to
use poll() to avoid blocking reads.

Fixes: pybricks/support#1102

Author: dlech

CHANGELOG.md

@@ -7,6 +7,7 @@
 ### Added
 - Added `'modes'` entry to the dictionary returned by `PUPDevice.info()`. It
   is a tuple of `(name, num_values, data_type)` tuples for each available mode.
+- Added `pybricks.tools.read_input_byte()` function ([support#1102]).
 
 ### Changed
 - Changed internal drivers for LEGO devices (motors and sensors) on all platforms.
@@ -17,6 +18,7 @@
 
 [support#1095]: https://github.com/pybricks/support/issues/1095
 [support#1098]: https://github.com/pybricks/support/issues/1098
+[support#1102]: https://github.com/pybricks/support/issues/1102
 
 ## [3.3.0b6] - 2023-06-02
 

bricks/ev3dev/Makefile

@@ -311,6 +311,9 @@ test: $(BUILD)/$(PROG) $(TOP)/tests/run-tests.py $(GRX_TEST_PLUGIN_LIB)
 		GRX_PLUGIN_PATH=$(realpath $(BUILD)) GRX_DRIVER=test \
 		./run-tests.py
 
+repl: $(BUILD)/$(PROG) $(GRX_TEST_PLUGIN_LIB) modules/core.py
+	GRX_PLUGIN_PATH=$(realpath $(BUILD)) GRX_DRIVER=test $< -i modules/core.py
+
 # Value of configure's --host= option (required for cross-compilation).
 # Deduce it from CROSS_COMPILE by default, but can be overridden.
 ifneq ($(CROSS_COMPILE),)

bricks/ev3dev/ev3dev_mphal.c

@@ -26,11 +26,14 @@
 
 #include <assert.h>
 #include <errno.h>
+#include <poll.h>
 #include <time.h>
 #include <sys/time.h>
+#include <unistd.h>
 
 #include "py/mphal.h"
 #include "py/runtime.h"
+#include "py/stream.h"
 
 void mp_hal_stdout_tx_flush(void) {
     // currently not buffered
@@ -55,3 +58,26 @@ void pb_ev3dev_hal_delay_ms(mp_uint_t ms) {
         break;
     }
 }
+
+uintptr_t mp_hal_stdio_poll(uintptr_t flags) {
+    struct pollfd fds[] = {
+        { .fd = STDIN_FILENO, .events = flags & MP_STREAM_POLL_RD ? POLLIN : 0, },
+        { .fd = STDOUT_FILENO, .events = flags & MP_STREAM_POLL_WR ? POLLOUT : 0, },
+    };
+    int ret;
+
+    MP_HAL_RETRY_SYSCALL(ret, poll(fds, MP_ARRAY_SIZE(fds), 0), mp_raise_OSError(err));
+
+    uintptr_t rflags = 0;
+
+    if (ret > 0) {
+        if (fds[0].revents & POLLIN) {
+            rflags |= MP_STREAM_POLL_RD;
+        }
+        if (fds[1].revents & POLLOUT) {
+            rflags |= MP_STREAM_POLL_WR;
+        }
+    }
+
+    return rflags;
+}

bricks/ev3dev/modules/core.py

@@ -9,7 +9,7 @@
     GyroSensor,
 )
 from pybricks.parameters import Port, Stop, Direction, Button, Color
-from pybricks.tools import wait, StopWatch, DataLog
+from pybricks.tools import read_input_byte, wait, StopWatch, DataLog
 from pybricks.robotics import DriveBase
 from pybricks.media.ev3dev import ImageFile, SoundFile
 

bricks/virtualhub/mp_port.c

@@ -3,12 +3,14 @@
 
 // MicroPython port-specific implementation hooks
 
+#include <poll.h>
 #include <pthread.h>
 #include <signal.h>
 #include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/select.h>
+#include <unistd.h>
 
 #include <contiki.h>
 
@@ -25,6 +27,7 @@
 #include "py/objstr.h"
 #include "py/objtuple.h"
 #include "py/runtime.h"
+#include "py/stream.h"
 
 #include "pybricks/util_pb/pb_error.h"
 #include <pybricks/common.h>
@@ -140,3 +143,26 @@ void pb_virtualhub_delay_us(mp_uint_t us) {
         pb_virtualhub_poll();
     }
 }
+
+uintptr_t mp_hal_stdio_poll(uintptr_t flags) {
+    struct pollfd fds[] = {
+        { .fd = STDIN_FILENO, .events = flags & MP_STREAM_POLL_RD ? POLLIN : 0, },
+        { .fd = STDOUT_FILENO, .events = flags & MP_STREAM_POLL_WR ? POLLOUT : 0, },
+    };
+    int ret;
+
+    MP_HAL_RETRY_SYSCALL(ret, poll(fds, MP_ARRAY_SIZE(fds), 0), mp_raise_OSError(err));
+
+    uintptr_t rflags = 0;
+
+    if (ret > 0) {
+        if (fds[0].revents & POLLIN) {
+            rflags |= MP_STREAM_POLL_RD;
+        }
+        if (fds[1].revents & POLLOUT) {
+            rflags |= MP_STREAM_POLL_WR;
+        }
+    }
+
+    return rflags;
+}

bricks/virtualhub/mpvarianthal.h

@@ -32,7 +32,7 @@
 
 void mp_hal_set_interrupt_char(char c);
 
-#define mp_hal_stdio_poll unused // this is not implemented, nor needed
+uintptr_t mp_hal_stdio_poll(uintptr_t);
 void mp_hal_stdio_mode_raw(void);
 void mp_hal_stdio_mode_orig(void);
 

pybricks/tools/pb_module_tools.c

@@ -10,6 +10,7 @@
 #include "py/mphal.h"
 #include "py/objmodule.h"
 #include "py/runtime.h"
+#include "py/stream.h"
 
 #include <pbio/int_math.h>
 
@@ -83,6 +84,24 @@ STATIC mp_obj_t pb_module_tools_wait(size_t n_args, const mp_obj_t *pos_args, mp
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pb_module_tools_wait_obj, 0, pb_module_tools_wait);
 
+/**
+ * Reads one byte from stdin without blocking.
+ *
+ * @returns The integer value of the byte read or @c None if no data is available.
+ */
+STATIC mp_obj_t pb_module_tools_read_input_byte(void) {
+    if (!(mp_hal_stdio_poll(MP_STREAM_POLL_RD) & MP_STREAM_POLL_RD)) {
+        // No bytes available.
+        return mp_const_none;
+    }
+
+    // REVISIT: In theory, this should not block if mp_hal_stdio_poll() and
+    // mp_hal_stdin_rx_chr() are implemented correctly and nothing happens
+    // in a thread/interrupt/kernel that changes the state.
+    return MP_OBJ_NEW_SMALL_INT(mp_hal_stdin_rx_chr());
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(pb_module_tools_read_input_byte_obj, pb_module_tools_read_input_byte);
+
 STATIC mp_obj_t pb_module_tools_run_task(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     PB_PARSE_ARGS_FUNCTION(n_args, pos_args, kw_args,
         PB_ARG_REQUIRED(task),
@@ -127,6 +146,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pb_module_tools_run_task_obj, 1, pb_module_too
 STATIC const mp_rom_map_elem_t tools_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__),    MP_ROM_QSTR(MP_QSTR_tools)                    },
     { MP_ROM_QSTR(MP_QSTR_wait),        MP_ROM_PTR(&pb_module_tools_wait_obj)         },
+    { MP_ROM_QSTR(MP_QSTR_read_input_byte), MP_ROM_PTR(&pb_module_tools_read_input_byte_obj) },
     { MP_ROM_QSTR(MP_QSTR_run_task),    MP_ROM_PTR(&pb_module_tools_run_task_obj)     },
     { MP_ROM_QSTR(MP_QSTR_StopWatch),   MP_ROM_PTR(&pb_type_StopWatch)                },
     { MP_ROM_QSTR(MP_QSTR_multitask),   MP_ROM_PTR(&pb_type_Task)                     },