Adds support for parity bit, including mark / space, and 2 stop bits.

Parity errors must be checked and handled in user code, the API provides access to parity
for write() and read().

Author: dok-net

README.md

@@ -12,12 +12,13 @@ Except at high bitrates, depending on other ongoing activity,
 interrupts in particular, this software serial adapter
 supports full duplex receive and send. At high bitrates (115200bps)
 send bit timing can be improved at the expense of blocking concurrent
-full duplex receives, with the SoftwareSerial::enableIntTx(false) function call.
+full duplex receives, with the ``SoftwareSerial::enableIntTx(false)`` function call.
 
 The same functionality is given as the corresponding AVR library but
 several instances can be active at the same time. Speed up to 115200 baud
-is supported. Diverging from the AVR SoftwareSerial class, the constructor takes
-no arguments, instead the begin() function handles pin assignments and logic inversion.
+is supported. Besides a constructor compatible to the AVR SoftwareSerial class,
+and updated constructor that takes no arguments exists, instead the ``begin()``
+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.
 
@@ -26,12 +27,11 @@ ongoing, there will be some inexactness in interrupt timings. This may
 lead to inevitable, but few, bit errors when having heavy data traffic
 at high baud rates.
 
-
 ## Resource optimization
 
 The memory footprint can be optimized to just fit the amount of expected
 incoming asynchronous data.
-For this, the SoftwareSerial constructor provides two arguments. First, the
+For this, the ``SoftwareSerial`` constructor provides two arguments. First, the
 octet buffer capacity for assembled received octets can be set. Read calls are
 satisfied from this buffer, freeing it in return.
 Second, the signal edge detection buffer of 32bit fields can be resized.
@@ -41,7 +41,7 @@ to assemble received octets, thus promoting completed octets to the octet
 buffer, freeing fields in the edge detection buffer.
 
 Look at the swsertest.ino example. There, on reset, ASCII characters ' ' to 'z'
-are send. This happens not as a block write, but in single write calls per
+are sent. This happens not as a block write, but in a single write call per
 character. As the example uses a local loopback wire, every outgoing bit is
 immediately received back. Therefore, any single write call causes up to
 10 fields - depending on the exact bit pattern - to be occupied in the signal
@@ -57,43 +57,67 @@ data until the next read call.
 For the swsertest.ino example, this results in the following optimized
 constructor arguments to spend only the minimum RAM on buffers required:
 
-The octet buffer capacity (bufCapacity) is 93 (91 characters net plus two tolerance).
-The signal edge detection buffer capacity (isrBufCapacity) is 10, as each octet has
+The octet buffer capacity (``bufCapacity``) is 93 (91 characters net plus two tolerance).
+The signal edge detection buffer capacity (``isrBufCapacity``) is 10, as each octet has
 10 bits on the wire, which are immediately received during the write, and each
 write call causes the signal edge detection to promote the previously sent and
 received bits to the octet buffer.
 
 In a more generalized scenario, calculate the bits (use message size in octets
 times 10) that may be asynchronously received to determine the value for
-isrBufCapacity in the constructor. Also use the number of received octets
-that must be buffered for reading as the value of bufCapacity.
+``isrBufCapacity`` in the constructor. Also use the number of received octets
+that must be buffered for reading as the value of ``bufCapacity``.
 The more frequently your code calls write or read functions, the greater the
-chances are that you can reduce the isrBufCapacity footprint without losing data,
+chances are that you can reduce the ``isrBufCapacity`` footprint without losing data,
 and each time you call read to fetch from the octet buffer, you reduce the
 need for space there.
 
+## SoftwareSerialConfig and parity
+The configuration of the data stream is done via a ``SoftwareSerialConfig``
+argument to ``begin()``. Word lengths can be set to between 5 and 8 bits, parity
+can be N(one), O(dd) or E(ven) and 1 or 2 stop bits can be used. The default is
+``SWSERIAL_8N1`` using 8 bits, no parity and 1 stop bit but any combination can
+be used, e.g. ``SWSERIAL_7E2``. If using EVEN or ODD parity, any parity errors
+can be detected with the ``peekParityError()`` function. Note that parity 
+checking must be done before ``read()``, as the parity information is removed
+from the buffer when reading the corresponding byte.
+
+To allow flexible 9-bit and data/addressing protocols, the additional parity
+modes MARK and SPACE are also available. Furthermore, the parity mode can be
+individually set in each call to ``write()``.
+
+This allows a simple implementation of protocols where the parity bit is used to
+distinguish between data and addresses/commands ("9-bit" protocols). First set
+up SoftwareSerial with parity mode SPACE, e.g. ``SWSERIAL_8S1``. This will add a
+parity bit to every byte sent, setting it to logical zero (SPACE parity).
+
+To detect incoming bytes with the parity bit set (MARK parity), use the
+``peekParityError()`` function. To send a byte with the parity bit set, just add
+``MARK`` as the second argument when writing, e.g. ``write(ch, MARK)``.
 
 ## Using and updating EspSoftwareSerial in the esp8266com/esp8266 Arduino build environment
 
-The EspSoftwareSerial is both part of the BSP download for ESP8266 in Arduino,
+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 Github
+specifically in ``.../esp8266/libraries/SoftwareSerial`` when using a Github
 repository clone in your Arduino sketchbook hardware directory.
 This supersedes any version of EspSoftwareSerial installed for instance via
 the Arduino library manager, it is not required to install EspSoftwareSerial
-for the ESP8266 separately at all.
+for the ESP8266 separately at all, but doing so has ill effect.
 
 The responsible maintainer of the esp8266 repository has kindly shared the
 following command line instructions to use, if one wishes to manually
 update EspSoftwareSerial to a newer release than pulled in via the ESP8266 Arduino BSP:
 
 To update esp8266/arduino SoftwareSerial submodule to lastest master:
 
