Asynchronous UART TX on STM32 and Pyboard

[AsensioL]

I have been using MicroPython on a few STM32 Nucleo boards (F0, L4, G0) and built a few small tools that handle multiple UART channels at the same time.

I love how easy it is to set up UARTs to asynchronously receive data, and throw an interrupt when RX_IDLE.
However, I have never managed to get multiple UARTs TX-ing at the same time due to the blocking nature of uart.write() on STM32 MCUs.
This is not usually a problem at high baudrates, but at 2000bps, it is kind of noticeable when sending long UART packets.

Does the Pyboard support multiple non-blocking calls to uart.write() (on different UART peripherals, of course) ?

Research:
I have seen that there is an Issue open about this #1642 but it hasn't been updated in years.
I see that asynchronous UART Tx is a thing for for other boards, and we just recently added uart.flush() and uart.txdone() to check the status of asynchronous UART Tx.

[jimmo]

Does the Pyboard support multiple non-blocking calls to uart.write() (on different UART peripherals, of course) ?

Not at the moment unfortunately.

Some of the ports (e.g. rp2) have a tx ring buffer and an IRQ that keeps writing out the buffer in the background (which is what lets flush and txdone work). The STM32 does not have this.

Ideally, DMA support for the various busses (I2C, SPI, UART, etc) is something that would be great to support.

[peterhinch]

The easiest way to handle concurrent use of different UARTs is to use uasyncio with the StreamReader and StreamWriter classes. This demo illustrates the principle, discussed here.

[robert-hh]

Looking into the implementation for STM32, ioctl for checking, whether the UART can accept data is implemented, telling that the UART can accept at least 1 byte of data. It checks the transmitter empty flag.

[jimmo]

Yes, but it appears to me that if StreamWriter then does the write, it will happily accept as many bytes as StreamWriter gives it, and then block while it writes them out synchronously in uart_tx_data.

Compare to rp2 which will just copy the bytes into the ring buffer and return immediately.

[robert-hh]

Indeed, but also rp2 will block if more data is written than the ring buffer can hold.

Unrelated note: You see below a much older comment. That is a little bit confusing with github discussions.

[AsensioL]

So, it looks like the STM32 UART ioctl method deviates from the stream interface, and that is probably a bug.
However,

Do people rely on the current behavior for their applications?

Most likely, yes.

Can we fix STM32 UART without breaking API?

Maybe.

How?

Since the current implementation of STM32 UART.init(...) does not accept the kwarg txbuffer.
I would propose we use that to extend UART.init(...) so it accepts txbuffer with default value 0 or -1. Then

• if txbuffer <= 0, UART.write(...) handles that case as a blocking transmission (maintaining current behavior)
• if txbuffer >= MIN_BUFFER_SIZE and txbuffer < MAX_BUFFER_SIZE, UART.write(...) copies the data to a TX ring buffer (like rp2) and then, it either,
  1. uses the DMA for non-blocking transmission, or
  2. uses the UART TX-complete ISR for non-blocking transmission, or
  3. if the TX ring buffer is full, performs blocking transmission (again, like the rp2 port),
• otherwise, UART.init(...) returns an error

I think this should maintain existing behavior moving forward, while giving the options for new users/applications to benefit from uasyncio and non-blocking UART TX.

Edit: and now that we have UART.flush() and UART.tx_done() we'll have plenty of flexibility to build new things.

[robert-hh]

So, it looks like the STM32 UART ioctl method deviates from the stream interface

I don't think so. ioctl poll just tells, that there is room to write, not how much. The behavior varies a lot between the boards. The data that can be written without blocking is:

• at least 1 at the stm32
• at least 1 for rp2
• unknown at the esp32 board (can be fixed, but will be > 1)
• unknown at the mimxrt board. A PR is made to change it.
• at least 1 for ESP8266
• not supported for the nrf port
• at least 1 for the renesas-ra port
• unknown at the zephyr board. It always tells: go ahead

Anhow, enhancing the STM32 uart write to buffered operation is surely a good thing. So go ahead and do it.

[AsensioL]

Just checked the implementation of uasyncio.Stream (same as StreamWriter), and it relies on the stream's object (s) .write() function, which in the case of UART for the STM32 MCUs, it is provided by ports/stm32/machine_uart.c::pyb_uart_write(...).

pyb_uart_write(...) uses uart_tx_data(...) which looks like it could support partial writes and returning the number of bytes written, however if you look at ports/stm32/uart.c::uart_tx_data(...) it shows a while loop that iterates on every byte passed (using while (num_tx < num_chars) and uart_wait_flag_set(self, UART_FLAG_TXE, timeout)) until the entire array has been sent.

[peterhinch]

OK, I stand corrected. My testing was done with short bytearrays and mainly at high baudrates. Sending a 1000 byte array at 9600 baud, StreamWriter does indeed block for a second, both on RP2 and STM. You learn something every day round here :)

[Jibun-no-Kage]

Do you have to grab or push the large data blob in one take? Can't you nibble at the data for read, and nibble at the data when writing? The only requirement is a known terminator, right? Would this not address the issue at practical level?

Not sure if this helps, but I have been playing with or using an asyncio wrapper (task) around just using UART.any(), and setting the task to self schedule using a custom decorator at a duration 0.1 seconds. For what I am doing this seems to be responsive enough, while still letting other tasks get time via asyncio even loop. I am nibbling away at strings that are between 1 and 512 or so, using ESP as bridge to a Pico H, sending json formatted strings that are actually encapsulated MQTT messages. I can do the same idea sending data base to ESP from sending the topic then the payload as different writes, or fragments of same, I just need to know that the terminator is, say 3 zero bytes for example. So sending 100 bytes, then 100, then 100, etc. until 3 zero bytes? I would think as long as you know the expected terminator, the number of reads or writes can be any number until terminator.

