StandardFirmataEthernet improvements

- Break out ethernet config to ethernetConfig.h file included with sketch
- Update comments to be more descriptive
- Update both StandardFirmataEthernet and StandardFirmataEthernetPlus

Author: soundanalogous

examples/StandardFirmataEthernet/StandardFirmataEthernet.ino

@@ -11,7 +11,7 @@
   Copyright (C) 2006-2008 Hans-Christoph Steiner.  All rights reserved.
   Copyright (C) 2010-2011 Paul Stoffregen.  All rights reserved.
   Copyright (C) 2009 Shigeru Kobayashi.  All rights reserved.
-  Copyright (C) 2009-2015 Jeff Hoefs.  All rights reserved.
+  Copyright (C) 2009-2016 Jeff Hoefs.  All rights reserved.
 
   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
@@ -20,20 +20,24 @@
 
   See file LICENSE.txt for further informations on licensing terms.
 
-  Last updated by Jeff Hoefs: December 26th, 2015
+  Last updated by Jeff Hoefs: January 9th, 2016
 */
 
 /*
   README
 
+  StandardFirmataEthernet is a client implementation. You will need a Firmata client library with
+  a network transport that can act as a server in order to establish a connection between
+  StandardFirmataEthernet and the Firmata client application.
+
   To use StandardFirmataEthernet you will need to have one of the following
   boards or shields:
 
   - Arduino Ethernet shield (or clone)
   - Arduino Ethernet board (or clone)
   - Arduino Yun
 
-  Follow the instructions in the NETWORK CONFIGURATION section below to
+  Follow the instructions in the ethernetConfig.h file (ethernetConfig.h tab in Arduino IDE) to
   configure your particular hardware.
 
   NOTE: If you are using an Arduino Ethernet shield you cannot use the following pins on
@@ -43,6 +47,7 @@
   - Arduino Mega: (D4, D10, D50, D51, D52, D53)
   - Arduino Leonardo: (D4, D10)
   - Arduino Due: (D4, D10)
+  - Arduino Zero: (D4, D10)
 
   If you are using an ArduinoEthernet board, the following pins cannot be used (same as Uno):
   - D4, D10, D11, D12, D13
@@ -52,9 +57,18 @@
 #include <Wire.h>
 #include <Firmata.h>
 
+/*
+ * Uncomment the #define SERIAL_DEBUG line below to receive serial output messages relating to your connection
+ * that may help in the event of connection issues. If defined, some boards may not begin executing this sketch
+ * until the Serial console is opened.
+ */
 //#define SERIAL_DEBUG
 #include "utility/firmataDebug.h"
 
+// follow the instructions in ethernetConfig.h to configure your particular hardware
+#include "ethernetConfig.h"
+#include "utility/EthernetClientStream.h"
+
 #define I2C_WRITE                   B00000000
 #define I2C_READ                    B00001000
 #define I2C_READ_CONTINUOUSLY       B00010000
@@ -70,85 +84,11 @@
 // the minimum interval for sampling analog input
 #define MINIMUM_SAMPLING_INTERVAL   1
 
