Adds UART RX IRQ Callback with onReceive()

[SuGlider]

Summary

This PR adds a new feature to UART / Arduino Serial API.

Users have requested a feature related to UART ISR that allow a callback function to be executed as soon as data arrives to UART port. This PR adds Serial.onReceive() functionality to Arduino Hardware Serial.

Example:

void UART_RX_IRQ() {
  uint16_t size = Serial.available();
  Serial.printf("Got %d bytes on Serial to read\n", size);
  while(Serial.available())  {
    Serial.write(Serial.read());
  }
  Serial.printf("\nSerial data processed!\n");
}

void setup() {
  Serial.begin(115200);
  Serial.onReceive(UART_RX_IRQ);
  Serial.println("Send data to UART0 in order to activate the RX callback");
}

void loop() {
  Serial.println("Sleeping for 10 seconds...");
  delay(10000);
}

Output of the example in the ESP32-C3 (Hello World! sent to default Serial port using Arduino Serial Monitor):

ESP-ROM:esp32c3-api1-20210207
Build:Feb  7 2021
rst:0x1 (POWERON),boot:0xc (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd6100,len:0x420
load:0x403ce000,len:0x90c
load:0x403d0000,len:0x236c
SHA-256 comparison failed:
Calculated: ccb0d00bac7e84e1d90a12e4f75f4ab6c5f7e71bb209afd5819c4c9557a6db71
Expected: c9cf160580940ec7801c73b16423824e72ad12055c732e83ce66332240af42a7
Attempting to boot anyway...
entry 0x403ce000
Send data to UART0 in order to activate the RX callback
Sleeping for 10 seconds...
Sleeping for 10 seconds...
Got 13 bytes on Serial to read
Hello World!

Serial data processed!
Sleeping for 10 seconds...

Impact

It includes a new feature to Arduino Hardware Serial.
It needs to be documented (@pedrominatel)

Related links

Initial PR requesting the feature
PR #4656
PR #3376

Related Issues
Fixes #5678
Fixes #5620
Fixes #5472
Fixes #6102

[me-no-dev]

I like it :) let's discuss my single comment and we can merge it.

[SuGlider]

Adds LOCKs to UART Event Callback Task.

[SuGlider]

Ready for merging.

[FredGlaum]

Hi I recently also experienced buffer overrun errors on high baudrates - I am glad to see there is solution in the works. When can we expect to use the onReceive() event callback for the Arduino/PlatformIO ESP32 development.

I tried the latest dev and stable core releases and its not there.

[SuGlider]

Hi I recently also experienced buffer overrun errors on high baudrates - I am glad to see there is solution in the works. When can we expect to use the onReceive() event callback for the Arduino/PlatformIO ESP32 development.

I tried the latest dev and stable core releases and its not there.

PlaformIO ESP32 still uses old Arduino Core version 1.0.6.
This patch depends on IDF and it will be available in Arduino Core version 2.0.3+.
You can try to manually setup your PlatformIO to use the latest master version to use this feature.

Maybe this link may help you:
https://community.platformio.org/t/use-different-version-of-arduino-framework-on-espressif-platform/23669

[gemu2015]

@SuGlider
could you please verify this pr since it seems to break UART receive in some users of Tasmota.
under some circumstances receive stops and only reverts after a restart. this is fixed after reverting this pr.
since this option is only needed in rare cases i would also prefer to not enable it by default since it creates an extra queue and task wasting memory and cpu cycles.
probably only create queue and task when uartOnReceive is actually called ?

[SuGlider]

@gemu2015
This PR has an issue fixed and merged to master in PR #6201
This shall fix the issue you report as "break UART receive".

[SuGlider]

probably only create queue and task when uartOnReceive is actually called ?

This is not possible because of IDF UART driver setup.
IDF is the base for all HAL layer of ESP32 Arduino in Arduino Core Version 2.0.0+.

[gemu2015]

@gemu2015
This PR has an issue fixed and merged to master in PR #6201
This shall fix the issue you report as "break UART receive".

however we do not use HardwareSerial::onReceive() at all and get locks too ??

[SuGlider]

however we do not use HardwareSerial::onReceive() at all and get locks too ??

As said it is fixed. You are talking about WIP - the final version 2.0.3 is not released yet.
The decision of merging isolated PRs to other projects is beyond our control.

The lock issue will only occur if the sketch actually calls onReceive( fucntion ), otherwise it will never lock.
Anyway, it has been fixed in #6201
Master branch is free of issues with UART at this time, as the final release of 2.0.3 will be when the time arrives.

[Jason2866]

For completness tested with applying #6201 too. Still issues. Maybe it is related to #6326

[SuGlider]

@Jason2866 - Please check #6364 because it shall be the final version of HardwareSerial and esp32-hal-uart for the next Arduino Core Version 2.0.3.

I fixed a number of issues related to HardwareSerial overflows, locking issues, onReceive() and others.

[SuGlider]

@SuGlider could you please verify this pr since it seems to break UART receive in some users of Tasmota. under some circumstances receive stops and only reverts after a restart. this is fixed after reverting this pr. since this option is only needed in rare cases i would also prefer to not enable it by default since it creates an extra queue and task wasting memory and cpu cycles. probably only create queue and task when uartOnReceive is actually called ?

@gemu2015
#6364 does what you requested - task is only created when Serial.onReceive() is actually used, otherwise the task is never created. The queue is created as part of UART IDF initialization, thus it is created always. The queue is only checked in the task, thus it won't waste CPU cycles anymore. This queue is very small and waste less than 64 bytes - no harm. More memory is really allocated for the task that will only be created when the user really wants to use onReveive().

Locking issue is fixed as well.

[Jason2866]

@SuGlider thx, will do a build with. @gemu2015 when it is compiled i will drop you a note.

[dagi0627]

My esp32 (device1) connected to another MCU (device2) over UART2. Device2 sends some data at every second then device1 recieveing it well and send back over UART0 for show on terminal. It is good working. But some in case device1 or esp32 send character "@" to device2 then device2 stop to send data at everysecond and send some information at once time . That is same following

2. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s,
3. when an unknown printer took a galley of type 
4. and scrambled it to make a type specimen book. 
5. It has survived not only five centuries, 
6. but also the leap into electronic typesetting, 
7. remaining essentially unchanged. 
8. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, 
9. and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.```  
But it is not show on terminal. After few minute Device2 send data at everysecond then i show above information. Why it is Buffered data.