[peterhinch]

We've established (by code review and by testing) that StreamWriter can block, which is surely a bug. So before this line a call to an s method needs to be made to establish how many bytes can be written without blocking. The subsequent write would then be made with an appropriate buffer segment.

A possible issue is that s can be any stream, notably a socket but possibly other objects. It would simplify the code if all supported the same named method.

Does anyone know of any existing stream types other than UART and socket which may be passed to StreamWriter?

[jimmo]

@peterhinch I think rather than asking the stream how many non-blocking bytes can be written, it would be better to support a force-non-blocking write that returns the number of bytes written. (I guess my argument is that the additional function you're proposing is only useful to then decide how many bytes to carve off to send to write, so you might as well just make write do it).

The problem on rp2 is that it it's non-blocking up to the size of the ring buffer, but then goes ahead and blocks for the entire write if you pass more bytes than the size of the ringbuffer. Peter, in your test on rp2, had you set the UART's timeout to zero? I think in that case you'd get the exact behavior you want.

@AsensioL For stm32, I think all that might be missing to match rp2 is to make uart_tx_data not calculate the per-character timeout if self->timeout == 0. it would then just return a single byte written and asyncio would do the right thing.

i.e.

if (self->timeout == 0 || self->uartx->CR3 & USART_CR3_CTSE) {
    // ...
    timeout = 0;
} else {
    // ...
    timeout = 2 * self->timeout_char;
}

(In other words, if you want to pass a UART to StreamWriter, you really should ensure that it was constructed with timeout=0).

That said, doing a whole asyncio loop and poll just to write a single byte is obviously not very efficient, so adding a ringbuffer with a background interrupt (i.e. identical to rp2) would obviously be a good follow-up.

[robert-hh]

So we have a kind of grey box, with the Python code calling uart.write() and at the other side machine_uart_write(), which receives the data to put it on the wire. At the moment machine_uart_write() does not returns until all data is sent, and returns that size, unless there is a timeout. Then it will report how much has been sent.
This function can easily be changed to just take what it at the moment can handle and returns that number, which may be 0. But would not the Python code expect that all data is sent or accepted to be sent, when the call to uart.write() returns?

[peterhinch]

@jimmo Setting timeout=0 does indeed work. Tested on Pyboard and RP2. Can we assume that this is the case on other ports?
[EDIT]
This suggests that my original suggestion of using StreamWriter to achieve concurrent transmission from multiple UARTs is correct, so long as all UARTs are set up with timeout=0. Do the assembled UART gurus agree?

[robert-hh]

For the mimxrt port and the samd PR it should work. The ESP32 and ESP8266 port do not have a check for tx timeout.

[robert-hh]

No check for timeout at nrf and Zephyr port.

[peterhinch]

The plot thickens. Even with timeout=0 concurrent writes don't work on a Pyboard 1.1. I have raised this issue.

[robert-hh]

That's because at STM32 the UART code it waits for timeout_char instead of timeout. And timout_char will be forced to be at least 1 character time.

Edit: Actually finally twice the time is used.

[peterhinch]

Setting timeout_char=0 (and timeout=0) has made no difference. It still blocks for the entire 990 character message.

[robert-hh]

That's not a surprise. A setting of timeout_char=0 will be changed into timeout_char = 1. And the STM32 UART code will block for every message longer than 2 byte.

[jimmo]

@peterhinch have you also made the change to uart_tx_data (in stm32/uart.c) I proposed above to make use of the timeout?

[peterhinch]

@jimmo I tried this with the following outcome (repeated for each UART task):

Task exception wasn't retrieved
future: <Task> coro= <generator object 'sender' at 200082a0>
Traceback (most recent call last):
  File "uasyncio/core.py", line 1, in run_until_complete
  File "utest.py", line 17, in sender
  File "uasyncio/stream.py", line 1, in drain
OSError: [Errno 110] ETIMEDOUT

[jimmo]

OK thanks for testing! Looks like it'll take a bit more investigation. Will continue this in #9233

[peterhinch]

@jimmo As a general point I think TX should always be buffered as per RP2. Having .write restricted to sending one char would mean that StreamWriter.drain iterates and yields for every character. This would throttle communication at high baudrates. The buffer size should be user configurable via the existing init.txbuf arg. The point being that the application designer will know how much latency is likely to result from a yield and may want to define a buffer large enough so that transmission will continue during that period.

Buffering also offers the prospect of abstracting the UART hardware and ensuring all ports behave similarly.

Where an application requires timeouts, a task using StreamWriter to output a message can be subjected to a timeout using a uasyncio timeout. This is simpler than dealing with timeouts at the UART level. It also allows for cancellation.

[robert-hh]

@peterhinch @jimmo With the MIMXRT port, the timeout setting is ignore for tx.write() at the moment. There is a timeout, but internally calculated based on the message size and the baudrate, ensuring that the call will not block forever. The only thing I could implement easily at the moment is a special treatment of timeout=0, which would return a timeout error if uart.write() cannot put all data immediately into the send buffer, but instead would block until all data is either sent or put into a send buffer.

[peterhinch]

See #9233 (comment)

[robert-hh]

I made an implementation for MIMXRT which makes an estimation of the blocking time and sends as many characters as possible without blocking longer than timeout. And I changed the rp2 port accordingly. That results in situations, that uart.write() does not write the full message, like it used to do, albeit blocking. Let's see if that causes protests.
For STM32 the situation is more complex. It requires to rewrite the uart driver substantially.