-
-/*==============================================================================
- * NETWORK CONFIGURATION
- *
- * You must configure your particular hardware. Follow the steps below.
- *============================================================================*/
-
-// STEP 1 [REQUIRED]
-// Uncomment / comment the appropriate set of includes for your hardware (OPTION A or B)
-// Option A is enabled by default.
-
-/*
- * OPTION A: Configure for Arduino Ethernet board or shield
- *
- * To configure StandardFirmataEthernet to use the original WIZ5100-based
- * ethernet shield or Arduino Ethernet uncomment the includes of 'SPI.h' and 'Ethernet.h':
- */
-
-#include <SPI.h>
-#include <Ethernet.h>
-
-/*
- * OPTION B: Configure for Arduin Yun
- *
- * To execute StandardFirmataEthernet on Yun uncomment Bridge.h and YunClient.h.
- * Do not include Ethernet.h or SPI.h above in this case.
- * On Yun there's no need to configure local_ip and mac in the sketch
- * as this is configured on the linux-side of Yun.
- */
-
-// #include <Bridge.h>
-// #include <YunClient.h>
-
-
-// STEP 2 [REQUIRED for all boards and shields]
-// replace with IP of the server you want to connect to, comment out if using 'remote_host'
-#define remote_ip IPAddress(10, 0, 0, 3)
-// *** REMOTE HOST IS NOT YET WORKING ***
-// replace with hostname of server you want to connect to, comment out if using 'remote_ip'
-// #define remote_host "server.local"
-
-// STEP 3 [REQUIRED unless using Arduin Yun]
-// Replace with the port that your server is listening on
-#define remote_port 3030
-
-// STEP 4 [REQUIRED unless using Arduino Yun OR if not using DHCP]
-// Replace with your board or ethernet shield's IP address
-// Comment out if you want to use DHCP
-#define local_ip IPAddress(10, 0, 0, 15)
-
-// STEP 5 [REQUIRED unless using Arduino Yun]
-// replace with ethernet shield mac. Must be unique for your network
-const byte mac[] = {0x90, 0xA2, 0xDA, 0x00, 0x53, 0xE5};
-
-// Since Arduino 1.6.6 ethernet_h is not recognized, even when Ethernet.h is included so this
-// always throws the error. Commenting out until the issue introduced in Arduino 1.6.6 is resolved.
-// #if !defined ethernet_h && !defined _YUN_CLIENT_H_
-// #error "you must uncomment the includes for your board configuration. See OPTIONS A and B in the NETWORK CONFIGURATION SECTION"
-// #endif
-
-#if defined remote_ip && defined remote_host
-#error "cannot define both remote_ip and remote_host at the same time!"
-#endif
-
-
 /*==============================================================================
  * GLOBAL VARIABLES
  *============================================================================*/
 
 /* network */
-
-#include "utility/EthernetClientStream.h"
-
-#ifdef _YUN_CLIENT_H_
-YunClient client;
-#else
-EthernetClient client;
-#endif
-
 #if defined remote_ip && !defined remote_host
 #ifdef local_ip
 EthernetClientStream stream(client, local_ip, remote_ip, NULL, remote_port);
@@ -845,7 +785,7 @@ void setup()
 {
   DEBUG_BEGIN(9600);
 
-#ifdef _YUN_CLIENT_H_
+#ifdef YUN_ETHERNET
   Bridge.begin();
 #else
 #ifdef local_ip
@@ -868,27 +808,26 @@ void setup()
   Firmata.attach(START_SYSEX, sysexCallback);
   Firmata.attach(SYSTEM_RESET, systemResetCallback);
 
+#ifdef WIZ5100_ETHERNET
   // StandardFirmataEthernet communicates with Ethernet shields over SPI. Therefore all
   // SPI pins must be set to IGNORE. Otherwise Firmata would break SPI communication.
   // add Pin 10 and configure pin 53 as output if using a MEGA with an Ethernet shield.
 
-  // ignore SPI and pin 4 that is SS for SD-Card on Ethernet-shield
   for (byte i = 0; i < TOTAL_PINS; i++) {
-    if (IS_PIN_SPI(i)
-        || 4 == i  // SD-Card on Ethernet-shield uses pin 4 for SS
-        || 10 == i // Ethernet-shield uses pin 10 for SS
-#if defined(__AVR_ATmega32U4__)
+    if (IS_IGNORE_ETHERNET_SHIELD(i)
+  #if defined(__AVR_ATmega32U4__)
         || 24 == i // On Leonardo, pin 24 maps to D4 and pin 28 maps to D10
         || 28 == i
-#endif
+  #endif
        ) {
       pinConfig[i] = PIN_MODE_IGNORE;
     }
   }
 
-  // Arduino Ethernet, Arduino EthernetShield and Arduino Yun all have SD SS wired to D4
+  // Arduino Ethernet and Arduino EthernetShield have SD SS wired to D4
   pinMode(PIN_TO_DIGITAL(4), OUTPUT);    // switch off SD card bypassing Firmata
   digitalWrite(PIN_TO_DIGITAL(4), HIGH); // SS is active low;
+#endif // WIZ5100_ETHERNET
 
 #if defined(__AVR_ATmega1280__) || defined(__AVR_ATmega2560__)
   pinMode(PIN_TO_DIGITAL(53), OUTPUT); // configure hardware SS as output on MEGA
@@ -937,9 +876,9 @@ void loop()
     }
   }
 
