Merge pull request #14 from bxparks/develop

use environments as built targets instead of board aliases
bxparks · Sep 17, 2018 · 0eed86c · 0eed86c
2 parents 13e42d5 + c875d57
commit 0eed86c
Show file tree

Hide file tree

Showing 7 changed files with 690 additions and 468 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,10 +1,37 @@
 # Changelog
 
+* 1.7 (2018-09-16)
+    * Remove --board, --boards, and --ports flags to simplify the auniter.sh
+      script.
+    * Change name of `auniter.conf` to `auniter.ini` because tools (e.g. vim)
+      are able to recoginize INI file format and handle them better
+      (e.g. syntax highlighting).
+    * Change the compile target from "board aliases" to "environments", where
+      the "environment" is defined by a section of auniter.ini file whose name
+      has the form `[env:NAME]`.
+    * Add `port_timeout` parameters to the `[auniter]` section.
+    * Add `locking` and 'board' parameters to the `[env:NAME]` section.
+    * Add support for 'preprocessor' parameter in '[env:NAME]' section
+      which defines a space-separated list of C-preprocessor macros in the
+      form of `MACRO MACRO=value MACRO="string value"`.
+    * Remove overly flexible --pref flag, replace with semantically specific
+      flags (e.g. --sketchbook, --preprocessor).
+    * Remove --monitor flag from `run_arduino.sh`. Was already replaced with
+      shell exec to a user-definable terminal program. Add example
+      configurations for 'picocom` and `microcom` terminal programs.
+    * Add `auniter envs` subcommand which lists the environments defined in the
+      auniter ini file.
+    * Changed name of `--skip_if_no_port` flag to `--skip_missing_port`.
+    * Add documentation of the recommended structure of `config.h` file to
+      support multiple environments using both Arduino IDE and AUniter tools.
 * 1.6 (2018-09-11)
     * Support 'monitor' subcommand using an external serial port terminal
       (e.g. picocom).
     * Add 'upmon' subcommand, a combination of 'upload' and 'monitor'.
     * Add '[auniter] baud' parameter to control default baud rate of port.
+* 1.5 (2018-09-03)
+    * Use subcommands instead of flags in auniter.sh to simplify the
+      common interactive use cases.
 * 1.4.1 (2018-09-03)
     * Fix bug which disabled --locking by default.
     * Allow serial port specifier in --boards flag to omit "/dev/tty" prefix.

diff --git a/README.md b/README.md
@@ -9,15 +9,37 @@ continuous integration system.
 There are 3 components to the **AUniter** package:
 
 1. Command line tools (`tools/`) that can compile and upload Arduino programs
