feat: NoteSerial Interface (#42)

Author: zfields

library.properties

@@ -7,3 +7,4 @@ paragraph=Supports Serial and I2C for communication from a host MCU.
 category=Communication
 url=https://github.com/blues/note-arduino
 architectures=*
+includes=Notecard.h

src/NoteSerial.hpp

@@ -0,0 +1,72 @@
+#ifndef NOTE_SERIAL_HPP
+#define NOTE_SERIAL_HPP
+
+#include <stddef.h>
+#include <stdint.h>
+
+class NoteSerial {
+  public:
+    /**************************************************************************/
+    /*!
+        @brief  Type used to abstract specific hardware implementation types.
+    */
+    /**************************************************************************/
+    typedef void * channel_t;
+
+    virtual ~NoteSerial(void) {}
+
+    /**************************************************************************/
+    /*!
+        @brief  Determines if the Notecard Serial port has data available.
+        @return The number of bytes available to read.
+    */
+    /**************************************************************************/
+    virtual size_t available(void) = 0;
+
+    /**************************************************************************/
+    /*!
+        @brief  Read a byte from the Notecard Serial port.
+        @return A single character byte.
+    */
+    /**************************************************************************/
+    virtual char receive(void) = 0;
+
+    /**************************************************************************/
+    /*!
+        @brief  Resets the serial port.
+        @return `true` if the Serial port is available.
+    */
+    /**************************************************************************/
+    virtual bool reset(void) = 0;
+
+    /**************************************************************************/
+    /*!
+        @brief  Writes a message to the Notecard Serial port.
+        @param    buffer
+                The bytes to write.
+        @param    size
+                The number of bytes to write.
+        @param    flush
+                Use `true` to flush to Serial.
+        @return The number of bytes transmitted.
+    */
+    /**************************************************************************/
+    virtual size_t transmit(uint8_t * buffer, size_t size, bool flush) = 0;
+};
+
+/******************************************************************************/
+/*!
+    @brief  Helper function to abstract, create and maintain a single instance
+    of the NoteSerial interface implementation, as required by the underlying
+    `note-c` library.
+    @param[in] serial_channel  Pointer to the hardware specific UART
+    implementation.
+    @param[in] baut_rate       The operating baud rate for the UART.
+*/
+/******************************************************************************/
+NoteSerial * make_note_serial (
+    NoteSerial::channel_t serial_channel,
+    size_t baud_rate
+);
+
+#endif // NOTE_SERIAL_HPP

src/NoteSerial_Arduino.cpp

@@ -0,0 +1,61 @@
+#include "NoteSerial_Arduino.hpp"
+
+NoteSerial * make_note_serial (
+    NoteSerial::channel_t serial_channel_,
+    size_t baud_rate_
+) {
+    static NoteSerial * note_serial = nullptr;
+    if (note_serial) {
+        delete note_serial;
+    }
+    note_serial = new NoteSerial_Arduino(*reinterpret_cast<HardwareSerial *>(serial_channel_), baud_rate_);
+    return note_serial;
+}
+
+NoteSerial_Arduino::NoteSerial_Arduino
+(
+    HardwareSerial & hw_serial_,
+    size_t baud_rate_
+) :
+    _notecardSerial(hw_serial_),
+    _notecardSerialSpeed(baud_rate_)
+{
+    _notecardSerial.begin(_notecardSerialSpeed);
+}
+
+size_t
+NoteSerial_Arduino::available (
+    void
+) {
+    return _notecardSerial.available();
+}
+
+char
+NoteSerial_Arduino::receive (
+    void
+) {
+    return _notecardSerial.read();
+}
+
+bool
+NoteSerial_Arduino::reset (
+    void
+) {
+    _notecardSerial.begin(_notecardSerialSpeed);
+
+    return true;
+}
+
+size_t
+NoteSerial_Arduino::transmit (
+    uint8_t *buffer,
+    size_t size,
+    bool flush
+) {
+    size_t result;
+    result = _notecardSerial.write(buffer, size);
+    if (flush) {
+        _notecardSerial.flush();
+    }
+    return result;
+}

src/NoteSerial_Arduino.hpp

@@ -0,0 +1,25 @@
+#ifndef NOTE_SERIAL_ARDUINO_HPP
+#define NOTE_SERIAL_ARDUINO_HPP
+
+#include "NoteSerial.hpp"
+
+#ifndef MOCK
+  #include <Arduino.h>
+#else
+  #include "mock/mock-arduino.hpp"
+#endif
+
+class NoteSerial_Arduino final : public NoteSerial {
+  public:
+    NoteSerial_Arduino(HardwareSerial & hw_serial_, size_t baud_rate_);
+    size_t available(void) override;
+    char receive(void) override;
+    bool reset(void) override;
+    size_t transmit(uint8_t * buffer, size_t size, bool flush) override;
+
+  private:
+    HardwareSerial & _notecardSerial;
+    int _notecardSerialSpeed;
+};
+
+#endif // NOTE_SERIAL_ARDUINO_HPP

src/Notecard.cpp

@@ -42,9 +42,9 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+#include "NoteSerial.hpp"
+
 TwoWire *Notecard::_i2cPort;
-HardwareSerial *Notecard::_notecardSerial;
-int Notecard::_notecardSerialSpeed;
 Stream *Notecard::_debugSerial;
 bool Notecard::_debugSerialInitialized;
 
@@ -54,6 +54,46 @@ bool Notecard::_debugSerialInitialized;
 static const char *i2cerr = "i2c?";
 #endif
 
+namespace {
+    NoteSerial * noteSerial(nullptr);
+
+    bool noteSerialAvailable (void) {
+        bool result;
+        if (noteSerial) {
+            result = noteSerial->available();
+        } else {
+            result = false;
+        }
+        return result;
+    }
+
+    char noteSerialReceive (void) {
+        char result;
+        if (noteSerial) {
+            result = noteSerial->receive();
+        } else {
+            result = '\0';
+        }
+        return result;
+    }
+
+    bool noteSerialReset (void) {
+        bool result;
+        if (noteSerial) {
+            result = noteSerial->reset();
+        } else {
+            result = false;
+        }
+        return result;
+    }
+
+    void noteSerialTransmit (uint8_t *text_, size_t len_, bool flush_) {
+        if (noteSerial) {
+            noteSerial->transmit(text_, len_, flush_);
+        }
+    }
+}
+
 // 2018-06 ST Microelectronics has a HAL bug that causes an infinite hang.
 // This code enables us to exercise that code path to test the state of the bug.
 int _readLengthAdjustment = 0;
@@ -102,12 +142,10 @@ void Notecard::begin(uint32_t i2caddress, uint32_t i2cmax, TwoWire &wirePort)
 void Notecard::begin(HardwareSerial &selectedSerialPort, int selectedSpeed)
 {
     NoteSetFnDefault(malloc, free, delay, millis);
-    _notecardSerial = &selectedSerialPort;
-    _notecardSerialSpeed = selectedSpeed;
+    noteSerial = make_note_serial(&selectedSerialPort, selectedSpeed);
 
-    NoteSetFnSerial(Notecard::noteSerialReset, Notecard::noteSerialTransmit,
-                    Notecard::noteSerialAvailable, Notecard::noteSerialReceive);
-    _notecardSerial->begin(_notecardSerialSpeed);
+    NoteSetFnSerial(noteSerialReset, noteSerialTransmit,
+                    noteSerialAvailable, noteSerialReceive);
 }
 
 /**************************************************************************/
@@ -290,62 +328,6 @@ size_t Notecard::debugSerialOutput(const char *message)
     return(_debugSerial->print(message));
 }
 
