micropython · dpgeorge · Aug 29, 2024 · Feb 20, 2024 · Feb 22, 2024 · Sep 24, 2023
diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst
@@ -152,31 +152,6 @@ Methods
    Send a break condition on the bus. This drives the bus low for a duration
    longer than required for a normal transmission of a character.
 
-.. method:: UART.irq(trigger, priority=1, handler=None, wake=machine.IDLE)
-
-   Create a callback to be triggered when data is received on the UART.
-
-       - *trigger* can only be ``UART.RX_ANY``
-       - *priority* level of the interrupt. Can take values in the range 1-7.
-         Higher values represent higher priorities.
-       - *handler* an optional function to be called when new characters arrive.
-       - *wake* can only be ``machine.IDLE``.
-
-   .. note::
-
-      The handler will be called whenever any of the following two conditions are met:
-
-          - 8 new characters have been received.
-          - At least 1 new character is waiting in the Rx buffer and the Rx line has been
-            silent for the duration of 1 complete frame.
-
-      This means that when the handler function is called there will be between 1 to 8
-      characters waiting.
-
-   Returns an irq object.
-
-   Availability: WiPy.
-
 .. method:: UART.flush()
 
    Waits until all data has been sent. In case of a timeout, an exception is raised. The timeout
@@ -203,11 +178,85 @@ Methods
 
    Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra
 
+.. method:: UART.irq(handler=None, trigger=0, hard=False)
+
+   Configure an interrupt handler to be called when a UART event occurs.
+
+   The arguments are:
+
+     - *handler* is an optional function to be called when the interrupt event
+       triggers.  The handler must take exactly one argument which is the
+       ``UART`` instance.
+
+     - *trigger* configures the event(s) which can generate an interrupt.
+       Possible values are a mask of one or more of the following:
+
+       - ``UART.IRQ_RXIDLE`` interrupt after receiving at least one character
+         and then the RX line goes idle.
+       - ``UART.IRQ_RX`` interrupt after each received character.
+       - ``UART.IRQ_TXIDLE`` interrupt after or while the last character(s) of
+         a message are or have been sent.
+       - ``UART.IRQ_BREAK`` interrupt when a break state is detected at RX
+
+     - *hard* if true a hardware interrupt is used.  This reduces the delay
+       between the pin change and the handler being called. Hard interrupt
+       handlers may not allocate memory; see :ref:`isr_rules`.
+
+   Returns an irq object.
+
+   Due to limitations of the hardware not all trigger events are available on all ports.
+
+   .. table:: Availability of triggers
+      :align: center 
+
+      ============== ========== ====== ========== =========
+      Port / Trigger IRQ_RXIDLE IRQ_RX IRQ_TXIDLE IRQ_BREAK
+      ============== ========== ====== ========== =========
+      CC3200                      yes
+      ESP32            yes        yes                yes
+      MIMXRT           yes                yes
+      NRF                         yes     yes
+      RENESAS-RA       yes        yes
+      RP2              yes                yes        yes
+      SAMD             yes        yes     yes
+      STM32            yes        yes
+      ============== ========== ====== ========== =========
+
+
+   .. note::
+     - The ESP32 port does not support the option hard=True.
+
+     - The rp2 port's UART.IRQ_TXIDLE is only triggered when the message
+       is longer than 5 characters and the trigger happens when still 5 characters
+       are to be sent.
+
+     - The rp2 port's UART.IRQ_BREAK needs receiving valid characters for triggering
+       again.
+
+     - The SAMD port's UART.IRQ_TXIDLE is triggered while the last character is sent.
+
+     - On STM32F4xx MCU's, using the trigger UART.IRQ_RXIDLE the handler will be called once
+       after the first character and then after the end of the message, when the line is
+       idle.
+
+
+   Availability: cc3200, esp32, mimxrt, nrf, renesas-ra, rp2, samd, stm32.
+
 Constants
 ---------
 
-.. data:: UART.RX_ANY
+.. data:: UART.RTS
+          UART.CTS
+
+    Flow control options.
+
+    Availability: esp32, mimxrt, renesas-ra, rp2, stm32.
+
+.. data:: UART.IRQ_RXIDLE
+          UART.IRQ_RX
+          UART.IRQ_TXIDLE
+          UART.IRQ_BREAK
 
