arduino_ci 0.1.10 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3120211b8610970115b711ea7647e43db7382f65baf3f5b58290c914e6bb68d
-  data.tar.gz: 976468bc18dd707eb5eeab43d020e034e57e9d898cd2cb140e2e7c2398a9ca11
+  metadata.gz: 158ec153267d358e71149cc9814043f1d1d8c07a1be5f8e261f794d3159e4bad
+  data.tar.gz: e03b6a69dc0e486d9147e7bdc48c4bf4b595c66caad48ed8c03350814dcffd1c
 SHA512:
-  metadata.gz: aa3afee9f49c16b9ab7e05ce252fd5254cf1e01ab27f5b654de6050278b924169c425c72331cfe02047890497ed001a55af50c55d0bf3e861a67537234b351b2
-  data.tar.gz: 365c09a2d5063e08e1ed57c7cd02b8d5aa8ea9b9899e7214408e4b6b81cb150f49523755f2c0f1f31923a228acd2e13e27ff0abbb2124eb67765cb8168bc01e9
+  metadata.gz: 9c216c4195a1166c99a252e666f30e8e73cf6018ccb61fba693fef08da319710c180d88cf57c5207a3b1a03e168ee208c202e056cdfaec2765d6f8455ecc33e0
+  data.tar.gz: 41c4a7a2f88a49c28ed1315316e37495e057e934f85b2c67002d90583dbecaa7b637371a69e49d1edc57ccdcb0fbf90623202fef6658e6648a38849ae35e2b68

data/README.md

@@ -1,12 +1,13 @@
 
-# ArduinoCI Ruby gem (`arduino_ci`) [![Gem Version](https://badge.fury.io/rb/arduino_ci.svg)](https://rubygems.org/gems/arduino_ci) [![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/arduino_ci/0.1.10)
+# ArduinoCI Ruby gem (`arduino_ci`) [![Gem Version](https://badge.fury.io/rb/arduino_ci.svg)](https://rubygems.org/gems/arduino_ci) [![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/arduino_ci/0.1.11)
 