-#if !defined local_ip && !defined _YUN_CLIENT_H_
-  if (Ethernet.maintain())
-  {
+#if !defined local_ip && !defined YUN_ETHERNET
+  // only necessary when using DHCP, ensures local IP is updated appropriately if it changes
+  if (Ethernet.maintain()) {
     stream.maintain(Ethernet.localIP());
   }
 #endif

examples/StandardFirmataEthernet/ethernetConfig.h

@@ -0,0 +1,85 @@
+/*==============================================================================
+ * NETWORK CONFIGURATION
+ *
+ * You must configure your particular hardware. Follow the steps below.
+ *
+ * Currently StandardFirmataEthernet is configured as a client. An option to
+ * configure as a server may be added in the future.
+ *============================================================================*/
+
+// STEP 1 [REQUIRED]
+// Uncomment / comment the appropriate set of includes for your hardware (OPTION A or B)
+// Option A is enabled by default.
+
+/*
+ * OPTION A: Configure for Arduino Ethernet board or Arduino Ethernet shield (or clone)
+ *
+ * To configure StandardFirmataEthernet to use the original WIZ5100-based
+ * ethernet shield or Arduino Ethernet uncomment the WIZ5100_ETHERNET define below
+ */
+#define WIZ5100_ETHERNET
+
+#ifdef WIZ5100_ETHERNET
+#include <SPI.h>
+#include <Ethernet.h>
+EthernetClient client;
+#endif
+
+/*
+ * OPTION B: Configure for Arduin Yun
+ *
+ * The Ethernet port on the Arduino Yun board can be used with Firmata in this configuration.
+ *
+ * To execute StandardFirmataEthernet on Yun uncomment the YUN_ETHERNET define below and make
+ * sure the WIZ5100_ETHERNET define (above) is commented out.
+ *
+ * On Yun there's no need to configure local_ip and mac address as this is automatically
+ * configured on the linux-side of Yun.
+ */
+//#define YUN_ETHERNET
+
+#ifdef YUN_ETHERNET
+#include <Bridge.h>
+#include <YunClient.h>
+YunClient client;
+#endif
+
+
+// STEP 2 [REQUIRED for all boards and shields]
+// replace with IP of the server you want to connect to, comment out if using 'remote_host'
+#define remote_ip IPAddress(10, 0, 0, 3)
+// *** REMOTE HOST IS NOT YET WORKING ***
+// replace with hostname of server you want to connect to, comment out if using 'remote_ip'
+// #define remote_host "server.local"
+
+// STEP 3 [REQUIRED unless using Arduin Yun]
+// Replace with the port that your server is listening on
+#define remote_port 3030
+
+// STEP 4 [REQUIRED unless using Arduino Yun OR if not using DHCP]
+// Replace with your board or ethernet shield's IP address
+// Comment out if you want to use DHCP
+#define local_ip IPAddress(10, 0, 0, 15)
+
+// STEP 5 [REQUIRED unless using Arduino Yun]
+// replace with ethernet shield mac. Must be unique for your network
+const byte mac[] = {0x90, 0xA2, 0xDA, 0x00, 0x53, 0xE5};
+
+/*==============================================================================
+ * CONFIGURATION ERROR CHECK (don't change anything here)
+ *============================================================================*/
+
+#if !defined WIZ5100_ETHERNET && !defined YUN_ETHERNET
+#error "you must define either WIZ5100_ETHERNET or YUN_ETHERNET in ethernetConfig.h"
+#endif
+
+#if defined remote_ip && defined remote_host
+#error "cannot define both remote_ip and remote_host at the same time in ethernetConfig.h"
+#endif
+
+/*==============================================================================
+ * PIN IGNORE MACROS (don't change anything here)
+ *============================================================================*/
+
+// ignore SPI pins, pin 10 (Ethernet SS) and pin 4 (SS for SD-Card on Ethernet shield)
+#define IS_IGNORE_ETHERNET_SHIELD(p) ((IS_PIN_SPI(p) || (p) == 4) || (p) == 10)