125 lines
6.6 KiB
Markdown
125 lines
6.6 KiB
Markdown
# EspSoftwareSerial
|
|
|
|
## Implementation of the Arduino software serial library for the ESP8266 / ESP32
|
|
|
|
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 ``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. 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.
|
|
|
|
## 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
|
|
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 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``.
|
|
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.
|
|
|
|
## 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
|
|
|
|
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 SoftwareSerial 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
|
|
```
|