+You want your Arduino library to be automatically built and tested every time someone contributes code to your project on GitHub, but the Arduino IDE lacks the ability to run unit tests. [Arduino CI](https://github.com/ianfixes/arduino_ci) provides that ability.
 
-[Arduino CI](https://github.com/ianfixes/arduino_ci) is a cross-platform Ruby gem for executing Continuous Integration (CI) tests on an Arduino library -- both locally and as part of a service like Travis CI.
+You want to run tests on your Arduino library without hardware present, but the IDE doesn't support that.  Arduino CI proivdes that ability.
 
-It doesn't matter whether your contributors are using OSX, Linux, or Windows; everyone can run unit tests locally with `arduino_ci`, and be assured that the CI system used by the GitHub project maintainer will run the same tests and get the same results.
+You want to precisely replicate certain software states in your library, but you don't have sub-millisecond reflexes for physically faking the inputs, outputs, and serial port.   Arduino CI fakes 100% of the physical input and output of an Arduino board, including the clock.
 
-You don't have to take my word for it; let the build logs speak for themselves:
+`arduino_ci` is a cross-platform build/test system, consisting of a Ruby gem and a series of C++ mocks.  It enables tests to be run both locally and as part of a CI service like Travis or Appveyor.  Any OS that can run the Arduino IDE can run `arduino_ci`.
 
 Platform | CI Status
 ---------|:---------
@@ -17,6 +18,15 @@ Windows  | [![Windows Build status](https://ci.appveyor.com/api/projects/status/
 
 ## Installation In Your GitHub Project And Using Travis CI
 
+The following prerequisites must be fulfilled:
+
+* A compiler; [g++](https://gcc.gnu.org/) is preferred.  On OSX, this is provided by the built-in `clang`.
+* A GitHub (or other repository-hosting) project for your library
+* A CI system like Travis or Appveor that is linked to your project
+
+
+### Changes to Your Repo
+
 Add a file called `Gemfile` (no extension) to your Arduino project:
 
 ```ruby
@@ -24,7 +34,14 @@ source 'https://rubygems.org'
 gem 'arduino_ci'
 ```
 
-Next, you need this in `.travis.yml`
+> **Note:** `arduino_ci_remote.rb` expects to be run from the root directory of your Arduino project library.
+
+
+#### Travis CI
+
+You'll need to go to https://travis-ci.org/profile/ and enable testing for your Arduino project.  Once that happens, you should be all set.  The script will test all example projects of the library and all unit tests.
+
+Next, you need this in `.travis.yml` in your repo
 
 ```yaml
 sudo: false
@@ -34,348 +51,32 @@ script:
    - bundle exec arduino_ci_remote.rb
 ```
 
-That's literally all there is to it on the repository side.  You'll need to go to https://travis-ci.org/profile/ and enable testing for your Arduino project.  Once that happens, you should be all set.  The script will test all example projects of the library and all unit tests.
-
-> **Note:** `arduino_ci_remote.rb` expects to be run from the root directory of your Arduino project library.
-
-### Unit tests in `test/`
-
-All `.cpp` files in the `test/` directory of your Arduino library are assumed to contain unit tests.  Each and every one will be compiled and executed on its own.
-
-The most basic unit test file is as follows:
-
-```C++
-#include <ArduinoUnitTests.h>
-#include "../do-something.h"
-
-unittest(your_test_name)
-{
-  assertEqual(4, doSomething());
-}
-
-unittest_main()
-```
-
-This test defines one `unittest` (a macro provided by `ArduionUnitTests.h`), called `your_test_name`, which makes some assertions on the target library.  The `unittest_main()` is a macro for the `int main()` boilerplate required for unit testing.
+#### Appveyor CI
 
+You'll need to go to https://ci.appveyor.com/projects and add your project.
 
-### Using `GODMODE`
-
-Complete control of the Arduino environment is available in your unit tests through a construct called `GODMODE()`.
-
-```C++
-unittest(example_godmode_stuff)
-{
-  GodmodeState* state = GODMODE();   // get access to the state
-  state->reset();                    // does a full reset of the state.
-  state->resetClock();               //  - you can reset just the clock (to zero)
-  state->resetPins();                //  - or just the pins
-  state->micros = 1;                 // manually set the clock such that micros() returns 1
-  state->digitalPin[4];              // tells you the commanded state of digital pin 4
-  state->digitalPin[4] = HIGH;       // digitalRead(4) will now return HIGH
-  state->analogPin[3];               // tells you the commanded state of analog pin 3
-  state->analogPin[3] = 99;          // analogRead(3) will now return 99
-}
-```
-
-#### Pin Histories
-
-Of course, it's possible that your code might flip the bit more than once in a function.  For that scenario, you may want to examine the history of a pin's commanded outputs:
-
-```C++
-unittest(pin_history)
-{
-  GodmodeState* state = GODMODE();
-  int myPin = 3;
-  state->reset();            // pin will start LOW
-  digitalWrite(myPin, HIGH);
-  digitalWrite(myPin, LOW);
-  digitalWrite(myPin, LOW);
-  digitalWrite(myPin, HIGH);
-  digitalWrite(myPin, HIGH);
-
-  // pin history is queued in case we want to analyze it later.
-  // we expect 6 values in that queue.
-  assertEqual(6, state->digitalPin[1].size());
-  bool expected[6] = {LOW, HIGH, LOW, LOW, HIGH, HIGH};
-  bool actual[6];
-
-  // convert history queue into an array so we can verify it
-  int numMoved = state->digitalPin[myPin].toArray(actual, 6);
-  assertEqual(6, numMoved);
-
-  // verify each element
-  for (int i = 0; i < 6; ++i) {
-    assertEqual(expected[i], actual[i]);
-  }
-}
-```
-
-
-#### Pin Futures
-
-Reading the pin more than once per function is also a possibility.  In that case, we want to queue up a few values for the `digitalRead` or `analogRead` to find.
-
-```C++
-unittest(pin_read_history)
-{
-  GodmodeState* state = GODMODE();
-  state->reset();
-
-  int future[6] = {33, 22, 55, 11, 44, 66};
-  state->analogPin[1].fromArray(future, 6);
-  for (int i = 0; i < 6; ++i)
-  {
-    assertEqual(future[i], analogRead(1));
-  }
-
-  // for digital pins, we have the added possibility of specifying
-  // a stream of input bytes encoded as ASCII
-  bool bigEndian = true;
-  state->digitalPin[1].fromAscii("Yo", bigEndian);
-
-  // digitial history as serial data, big-endian
-  bool expectedBits[16] = {
-    0, 1, 0, 1, 1, 0, 0, 1,  // Y
-    0, 1, 1, 0, 1, 1, 1, 1   // o
-  };
-
-  for (int i = 0; i < 16; ++i) {
-    assertEqual(expectedBits[i], digitalRead(1));
-  }
-}
-```
-
-#### Serial Data
-
-Basic input and output verification of serial port data can be done as follows:
-
-```c++
-unittest(reading_writing_serial)
-{
-  GodmodeState* state = GODMODE();
-  state->serialPort[0].dataIn = "";             // the queue of data waiting to be read
-  state->serialPort[0].dataOut = "";            // the history of data written
-
-  // When there is no data, nothing happens
-  assertEqual(-1, Serial.peek());
-  assertEqual("", state->serialPort[0].dataIn);
-  assertEqual("", state->serialPort[0].dataOut);
-
-  // if we put data on the input and peek at it, we see the value and it's not consumed
-  state->serialPort[0].dataIn = "a";
-  assertEqual('a', Serial.peek());
-  assertEqual("a", state->serialPort[0].dataIn);
-  assertEqual("", state->serialPort[0].dataOut);
-
-  // if we read the input, we see the value and it's consumed
-  assertEqual('a', Serial.read());
-  assertEqual("", state->serialPort[0].dataIn);
-  assertEqual("", state->serialPort[0].dataOut);
-
-  // when we write data, it shows up in the history -- the output buffer
-  Serial.write('b');
-  assertEqual("", state->serialPort[0].dataIn);
-  assertEqual("b", state->serialPort[0].dataOut);
-
-  // when we print more data, note that the history
-  // still contains the first thing we wrote
-  Serial.print("cdefg");
-  assertEqual("", state->serialPort[0].dataIn);
-  assertEqual("bcdefg", state->serialPort[0].dataOut);
-}
-```
-
-A more complicated example: working with serial port IO.  Let's say I have the following function:
-
-```C++
-void smartLightswitchSerialHandler(int pin) {
-  if (Serial.available() > 0) {
-    int incomingByte = Serial.read();
-    int val = incomingByte == '0' ? LOW : HIGH;
-    Serial.print("Ack ");
-    digitalWrite(pin, val);
-    Serial.print(String(pin));
-    Serial.print(" ");
-    Serial.print((char)incomingByte);
-  }
-}
-```
-
-This function has 3 side effects: it drains the serial port's receive buffer, affects a pin, and puts data in the serial port's send buffer.  Or, if the receive buffer is empty, it does nothing at all.
-
-```C++
-unittest(does_nothing_if_no_data)
-{
-    // configure initial state
-    GodmodeState* state = GODMODE();
-    int myPin = 3;
-    state->serialPort[0].dataIn = "";
-    state->serialPort[0].dataOut = "";
-    state->digitalPin[myPin] = LOW;
-
-    // execute action
-    smartLightswitchSerialHandler(myPin);
-
-    // assess final state
-    assertEqual(LOW, state->digitalPin[myPin]);
-    assertEqual("", state->serialPort[0].dataIn);
-    assertEqual("", state->serialPort[0].dataOut);
-}
-
-unittest(two_flips)
-{
-    GodmodeState* state = GODMODE();
-    int myPin = 3;
-    state->serialPort[0].dataIn = "10junk";
-    state->serialPort[0].dataOut = "";
-    state->digitalPin[myPin] = LOW;
-    smartLightswitchSerialHandler(myPin);
-    assertEqual(HIGH, state->digitalPin[myPin]);
-    assertEqual("0junk", state->serialPort[0].dataIn);
-    assertEqual("Ack 3 1", state->serialPort[0].dataOut);
-
-    state->serialPort[0].dataOut = "";
-    smartLightswitchSerialHandler(myPin);
-    assertEqual(LOW, state->digitalPin[myPin]);
-    assertEqual("junk", state->serialPort[0].dataIn);
-    assertEqual("Ack 3 0", state->serialPort[0].dataOut);
-}
-```
-
-#### Pin History as ASCII
-
-
-For additional complexity, there are some cases where you want to use a pin as a serial port.  There are history functions for that too.
-
-```C++
-  int myPin = 3;
-
-  // digitial history as serial data, big-endian
-  bool bigEndian = true;
-  bool binaryAscii[24] = {
-    0, 1, 0, 1, 1, 0, 0, 1,  // Y
-    0, 1, 1, 0, 0, 1, 0, 1,  // e
-    0, 1, 1, 1, 0, 0, 1, 1   // s
-  };
-
-  // "send" these bits
-  for (int i = 0; i < 24; digitalWrite(myPin, binaryAscii[i++]));
-
-  // The first bit in the history is the initial value, which we will ignore
-  int offset = 1;
-
-  // We should be able to parse the bits as ascii
-  assertEqual("Yes", state->digitalPin[myPin].toAscii(offset, bigEndian));
-```
-
-Instead of queueing bits as ASCII for future use with `toAscii`, you can send those bits directly (and immediately) to the output using `outgoingFromAscii`.  Likewise, you can reinterpret/examine (as ASCII) the bits you have previously queued up by calling `incomingToAscii` on the PinHistory object.
-
-
-#### Interactivity of "Devices" with Observers
-
-Even pin history and input/output buffers aren't capable of testing interactive code.  For example, queueing the canned responses from a serial device before the requests are even sent to it is not a sane test environment; the library under test will see the entire future waiting for it on the input pin instead of a buffer that fills and empties over time.  This calls for something more complicated.
-
-In this example, we create a simple class to emulate a Hayes modem.  (For more information, dig into the `DataStreamObserver` code on which `DeviceUsingBytes` is based.
-
-```c++
-class FakeHayesModem : public DeviceUsingBytes {
-  public:
-    String mLast;
-
-    FakeHayesModem() : DeviceUsingBytes() {
-      mLast = "";
-      addResponseLine("AT", "OK");
-      addResponseLine("ATV1", "NO CARRIER");
-    }
-    virtual ~FakeHayesModem() {}
-    virtual void onMatchInput(String output) { mLast = output; }
-};
-
-unittest(modem_hardware)
-{
-  GodmodeState* state = GODMODE();
-  state->reset();
-  FakeHayesModem m;
-  m.attach(&Serial);
-
-  Serial.write("AT\n");
-  assertEqual("AT\n", state->serialPort[0].dataOut);
-  assertEqual("OK\n", m.mLast);
-}
-```
-
-Note that instead of setting `mLast = output` in the `onMatchInput()` function for test purposes, we could just as easily queue some bytes to state->serialPort[0].dataIn for the library under test to find on its next `peek()` or `read()`.  Or we could execute some action on a digital or analog input pin; the possibilities are fairly endless in this regard, although you will have to define them yourself -- from scratch -- extending the `DataStreamObserver` class to emulate your physical device.
-
-
-## Overriding default build behavior
-
-You can add `.arduino-ci.yml` files to the project directory (which will then apply to both `test/` and `examples/`), as well as to the `test/` directory and each example directory in `examples/`.  All defined fields can be overridden.
-
-You may define new platforms, or edit existing platform definitions:
+Next, you'll need this in `appveyor.yml` in your repo.
 
 ```yaml
-platforms:
-  bogo:
-    board: fakeduino:beep:bogo
-    package: potato:salad
-    gcc:
-      features:
-        - omit-frame-pointer  # becomes -fomit-frame-pointer flag
-      defines:
-        - HAVE_THING          # becomes -DHAVE_THING flag
-      warnings:
-        - no-implicit         # becomes -Wno-implicit flag
-      flags:
-        - -foobar             # becomes -foobar flag
-
-  zero: ~                     # undefines the `zero` board completely
-
-  esp8266:                    # redefines the existing esp8266
-    board: esp8266:esp8266:booo
-    package: esp8266:esp8266
-    gcc:
-      features:
-      defines:
-      warnings:
-      flags:
+build: off
+test_script:
+  - bundle install
+  - bundle exec arduino_ci_remote.rb
 ```
 
+## Quick Start
 
-For your example programs, you may set external libraries to be installed and included.  You may also choose the platforms on which the compilation will be attempted:
-
-```yaml
-compile:
-  libraries:
-    - "Adafruit FONA Library"
-  platforms:
-    - esp8266
-```
-
+This software is in beta.  But [SampleProjects/DoSomething](SampleProjects/DoSomething) has a decent writeup and is a good bare-bones example of all the features.
 
-For your unit tests, in addition to setting specific libraries and platforms, you may filter the list of test files that are compiled and tested.  This may help speed up targeted testing.
+## Reference
 
-```yaml
-unittest:
-  compilers:
-    - g++      # default
-    - g++-4.9
-    - g++-7
-  testfiles:
-    select:
-      - "*-*.*"
-    reject:
-      - "sam-squamsh.*"
-  libraries:
-    - "abc123"
-    - "def456"
-  platforms:
-    - bogo
-```
+For more information on the usage of `arduino_ci`, see [REFERENCE.md](REFERENCE.md).  It contains information such as:
 
-## More Documentation
+* Where to put unit test files
+* How to structure unit test files
+* How to control the global (physical) state of the Arduino board
+* How to modify the Arduino platforms, compilers, test plans, etc
 
-This software is in alpha.  But [SampleProjects/DoSomething](SampleProjects/DoSomething) has a decent writeup and is a good bare-bones example of all the features.
 
 ## Known Problems
 
@@ -384,6 +85,16 @@ This software is in alpha.  But [SampleProjects/DoSomething](SampleProjects/DoSo
 * https://github.com/ianfixes/arduino_ci/issues
 
 
+## Comparison to Other Arduino Testing Tools
+
+
+| Project | CI | Builds Examples | Unittest | Arduino Mocks | Windows | OSX | Linux | License |
+|---------|----|-----------------|----------|---------------|---------|-----|-------|---------|
+|[ArduinoCI](https://github.com/ianfixes/arduino_ci)| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |Free (Apache-2.0)|
+|[ArduinoUnit](https://github.com/mmurdoch/arduinounit)|❌ |❌ |Hardware-based|❌ | ✅ | ✅ | ✅ |Free (MIT)| |
+|[Adafruit `travis-ci-arduino`](https://github.com/adafruit/travis-ci-arduino)   | ✅ | ✅ | ❌| ❌ | ❌ | ❌ | ✅ |Free (MIT)|
+|[PlatformIO](https://platformio.org)| ✅ | ✅ | Paid only | ❌ | ✅ | ✅ | ✅ |Proprietary (EULA)|
+
 ## Author
 
 This gem was written by Ian Katz (ianfixes@gmail.com) in 2018.  It's released under the Apache 2.0 license.
@@ -394,3 +105,4 @@ This gem was written by Ian Katz (ianfixes@gmail.com) in 2018.  It's released un
 * [Contributing](CONTRIBUTING.md)
 * [Adafruit/travis-ci-arduino](https://github.com/adafruit/travis-ci-arduino) which inspired this project
 * [mmurdoch/arduinounit](https://github.com/mmurdoch/arduinounit) from which the unit test macros were adopted
+

data/cpp/arduino/Arduino.h

@@ -14,6 +14,7 @@ Where possible, variable names from the Arduino library are used to avoid confli
 #include "Print.h"
 #include "Stream.h"
 #include "HardwareSerial.h"
+#include "SPI.h"
 
 typedef bool boolean;
 typedef uint8_t byte;
@@ -43,9 +44,6 @@ typedef uint8_t byte;
 #define yield() _NOP()
 #define interrupts() _NOP()
 #define noInterrupts() _NOP()
-#define attachInterrupt(...) _NOP()
-#define detachInterrupt(...) _NOP()
-
 
 // TODO: correctly establish this per-board!
 #define F_CPU 1000000UL
@@ -59,14 +57,6 @@ typedef unsigned int word;
 
 
 
-/*
-unsigned long pulseIn(uint8_t pin, uint8_t state, unsigned long timeout);
-unsigned long pulseInLong(uint8_t pin, uint8_t state, unsigned long timeout);
-
-void shiftOut(uint8_t dataPin, uint8_t clockPin, uint8_t bitOrder, uint8_t val);
-uint8_t shiftIn(uint8_t dataPin, uint8_t clockPin, uint8_t bitOrder);
-
-*/
 
 // Get the bit location within the hardware port of the given virtual pin.
 // This comes from the pins_*.c file for the active board configuration.
@@ -74,43 +64,6 @@ uint8_t shiftIn(uint8_t dataPin, uint8_t clockPin, uint8_t bitOrder);
 #define analogInPinToBit(P) (P)
 #define digitalPinToInterrupt(P) (P)
 
-/*
-// On the ATmega1280, the addresses of some of the port registers are
-// greater than 255, so we can't store them in uint8_t's.
-extern const uint16_t PROGMEM port_to_mode_PGM[];
-extern const uint16_t PROGMEM port_to_input_PGM[];
-extern const uint16_t PROGMEM port_to_output_PGM[];
-
-extern const uint8_t PROGMEM digital_pin_to_port_PGM[];
-// extern const uint8_t PROGMEM digital_pin_to_bit_PGM[];
-extern const uint8_t PROGMEM digital_pin_to_bit_mask_PGM[];
-extern const uint8_t PROGMEM digital_pin_to_timer_PGM[];
-
-// Get the bit location within the hardware port of the given virtual pin.
-// This comes from the pins_*.c file for the active board configuration.
-//
-// These perform slightly better as macros compared to inline functions
-//
-#define digitalPinToPort(P) ( pgm_read_byte( digital_pin_to_port_PGM + (P) ) )
-#define digitalPinToBitMask(P) ( pgm_read_byte( digital_pin_to_bit_mask_PGM + (P) ) )
-#define digitalPinToTimer(P) ( pgm_read_byte( digital_pin_to_timer_PGM + (P) ) )
-#define analogInPinToBit(P) (P)
-#define portOutputRegister(P) ( (volatile uint8_t *)( pgm_read_word( port_to_output_PGM + (P))) )
-#define portInputRegister(P) ( (volatile uint8_t *)( pgm_read_word( port_to_input_PGM + (P))) )
-#define portModeRegister(P) ( (volatile uint8_t *)( pgm_read_word( port_to_mode_PGM + (P))) )
-
-*/
-
-
-/* TODO
-
-// USB
-#include "USBAPI.h"
-Keyboard
-Mouse
-
-*/
-
 // uint16_t makeWord(uint16_t w);
 // uint16_t makeWord(byte h, byte l);
 inline unsigned int makeWord(unsigned int w) { return w; }
@@ -118,23 +71,6 @@ inline unsigned int makeWord(unsigned char h, unsigned char l) { return (h << 8)
 
 #define word(...) makeWord(__VA_ARGS__)
 
-unsigned long pulseIn(uint8_t pin, uint8_t state, unsigned long timeout = 1000000L);
-unsigned long pulseInLong(uint8_t pin, uint8_t state, unsigned long timeout = 1000000L);
-
-// audio is taken care of in GODMODE
-
-
-// BIG TODO ON THIS ONE
-// $ find . | grep pins_
-// ./arduino-1.8.5/hardware/arduino/avr/variants/circuitplay32u4/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/eightanaloginputs/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/ethernet/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/gemma/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/leonardo/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/mega/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/micro/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/robot_control/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/robot_motor/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/standard/pins_arduino.h
-// ./arduino-1.8.5/hardware/arduino/avr/variants/yun/pins_arduino.h
-// #include "pins_arduino.h"
+
+
+