Repository files navigation

This fork implements interrupt service routine best practice.In the receive interrupt, instead of blocking for whole bytesat a time - voiding any near-realtime behavior of the CPU - only levelchange and timestamp are recorded. The more time consuming phasedetection and byte assembly are done in the main code.

Except at high bitrates, depending on other ongoing activity,interrupts in particular, this software serial adaptersupports full duplex receive and send. At high bitrates (115200bps)send bit timing can be improved at the expense of blocking concurrentfull duplex receives, with theEspSoftwareSerial::UART::enableIntTx(false) function call.

The same functionality is given as the corresponding AVR library butseveral instances can be active at the same time. Speed up to 115200 baudis supported. Besides a constructor compatible to the AVR SoftwareSerial class,and updated constructor that takes no arguments exists, instead thebegin()function can handle the pin assignments and logic inversion.It also has optional input buffer capacity arguments for byte buffer and ISR bit buffer.This way, it is a better drop-in replacement for the hardware serial APIs on the ESP MCUs.

Please note that due to the fact that the ESPs always have other activitiesongoing, there will be some inexactness in interrupt timings. This maylead to inevitable, but few, bit errors when having heavy data trafficat high baud rates.

This library supports ESP8266, ESP32, ESP32-S2 and ESP32-C3 devices.

The memory footprint can be optimized to just fit the amount of expectedincoming asynchronous data.For this, theEspSoftwareSerial::UART constructor provides two arguments. First, theoctet buffer capacity for assembled received octets can be set. Read calls aresatisfied from this buffer, freeing it in return.Second, the signal edge detection buffer of 32bit fields can be resized.One octet may require up to to 10 fields, but fewer may be needed,depending on the bit pattern. Any read or write calls check this bufferto assemble received octets, thus promoting completed octets to the octetbuffer, freeing fields in the edge detection buffer.

Look at the swsertest.ino example. There, on reset, ASCII characters ' ' to 'z'are sent. This happens not as a block write, but in a single write call percharacter. As the example uses a local loopback wire, every outgoing bit isimmediately received back. Therefore, any single write call causes up to10 fields - depending on the exact bit pattern - to be occupied in the signaledge detection buffer. In turn, as explained before, each single write callalso causes received bit assembly to be performed, promoting these bits fromthe signal edge detection buffer to the octet buffer as soon as possible.Explaining by way of contrast, if during a a single write call, perhaps becauseof using block writing, more than a single octet is received, there will be aneed for more than 10 fields in the signal edge detection buffer.The necessary capacity of the octet buffer only depends on the amount of incomingdata until the next read call.

For the swsertest.ino example, this results in the following optimizedconstructor arguments to spend only the minimum RAM on buffers required:

The octet buffer capacity (bufCapacity) is 95 (93 characters net plus two tolerance).The signal edge detection buffer capacity (isrBufCapacity) is 11, as eachsingle octet can have up to 11 bits on the wire,which are immediately received during the write, and eachwrite call causes the signal edge detection to promote the previously sent andreceived bits to the octet buffer.

In a more generalized scenario, calculate the bits (use message size in octetstimes 10) that may be asynchronously received to determine the value forisrBufCapacity in the constructor. Also use the number of received octetsthat must be buffered for reading as the value ofbufCapacity.The more frequently your code calls write or read functions, the greater thechances are that you can reduce theisrBufCapacity footprint without losing data,and each time you call read to fetch from the octet buffer, you reduce theneed for space there.

The configuration of the data stream is done via aEspSoftwareSerial::Configargument tobegin(). Word lengths can be set to between 5 and 8 bits, paritycan be N(one), O(dd) or E(ven) and 1 or 2 stop bits can be used. The default isSWSERIAL_8N1 using 8 bits, no parity and 1 stop bit but any combination canbe used, e.g.SWSERIAL_7E2. If using EVEN or ODD parity, any parity errorscan be detected with thereadParity() andparityEven() orparityOdd()functions respectively. Note that the result ofreadParity() always appliesto the precedingread() orpeek() call, and is undefined if they reportno data or an error.

To allow flexible 9-bit and data/addressing protocols, the additional paritymodes MARK and SPACE are also available. Furthermore, the parity mode can beindividually set in each call towrite().

This allows a simple implementation of protocols where the parity bit is used todistinguish between data and addresses/commands ("9-bit" protocols). First setup EspSoftwareSerial::UART with parity mode SPACE, e.g.SWSERIAL_8S1. This will add aparity bit to every byte sent, setting it to logical zero (SPACE parity).

To detect incoming bytes with the parity bit set (MARK parity), use thereadParity() function. To send a byte with the parity bit set, just addMARK as the second argument when writing, e.g.write(ch, SWSERIAL_PARITY_MARK).

In general, most pins on the ESP8266 and ESP32 devices can be used by EspSoftwareSerial,however each device has a number of pins that have special functions or require carefulhandling to prevent undesirable situations, for example they are connected to theon-board SPI flash memory or they are used to determine boot and programming modesafter powerup or brownouts. These pins are not able to be configured by this library.

The exact list for each device can be found in theESP32 data sheetin sections 2.2 (Pin Descriptions) and 2.4 (Strapping pins). There is a discussiondedicated to the use of GPIO12 in thisnote about GPIO12.Refer to theisValidPin(),isValidRxPin() andisValidTxPin()functions in theEspSoftwareSerial::GpioCapabilities class for the GPIO restrictionsenforced by this library by default.

The easiest and safest method is to test the object returned at runtime, to see ifit is valid. For example:

#include <SoftwareSerial.h>#define MYPORT_TX 12#define MYPORT_RX 13EspSoftwareSerial::UART myPort;[...]Serial.begin(115200); // Standard hardware serial portmyPort.begin(38400, SWSERIAL_8N1, MYPORT_RX, MYPORT_TX, false);if (!myPort) { // If the object did not initialize, then its configuration is invalid  Serial.println("Invalid EspSoftwareSerial pin configuration, check config");   while (1) { // Don't continue with invalid configuration    delay (1000);  }} [...]

EspSoftwareSerial is both part of the BSP download for ESP8266 in Arduino,and it is set up as a Git submodule in the esp8266 source tree,specifically in.../esp8266/libraries/SoftwareSerial when using a Githubrepository clone in your Arduino sketchbook hardware directory.This supersedes any version of EspSoftwareSerial installed for instance viathe Arduino library manager, it is not required to install EspSoftwareSerialfor the ESP8266 separately at all, but doing so has ill effect.

The responsible maintainer of the esp8266 repository has kindly shared thefollowing command line instructions to use, if one wishes to manuallyupdate EspSoftwareSerial to a newer release than pulled in via the ESP8266 Arduino BSP:

To update esp8266/arduino EspSoftwareSerial submodule to latest main:

Clean it (optional):

$ rm -rf libraries/SoftwareSerial$ git submodule update --init

Now update it:

$cd libraries/SoftwareSerial$ git checkout main$ git pull