Merge pull request #24 from bxparks/develop

merge 1.2.3 into master

CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
 * Unreleased
+* 1.2.3 (2021-01-19)
+    * Add official support for STM32 by validating on a Blue Pill board.
+    * Add scripts to `AutoBenchmark` to automate data collection.
+    * Update `MemoryBenchmark` and `AutoBenchmark` tables with STM32; re-add
+      Teensy 3.2 benchmarks now that I'm able to upload again.
+    * No functional change in this release.
 * 1.2.2 (2020-12-20)
     * Add generic definition of `FPSTR()` macro for unrecognized platforms.
       Allows code with `ARDUINO_ARCH_STM32` dependencies to compile. I will

README.md

@@ -46,11 +46,12 @@ others (in my opinion of course):
     * the `CoroutineScheduler` consumes only 2 bytes (8-bit) or 4 bytes (32-bit)
       no matter how many coroutines are active
 * extremely fast context switching
-    * ~6 microseconds on a 16 MHz ATmega328P
-    * ~2.9 microseconds on a 48 MHz SAMD21
-    * ~1.7 microseconds on a 80 MHz ESP8266
+    * ~5.3 microseconds on a 16 MHz ATmega328P
+    * ~2.5 microseconds on a 48 MHz SAMD21
+    * ~1.8 microseconds on a 72 MHz STM32
+    * ~1.5 microseconds on a 80 MHz ESP8266
     * ~0.4 microseconds on a 240 MHz ESP32
-    * 0.7-1.1 microseconds on 96 MHz Teensy 3.2 (depending on compiler settings)
+    * ~1.0 microseconds on 96 MHz Teensy 3.2 (depending on compiler settings)
 * uses the [computed goto](https://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html)
   feature of the GCC compiler (also supported by Clang) to avoid the
   [Duff's Device](https://en.wikipedia.org/wiki/Duff%27s_device) hack
@@ -81,7 +82,7 @@ AceRoutine is a self-contained library that works on any platform supporting the
 Arduino API (AVR, Teensy, ESP8266, ESP32, etc), and it provides a handful of
 additional macros that can reduce boilerplate code.
 
-**Version**: 1.2.2 (2020-12-20)
+**Version**: 1.2.3 (2021-01-19)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -455,8 +456,8 @@ etc) for a handful of AceRoutine features. Here are some highlights:
 * AVR (e.g. Nano)
     * 1 Coroutine: 1098 bytes
     * 2 Coroutines: 1326 bytes
-    * `CoroutineScheduler()` + 1 Coroutine: 1238 bytes
-    * `CoroutineScheduler()` + 2 Coroutines: 1388 bytes
+    * `CoroutineScheduler()` + 1 Coroutine: 1240 bytes
+    * `CoroutineScheduler()` + 2 Coroutines: 1390 bytes
 * ESP8266
     * 1 Coroutine: 680 bytes
     * 2 Coroutines: 908 bytes
@@ -466,21 +467,45 @@ etc) for a handful of AceRoutine features. Here are some highlights:
 <a name="CPU"></a>
 ### CPU
 
-See [examples/AutoBenchmark](examples/AutoBenchmark).
+See [examples/AutoBenchmark](examples/AutoBenchmark). In summary, the overhead
+of AceRoutine context switching is about 5 micros on an 8-bit AVR, to as low as
+0.41 micros on a 32-bit ESP32.
 
 <a name="SystemRequirements"></a>
 ## System Requirements
 