-    IRQ trigger sources
+    IRQ trigger sources.
 
-    Availability: WiPy.
+    Availability: renesas-ra, stm32, esp32, rp2040, mimxrt, samd, cc3200.
diff --git a/ports/cc3200/mods/pybuart.c b/ports/cc3200/mods/pybuart.c
@@ -590,6 +590,7 @@ static const mp_rom_map_elem_t pyb_uart_locals_dict_table[] = {
 
     // class constants
     { MP_ROM_QSTR(MP_QSTR_RX_ANY),      MP_ROM_INT(UART_TRIGGER_RX_ANY) },
+    { MP_ROM_QSTR(MP_QSTR_IRQ_RX),      MP_ROM_INT(UART_TRIGGER_RX_ANY) },
 };
 
 static MP_DEFINE_CONST_DICT(pyb_uart_locals_dict, pyb_uart_locals_dict_table);

diff --git a/ports/esp32/esp32_common.cmake b/ports/esp32/esp32_common.cmake
@@ -32,6 +32,7 @@ list(APPEND MICROPY_SOURCE_SHARED
     ${MICROPY_DIR}/shared/netutils/netutils.c
     ${MICROPY_DIR}/shared/timeutils/timeutils.c
     ${MICROPY_DIR}/shared/runtime/interrupt_char.c
+    ${MICROPY_DIR}/shared/runtime/mpirq.c
     ${MICROPY_DIR}/shared/runtime/stdout_helpers.c
     ${MICROPY_DIR}/shared/runtime/sys_stdio_mphal.c
     ${MICROPY_DIR}/shared/runtime/pyexec.c

diff --git a/ports/esp32/machine_timer.c b/ports/esp32/machine_timer.c
@@ -38,6 +38,7 @@
 #include "hal/timer_hal.h"
 #include "hal/timer_ll.h"
 #include "soc/timer_periph.h"
+#include "machine_timer.h"
 
 #define TIMER_DIVIDER  8
 
@@ -46,27 +47,8 @@
 
 #define TIMER_FLAGS    0
 
-typedef struct _machine_timer_obj_t {
-    mp_obj_base_t base;
-
-    timer_hal_context_t hal_context;
-    mp_uint_t group;
-    mp_uint_t index;
-
-    mp_uint_t repeat;
-    // ESP32 timers are 64 or 54-bit
-    uint64_t period;
-
-    mp_obj_t callback;
-
-    intr_handle_t handle;
-
-    struct _machine_timer_obj_t *next;
-} machine_timer_obj_t;
-
 const mp_obj_type_t machine_timer_type;
 
-static void machine_timer_disable(machine_timer_obj_t *self);
 static mp_obj_t machine_timer_init_helper(machine_timer_obj_t *self, mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args);
 
 void machine_timer_deinit_all(void) {
@@ -91,18 +73,17 @@ static void machine_timer_print(const mp_print_t *print, mp_obj_t self_in, mp_pr
     #endif
 }
 
-static mp_obj_t machine_timer_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
-    mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true);
+machine_timer_obj_t *machine_timer_create(mp_uint_t timer) {
+
+    machine_timer_obj_t *self = NULL;
     #if CONFIG_IDF_TARGET_ESP32C3
-    mp_uint_t group = mp_obj_get_int(args[0]) & 1;
+    mp_uint_t group = timer & 1;
     mp_uint_t index = 0;
     #else
-    mp_uint_t group = (mp_obj_get_int(args[0]) >> 1) & 1;
-    mp_uint_t index = mp_obj_get_int(args[0]) & 1;
+    mp_uint_t group = (timer >> 1) & 1;
+    mp_uint_t index = timer & 1;
     #endif
 
-    machine_timer_obj_t *self = NULL;
-
     // Check whether the timer is already initialized, if so use it
     for (machine_timer_obj_t *t = MP_STATE_PORT(machine_timer_obj_head); t; t = t->next) {
         if (t->group == group && t->index == index) {
@@ -120,6 +101,14 @@ static mp_obj_t machine_timer_make_new(const mp_obj_type_t *type, size_t n_args,
         self->next = MP_STATE_PORT(machine_timer_obj_head);
         MP_STATE_PORT(machine_timer_obj_head) = self;
     }
+    return self;
+}
+
+static mp_obj_t machine_timer_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
+    mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true);
+
+    // Create the new timer.
+    machine_timer_obj_t *self = machine_timer_create(mp_obj_get_int(args[0]));
 
     if (n_args > 1 || n_kw > 0) {
         mp_map_t kw_args;
@@ -130,7 +119,7 @@ static mp_obj_t machine_timer_make_new(const mp_obj_type_t *type, size_t n_args,
     return self;
 }
 
-static void machine_timer_disable(machine_timer_obj_t *self) {
+void machine_timer_disable(machine_timer_obj_t *self) {
     if (self->hal_context.dev != NULL) {
         // Disable the counter and alarm.
         timer_ll_enable_counter(self->hal_context.dev, self->index, false);
@@ -162,7 +151,7 @@ static void machine_timer_isr(void *self_in) {
     }
 }
 
-static void machine_timer_enable(machine_timer_obj_t *self) {
+void machine_timer_enable(machine_timer_obj_t *self, void (*timer_isr)) {
     // Initialise the timer.
     timer_hal_init(&self->hal_context, self->group, self->index);
     timer_ll_enable_counter(self->hal_context.dev, self->index, false);
@@ -176,7 +165,7 @@ static void machine_timer_enable(machine_timer_obj_t *self) {
     timer_ll_clear_intr_status(self->hal_context.dev, TIMER_LL_EVENT_ALARM(self->index));
     ESP_ERROR_CHECK(
         esp_intr_alloc(timer_group_periph_signals.groups[self->group].timer_irq_id[self->index],
-            TIMER_FLAGS, machine_timer_isr, self, &self->handle)
+            TIMER_FLAGS, timer_isr, self, &self->handle)
         );
     timer_ll_enable_intr(self->hal_context.dev, TIMER_LL_EVENT_ALARM(self->index), true);
 
@@ -234,7 +223,7 @@ static mp_obj_t machine_timer_init_helper(machine_timer_obj_t *self, mp_uint_t n
     self->callback = args[ARG_callback].u_obj;
     self->handle = NULL;
 
-    machine_timer_enable(self);
+    machine_timer_enable(self, machine_timer_isr);
 
     return mp_const_none;
 }

diff --git a/ports/esp32/machine_timer.h b/ports/esp32/machine_timer.h
@@ -0,0 +1,66 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * Development of the code in this file was sponsored by Microbric Pty Ltd
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2013-2015 Damien P. George
+ * Copyright (c) 2016 Paul Sokolovsky
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_ESP32_MACHINE_TIMER_H
+#define MICROPY_INCLUDED_ESP32_MACHINE_TIMER_H
+
+#include "hal/timer_hal.h"
+#include "hal/timer_ll.h"
+#include "soc/timer_periph.h"
+
+#define TIMER_DIVIDER  8
+
+// TIMER_BASE_CLK is normally 80MHz. TIMER_DIVIDER ought to divide this exactly
+#define TIMER_SCALE    (APB_CLK_FREQ / TIMER_DIVIDER)
+
+#define TIMER_FLAGS    0
+
+typedef struct _machine_timer_obj_t {
+    mp_obj_base_t base;
+
+    timer_hal_context_t hal_context;
+    mp_uint_t group;
+    mp_uint_t index;
+
+    mp_uint_t repeat;
+    // ESP32 timers are 64-bit
+    uint64_t period;
+
+    mp_obj_t callback;
+
+    intr_handle_t handle;
+
+    struct _machine_timer_obj_t *next;
+} machine_timer_obj_t;
+
+machine_timer_obj_t *machine_timer_create(mp_uint_t timer);
+void machine_timer_enable(machine_timer_obj_t *self, void (*timer_isr));
+void machine_timer_disable(machine_timer_obj_t *self);
+
+#endif // MICROPY_INCLUDED_ESP32_MACHINE_TIMER_H