Skip to content

Commit e3c0977

Browse files
bxparksbxparks
authored
Merge pull request #102 from bxparks/develop
merge 1.7.1 into master
2 parents e2858c6 + 09a77cb commit e3c0977

File tree

119 files changed

+1300
-374
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

119 files changed

+1300
-374
lines changed

‎CHANGELOG.md‎

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,51 @@
11
# Changelog
22

33
* Unreleased
4+
* 1.7.1 (2023-06-15)
5+
* This is a maintenance release, to update the list of supported boards,
6+
and update the documentation.
7+
* No functional change.
8+
* Add [MemoryBenchmark](examples/MemoryBenchmark) to collect flash and
9+
static memory usage.
10+
* For consistency with my other arduino libraries.
11+
* Also enables an automated script to verify that AUnit compiles under
12+
various microcontrollers.
13+
* Update supported boards and tiers
14+
* Update [Flash.h](src/aunit/Flash.h) to work better with Teensyduino,
15+
Adafruit SAMD, and Seeeduino SAMD boards by hacking around their bugs
16+
and inconsistent APIs
17+
* Add SAMD21 and SAMD51 boards to Tier 1
18+
* Add 2 SAMD boards from 2 different companies, to test their
19+
Arduino Core software:
20+
* Seeeduino XIAO M0 (SAMD21 48MHz ARM Cortex-M0+)
21+
* Adafruit ItsyBitsy M4 (SAMD51 120MHz ARM Cortex-M4)
22+
* SAMD21 and SAMD51 boards are back in Tier 1, as long as they use
23+
the traditional Arduino API instead of the new
24+
[ArduinoCore-API](https://github.com/arduino/ArduinoCore-api).
25+
* Fortunately most third party SAMD21 and SAMD51 boards continue to
26+
use the traditional Arduino API.
27+
* Move Teensy 3.2 to Tier 2 ("Should work but not tested often")
28+
* This board is entering end-of-life.
29+
* As well, the Teensyduino environment integrates with the Arduino
30+
IDE and CLI in a way that's different than all other third-party
31+
Arduino boards. Some of my automation scripts do not work with
32+
Teensyduino, so it becomes very time consuming to test the Teensy
33+
boards.
34+
* All Teensy boards are now in Tier 2.
35+
* The various tiers are documented in the
36+
[README.md](README.md#Hardware).
37+
* Upgrade tool chain.
38+
* Arduino CLI from 0.19.2 to 0.33.0
39+
* Arduino AVR Core from 1.8.4 to 1.8.6
40+
* STM32duino from 2.2.0 to 2.5.0
41+
* ESP32 Core from 2.0.2 to 2.0.9
42+
* Teensyduino from 1.56 to 1.57 (unable to install 1.58)
443
* 1.7.0 (2022-12-08)
5-
* **Potentially Breaking** Change format of assertion failure message from:
6-
* "Assertion failed: (expected=3) == (counter=4), file AUnitTest.ino,
7-
line 134.", to
8-
* "AUnitTest.ino:134: Assertion failed: (expected=3) == (counter=4)."
44+
* **Potentially Breaking** Change format of assertion failure message
45+
* from: `Assertion failed: (expected=3) == (counter=4), file
46+
AUnitTest.ino, line 134.`
47+
* to: `AUnitTest.ino:134: Assertion failed: (expected=3) ==
48+
(counter=4).`
949
* This format is compatible with various Linux/MacOS/Unix command line
1050
tools, in particular, the `vim` editor.
1151
* When used with EpoxyDuino, this message format allows the `vim` editor

‎README.md‎

Lines changed: 164 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,25 @@
44

55
A unit testing framework for Arduino platforms inspired by by
66
[ArduinoUnit](https://github.com/mmurdoch/arduinounit) and [Google
7-
Test](https://github.com/google/googletest/). The unit tests usually run on the
8-
embedded controller which allows detection of architecture-specific problems.
9-
But for faster development, many unit tests can be compiled and executed
10-
natively on Linux or MacOS using the
11-
[EpoxyDuino](https://github.com/bxparks/EpoxyDuino) companion project.
12-
13-
AUnit is almost a drop-in replacement of ArduinoUnit with some advantages. AUnit
14-
supports timeouts and test fixtures. It sometimes consumes 50% less flash memory
15-
on the AVR platform, and it has been tested to work on the AVR, SAMD21, STM32,
16-
ESP8266, ESP32 and Teensy platforms. Another companion project
17-
[AUniter](https://github.com/bxparks/AUniter) project provides command line
18-
tools to verify, upload and validate the unit tests to the microcontroller,
19-
instead of having to go through the Arduino IDE. Both the AUniter and
20-
EpoxyDuino tools can be used in a continuous integration system like Jenkins,
21-
or with [GitHub Actions](https://github.com/features/actions).
22-
23-
**Version**: 1.7.0 (2022-12-08)
7+
Test](https://github.com/google/googletest/). AUnit is almost a drop-in
8+
replacement of ArduinoUnit (v2.2) with some advantages. AUnit supports timeouts
9+
and test fixtures. It sometimes consumes 50% less flash memory on the AVR
10+
platform, and it has been tested to work on the AVR, SAMD21, STM32, ESP8266,
11+
ESP32 and Teensy platforms. The assertion error messages were updated in v1.7 to
12+
provide seamless integration with Unix tools like `vim`.
13+
14+
Originally, the AUnit tests were designed to run on the embedded controller
15+
itself which allows detection of architecture-specific problems. But the
16+
uploading, flashing, and execution process is often slow and flaky, causing the
17+
iteration cycle to take too much time. It is often more effective to execute the
18+
AUnit tests natively on a host machine (running Linux, MacOS, or FreeBSD) using
19+
the [EpoxyDuino](https://github.com/bxparks/EpoxyDuino) companion project. Once
20+
the unit tests are running on the Linux or MacOS host machine, they can be
21+
incorporated into a continuous integration system like
22+
[Jenkins](https://www.jenkins.io/) system or a cloud-based system like [GitHub
23+
Actions](https://github.com/features/actions).
24+
25+
**Version**: 1.7.1 (2023-06-15)
2426

2527
**Changelog**: [CHANGELOG.md](CHANGELOG.md)
2628

@@ -78,6 +80,8 @@ or with [GitHub Actions](https://github.com/features/actions).
7880
* [Class Hierarchy](#ClassHierarchy)
7981
* [Testing Private Helper Methods](#PrivateHelperMethods)
8082
* [Benchmarks](#Benchmarks)
83+
* [Memory Benchmark](#MemoryBenchmark)
84+
* [Compared with ArduinoUnit](#CompareArduinoUnit)
8185
* [System Requirements](#SystemRequirements)
8286
* [Hardware](#Hardware)
8387
* [Tool Chain](#ToolChains)
@@ -248,36 +252,66 @@ The source files are organized as follows:
248252

249253
The `examples/` directory has a number of examples:
250254

251-
* `advanced` - how to subclass `Test` and `TestOnce` manually
252-
* `basic` - using the `test()` macro
253-
* `continuous` - using the `testing()` macro
254-
* `filter` - how to filter tests using `TestRunner::include()` and
255-
`TestRunner::exclude()`
256-
* `fixture` - how to use the `testF()` macro with test fixtures
257-
* `meta_asserts` - how to use `assertTestXxx()` and `checkTestXxx()`
258-
259-
In the `tests/` directory:
260-
261-
* `AUnitTest` - the unit test for core `AUnit` functions,
262-
* `AUnitMetaTest` - the unit test for meta assertions and `extern*()` macros
263-
* `FilterTest` - manual tests for `include()` and `exclude()` filters
264-
* `SetupAndTeardownTest` - tests to verify that `setup()` and `teardown()` are
265-
called properly by the finite state machine
266-
267-
Perhaps the best way to see AUnit in action through real life examples. All my
268-
libraries use AUnit for testing and for continuous integration through
269-
EpoxyDuino. Here are some examples:
255+
* Basic
256+
* [basic](examples/basic)
257+
* using the `test()` macro
258+
* [fixture](examples/fixture)
259+
* how to use the `testF()` macro with test fixtures
260+
* Intermediate
261+
* [filter](examples/filter)
262+
* how to filter tests using `TestRunner::include()` and
263+
`TestRunner::exclude()`
264+
* [meta_asserts](examples/meta_asserts)
265+
* how to use `assertTestXxx()` and `checkTestXxx()`
266+
* Advanced
267+
* [advanced](examples/advanced/)
268+
* how to subclass `Test` and `TestOnce` manually
269+
* [continuous](examples/continuous)
270+
* using the `testing()` macro
271+
* Benchmarks
272+
* These are internal benchmark programs, not meant as examples (they are in
273+
the `examples/` directory because of the Arduino IDE).
274+
* [MemoryBenchmark](examples/MemoryBenchmark)
275+
* Determines the flash and static memory consumption of AUnit for
276+
various microcontroller
277+
278+
In the `tests/` directory, there are unit tests to test the AUnit framework
279+
itself:
280+
281+
* [AUnitTest](tests/AUnitTest)
282+
* the unit test for core `AUnit` functions
283+
* [AUnitMoreTest](tests/AUnitMoreTest)
284+
* more tests
285+
* [AUnitMetaTest](tests/AUnitMetaTest)
286+
* the unit test for meta assertions and `extern*()` macros
287+
* [CompareTest](tests/CompareTest)
288+
* tests for the low-level compare functions
289+
* [FailingTest](tests/FailingTest)
290+
* tests that are expected to fail
291+
* [FilterTest](tests/FilterTest)
292+
* manual tests for `include()` and `exclude()` filters
293+
* [Print64Test](tests/Print64Test)
294+
* manual tests for `include()` and `exclude()` filters
295+
* [SetupAndTeardownTest](tests/SetupAndTeardownTest)
296+
* tests to verify that `setup()` and `teardown()` are called properly by the
297+
finite state machine
298+
* [tests/Makefile](tests/Makefile)
299+
* Runs the tests on a Linux or Mac machine using EpoxyDuino
300+
301+
Perhaps the best way to see AUnit in action is through real life examples. All
302+
my libraries use AUnit for testing and for continuous integration through
303+
EpoxyDuino. Here are some of my libraries:
270304

271305
* [AceButton](https://github.com/bxparks/AceButton)
272306
* My first Arduino library, which originally used ArduinoUnit 2.2.
273307
* I kept many of the original ArduinoUnit tests for backwards compatibility
274-
testing. But over time, I started to use nore AUnit features.
308+
testing. But over time, I started to use more AUnit features so I'm not
309+
sure if they work with ArduinoUnit anymore.
275310
* [AceCRC](https://github.com/bxparks/AceCRC)
276311
* [AceCommon](https://github.com/bxparks/AceCommon)
277312
* [AceRoutine](https://github.com/bxparks/AceRoutine)
278313
* [AceSegment](https://github.com/bxparks/AceSegment)
279314
* [AceSorting](https://github.com/bxparks/AceSorting)
280-
* [AceTimeClock](https://github.com/bxparks/AceTimeClock)
281315
* [AceTime](https://github.com/bxparks/AceTime)
282316

283317
<a name="Usage"></a>
@@ -518,7 +552,7 @@ SampleTest.ino:10: Assertion failed: (2) == (1)
518552
The format of the assertion failure messages was changed in v1.7 to the
519553
following:
520554
```
521-
{filName}:{lineNumber}: Assertion failed: {expression}
555+
{fileName}:{lineNumber}: Assertion failed: {expression}
522556
```
523557
524558
This format is a widely used in many other programs, for example, the C compiler
@@ -1476,21 +1510,16 @@ copied from the `AUniter/README.md` file:
14761510
* list the available serial ports and devices
14771511
* `$ auniter verify nano Blink.ino`
14781512
* verify (compile) `Blink.ino` using the `env:nano` environment
1479-
* `$ auniter verify nano,esp8266,esp32 Blink.ino`
1480-
* verify `Blink.ino` on 3 target environments (`env:nano`, `env:esp8266`,
1481-
`env:esp32`)
14821513
* `$ auniter upload nano:/dev/ttyUSB0 Blink.ino`
14831514
* upload `Blink.ino` to the `env:nano` target environment connected to
14841515
`/dev/ttyUSB0`
14851516
* `$ auniter test nano:USB0 BlinkTest.ino`
14861517
* compile and upload `BlinkTest.ino` using the `env:nano` environment,
14871518
upload it to the board at `/dev/ttyUSB0`, then validate the output of the
14881519
[AUnit](https://github.com/bxparks/AUnit) unit test
1489-
* `$ auniter test nano:USB0,esp8266:USB1,esp32:USB2 BlinkTest/ ClockTest/`
1520+
* `$ auniter test nano:USB0 BlinkTest/ ClockTest/`
14901521
* upload and verify the 2 unit tests (`BlinkTest/BlinkTest.ino`,
1491-
`ClockTest/ClockTest.ino`) on 3 target environments (`env:nano`,
1492-
`env:esp8266`, `env:esp32`) located at the 3 respective ports
1493-
(`/dev/ttyUSB0`, `/dev/ttyUSB1`, `/dev/ttyUSB2`)
1522+
`ClockTest/ClockTest.ino`) on the target environment (`env:nano`)
14941523
* `$ auniter upmon nano:USB0 Blink.ino`
14951524
* upload the `Blink.ino` sketch and monitor the serial port using a
14961525
user-configurable terminal program (e.g. `picocom`) on `/dev/ttyUSB0`
@@ -1528,10 +1557,22 @@ For real Arduino boards, you get more reliable unit tests if you add a
15281557
necessary, so I recommend calling this only on real Arduino boards, like this:
15291558
```C++
15301559
void setup() {
1531-
#ifdef ARDUINO
1560+
#if ! defined(EPOXY_DUINO)
15321561
delay(1000); // Wait for stability on some boards, otherwise garage on Serial
15331562
#endif
1563+
1564+
Serial.begin(115200);
1565+
while (! Serial); // Wait until Serial is ready - Leonardo/Micro
1566+
1567+
#if defined(EPOXY_DUINO)
1568+
Serial.setLineModeUnix(); // use Unix line terminator instead of DOS
1569+
#endif
15341570
...
1571+
}
1572+
1573+
void loop() {
1574+
aunit::TestRunner::run();
1575+
}
15351576
```
15361577

15371578
**Exit() Status Code**
@@ -1881,13 +1922,50 @@ testF(TargetTest, helper) {
18811922
```
18821923

18831924
The tricky part is that `Target.h` must have forward declarations of the various
1884-
auto-generated AUnit test classes. And within the `Target` class itsef, the
1925+
auto-generated AUnit test classes. And within the `Target` class itself, the
18851926
`friend` declarations need to have a global scope `::` specifier before the name
18861927
of the test class.
18871928

18881929
<a name="Benchmarks"></a>
18891930
## Benchmarks
18901931

1932+
<a name="MemoryBenchmark"></a>
1933+
### MemoryBenchmark
1934+
1935+
The [MemoryBenchmark](examples/MemoryBenchmark/) directory collects the flash
1936+
and static RAM usage of the AUnit library on various microcontroller boards, and
1937+
renders the results as tables embedded in the README.md file. Here are 2
1938+
highlights:
1939+
1940+
**Arduino Nano (8-bit)**
1941+
1942+
```
1943+
+---------------------------------------------------------------------+
1944+
| Functionality | flash/ ram | delta |
1945+
|----------------------------------------+--------------+-------------|
1946+
| Baseline | 1586/ 185 | 0/ 0 |
1947+
|----------------------------------------+--------------+-------------|
1948+
| AUnit Single Test | 4456/ 366 | 2870/ 181 |
1949+
| AUnit Single Test Verbose | 4500/ 366 | 2914/ 181 |
1950+
+---------------------------------------------------------------------+
1951+
```
1952+
1953+
**ESP8266 (32-bit)**
1954+
1955+
```
1956+
+---------------------------------------------------------------------+
1957+
| Functionality | flash/ ram | delta |
1958+
|----------------------------------------+--------------+-------------|
1959+
| Baseline | 264949/27984 | 0/ 0 |
1960+
|----------------------------------------+--------------+-------------|
1961+
| AUnit Single Test | 268021/28148 | 3072/ 164 |
1962+
| AUnit Single Test Verbose | 268081/28148 | 3132/ 164 |
1963+
+---------------------------------------------------------------------+
1964+
```
1965+
1966+
<a name="CompareArduinoUnit"></a>
1967+
### Compared to ArduinoUnit 2.2
1968+
18911969
AUnit consumes as much as 65% less flash memory than ArduinoUnit 2.2 on an AVR
18921970
platform (e.g. Arduino UNO, Nano), and 30% less flash on the Teensy-ARM platform
18931971
(e.g. Teensy LC ). (ArduinoUnit 2.3 reduces the flash memory by 30% or so, which
@@ -1929,50 +2007,69 @@ AUnit, but a savings of 30-50% seems to be common.
19292007
<a name="Hardware"></a>
19302008
### Hardware
19312009

1932-
The library is tested on the following boards:
2010+
**Tier 1: Fully supported**
2011+
2012+
These boards are tested on each release:
19332013

19342014
* Arduino Nano clone (16 MHz ATmega328P)
19352015
* SparkFun Pro Micro clone (16 MHz ATmega32U4)
1936-
* SAMD21 M0 Mini board (Arduino Zero compatible, 48 MHz ARM Cortex-M0+)
2016+
* Seeeduino XIAO M0 (SAMD21, 48 MHz ARM Cortex-M0+)
19372017
* STM32 Blue Pill (STM32F103C8, 72 MHz ARM Cortex-M3)
2018+
* Adafruit ItsyBitsy M4 (SAMD51, 120 MHz ARM Cortext-M4)
19382019
* NodeMCU 1.0 (ESP-12E module, 80 MHz ESP8266)
19392020
* WeMos D1 Mini (ESP-12E module, 80 MHz ESP8266)
19402021
* ESP32 dev board (ESP-WROOM-32 module, 240 MHz dual core Tensilica LX6)
1941-
* Teensy 3.2 (96 MHz ARM Cortex-M4)
19422022

1943-
I will occasionally test on the following hardware as a sanity check:
2023+
**Tier 2: Should work**
2024+
2025+
These boards should work but I don't test them as often:
19442026

19452027
* Arduino Pro Mini (16 MHz ATmega328P)
19462028
* Mini Mega 2560 (Arduino Mega 2560 compatible, 16 MHz ATmega2560)
19472029
* Teensy LC (48 MHz ARM Cortex-M0+)
2030+
* Teensy 3.2 (96 MHz ARM Cortex-M4)
2031+
2032+
**Tier 3: May work, but not supported**
19482033

1949-
The following boards are **not** supported:
2034+
* Other 3rd party SAMD21 and SAMD51 boards *may* work if their board software
2035+
uses the traditional Arduino API, instead of the
2036+
[ArduinoCore-API](https://github.com/arduino/ArduinoCore-api)
19502037

1951-
* Any platform using the ArduinoCore-API
1952-
(https://github.com/arduino/ArduinoCore-api), such as:
1953-
* megaAVR (e.g. Nano Every) using ArduinoCore-megaavr
1954-
(https://github.com/arduino/ArduinoCore-megaavr/)
1955-
* SAMD21 boards (e.g. MKRZero) using ArduinoCore-samd
1956-
(https://github.com/arduino/ArduinoCore-samd) starting with
1957-
`arduino:samd` version >= 1.8.10
1958-
* Raspberry Pi Pico (RP2040) using Arduino-Pico
1959-
(https://github.com/earlephilhower/arduino-pico)
2038+
**Tier Blacklisted**
2039+
2040+
The following boards are *not* supported and are explicitly blacklisted to allow
2041+
the compiler to print useful error messages instead of hundreds of lines of
2042+
compiler errors:
2043+
2044+
* Any platform using the
2045+
[ArduinoCore-API](https://github.com/arduino/ArduinoCore-api), such as:
2046+
* Arduino-branded megaAVR using
2047+
[ArduinoCore-megaavr](https://github.com/arduino/ArduinoCore-megaavr/)
2048+
* Nano Every
2049+
* Arduino-branded SAMD21 or SAMD51 boards using
2050+
[ArduinoCore-samd](https://github.com/arduino/ArduinoCore-samd) after
2051+
version >= 1.8.10
2052+
* MKRZero
2053+
* Nano 33 IoT
2054+
* Raspberry Pi Pico (RP2040) using
2055+
[Arduino-Pico](https://github.com/earlephilhower/arduino-pico)
19602056

19612057
<a name="ToolChain"></a>
19622058
### Tool Chain
19632059

19642060
This library was validated using:
19652061

19662062
* [Arduino IDE 1.8.19](https://www.arduino.cc/en/Main/Software)
1967-
* [Arduino CLI 0.19.2](https://arduino.github.io/arduino-cli)
1968-
* [Arduino AVR Boards 1.8.4](https://github.com/arduino/ArduinoCore-avr)
2063+
* [Arduino CLI 0.33.0](https://arduino.github.io/arduino-cli)
2064+
* [Arduino AVR Boards 1.8.6](https://github.com/arduino/ArduinoCore-avr)
19692065
* [Arduino SAMD Boards 1.8.9](https://github.com/arduino/ArduinoCore-samd)
2066+
(versions >= 1.8.10 not supported)
19702067
* [SparkFun AVR Boards 1.1.13](https://github.com/sparkfun/Arduino_Boards)
19712068
* [SparkFun SAMD Boards 1.8.6](https://github.com/sparkfun/Arduino_Boards)
1972-
* [STM32duino 2.2.0](https://github.com/stm32duino/Arduino_Core_STM32)
2069+
* [STM32duino 2.5.0](https://github.com/stm32duino/Arduino_Core_STM32)
19732070
* [ESP8266 Arduino 3.0.2](https://github.com/esp8266/Arduino)
1974-
* [ESP32 Arduino 2.0.2](https://github.com/espressif/arduino-esp32)
1975-
* [Teensyduino 1.56](https://www.pjrc.com/teensy/td_download.html)
2071+
* [ESP32 Arduino 2.0.9](https://github.com/espressif/arduino-esp32)
2072+
* [Teensyduino 1.57](https://www.pjrc.com/teensy/td_download.html)
19762073

19772074
This library is *not* compatible with:
19782075

0 commit comments

Comments
 (0)