-   to microcontroller boards programmatically.
+   to microcontroller boards programmatically. Here are some examples supported
+   by the `auniter.sh` command line tool:
 1. Integration with a locally hosted Jenkins system (`jenkins/`).
 1. A badge service (`BadgeService/`) running on
    [Google Cloud Functions](https://cloud.google.com/functions/)
    that allows the locally hosted Jenkins system to update the status of the
    build, so that an indicator badge can be displayed on a source control
    repository like GitHub.
 
-Version: 1.6 (2018-09-11)
+The `auniter.sh` script uses the Arduino IDE binary in command line mode.
+Here are some examples that you can perform on the command line:
+
+* `$ auniter ports` - list the ports and devices
+* `$ auniter verify nano Blink.ino` - verify `Blink.ino`
+* `$ auniter verify nano,esp8266,esp32 Blink.ino` - verify on 3 target
+  environments (`nano`, `esp8266`, `esp32`)
+* `$ auniter upload nano:USB0 Blink.ino` - upload to the `nano` target
+  connected to `/dev/ttyUSB0`
+* `$ auniter test nano:USB0 BlinkTest.ino` - compile, upload, then validate
+  the `BlinkTest.ino` unit test written using
+  [AUnit](https://github.com/bxparks/AUnit)
+* `$ auniter test nano:USB0,esp8266:USB1,esp32:USB2 BlinkTest/ ClockTest/`
+  - upload and verify 2 sketches (`BlinkTest/BlinkTest.ino`,
+  `ClockTest/ClockTest.ino`) on 3 target environments (`nano`, `esp8266`,
+  `esp32`) located at the 3 respective ports (`/dev/ttyUSB0`, `/dev/ttyUSB1`,
+  `/dev/ttyUSB2`)
+* `$ auniter upmon nano:USB0 Blink.ino` - upload the sketch and monitor the
+  serial port using a user-configurable terminal program (e.g. `picocom`) on
+  `/dev/ttyUSB0`
+
+Version: 1.7 (2018-09-16)
 
 ## Installation
 
@@ -30,14 +52,14 @@ Version: 1.6 (2018-09-11)
 ## System Requirements
 
 * AUniter Tools requires the following:
-    * Arduino IDE 1.8.5
+    * Arduino IDE 1.8.5, 1.8.6
     * I have tested the integration on the following systems:
         * Ubuntu 16.04, 17.10, 18.04
         * Xubuntu 18.04
 * AUniter Integration with Jenkins requires the following:
     * AUniter Tools
-    * AUnit (optional)
-    * Jenkins Continuous Integration platform
+    * [AUnit](https://github.com/bxparks/AUnit) (optional)
+    * [Jenkins](https://jenkins.io) Continuous Integration platform
     * I have tested the integration on the following systems:
         * Ubuntu 16.04, 17.10, 18.04
         * Xubuntu 18.04

diff --git a/jenkins/README.md b/jenkins/README.md
@@ -208,9 +208,9 @@ dispatching.
 
 I have also assumed that you have an Arduino UNO (or an equivalent clone)
 attached to the serial port, and that the OS has assigned it to the serial port
-`/dev/ttyACM0`. The argument to the `--boards` flag will be set to
-`uno:/dev/ttyACM0`. If you are using another Arduino board, for example an old
-Nano, then the `--boards` flag could be something like `nano:/dev/ttyUSB0`.
+`/dev/ttyACM0`. The value of `$BOARDS` will be set to `uno:/dev/ttyACM0`. If you
+are using another Arduino board, for example an old Nano, then the value of
+`$BOARDS` will be something like `nano:/dev/ttyUSB0`.
 
 ### 1. Clone the AceButton Project
 
@@ -251,7 +251,7 @@ purposes of this tutorial, I will assume that you have an Arduino UNO.
     * In the "Name" parameter, enter "BOARDS".
     * In the "Default Value", enter "uno:/dev/ttyACM0".
 
-This is the value that is passed into the `--boards {alias}[:{port}],...` flag
+This is the value that is passed into the `$BOARDS` argument
 of the `auniter.sh` script. Use the `auniter.sh ports` command if you
 need to.
 
@@ -357,31 +357,31 @@ pipeline {
         stage('Verify Examples') {
             steps {
                 sh "AUniter/auniter.sh \
-                    --config libraries/AceButton/tests/auniter.conf \
+                    --config libraries/AceButton/tests/auniter.ini \
                     verify \
-                    --pref sketchbook.path=$WORKSPACE \
-                    --boards $BOARDS \
+                    --sketchbook $WORKSPACE \
+                    $BOARDS \
                     libraries/AceButton/examples/*"
             }
         }
         stage('Verify Tests') {
             steps {
                 sh "AUniter/auniter.sh \
-                    --config libraries/AceButton/tests/auniter.conf \
+                    --config libraries/AceButton/tests/auniter.ini \
                     verify \
-                    --pref sketchbook.path=$WORKSPACE \
-                    --boards $BOARDS \
+                    --sketchbook $WORKSPACE \
+                    $BOARDS \
                     libraries/AceButton/tests/AceButtonTest"
             }
         }
         stage('Test') {
             steps {
                 sh "AUniter/auniter.sh \
-                    --config libraries/AceButton/tests/auniter.conf \
+                    --config libraries/AceButton/tests/auniter.ini \
                     test \
-                    --skip_if_no_port \
-                    --pref sketchbook.path=$WORKSPACE \
-                    --boards $BOARDS \
+                    --skip_missing_port \
+                    --sketchbook $WORKSPACE \
+                    $BOARDS \
                     libraries/AceButton/tests/AceButtonTest"
             }
         }
@@ -408,8 +408,8 @@ with the "This project is parameterized" checkbox option.
 
 Sometimes you may want to verify compiliation against multiple boards but you
 don't have all of them connected to your serial ports. If you use the
-`--skip_if_no_port` flag with the `test` command, the absence of a port in the
-`{alias}:{port}` pair of the `$BOARDS` parameter means that the test (hence, the
+`--skip_missing_port` flag with the `test` command, the absence of a port in the
+`{env}:{port}` pair of the `$BOARDS` parameter means that the test (hence, the
 upload) should be skipped for that particular board. For example, if `$BOARDS`
 is set to `nano:/dev/ttyUSB0,leonardo,esp8266,esp32`, that means that only an
 Arduino Nano board is connected and the upload and test should be run only on
@@ -474,7 +474,7 @@ is:
         `-- tests
 ```
 
-We then pass along the `--pref sketchbook.path=$WORKSPACE` flag to the Arduino
+We then pass along the `--sketchbook $WORKSPACE` flag to the Arduino
 command line binary. This tells the Arduino binary that the sketchbook folder is
 `/var/lib/jenkins/workspace/AceButtonPipeline`, which has the exact folder
 layout expected by the Arduino binary. In particular the `libraries/` folder
@@ -496,6 +496,59 @@ structure would look like this:
 But this structure does not leave any room to hold the external libraries
 dependencies and it is not the layout expected by the Arduino IDE.
 
+## AUniter Config File
+
+Jenkins should *not* use the `$HOME/.auniter.ini` config file that you use
+interactively because we don't want the continuous build system to depend on
+ad-hoc changes. Instead, each project should create a minimal `auniter.ini` file
+that is customized for the environments that the Jenkins server will use to
+perform its validation. The location of the custom config file is passed to the
+`auniter.sh` script using the `--config` flag.
+
+Here is the `auniter.ini` file used by `AceButton/tests`. It contains only 5
+environments (and 5 board aliases) because I am interested in validating only
+those for boards at this time.
+
+```ini
+[boards]
+  uno = arduino:avr:uno
+  nano = arduino:avr:nano:cpu=atmega328old
+  leonardo = arduino:avr:leonardo
+  nodemcuv2 = esp8266:esp8266:nodemcuv2:CpuFrequency=80,FlashSize=4M1M,LwIPVariant=v2mss536,Debug=Disabled,DebugLevel=None____,FlashErase=none,UploadSpeed=921600
+  esp32 = espressif:esp32:esp32:PartitionScheme=default,FlashMode=qio,FlashFreq=80,FlashSize=4M,UploadSpeed=921600,DebugLevel=none
+
+[env:uno]
+  board = uno
+
+[env:nano]
+  board = nano
+
+[env:leonardo]
+  board = leonardo
+  locking = false
+
+[env:esp8266]
+  board = nodemcuv2
+  exclude = CapacitiveButton
+
+[env:esp32]
+  board = esp32
+  exclude = CapacitiveButton
+```
+
+In the Jenkins web UI, I set the `BOARDS` parameter to contain only 4 of the
+boards because the `uno` board is essentially identical to the `nano`, and I
+don't have the UNO connected to the computer most of the time:
+```
+nano:/dev/ttyUSB0,leonardo,esp8266,esp32
+```
+
+The `{port}` specification is given only on the `nano` board which causes the
+AUnit tests to run only on the Nano, while the other boards perform only a
+`verify` step to check if the program compiles on that target. Ideally we would
+run the unit tests on all boards, but it takes too much time to run the test
+suites across all the boards.
+
 ## Arduino IDE Maintenance
 
 The `jenkins` user uses a completely independent instance of the Arduino IDE