-/**************************************************************************/
-/*!
-    @brief  Resets the serial port.
-    @return `True` if the Serial port is available.
-*/
-/**************************************************************************/
-bool Notecard::noteSerialReset()
-{
-    _notecardSerial->begin(_notecardSerialSpeed);
-
-    return (!!_notecardSerial);
-}
-
-/**************************************************************************/
-/*!
-    @brief  Writes a message to the Notecard Serial port.
-    @param    text
-              The text to write.
-    @param    len
-              The number of bytes to write.
-    @param    flush
-              `True` to flush to Serial.
-*/
-/**************************************************************************/
-void Notecard::noteSerialTransmit(uint8_t *text, size_t len, bool flush)
-{
-    _notecardSerial->write(text, len);
-    if (flush) {
-        _notecardSerial->flush();
-    }
-}
-
-/**************************************************************************/
-/*!
-    @brief  Determines if the Notecard Serial port has data available.
-    @return `True` if there are bytes available to read.
-*/
-/**************************************************************************/
-bool Notecard::noteSerialAvailable()
-{
-    return (_notecardSerial->available() > 0);
-}
-
-/**************************************************************************/
-/*!
-    @brief  Read a byte from the Notecard Serial port. guaranteed only ever to
-            be called if there is data available.
-    @return a single character byte.
-*/
-/**************************************************************************/
-char Notecard::noteSerialReceive()
-{
-    return _notecardSerial->read();
-}
-
-
 /**************************************************************************/
 /*!
     @brief  Resets the I2C port. Required by note-c.

src/Notecard.h

@@ -26,6 +26,7 @@
 
 #include <stddef.h>
 #include <stdint.h>
+
 #ifndef MOCK
 #include <Arduino.h>
 #include <HardwareSerial.h>
@@ -137,15 +138,9 @@ class Notecard
 
 private:
     static TwoWire *_i2cPort;
-    static HardwareSerial *_notecardSerial;
-    static int _notecardSerialSpeed;
     static Stream *_debugSerial;
     static bool _debugSerialInitialized;
 
-    static bool noteSerialReset(void);
-    static void noteSerialTransmit(uint8_t *text, size_t len, bool flush);
-    static bool noteSerialAvailable(void);
-    static char noteSerialReceive(void);
     static bool noteI2CReset(uint16_t DevAddress);
     static const char *noteI2CTransmit(uint16_t DevAddress, uint8_t* pBuffer, uint16_t Size);
     static const char *noteI2CReceive(uint16_t DevAddress, uint8_t* pBuffer, uint16_t Size, uint32_t *avail);