lzj_branch
parent
d3c5d007a8
commit
37bade9cb3
@ -0,0 +1,171 @@
|
||||
# EspSoftwareSerial
|
||||
|
||||
## Implementation of the Arduino software serial library for the ESP8266 / ESP32 family
|
||||
|
||||
This fork implements interrupt service routine best practice.
|
||||
In the receive interrupt, instead of blocking for whole bytes
|
||||
at a time - voiding any near-realtime behavior of the CPU - only level
|
||||
change and timestamp are recorded. The more time consuming phase
|
||||
detection and byte assembly are done in the main code.
|
||||
|
||||
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
|
||||
`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
|
||||
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.
|
||||
|
||||
Please note that due to the fact that the ESPs always have other activities
|
||||
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.
|
||||
|
||||
This library supports ESP8266, ESP32, ESP32-S2 and ESP32-C3 devices.
|
||||
|
||||
## Resource optimization
|
||||
|
||||
The memory footprint can be optimized to just fit the amount of expected
|
||||
incoming asynchronous data.
|
||||
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.
|
||||
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 buffer
|
||||
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 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
|
||||
edge detection buffer. In turn, as explained before, each single write call
|
||||
also causes received bit assembly to be performed, promoting these bits from
|
||||
the 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 because
|
||||
of using block writing, more than a single octet is received, there will be a
|
||||
need for more than 10 fields in the signal edge detection buffer.
|
||||
The necessary capacity of the octet buffer only depends on the amount of incoming
|
||||
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 95 (93 characters net plus two tolerance).
|
||||
The signal edge detection buffer capacity (`isrBufCapacity`) is 11, as each
|
||||
single octet can have up to 11 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`.
|
||||
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,
|
||||
and each time you call read to fetch from the octet buffer, you reduce the
|
||||
need for space there.
|
||||
|
||||
## 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
|
||||
be used, e.g. `SWSERIAL_7E2`. If using EVEN or ODD parity, any parity errors
|
||||
can be detected with the `readParity()` and `parityEven()` or `parityOdd()`
|
||||
functions respectively. Note that the result of `readParity()` always applies
|
||||
to the preceding `read()` or `peek()` call, and is undefined if they report
|
||||
no data or an error.
|
||||
|
||||
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 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
|
||||
`readParity()` function. To send a byte with the parity bit set, just add
|
||||
`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 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
|
||||
after powerup or brownouts. These pins are not able to be configured by this library.
|
||||
|
||||
The exact list for each device can be found in the
|
||||
[ESP32 data sheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
|
||||
in sections 2.2 (Pin Descriptions) and 2.4 (Strapping pins). There is a discussion
|
||||
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 `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
|
||||
it is valid. For example:
|
||||
|
||||
```
|
||||
#include <SoftwareSerial.h>
|
||||
|
||||
#define MYPORT_TX 12
|
||||
#define MYPORT_RX 13
|
||||
|
||||
EspSoftwareSerial::UART myPort;
|
||||
|
||||
[...]
|
||||
|
||||
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 EspSoftwareSerial pin configuration, check config");
|
||||
while (1) { // Don't continue with invalid configuration
|
||||
delay (1000);
|
||||
}
|
||||
}
|
||||
|
||||
[...]
|
||||
```
|
||||
|
||||
## Using and updating EspSoftwareSerial in the esp8266com/esp8266 Arduino build environment
|
||||
|
||||
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
|
||||
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, 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 EspSoftwareSerial submodule to lastest master:
|
||||
|
||||
Clean it (optional):
|
||||
```shell
|
||||
$ rm -rf libraries/SoftwareSerial
|
||||
$ git submodule update --init
|
||||
```
|
||||
Now update it:
|
||||
```shell
|
||||
$ cd libraries/SoftwareSerial
|
||||
$ git checkout master
|
||||
$ git pull
|
||||
```
|
||||
@ -0,0 +1,71 @@
|
||||
#include "SoftwareSerial.h"
|
||||
|
||||
#ifndef D5
|
||||
#if defined(ESP8266)
|
||||
#define D8 (15)
|
||||
#define D5 (14)
|
||||
#define D7 (13)
|
||||
#define D6 (12)
|
||||
#define RX (3)
|
||||
#define TX (1)
|
||||
#elif defined(ESP32)
|
||||
#define D8 (5)
|
||||
#define D5 (18)
|
||||
#define D7 (23)
|
||||
#define D6 (19)
|
||||
#define RX (3)
|
||||
#define TX (1)
|
||||
#endif
|
||||
#endif
|
||||
|
||||
EspSoftwareSerial::UART swSer;
|
||||
#ifdef ESP8266
|
||||
auto logSer = EspSoftwareSerial::UART(-1, TX);
|
||||
auto hwSer = Serial;
|
||||
#else
|
||||
auto logSer = Serial;
|
||||
auto hwSer = Serial1;
|
||||
#endif
|
||||
|
||||
constexpr uint32_t TESTBPS = 115200;
|
||||
|
||||
void setup() {
|
||||
delay(2000);
|
||||
#ifdef ESP8266
|
||||
hwSer.begin(TESTBPS, ::SERIAL_8N1);
|
||||
hwSer.swap();
|
||||
#else
|
||||
hwSer.begin(TESTBPS, ::SERIAL_8N1, D6, D5);
|
||||
#endif
|
||||
logSer.begin(115200);
|
||||
logSer.println(PSTR("\nOne Wire Half Duplex Bitpattern and Datarate Test"));
|
||||
swSer.begin(TESTBPS, EspSoftwareSerial::SWSERIAL_8N1, D6, D5);
|
||||
swSer.enableIntTx(true);
|
||||
logSer.println(PSTR("Tx on swSer"));
|
||||
}
|
||||
|
||||
uint8_t val = 0xff;
|
||||
|
||||
void loop() {
|
||||
swSer.write((uint8_t)0x00);
|
||||
swSer.write(val);
|
||||
swSer.write(val);
|
||||
auto start = ESP.getCycleCount();
|
||||
int rxCnt = 0;
|
||||
while (ESP.getCycleCount() - start < ESP.getCpuFreqMHz() * 1000000 / 10) {
|
||||
if (hwSer.available()) {
|
||||
auto rxVal = hwSer.read();
|
||||
if ((!rxCnt && rxVal) || (rxCnt && rxVal != val)) {
|
||||
logSer.printf(PSTR("Rx bit error: tx = 0x%02x, rx = 0x%02x\n"), val, rxVal);
|
||||
}
|
||||
++rxCnt;
|
||||
}
|
||||
}
|
||||
if (rxCnt != 3) {
|
||||
logSer.printf(PSTR("Rx cnt error, tx = 0x%02x\n"), val);
|
||||
}
|
||||
++val;
|
||||
if (!val) {
|
||||
logSer.println("Starting over");
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,74 @@
|
||||
// circular_mp_test.cpp : This file contains the 'main' function. Program execution begins and ends there.
|
||||
//
|
||||
|
||||
#include <iostream>
|
||||
#include <thread>
|
||||
#include <chrono>
|
||||
#include <vector>
|
||||
#include "circular_queue/circular_queue_mp.h"
|
||||
|
||||
struct qitem
|
||||
{
|
||||
// produer id
|
||||
int id;
|
||||
// monotonic increasing value
|
||||
int val = 0;
|
||||
};
|
||||
|
||||
constexpr int TOTALMESSAGESTARGET = 60000000;
|
||||
// reserve one thread as consumer
|
||||
const auto THREADS = std::thread::hardware_concurrency() / 2 - 1;
|
||||
const int MESSAGES = TOTALMESSAGESTARGET / THREADS;
|
||||
circular_queue<std::thread> threads(THREADS);
|
||||
circular_queue_mp<qitem> queue(threads.capacity()* MESSAGES / 10);
|
||||
std::vector<int> checks(threads.capacity());
|
||||
|
||||
int main()
|
||||
{
|
||||
using namespace std::chrono_literals;
|
||||
std::cerr << "Utilizing " << THREADS << " producer threads" << std::endl;
|
||||
for (int i = 0; i < threads.capacity(); ++i)
|
||||
{
|
||||
threads.push(std::thread([i]() {
|
||||
for (int c = 0; c < MESSAGES;)
|
||||
{
|
||||
// simulate some load
|
||||
auto start = std::chrono::system_clock::now();
|
||||
while (std::chrono::system_clock::now() - start < 1us);
|
||||
if (queue.push({ i, c }))
|
||||
{
|
||||
++c;
|
||||
}
|
||||
else
|
||||
{
|
||||
//std::cerr << "queue full" << std::endl;
|
||||
//std::this_thread::sleep_for(10us);
|
||||
}
|
||||
//if (0 == c % 10000) std::this_thread::sleep_for(10us);
|
||||
}
|
||||
}));
|
||||
}
|
||||
for (int o = 0; o < threads.available() * MESSAGES; ++o)
|
||||
{
|
||||
auto now = std::chrono::system_clock::now();
|
||||
while (!queue.available())
|
||||
{
|
||||
auto starvedFor = std::chrono::system_clock::now() - now;
|
||||
if (starvedFor > 20s) std::cerr << "queue starved for > 20s" << std::endl;
|
||||
//std::this_thread::sleep_for(20ms);
|
||||
}
|
||||
auto item = queue.pop();
|
||||
if (checks[item.id] != item.val)
|
||||
{
|
||||
std::cerr << "item mismatch" << std::endl;
|
||||
}
|
||||
checks[item.id] = item.val + 1;
|
||||
if (0 == item.val % 1000) std::this_thread::sleep_for(100us);
|
||||
}
|
||||
while (threads.available())
|
||||
{
|
||||
auto thread = threads.pop();
|
||||
thread.join();
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
Loading…
Reference in new issue