-```
-(optional, clean it:)
+Clean it (optional):
+```shell
 $ rm -rf libraries/SoftwareSerial
 $ git submodule update --init
-(now update it:)
+```
+Now update it:
+```shell
 $ cd libraries/SoftwareSerial
 $ git checkout master
 $ git pull

examples/loopback/loopback.ino

@@ -36,8 +36,12 @@ constexpr int IUTBITRATE = 64000;
 constexpr int IUTBITRATE = 153600;
 #endif
 
-#if defined(ESP8266) || defined(ESP32)
-constexpr SoftwareSerialConfig swSerialConfig = SWSERIAL_8N1;
+#if defined(ESP8266)
+constexpr SoftwareSerialConfig swSerialConfig = SWSERIAL_8E2;
+constexpr SerialConfig hwSerialConfig = SERIAL_8E2;
+#elif defined(ESP32)
+constexpr SoftwareSerialConfig swSerialConfig = SWSERIAL_8E2;
+constexpr uint32_t hwSerialConfig = SERIAL_8E2;
 #else
 constexpr unsigned swSerialConfig = 3;
 #endif
@@ -51,6 +55,7 @@ int txCount;
 int rxCount;
 int expected;
 int rxErrors;
+int rxParityErrors;
 constexpr int ReportInterval = IUTBITRATE / 8;
 
 #if defined(ESP8266)
@@ -83,20 +88,20 @@ HardwareSerial& logger(Serial);
 void setup() {
 #if defined(ESP8266)
 #if defined(HWLOOPBACK) || defined(HWSOURCESINK) || defined(HWSOURCESWSINK)
-    Serial.begin(IUTBITRATE);
+    Serial.begin(IUTBITRATE, hwSerialConfig);
     Serial.swap();
     Serial.setRxBufferSize(2 * BLOCKSIZE);
-    logger.begin(9600, swSerialConfig, -1, TX);
+    logger.begin(9600, SWSERIAL_8N1, -1, TX);
 #else
     Serial.begin(9600);
 #endif
 #elif defined(ESP32)
 #if defined(HWLOOPBACK) || defined(HWSOURCESWSINK)
-    Serial2.begin(IUTBITRATE);
+    Serial2.begin(IUTBITRATE, hwSerialConfig);
     Serial2.setRxBufferSize(2 * BLOCKSIZE);
     logger.begin(9600);
 #elif defined(HWSOURCESINK)
-    serialIUT.begin(IUTBITRATE, swSerialConfig, D5, D6);
+    serialIUT.begin(IUTBITRATE, hwSerialConfig, D5, D6);
     serialIUT.setRxBufferSize(2 * BLOCKSIZE);
     logger.begin(9600);
 #else
@@ -126,6 +131,7 @@ void setup() {
     txCount = 0;
     rxCount = 0;
     rxErrors = 0;
+    rxParityErrors = 0;
 
     logger.println("Loopback example for EspSoftwareSerial");
 }
@@ -198,13 +204,10 @@ void loop() {
     deadlineStart = ESP.getCycleCount();
     inCnt = 0;
     while ((ESP.getCycleCount() - deadlineStart) < (1000000 * 10 * BLOCKSIZE) / IUTBITRATE * 2 * ESP.getCpuFreqMHz()) {
-        int avail;
-        if (0 >= (avail = serialIUT.available())) {
-            continue;
-        }
-        avail = serialIUT.readBytes(inBuf, min(avail, 2 * BLOCKSIZE));
-        for (int i = 0; i < avail; ++i) {
-            unsigned char r = inBuf[i];
+        int avail = serialIUT.available();
+        for (int i = 0; i < avail; ++i)
+        {
+            unsigned char r = serialIUT.read();
             if (expected == -1) { expected = r; }
             else {
                 expected = (expected + 1) % 256;
@@ -213,25 +216,40 @@ void loop() {
                 ++rxErrors;
                 expected = -1;
             }
+            if ((serialIUT.readParity() ^ static_cast<bool>(swSerialConfig & 010)) != serialIUT.parityEven(r))
+            {
+                ++rxParityErrors;
+            }
             ++rxCount;
             ++inCnt;
         }
+
         if (inCnt >= BLOCKSIZE) { break; }
         // wait for more outstanding bytes to trickle in
         deadlineStart = ESP.getCycleCount();
     }
 
     const uint32_t interval = micros() - start;
     if (txCount >= ReportInterval && interval) {
+        uint8_t wordBits = (5 + swSerialConfig % 4) + static_cast<bool>(swSerialConfig & 070) + 1 + ((swSerialConfig & 0300) ? 1 : 0);
         logger.println(String("tx/rx: ") + txCount + "/" + rxCount);
         const long txCps = txCount * (1000000.0 / interval);
         const long rxCps = rxCount * (1000000.0 / interval);
-        logger.println(effTxTxt + 10 * txCps + "bps, "
-            + effRxTxt + 10 * rxCps + "bps, "
+        logger.print(effTxTxt + wordBits * txCps + "bps, "
+            + effRxTxt + wordBits * rxCps + "bps, "
             + rxErrors + " errors (" + 100.0 * rxErrors / (!rxErrors ? 1 : rxCount) + "%)");
+        if (0 != (swSerialConfig & 070))
+        {
+            logger.println(String(" (") + rxParityErrors + " parity errors)");
+        }
+        else
+        {
+            logger.println();
+        }
         txCount = 0;
         rxCount = 0;
         rxErrors = 0;
+        rxParityErrors = 0;
         expected = -1;
         // resync
         delay(static_cast<uint32_t>(1000 * 10 * BLOCKSIZE / IUTBITRATE * 16));