Use the new SPI transaction API

This new API makes sure that we always use our own SPI settings for
every transaction, even when other libraries also use the SPI bus with
different settings.

This also means that SPI initialization is now taken care of by this
library, instead of having callers do that.

Since we always use the transaction API, this means Arduino 1.5.8 or
above is now required to use this library.

examples/GSClientTLS/GSClientTLS.ino

@@ -25,9 +25,7 @@ void setup() {
   //Serial1.begin(115200);
   //gs.begin(Serial1);
 
-  // Use SPI at 2Mhz (GS1500 supports up to 3.5Mhz)
-  SPI.setClockDivider(SPI_CLOCK_DIV8);
-  SPI.begin();
+  // Use SPI with SS on pin 7
   gs.begin(7);
 
   // Disable the NCM, just in case it was set to autostart. Wait a bit

examples/GSModuleDirect/GSModuleDirect.ino

@@ -24,9 +24,7 @@ void setup() {
   //Serial1.begin(115200);
   //gs.begin(Serial1);
 
-  // Use SPI at 2Mhz (GS1500 supports up to 3.5Mhz)
-  SPI.setClockDivider(SPI_CLOCK_DIV8);
-  SPI.begin();
+  // Use SPI with SS on pin 7
   gs.begin(7);
 
   // Write a custom command

examples/GSUdpClient/GSUdpClient.ino

@@ -26,9 +26,7 @@ void setup() {
   //Serial1.begin(115200);
   //gs.begin(Serial1);
 
-  // Use SPI at 2Mhz (GS1500 supports up to 3.5Mhz)
-  SPI.setClockDivider(SPI_CLOCK_DIV8);
-  SPI.begin();
+  // Use SPI with SS on pin 7
   gs.begin(7);
 
   // Disable the NCM, just in case it was set to autostart. Wait a bit

examples/GSUdpServer/GSUdpServer.ino

@@ -25,9 +25,7 @@ void setup() {
   //Serial1.begin(115200);
   //gs.begin(Serial1);
 
-  // Use SPI at 2Mhz (GS1500 supports up to 3.5Mhz)
-  SPI.setClockDivider(SPI_CLOCK_DIV8);
-  SPI.begin();
+  // Use SPI with SS on pin 7
   gs.begin(7);
 
   // Disable the NCM, just in case it was set to autostart. Wait a bit

examples/Ncm/Ncm.ino

@@ -39,21 +39,18 @@ void setup() {
   delay(2000);
   Serial.begin(115200);
 
-  // Use an UART
-  //Serial1.begin(115200);
-  //gs.begin(Serial1);
-
-  // Use SPI at 2Mhz (GS1500 supports up to 3.5Mhz)
-  SPI.setClockDivider(SPI_CLOCK_DIV8);
-  SPI.begin();
-
   // Set event handlers and let them print to Serial
   gs.onNcmConnect = onNcmConnect;
   gs.onNcmDisconnect = onNcmDisconnect;
   gs.onAssociate = onAssociate;
   gs.onDisassociate = onDisassociate;
   gs.eventData = &Serial;
 
+  // Use an UART
+  //Serial1.begin(115200);
+  //gs.begin(Serial1);
+
+  // Use SPI with SS on pin 7
   gs.begin(7);
 
 #if defined(GS_INIT) || defined(GS_ONCE)

src/GSModule/GSCore.cpp

@@ -81,17 +81,18 @@ bool GSCore::begin(Stream &serial)
   return res;
 }
 
-bool GSCore::begin(uint8_t ss, uint8_t data_ready)
+bool GSCore::begin(uint8_t ss, uint8_t data_ready, SPISettings settings)
 {
   if (this->serial || this->ss_pin != INVALID_PIN || ss == INVALID_PIN)
     return false;
 
   this->initializing = true;
   this->ss_pin = ss;
   this->data_ready_pin = data_ready;
-
+  this->spi_settings = settings;
   pinMode(ss, OUTPUT);
   digitalWrite(ss, HIGH);
+  SPI.begin();
 
   bool res = _begin();
   this->initializing = false;
@@ -646,9 +647,11 @@ uint8_t GSCore::transferSpi(uint8_t out)
 {
   // Note that we need to toggle SS for every byte, otherwise the module
   // will ignore subsequent bytes and return 0xff
+  SPI.beginTransaction(this->spi_settings);
   digitalWrite(this->ss_pin, LOW);
   uint8_t in = SPI.transfer(out);
   digitalWrite(this->ss_pin, HIGH);
+  SPI.endTransaction();
   if (GS_DUMP_SPI && this->debug) {
     if (in != SPI_SPECIAL_IDLE || out != SPI_SPECIAL_IDLE) {
       dump_byte(this->debug, "SPI: >> ", out, false);

src/GSModule/GSCore.h

@@ -30,6 +30,11 @@
 #include <stdint.h>
 #include <Stream.h>
 #include <IPAddress.h>
+#include <SPI.h>
+
+#if !defined(SPI_HAS_TRANSACTION) || !SPI_HAS_TRANSACTION
+#error "This library requires Arduino IDE 1.5.8 or above, supporting the SPI transaction API"
+#endif
 
 // NOTE: In addition to enable output here, an output target should also
 // be supplied at runtime by calling the setLogOutput method.
@@ -135,6 +140,10 @@ class GSCore {
   /**
    * Set up this library to talk over SPI.
    *
+   * This calls SPI.begin and sets the clock rate and other settings on
+   * every transfer using SPI.beginTransaction, so ther is no need to
+   * call SPI.begin or SPI.setClockDivider beforehand.
+   *
    * @param ss          The Arduino pin number that is connected to the
    *                    Gainspan's SPI Slave Select pin. Will be
    *                    configured as an output pin automatically.
@@ -147,8 +156,12 @@ class GSCore {
    *                    this pin. This is not recommended, as it adds
    *                    extra delays and latencies and is not documented
    *                    to work by Gainspan.
+   * @param settings    The SPI settings to use. Defaults to (up to)
+   *                    1.2Mhz as reported by Gainspan (even though the
+   *                    datasheet suggests that 3.5Mhz should be
+   *                    possible).
    */
-  bool begin(uint8_t ss, uint8_t data_read = INVALID_PIN);
+  bool begin(uint8_t ss, uint8_t data_read = INVALID_PIN, SPISettings spi_settings = SPISettings(1200000, MSBFIRST, SPI_MODE0));
 
   /**
    * Clean up this library (for example to switch from UART to SPI).
@@ -738,6 +751,8 @@ class GSCore {
   uint8_t ss_pin = INVALID_PIN;
   /** The data_ready pin to use, in SPI mode */
   uint8_t data_ready_pin = INVALID_PIN;
+  /** The SPI settings to use, in SPI mode */
+  SPISettings spi_settings;
   /** When true, the module has sent xoff */
   bool spi_xoff;
   /** When true, the previous SPI byte was an escape character */