Add DeviceUsingBytes implementation

Author: ianfixes

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Queue template implementation
 - Table template implementation
 - ObservableDataStream and DataStreamObserver pattern implementation
+- DeviceUsingBytes and implementation of mocked serial device
 
 ### Changed
 - Unit test executables print to STDERR just in case there are segfaults.  Uh, just in case I ever write any.

README.md

@@ -70,6 +70,8 @@ unittest(example_godmode_stuff)
 }
 ```
 
+#### 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++
@@ -102,6 +104,9 @@ unittest(pin_history)
   }
 ```
 
+
+#### 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++
@@ -134,6 +139,9 @@ unittest(pin_read_history)
 }
 ```
 
+#### Serial Data
+
+
 A more complicated example: working with serial port IO.  Let's say I have the following function:
 
 ```C++
@@ -191,10 +199,10 @@ unittest(two_flips)
 }
 ```
 
+#### Pin History as ASCII
 
 
-
-Finally, there are some cases where you want to use a pin as a serial port.  There are history functions for that too.
+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;
@@ -217,6 +225,45 @@ Finally, there are some cases where you want to use a pin as a serial port.  The
   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.

SampleProjects/TestSomething/test/deviceusingbytes.cpp

@@ -0,0 +1,93 @@
+#include <Arduino.h>
+#include <ArduinoUnitTests.h>
+#include <SoftwareSerial.h>
+#include <ci/DeviceUsingBytes.h>
+
+// DeviceUsingBytes extends DataStreamObserver,
+// so we will be able to attach this class to an
+// ObservableDataStream object, of which the pin
+// history (soft-serial) and HardwareSerial
+// objects are.
+class FakeHayesModem : public DeviceUsingBytes {
+  public:
+    String mLast;
+    bool mMatchedInput;
+
+    FakeHayesModem() : DeviceUsingBytes() {
+      mLast = "";
+      mMatchedInput = false;
+      addResponseLine("AT", "OK");
+      addResponseLine("ATV1", "NO CARRIER");
+    }
+
+    virtual ~FakeHayesModem() {}
+
+    virtual void onMatchInput(String output) {
+      mLast = output;
+      mMatchedInput = true;
+    }
+};
+
+unittest(modem_hardware)
+{
+  GodmodeState* state = GODMODE();
+  state->reset();
+
+  String cmd = "AT\n";
+
+  FakeHayesModem m;
+  m.attach(&Serial);
+  assertEqual(0, Serial.available());
+  assertFalse(m.mMatchedInput);
+  assertEqual("", m.mMessage);
+
+  for (int i = 0; i < cmd.length(); ++i) {
+    assertEqual(i, m.mMessage.length());  // before we write, length should equal i
+    Serial.write(cmd[i]);
+  }
+  assertEqual(0, m.mMessage.length());  // should have matched and reset
+
+  assertEqual("", state->serialPort[0].dataIn);
+  assertEqual("AT\n", state->serialPort[0].dataOut);
+
+  assureTrue(m.mMatchedInput);
+  //assertEqual(3, Serial.available());
+  assertEqual("OK\n", m.mLast);
+}
+
+unittest(modem_software)
+{
+  GodmodeState* state = GODMODE();
+  state->reset();
+
+  bool bigEndian = false;
+  bool flipLogic = false;
+  SoftwareSerial ss(1, 2, flipLogic);
+  ss.listen();
+
+  String cmd = "AT\n";
+
+  FakeHayesModem m;
+  m.attach(&state->digitalPin[2]);
+  assertEqual(0, ss.available());
+  assertFalse(m.mMatchedInput);
+  assertEqual("", m.mMessage);
+
+  for (int i = 0; i < cmd.length(); ++i) {
+    assertEqual(i, m.mMessage.length());  // before we write, length should equal i
+    assertEqual(cmd.substr(0, i), state->digitalPin[2].toAscii(1, bigEndian));
+    assertEqual(cmd.substr(0, i), m.mMessage);
+    ss.write(cmd[i]);
+  }
+  assertEqual(0, m.mMessage.length());  // should have matched and reset
+
+  assertEqual("", state->digitalPin[1].incomingToAscii(1, bigEndian));
+  assertEqual("AT\n", state->digitalPin[2].toAscii(1, bigEndian));
+
+
+  assureTrue(m.mMatchedInput);
+  //assertEqual(3, Serial.available());
+  assertEqual("OK\n", m.mLast);
+}
+
+unittest_main()

cpp/arduino/HardwareSerial.h

@@ -29,13 +29,13 @@
 #define SERIAL_7O2 0x3C
 #define SERIAL_8O2 0x3E
 
-class HardwareSerial : public Stream
+class HardwareSerial : public Stream, public ObservableDataStream
 {
   protected:
     String* mGodmodeDataOut;
 
   public:
-    HardwareSerial(String* dataIn, String* dataOut, unsigned long* delay): Stream() {
+    HardwareSerial(String* dataIn, String* dataOut, unsigned long* delay): Stream(), ObservableDataStream() {
       mGodmodeDataIn      = dataIn;
       mGodmodeDataOut     = dataOut;
       mGodmodeMicrosDelay = delay;
@@ -51,7 +51,11 @@ class HardwareSerial : public Stream
     // virtual int read(void);
     // virtual int availableForWrite(void);
     // virtual void flush(void);
-    virtual size_t write(uint8_t aChar) { mGodmodeDataOut->append(String((char)aChar)); return 1; }
+    virtual size_t write(uint8_t aChar) {
+      mGodmodeDataOut->append(String((char)aChar));
+      advertiseByte((unsigned char)aChar);
+      return 1;
+    }
 
     inline size_t write(unsigned long n) { return write((uint8_t)n); }
     inline size_t write(long n) { return write((uint8_t)n); }

cpp/arduino/PinHistory.h

@@ -1,10 +1,11 @@
 #pragma once
 #include "ci/Queue.h"
+#include "ci/ObservableDataStream.h"
 #include "WString.h"
 
 // pins with history.
 template <typename T>
-class PinHistory {
+class PinHistory : public ObservableDataStream {
   private:
     Queue<T> qIn;
     Queue<T> qOut;
@@ -15,13 +16,14 @@ class PinHistory {
     }
 
     // enqueue ascii bits
-    void a2q(Queue<T> &q, String input, bool bigEndian) {
+    void a2q(Queue<T> &q, String input, bool bigEndian, bool advertise) {
       // 8 chars at a time, form up
       for (int j = 0; j < input.length(); ++j) {
         for (int i = 0; i < 8; ++i) {
           int shift = bigEndian ? 7 - i : i;
           unsigned char mask = (0x01 << shift);
           q.push(mask & input[j]);
+          if (advertise) advertiseBit(q.back()); // not valid for all possible types but whatever
         }
       }
     }
@@ -61,7 +63,7 @@ class PinHistory {
     unsigned int asciiEncodingOffsetIn;
     unsigned int asciiEncodingOffsetOut;
 
-    PinHistory() {
+    PinHistory() : ObservableDataStream() {
       asciiEncodingOffsetIn = 0;  // default is sensible
       asciiEncodingOffsetOut = 1; // default is sensible
     }
@@ -87,6 +89,7 @@ class PinHistory {
     const T &operator=(const T& i) {
       qIn.clear();
       qOut.push(i);
+      advertiseBit(qOut.back()); // not valid for all possible types but whatever
       return qOut.back();
     }
 
@@ -107,10 +110,11 @@ class PinHistory {
       for (int i = 0; i < length; ++i) qIn.push(arr[i]);
     }
 
-    // enqueue ascii bits
-    void fromAscii(String input, bool bigEndian) { a2q(qIn, input, bigEndian); }
+    // enqueue ascii bits for future use by the retrieve() function
+    void fromAscii(String input, bool bigEndian) { a2q(qIn, input, bigEndian, false); }
 
-    void outgoingFromAscii(String input, bool bigEndian) { a2q(qOut, input, bigEndian); }
+    // send a stream of ascii bits immediately
+    void outgoingFromAscii(String input, bool bigEndian) { a2q(qOut, input, bigEndian, true); }
 
     // convert the queue of incoming data to a string as if it was Serial comms
     // start from offset, consider endianness
@@ -154,4 +158,3 @@ class PinHistory {
     }
 
 };
-

cpp/arduino/ci/DeviceUsingBytes.h

@@ -0,0 +1,56 @@
+#pragma once
+
+#include "ObservableDataStream.h"
+#include "Table.h"
+#include <WString.h>
+#include <Godmode.h>
+
+
+// Define a rudimentary serial device that responds to byte sequences
+//
+// The class monitors whatever stream it is observing, and builds up
+//  a buffer of the incoming data.  If/when that data matches one of
+//  the stored responses, the buffer is cleared and the response to
+//  the matched requests is sent to the handler `onMatchInput`
+//
+//  WARNING: if input is consumed and no matches are found, you are
+//    in a bad state where you can never match anything again.  @TODO
+//
+// The extender of this abstract class should provide the following:
+//   1. A set of responses using one of the provided convenience functions:
+//      * `addResponse`: request and response are taken verbatim
+//      * `addResponseLine`: request and response are appended a \n
+//      * `addResponseCRLF`: request and response are appended a \r\n
+//   2. An action `onMatchInput` -- what to do with a response when triggered
+class DeviceUsingBytes : public DataStreamObserver {
+  public:
+    String mMessage;
+    Table<String, String> mResponses;
+    GodmodeState* state;
+
+
+    DeviceUsingBytes() : DataStreamObserver(true, false) {
+      mMessage = "";
+      state = GODMODE();
+    }
+
+    virtual ~DeviceUsingBytes() {}
+
+    bool addResponse(String hear, String say) { return mResponses.add(hear, say); }
+    bool addResponseLine(String hear, String say) { return mResponses.add(hear + "\n", say + "\n"); }
+    bool addResponseCRLF(String hear, String say) { return mResponses.add(hear + "\r\n", say + "\r\n"); }
+
+    // what to do when there is a match
+    virtual void onMatchInput(String output) = 0;
+
+    virtual String observerName() const { return "DeviceUsingBytes"; }
+
+    virtual void onByte(unsigned char c) {
+      mMessage.concat(c);
+      if (mResponses.has(mMessage)) {
+        onMatchInput(mResponses.get(mMessage));
+        mMessage = "";
+      }
+    }
+};
+