From 156a2dd3d971b25e1ed480deb93000a1761f8381 Mon Sep 17 00:00:00 2001 From: "Dirk O. Kaar" Date: Sat, 4 Mar 2023 22:09:55 +0100 Subject: [PATCH] Some renaming after review feedback. --- README.md | 21 +++++++++++---------- examples/bitpattern/bitpattern.ino | 6 +++--- examples/loopback/loopback.ino | 28 ++++++++++++++-------------- examples/onewiretest/onewiretest.ino | 12 ++++++------ examples/onreceive/onreceive.ino | 4 ++-- examples/repeater/repeater.ino | 20 ++++++++++---------- examples/swsertest/swsertest.ino | 10 +++++----- keywords.txt | 3 ++- src/SoftwareSerial.cpp | 2 +- src/SoftwareSerial.h | 16 ++++++++-------- 10 files changed, 62 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 9fd61b2..37b106c 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ 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 +`EspSoftwareSerial::UART::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 @@ -33,7 +34,7 @@ This library supports ESP8266, ESP32, ESP32-S2 and ESP32-C3 devices. 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 `EspSoftwareSerial::UART` 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. @@ -75,8 +76,8 @@ chances are that you can reduce the `isrBufCapacity` footprint without losing da 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` +## EspSoftwareSerial::Config and parity +The configuration of the data stream is done via a `EspSoftwareSerial::Config` 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 @@ -92,7 +93,7 @@ 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 +up EspSoftwareSerial::UART 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 @@ -100,7 +101,7 @@ To detect incoming bytes with the parity bit set (MARK parity), use the `MARK` as the second argument when writing, e.g. `write(ch, SWSERIAL_PARITY_MARK)`. ## Checking for correct pin selection / configuration -In general, most pins on the ESP8266 and ESP32 devices can be used by SoftwareSerial, +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 careful handling to prevent undesirable situations, for example they are connected to the on-board SPI flash memory or they are used to determine boot and programming modes @@ -112,7 +113,7 @@ in sections 2.2 (Pin Descriptions) and 2.4 (Strapping pins). There is a discussi dedicated to the use of GPIO12 in this [note about GPIO12](https://github.com/espressif/esp-idf/tree/release/v3.2/examples/storage/sd_card#note-about-gpio12). Refer to the `isValidPin()`, `isValidRxPin()` and `isValidTxPin()` -functions in the `SoftwareSerialGpioCapabilities` class for the GPIO restrictions +functions in the `EspSoftwareSerial::GpioCapabilities` class for the GPIO restrictions enforced by this library by default. The easiest and safest method is to test the object returned at runtime, to see if @@ -124,7 +125,7 @@ it is valid. For example: #define MYPORT_TX 12 #define MYPORT_RX 13 -SoftwareSerial myPort; +EspSoftwareSerial::UART myPort; [...] @@ -132,7 +133,7 @@ Serial.begin(115200); // Standard hardware serial port myPort.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 SoftwareSerial pin configuration, check config"); + Serial.println("Invalid EspSoftwareSerial pin configuration, check config"); while (1) { // Don't continue with invalid configuration delay (1000); } @@ -155,7 +156,7 @@ 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: +To update esp8266/arduino EspSoftwareSerial submodule to lastest master: Clean it (optional): ```shell diff --git a/examples/bitpattern/bitpattern.ino b/examples/bitpattern/bitpattern.ino index 8bbc261..10c1045 100644 --- a/examples/bitpattern/bitpattern.ino +++ b/examples/bitpattern/bitpattern.ino @@ -18,9 +18,9 @@ #endif #endif -SoftwareSerial::UART swSer; +EspSoftwareSerial::UART swSer; #ifdef ESP8266 -auto logSer = SoftwareSerial::UART(-1, TX); +auto logSer = EspSoftwareSerial::UART(-1, TX); auto hwSer = Serial; #else auto logSer = Serial; @@ -39,7 +39,7 @@ void setup() { #endif logSer.begin(115200); logSer.println(PSTR("\nOne Wire Half Duplex Bitpattern and Datarate Test")); - swSer.begin(TESTBPS, SoftwareSerial::SERIAL_8N1, D6, D5); + swSer.begin(TESTBPS, EspSoftwareSerial::SERIAL_8N1, D6, D5); swSer.enableIntTx(true); logSer.println(PSTR("Tx on swSer")); } diff --git a/examples/loopback/loopback.ino b/examples/loopback/loopback.ino index 7e10411..6495ae8 100644 --- a/examples/loopback/loopback.ino +++ b/examples/loopback/loopback.ino @@ -1,18 +1,18 @@ #include // On ESP8266: -// Local SoftwareSerial loopback, connect D5 (rx) and D6 (tx). +// Local EspSoftwareSerial loopback, connect D5 (rx) and D6 (tx). // For local hardware loopback, connect D5 to D8 (tx), D6 to D7 (rx). // For hardware send/sink, connect D7 (rx) and D8 (tx). // Hint: The logger is run at 9600bps such that enableIntTx(true) can remain unchanged. Blocking -// interrupts severely impacts the ability of the SoftwareSerial devices to operate concurrently +// interrupts severely impacts the ability of the EspSoftwareSerial devices to operate concurrently // and/or in duplex mode. // Operating in software serial full duplex mode, runs at 19200bps and few errors (~2.5%). // Operating in software serial half duplex mode (both loopback and repeater), // runs at 57600bps with nearly no errors. // Operating loopback in full duplex, and repeater in half duplex, runs at 38400bps with nearly no errors. // On ESP32: -// For SoftwareSerial or hardware send/sink, connect D5 (rx) and D6 (tx). +// For EspSoftwareSerial or hardware send/sink, connect D5 (rx) and D6 (tx). // Hardware Serial2 defaults to D4 (rx), D3 (tx). // For local hardware loopback, connect D5 (rx) to D3 (tx), D6 (tx) to D4 (rx). @@ -47,10 +47,10 @@ constexpr int IUTBITRATE = 19200; #endif #if defined(ESP8266) -constexpr SoftwareSerial::Config swSerialConfig = SoftwareSerial::SERIAL_8E1; +constexpr EspSoftwareSerial::Config swSerialConfig = EspSoftwareSerial::SERIAL_8E1; constexpr SerialConfig hwSerialConfig = ::SERIAL_8E1; #elif defined(ESP32) -constexpr SoftwareSerial::Config swSerialConfig = SoftwareSerial::SERIAL_8E1; +constexpr EspSoftwareSerial::Config swSerialConfig = EspSoftwareSerial::SERIAL_8E1; constexpr uint32_t hwSerialConfig = ::SERIAL_8E1; #else constexpr unsigned swSerialConfig = 3; @@ -72,27 +72,27 @@ constexpr int ReportInterval = IUTBITRATE / 8; #if defined(ESP8266) #if defined(HWLOOPBACK) || defined(HWSOURCESWSINK) HardwareSerial& hwSerial(Serial); -SoftwareSerial::UART serialIUT; -SoftwareSerial::UART logger; +EspSoftwareSerial::UART serialIUT; +EspSoftwareSerial::UART logger; #elif defined(HWSOURCESINK) HardwareSerial& serialIUT(Serial); -SoftwareSerial::UART logger; +EspSoftwareSerial::UART logger; #else -SoftwareSerial::UART serialIUT; +EspSoftwareSerial::UART serialIUT; HardwareSerial& logger(Serial); #endif #elif defined(ESP32) #if defined(HWLOOPBACK) || defined (HWSOURCESWSINK) HardwareSerial& hwSerial(Serial2); -SoftwareSerial::UART serialIUT; +EspSoftwareSerial::UART serialIUT; #elif defined(HWSOURCESINK) HardwareSerial& serialIUT(Serial2); #else -SoftwareSerial::UART serialIUT; +EspSoftwareSerial::UART serialIUT; #endif HardwareSerial& logger(Serial); #else -SoftwareSerial::UART serialIUT(14, 12); +EspSoftwareSerial::UART serialIUT(14, 12); HardwareSerial& logger(Serial); #endif @@ -102,7 +102,7 @@ void setup() { Serial.begin(IUTBITRATE, hwSerialConfig, ::SERIAL_FULL, 1, invert); Serial.swap(); Serial.setRxBufferSize(2 * BLOCKSIZE); - logger.begin(9600, SoftwareSerial::SERIAL_8N1, -1, TX); + logger.begin(9600, EspSoftwareSerial::SERIAL_8N1, -1, TX); #else logger.begin(9600); #endif @@ -134,7 +134,7 @@ void setup() { logger.begin(9600); #endif - logger.println(PSTR("Loopback example for EspSoftwareSerial")); + logger.println(PSTR("Loopback example for EspEspSoftwareSerial")); start = micros(); txCount = 0; diff --git a/examples/onewiretest/onewiretest.ino b/examples/onewiretest/onewiretest.ino index 00ca5c1..2f437ba 100644 --- a/examples/onewiretest/onewiretest.ino +++ b/examples/onewiretest/onewiretest.ino @@ -10,17 +10,17 @@ #endif #endif -SoftwareSerial::UART swSer1; -SoftwareSerial::UART swSer2; +EspSoftwareSerial::UART swSer1; +EspSoftwareSerial::UART swSer2; void setup() { delay(2000); Serial.begin(115200); Serial.println(PSTR("\nOne Wire Half Duplex Serial Tester")); - swSer1.begin(115200, SoftwareSerial::SERIAL_8N1, D6, D6, false, 256); + swSer1.begin(115200, EspSoftwareSerial::SERIAL_8N1, D6, D6, false, 256); // high speed half duplex, turn off interrupts during tx swSer1.enableIntTx(false); - swSer2.begin(115200, SoftwareSerial::SERIAL_8N1, D5, D5, false, 256); + swSer2.begin(115200, EspSoftwareSerial::SERIAL_8N1, D5, D5, false, 256); // high speed half duplex, turn off interrupts during tx swSer2.enableIntTx(false); } @@ -36,7 +36,7 @@ void loop() { } -void checkSwSerial(SoftwareSerial::UART* ss) { +void checkSwSerial(EspSoftwareSerial::UART* ss) { byte ch; while (!Serial.available()); ss->enableTx(true); @@ -45,7 +45,7 @@ void checkSwSerial(SoftwareSerial::UART* ss) { ss->write(ch); } ss->enableTx(false); - // wait 1 second for the reply from SoftwareSerial if any + // wait 1 second for the reply from EspSoftwareSerial if any delay(1000); if (ss->available()) { Serial.print(PSTR("\nResult:")); diff --git a/examples/onreceive/onreceive.ino b/examples/onreceive/onreceive.ino index c178f0a..e737ded 100644 --- a/examples/onreceive/onreceive.ino +++ b/examples/onreceive/onreceive.ino @@ -16,7 +16,7 @@ #define BAUD_RATE 115200 #define MAX_FRAMEBITS (1 + 8 + 1 + 2) -SoftwareSerial::UART testSerial; +EspSoftwareSerial::UART testSerial; // Becomes set from ISR / IRQ callback function. std::atomic rxPending(false); @@ -30,7 +30,7 @@ void setup() { Serial.begin(115200); Serial.setDebugOutput(false); Serial.swap(); - testSerial.begin(BAUD_RATE, SoftwareSerial::SERIAL_8N1, RX, TX); + testSerial.begin(BAUD_RATE, EspSoftwareSerial::SERIAL_8N1, RX, TX); // Only half duplex this way, but reliable TX timings for high bps testSerial.enableIntTx(false); testSerial.onReceive(receiveHandler); diff --git a/examples/repeater/repeater.ino b/examples/repeater/repeater.ino index 9f0cf37..9f9132d 100644 --- a/examples/repeater/repeater.ino +++ b/examples/repeater/repeater.ino @@ -1,10 +1,10 @@ #include // On ESP8266: -// SoftwareSerial loopback for remote source (loopback.ino), or hardware loopback. +// EspSoftwareSerial loopback for remote source (loopback.ino), or hardware loopback. // Connect source D5 (rx) to local D8 (tx), source D6 (tx) to local D7 (rx). // Hint: The logger is run at 9600bps such that enableIntTx(true) can remain unchanged. Blocking -// interrupts severely impacts the ability of the SoftwareSerial devices to operate concurrently +// interrupts severely impacts the ability of the EspSoftwareSerial devices to operate concurrently // and/or in duplex mode. // On ESP32: // For software or hardware loopback, connect source rx to local D8 (tx), source tx to local D7 (rx). @@ -37,10 +37,10 @@ constexpr int IUTBITRATE = 19200; #endif #if defined(ESP8266) -constexpr SoftwareSerial::Config swSerialConfig = SoftwareSerial::SERIAL_8E1; +constexpr EspSoftwareSerial::Config swSerialConfig = EspSoftwareSerial::SERIAL_8E1; constexpr SerialConfig hwSerialConfig = ::SERIAL_8E1; #elif defined(ESP32) -constexpr SoftwareSerial::Config swSerialConfig = SoftwareSerial::SERIAL_8E1; +constexpr EspSoftwareSerial::Config swSerialConfig = EspSoftwareSerial::SERIAL_8E1; constexpr uint32_t hwSerialConfig = ::SERIAL_8E1; #else constexpr unsigned swSerialConfig = 3; @@ -60,20 +60,20 @@ constexpr int ReportInterval = IUTBITRATE / 8; #if defined(ESP8266) #if defined(HWLOOPBACK) HardwareSerial& repeater(Serial); -SoftwareSerial::UART logger; +EspSoftwareSerial::UART logger; #else -SoftwareSerial::UART repeater; +EspSoftwareSerial::UART repeater; HardwareSerial& logger(Serial); #endif #elif defined(ESP32) #if defined(HWLOOPBACK) HardwareSerial& repeater(Serial2); #else -SoftwareSerial::UART repeater; +EspSoftwareSerial::UART repeater; #endif HardwareSerial& logger(Serial); #else -SoftwareSerial::UART repeater(14, 12); +EspSoftwareSerial::UART repeater(14, 12); HardwareSerial& logger(Serial); #endif @@ -83,7 +83,7 @@ void setup() { repeater.begin(IUTBITRATE, hwSerialConfig, ::SERIAL_FULL, 1, invert); repeater.swap(); repeater.setRxBufferSize(2 * BLOCKSIZE); - logger.begin(9600, SoftwareSerial::SERIAL_8N1, -1, TX); + logger.begin(9600, EspSoftwareSerial::SERIAL_8N1, -1, TX); #else repeater.begin(IUTBITRATE, swSerialConfig, D7, D8, invert, 4 * BLOCKSIZE); #ifdef HALFDUPLEX @@ -107,7 +107,7 @@ void setup() { logger.begin(9600); #endif - logger.println(PSTR("Repeater example for EspSoftwareSerial")); + logger.println(PSTR("Repeater example for EspEspSoftwareSerial")); start = micros(); rxCount = 0; seqErrors = 0; diff --git a/examples/swsertest/swsertest.ino b/examples/swsertest/swsertest.ino index db845a1..bfb52b9 100644 --- a/examples/swsertest/swsertest.ino +++ b/examples/swsertest/swsertest.ino @@ -37,9 +37,9 @@ #ifndef SWAPSERIAL auto& usbSerial = Serial; -SoftwareSerial::UART testSerial; +EspSoftwareSerial::UART testSerial; #else -SoftwareSerial::UART usbSerial; +EspSoftwareSerial::UART usbSerial; auto& testSerial = Serial; #endif @@ -48,15 +48,15 @@ void setup() { usbSerial.begin(115200); // Important: the buffer size optimizations here, in particular the isrBufSize (11) that is only sufficiently // large to hold a single word (up to start - 8 data - parity - stop), are on the basis that any char written - // to the loopback SoftwareSerial adapter gets read before another write is performed. + // to the loopback EspSoftwareSerial adapter gets read before another write is performed. // Block writes with a size greater than 1 would usually fail. Do not copy this into your own project without // reading the documentation. - testSerial.begin(BAUD_RATE, SoftwareSerial::SERIAL_8N1, D7, D8, false, 95, 11); + testSerial.begin(BAUD_RATE, EspSoftwareSerial::SERIAL_8N1, D7, D8, false, 95, 11); #else testSerial.begin(115200); testSerial.setDebugOutput(false); testSerial.swap(); - usbSerial.begin(BAUD_RATE, SoftwareSerial::SERIAL_8N1, RX, TX, false, 95); + usbSerial.begin(BAUD_RATE, EspSoftwareSerial::SERIAL_8N1, RX, TX, false, 95); #endif usbSerial.println(PSTR("\nSoftware serial test started")); diff --git a/keywords.txt b/keywords.txt index d668cc2..df0426d 100644 --- a/keywords.txt +++ b/keywords.txt @@ -1,5 +1,5 @@ ####################################### -# Syntax Coloring Map for SoftwareSerial +# Syntax Coloring Map for EspSoftwareSerial # (esp8266) ####################################### @@ -7,6 +7,7 @@ # Datatypes (KEYWORD1) ####################################### +EspSoftwareSerial KEYWORD1 SoftwareSerial KEYWORD1 ####################################### diff --git a/src/SoftwareSerial.cpp b/src/SoftwareSerial.cpp index 6165795..4ed616b 100644 --- a/src/SoftwareSerial.cpp +++ b/src/SoftwareSerial.cpp @@ -23,7 +23,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #include "SoftwareSerial.h" #include -using namespace SoftwareSerial; +using namespace EspSoftwareSerial; constexpr bool GpioCapabilities::isValidPin(int8_t pin) { #if defined(ESP8266) diff --git a/src/SoftwareSerial.h b/src/SoftwareSerial.h index b7b0004..ba43431 100644 --- a/src/SoftwareSerial.h +++ b/src/SoftwareSerial.h @@ -1,7 +1,5 @@ /* -SoftwareSerial.h - -SoftwareSerial.cpp - Implementation of the Arduino software serial for ESP8266/ESP32. +SoftwareSerial.h - Implementation of the Arduino software serial for ESP8266/ESP32. Copyright (c) 2015-2016 Peter Lerup. All rights reserved. Copyright (c) 2018-2019 Dirk O. Kaar. All rights reserved. @@ -27,7 +25,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #include "circular_queue/circular_queue.h" #include -namespace SoftwareSerial { +namespace EspSoftwareSerial { class GpioCapabilities { public: @@ -315,7 +313,9 @@ class UART : private GpioCapabilities, public Stream { Delegate m_rxHandler; }; -}; // namespace SoftwareSerial +}; // namespace EspSoftwareSerial + +using SoftwareSerial = EspSoftwareSerial::UART; // The template member functions below must be in IRAM, but due to a bug GCC doesn't currently // honor the attribute. Instead, it is possible to do explicit specialization and adorn @@ -325,9 +325,9 @@ class UART : private GpioCapabilities, public Stream { extern template delegate::detail::DelegateImpl::operator bool() const; extern template void delegate::detail::DelegateImpl::operator()() const; -extern template size_t circular_queue::available() const; -extern template bool circular_queue::push(uint32_t&&); -extern template bool circular_queue::push(const uint32_t&); +extern template size_t circular_queue::available() const; +extern template bool circular_queue::push(uint32_t&&); +extern template bool circular_queue::push(const uint32_t&); #endif // __SoftwareSerial_h