|
| 1 | +/* |
| 2 | +
|
| 3 | + This Sketch demonstrates how to use onReceiveError(callbackFunc) with HardwareSerial |
| 4 | +
|
| 5 | + void HardwareSerial::onReceiveError(OnReceiveErrorCb function) |
| 6 | +
|
| 7 | + It is possible to register a UART callback function that will be called |
| 8 | + everytime that UART detects an error which is also associated to an interrupt. |
| 9 | +
|
| 10 | + There are some possible UART errors: |
| 11 | +
|
| 12 | + UART_BREAK_ERROR - when a BREAK event is detected in the UART line. In that case, a BREAK may |
| 13 | + be read as one or more bytes ZERO as part of the data received by the UART peripheral. |
| 14 | +
|
| 15 | + UART_BUFFER_FULL_ERROR - When the RX UART buffer is full. By default, Arduino will allocate a 256 bytes |
| 16 | + RX buffer. As data is received, it is copied to the UART driver buffer, but when it is full and data can't |
| 17 | + be copied anymore, this Error is issued. To prevent it the application can use |
| 18 | + HardwareSerial::setRxBufferSize(size_t new_size), before using HardwareSerial::begin() |
| 19 | +
|
| 20 | + UART_FIFO_OVF_ERROR - When the UART peripheral RX FIFO is full and data is still arriving, this error is issued. |
| 21 | + The UART driver will stash RX FIFO and the data will be lost. In order to prevent, the application shall set a |
| 22 | + good buffer size using HardwareSerial::setRxBufferSize(size_t new_size), before using HardwareSerial::begin() |
| 23 | +
|
| 24 | + UART_FRAME_ERROR - When the UART peripheral detects a UART frame error, this error is issued. It may happen because |
| 25 | + of line noise or bad impiedance. |
| 26 | +
|
| 27 | + UART_PARITY_ERROR - When the UART peripheral detects a parity bit error, this error will be issued. |
| 28 | +
|
| 29 | +
|
| 30 | + In summary, HardwareSerial::onReceiveError() works like an UART Error Notification callback. |
| 31 | +
|
| 32 | + Errors have priority in the order of the callbacks, therefore, as soon as an error is detected, |
| 33 | + the registered callback is executed firt, and only after that, the OnReceive() registered |
| 34 | + callback function will be executed. This will give opportunity for the Application to take action |
| 35 | + before reading data, if necessary. |
| 36 | +
|
| 37 | + In long UART transmissions, some data will be received based on FIFO Full parameter, and whenever |
| 38 | + an error ocurs, it will raise the UART error interrupt. |
| 39 | +
|
| 40 | + This sketch produces BREAK UART error in the begining of a transmission and also at the end of a |
| 41 | + transmission. It will be possible to understand the order of the events in the logs. |
| 42 | +
|
| 43 | +*/ |
| 44 | + |
| 45 | +#include <Arduino.h> |
| 46 | + |
| 47 | +// There are two ways to make this sketch work: |
| 48 | +// By physically connecting the pins 4 and 5 and then create a physical UART loopback, |
| 49 | +// Or by using the internal IO_MUX to connect the TX signal to the RX pin, creating the |
| 50 | +// same loopback internally. |
| 51 | +#define USE_INTERNAL_PIN_LOOPBACK 1 // 1 uses the internal loopback, 0 for wiring pins 4 and 5 externally |
| 52 | + |
| 53 | +#define DATA_SIZE 26 // 26 bytes is a lower than RX FIFO size (127 bytes) |
| 54 | +#define BAUD 9600 // Any baudrate from 300 to 115200 |
| 55 | +#define TEST_UART 1 // Serial1 will be used for the loopback testing with different RX FIFO FULL values |
| 56 | +#define RXPIN 4 // GPIO 4 => RX for Serial1 |
| 57 | +#define TXPIN 5 // GPIO 5 => TX for Serial1 |
| 58 | + |
| 59 | +#define BREAK_BEFORE_MSG 0 |
| 60 | +#define BREAK_AT_END_MSG 1 |
| 61 | + |
| 62 | + |
| 63 | +uint8_t fifoFullTestCases[] = {120, 20, 5, 1}; |
| 64 | +// volatile declaration will avoid any compiler optimization when reading variable values |
| 65 | +volatile size_t sent_bytes = 0, received_bytes = 0; |
| 66 | + |
| 67 | +const char *uartErrorStrings[] = { |
| 68 | + "UART_NO_ERROR", |
| 69 | + "UART_BREAK_ERROR", |
| 70 | + "UART_BUFFER_FULL_ERROR", |
| 71 | + "UART_FIFO_OVF_ERROR", |
| 72 | + "UART_FRAME_ERROR", |
| 73 | + "UART_PARITY_ERROR" |
| 74 | +}; |
| 75 | + |
| 76 | +// Callback function that will treat the UART errors |
| 77 | +void onReceiveErrorFunction(hardwareSerial_error_t err) { |
| 78 | + // This is a callback function that will be activated on UART RX Error Events |
| 79 | + Serial.printf("\n-- onReceiveError [ERR#%d:%s] \n", err, uartErrorStrings[err]); |
| 80 | + Serial.printf("-- onReceiveError:: There are %d bytes available.\n", Serial1.available()); |
| 81 | +} |
| 82 | + |
| 83 | +// Callback function that will deal with arriving UART data |
| 84 | +void onReceiveFunction() { |
| 85 | + // This is a callback function that will be activated on UART RX events |
| 86 | + size_t available = Serial1.available(); |
| 87 | + received_bytes += available; |
| 88 | + Serial.printf("onReceive Callback:: There are %d bytes available: {", available); |
| 89 | + while (available --) { |
| 90 | + Serial.print((char)Serial1.read()); |
| 91 | + } |
| 92 | + Serial.println("}"); |
| 93 | +} |
| 94 | + |
| 95 | +void setup() { |
| 96 | + // UART0 will be used to log information into Serial Monitor |
| 97 | + Serial.begin(115200); |
| 98 | + |
| 99 | + // UART1 will have its RX<->TX cross connected |
| 100 | + // GPIO4 <--> GPIO5 using external wire |
| 101 | + Serial1.begin(BAUD, SERIAL_8N1, RXPIN, TXPIN); // Rx = 4, Tx = 5 will work for ESP32, S2, S3 and C3 |
| 102 | +#if USE_INTERNAL_PIN_LOOPBACK |
| 103 | + uart_internal_loopback(TEST_UART, RXPIN); |
| 104 | +#endif |
| 105 | + |
| 106 | + for (uint8_t i = 0; i < sizeof(fifoFullTestCases); i++) { |
| 107 | + Serial.printf("\n\n================================\nTest Case #%d BREAK at END\n================================\n", i + 1); |
| 108 | + // First sending BREAK at the end of the UART data transmission |
| 109 | + testAndReport(fifoFullTestCases[i], BREAK_AT_END_MSG); |
| 110 | + Serial.printf("\n\n================================\nTest Case #%d BREAK at BEGINING\n================================\n", i + 1); |
| 111 | + // Now sending BREAK at the begining of the UART data transmission |
| 112 | + testAndReport(fifoFullTestCases[i], BREAK_BEFORE_MSG); |
| 113 | + Serial.println("========================\nFinished!"); |
| 114 | + } |
| 115 | + |
| 116 | +} |
| 117 | + |
| 118 | +void loop() { |
| 119 | +} |
| 120 | + |
| 121 | +void testAndReport(uint8_t fifoFull, bool break_at_the_end) { |
| 122 | + // Let's send 125 bytes from Serial1 rx<->tx and mesaure time using diferent FIFO Full configurations |
| 123 | + received_bytes = 0; |
| 124 | + sent_bytes = DATA_SIZE; // 26 characters |
| 125 | + |
| 126 | + uint8_t dataSent[DATA_SIZE + 1]; |
| 127 | + dataSent[DATA_SIZE] = '\0'; // string null terminator, for easy printing. |
| 128 | + |
| 129 | + // initialize all data |
| 130 | + for (uint8_t i = 0; i < DATA_SIZE; i++) { |
| 131 | + dataSent[i] = 'A' + i; // fill it with characters A..Z |
| 132 | + } |
| 133 | + |
| 134 | + Serial.printf("\nTesting onReceive for receiving %d bytes at %d baud, using RX FIFO Full = %d.\n", sent_bytes, BAUD, fifoFull); |
| 135 | + Serial.println("onReceive is called on both FIFO Full and RX Timeout events."); |
| 136 | + if (break_at_the_end) { |
| 137 | + Serial.printf("BREAK event will be sent at the END of the %d bytes\n", sent_bytes); |
| 138 | + } else { |
| 139 | + Serial.printf("BREAK event will be sent at the BEGINING of the %d bytes\n", sent_bytes); |
| 140 | + } |
| 141 | + Serial.flush(); // wait Serial FIFO to be empty and then spend almost no time processing it |
| 142 | + Serial1.setRxFIFOFull(fifoFull); // testing diferent result based on FIFO Full setup |
| 143 | + Serial1.onReceive(onReceiveFunction); // sets a RX callback function for Serial 1 |
| 144 | + Serial1.onReceiveError(onReceiveErrorFunction); // sets a RX callback function for Serial 1 |
| 145 | + |
| 146 | + if (break_at_the_end) { |
| 147 | + sent_bytes = uart_send_msg_with_break(TEST_UART, dataSent, DATA_SIZE); |
| 148 | + } else { |
| 149 | + uart_send_break(TEST_UART); |
| 150 | + sent_bytes = Serial1.write(dataSent, DATA_SIZE); |
| 151 | + } |
| 152 | + |
| 153 | + Serial.printf("\nSent String: %s\n", dataSent); |
| 154 | + while (received_bytes < sent_bytes) { |
| 155 | + // just wait for receiving all byte in the callback... |
| 156 | + } |
| 157 | + |
| 158 | + Serial.printf("\nIt has sent %d bytes from Serial1 TX to Serial1 RX\n", sent_bytes); |
| 159 | + Serial.printf("onReceive() has read a total of %d bytes\n", received_bytes); |
| 160 | + |
| 161 | + Serial1.onReceiveError(NULL); // resets/disables the RX Error callback function for Serial 1 |
| 162 | + Serial1.onReceive(NULL); // resets/disables the RX callback function for Serial 1 |
| 163 | +} |
0 commit comments