+### Hardware
+
+The library has been extensively tested on the following boards:
+
+* Arduino Nano clone (16 MHz ATmega328P)
+* SparkFun Pro Micro clone (16 MHz ATmega32U4)
+* SAMD21 M0 Mini (48 MHz ARM Cortex-M0+)
+* STM32 Blue Pill (STM32F103C8, 72 MHz ARM Cortex-M3)
+* NodeMCU 1.0 (ESP-12E module, 80 MHz ESP8266)
+* WeMos D1 Mini (ESP-12E module, 80 MHz ESP8266)
+* ESP32 dev board (ESP-WROOM-32 module, 240 MHz dual core Tensilica LX6)
+* Teensy 3.2 (96 MHz ARM Cortex-M4)
+
+I will occasionally test on the following hardware as a sanity check:
+
+* Arduino Pro Mini clone (16 MHz ATmega328P)
+* Mini Mega 2560 (Arduino Mega 2560 compatible, 16 MHz ATmega2560)
+* Teensy LC (48 MHz ARM Cortex-M0+)
+
 ### Tool Chain
 
 This library was developed and tested using:
 * [Arduino IDE 1.8.13](https://www.arduino.cc/en/Main/Software)
+* [Arduino CLI 0.14.0](https://arduino.github.io/arduino-cli)
 * [Arduino AVR Boards 1.8.3](https://github.com/arduino/ArduinoCore-avr)
-* [Arduino SAMD Boards 1.8.6](https://github.com/arduino/ArduinoCore-samd)
+* [Arduino SAMD Boards 1.8.9](https://github.com/arduino/ArduinoCore-samd)
 * [SparkFun AVR Boards 1.1.13](https://github.com/sparkfun/Arduino_Boards)
+* [SparkFun SAMD Boards 1.8.1](https://github.com/sparkfun/Arduino_Boards)
+* [STM32duino 1.9.0](https://github.com/stm32duino/Arduino_Core_STM32)
 * [ESP8266 Arduino 2.7.4](https://github.com/esp8266/Arduino)
 * [ESP32 Arduino 1.0.4](https://github.com/espressif/arduino-esp32)
-* [Teensydino 1.53.beta](https://www.pjrc.com/teensy/td_download.html)
+* [Teensydino 1.53](https://www.pjrc.com/teensy/td_download.html)
 
 It should work with [PlatformIO](https://platformio.org/) but I have
 not tested it.
@@ -493,23 +518,6 @@ the [UnixHostDuino](https://github.com/bxparks/UnixHostDuino) emulation layer.
 I use Ubuntu 18.04 and 20.04 for most of my development and sometimes do sanity
 checks on MacOS 10.14.5.
 
-### Hardware
-
-The library has been extensively tested on the following boards:
-
-* Arduino Nano clone (16 MHz ATmega328P)
-* Arduino Pro Mini clone (16 MHz ATmega328P)
-* Arduino Pro Micro clone (16 MHz ATmega32U4)
-* SAMD21 M0 Mini (48 MHz ARM Cortex-M0+) (compatible with Arduino Zero)
-* NodeMCU 1.0 clone (ESP-12E module, 80 MHz ESP8266)
-* ESP32 dev board (ESP-WROOM-32 module, 240 MHz dual core Tensilica LX6)
-* Teensy 3.2 (72 MHz ARM Cortex-M4)
-
-I will occasionally test on the following hardware as a sanity check:
-
-* Teensy LC (48 MHz ARM Cortex-M0+)
-* Mini Mega 2560 (Arduino Mega 2560 compatible, 16 MHz ATmega2560)
-
 <a name="License"></a>
 ## License
 
@@ -518,6 +526,10 @@ I will occasionally test on the following hardware as a sanity check:
 <a name="Feedback"></a>
 ## Feedback and Support
 
+If you find this library useful, consider starring this project on GitHub. The
+stars will let me prioritize the more popular libraries over the less popular
+ones.
+
 If you have any questions, comments, bug reports, or feature requests, please
 file a GitHub ticket instead of emailing me unless the content is sensitive.
 (The problem with email is that I cannot reference the email conversation when

USER_GUIDE.md

@@ -4,7 +4,7 @@ See the [README.md](README.md) for installation instructions and other
 background information. This document describes how to use the library once it
 is installed.
 
-**Version**: 1.2.2 (2020-12-20)
+**Version**: 1.2.3 (2021-01-19)
 
 ## Table of Contents
 

docs/doxygen.cfg

@@ -38,7 +38,7 @@ PROJECT_NAME           = "AceRoutine"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.2.2
+PROJECT_NUMBER         = 1.2.3
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

docs/html/AceRoutine_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>
@@ -103,8 +103,8 @@
 <div class="line"><a name="l00041"></a><span class="lineno">   41</span>&#160;<span class="preprocessor">#include &quot;ace_routine/Channel.h&quot;</span></div>
 <div class="line"><a name="l00042"></a><span class="lineno">   42</span>&#160; </div>
 <div class="line"><a name="l00043"></a><span class="lineno">   43</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00044"></a><span class="lineno">   44</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION 10202</span></div>
-<div class="line"><a name="l00045"></a><span class="lineno">   45</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION_STRING &quot;1.2.2&quot;</span></div>
+<div class="line"><a name="l00044"></a><span class="lineno">   44</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION 10203</span></div>
+<div class="line"><a name="l00045"></a><span class="lineno">   45</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION_STRING &quot;1.2.3&quot;</span></div>
 <div class="line"><a name="l00046"></a><span class="lineno">   46</span>&#160; </div>
 <div class="line"><a name="l00047"></a><span class="lineno">   47</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->

docs/html/Channel_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/CoroutineScheduler_8cpp_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/CoroutineScheduler_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/Coroutine_8cpp_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>
@@ -229,7 +229,7 @@
 <div class="ttc" id="aclassace__routine_1_1Coroutine_html_a79844c12576ff2fd2065c5f5e4b422c8"><div class="ttname"><a href="classace__routine_1_1Coroutine.html#a79844c12576ff2fd2065c5f5e4b422c8">ace_routine::Coroutine::kDelayTypeSeconds</a></div><div class="ttdeci">static const uint8_t kDelayTypeSeconds</div><div class="ttdoc">Delay using units of seconds.</div><div class="ttdef"><b>Definition:</b> <a href="Coroutine_8h_source.html#l00503">Coroutine.h:503</a></div></div>
 <div class="ttc" id="aclassace__routine_1_1Coroutine_html_ad29d0f43128b49c48a71a167331dac51"><div class="ttname"><a href="classace__routine_1_1Coroutine.html#ad29d0f43128b49c48a71a167331dac51">ace_routine::Coroutine::resume</a></div><div class="ttdeci">void resume()</div><div class="ttdoc">Add a Suspended coroutine into the head of the scheduler linked list, and change the state to Yieldin...</div><div class="ttdef"><b>Definition:</b> <a href="Coroutine_8cpp_source.html#l00103">Coroutine.cpp:103</a></div></div>
 <div class="ttc" id="aclassace__routine_1_1Coroutine_html_a668e339557964dc092540bad162056a7"><div class="ttname"><a href="classace__routine_1_1Coroutine.html#a668e339557964dc092540bad162056a7">ace_routine::Coroutine::kDelayTypeMillis</a></div><div class="ttdeci">static const uint8_t kDelayTypeMillis</div><div class="ttdoc">Delay using units of millis.</div><div class="ttdef"><b>Definition:</b> <a href="Coroutine_8h_source.html#l00497">Coroutine.h:497</a></div></div>
-<div class="ttc" id="acompat_8h_html_aaa60649c7ffe7ed1fbe16dc20ed7e8c3"><div class="ttname"><a href="compat_8h.html#aaa60649c7ffe7ed1fbe16dc20ed7e8c3">FPSTR</a></div><div class="ttdeci">#define FPSTR(p)</div><div class="ttdoc">A macro that converts a const char* that already points to a PROGMEM string to a const __FlashStringH...</div><div class="ttdef"><b>Definition:</b> <a href="compat_8h_source.html#l00081">compat.h:81</a></div></div>
+<div class="ttc" id="acompat_8h_html_aaa60649c7ffe7ed1fbe16dc20ed7e8c3"><div class="ttname"><a href="compat_8h.html#aaa60649c7ffe7ed1fbe16dc20ed7e8c3">FPSTR</a></div><div class="ttdeci">#define FPSTR(p)</div><div class="ttdoc">A macro that converts a const char* that already points to a PROGMEM string to a const __FlashStringH...</div><div class="ttdef"><b>Definition:</b> <a href="compat_8h_source.html#l00087">compat.h:87</a></div></div>
 <div class="ttc" id="aclassace__routine_1_1Coroutine_html_a826df2b7d3db16170a13ba4b2756c853"><div class="ttname"><a href="classace__routine_1_1Coroutine.html#a826df2b7d3db16170a13ba4b2756c853">ace_routine::Coroutine::coroutineMicros</a></div><div class="ttdeci">virtual unsigned long coroutineMicros() const</div><div class="ttdoc">Returns the current millisecond clock.</div><div class="ttdef"><b>Definition:</b> <a href="Coroutine_8cpp_source.html#l00118">Coroutine.cpp:118</a></div></div>
 <div class="ttc" id="aclassace__routine_1_1Coroutine_html_a397f0d87d99b538189353fa47e918022"><div class="ttname"><a href="classace__routine_1_1Coroutine.html#a397f0d87d99b538189353fa47e918022">ace_routine::Coroutine::kStatusSuspended</a></div><div class="ttdeci">static const Status kStatusSuspended</div><div class="ttdoc">Coroutine has been suspended using suspend() and the scheduler should remove it from the queue upon t...</div><div class="ttdef"><b>Definition:</b> <a href="Coroutine_8h_source.html#l00479">Coroutine.h:479</a></div></div>
 <div class="ttc" id="acompat_8h_html"><div class="ttname"><a href="compat_8h.html">compat.h</a></div></div>

docs/html/Coroutine_8h.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/Coroutine_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/annotated.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/classace__routine_1_1Channel-members.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/classace__routine_1_1Channel.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/classace__routine_1_1Coroutine-members.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/classace__routine_1_1Coroutine.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/classace__routine_1_1CoroutineScheduler-members.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/classace__routine_1_1CoroutineScheduler.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/classes.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/compat_8h.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2.2</span>
+   &#160;<span id="projectnumber">1.2.3</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>