Refactored examples and added some helpful methods

Author: nothans

README.md

@@ -20,8 +20,24 @@ Include the library in your sketch and initialize it with your WiFi credentials.
 
 ## Methods
 
-- `begin(const char* ssid, const char* password)`: Initialize the library with your WiFi credentials.
+- `begin(const char* ssid, const char* password)`: Initialize the library with your WiFi credentials to let the library handle the WiFi connection.
+- `begin()`: Initialize the library without WiFi credentials (use this if you want to manually connect to the WiFi network and manage the WiFi connection outside of the library).
+- `reconnect()`: Reconnect to the WiFi network.
+- `isConnected()`: Returns a boolean indicating whether the library is connected to the WiFi network.
 - `getCurrentColor()`: Get the current CheerLights color from ThingSpeak channel 1417. Returns a pointer to a constant char array.
 - `currentColorName()`: The current CheerLights color name (e.g. "red"). Returns a pointer to a constant char array.
 - `currentColorHex()`: The current CheerLights color as a hex value (e.g. 0xFF0000). Returns a uint32_t.
-- `currentRed()`, `currentGreen()`, `currentBlue()`: The RGB values for the current CheerLights color (e.g. 255, 0, 0). Returns a uint8_t.
+- `currentRed()`, `currentGreen()`, `currentBlue()`: The RGB values for the current CheerLights color (e.g. 255, 0, 0). Returns a uint8_t.
+- `hasColorChanged()`: Returns a boolean indicating whether the current CheerLights color has changed since the last call to this method.
+
+## Compatibility
+
+This library supports WiFi-enabled Arduino-compatible boards. It has been tested with the following boards:
+
+- Arduino MKR1000
+- Arduino MKR WiFi 1010
+- Arduino Uno WiFi Rev2
+- Arduino Mega WiFi Rev2
+- Arduino Uno R4 WiFi
+- ESP8266
+- ESP32

examples/CheerLights_Basic/CheerLights_Basic.ino

@@ -0,0 +1,84 @@
+/*
+'CheerLights_Basic' example demonstrates how to use the CheerLights Arduino library to fetch and print the current CheerLights color.
+
+To join the CheerLights community, visit https://cheerlights.com.
+*/
+
+// Include the correct WiFi library based on the board
+#if defined(ESP8266)
+  #include <ESP8266WiFi.h>
+#elif defined(ESP32)
+  #include <WiFi.h>
+#elif defined(ARDUINO_SAMD_MKR1000)
+  // For Arduino MKR1000 using WiFi101 library
+  #include <WiFi101.h>
+#elif defined(ARDUINO_SAMD_MKRWIFI1010)
+  // For Arduino MKR WiFi 1010 using WiFiNINA library
+  #include <WiFiNINA.h>
+#elif defined(ARDUINO_AVR_UNO_WIFI_REV2)
+  // For Arduino Uno WiFi Rev2
+  #include <WiFiNINA.h>
+#elif defined(ARDUINO_ARCH_SAMD)
+  // For other SAMD boards
+  #include <WiFiNINA.h>
+#else
+  #include <WiFi.h>
+#endif
+
+// Include the CheerLights library and instantiate the CheerLights object
+#include <CheerLights.h>
+CheerLights CheerLights;
+
+// Include the secrets file that contains the WiFi credentials
+#include "secrets.h"
+
+unsigned long previousMillis = 0;
+const long updateInterval = 15000;
+
+void setup() {
+    // Initialize serial communication
+    Serial.begin(115200);
+
+    // Initialize the CheerLights library
+    CheerLights.begin(SECRET_SSID, SECRET_PASSWORD);
+
+    // Get the current CheerLights color and print it
+    CheerLights.getCurrentColor();
+    Serial.print("Current CheerLights Color: ");
+    Serial.println(CheerLights.currentColorName());
+}
+
+void loop() {
+    unsigned long currentMillis = millis();
+
+    // Update the LEDs every updateInterval milliseconds
+    if (currentMillis - previousMillis >= updateInterval) {
+        previousMillis = currentMillis;
+
+        // Get the current CheerLights color and print it
+        CheerLights.getCurrentColor();
+        Serial.print("Current CheerLights Color: ");
+        Serial.println(CheerLights.currentColorName());
+
+        // Print the current CheerLights color as a hex value
+        Serial.print("Current CheerLights Color Hex: ");
+        Serial.println(CheerLights.currentColorHex());
+
+        // Print the current CheerLights color as RGB values
+        Serial.print("Current CheerLights Color RGB: ");
+        Serial.print(CheerLights.currentRed());
+        Serial.print(", ");
+        Serial.print(CheerLights.currentGreen());
+        Serial.print(", ");
+        Serial.println(CheerLights.currentBlue());
+
+        // Check if the color has changed
+        if (CheerLights.hasColorChanged()) {
+            Serial.println("Color has changed!");
+        }
+        else {
+            Serial.println("Color has not changed.");
+        }
+        Serial.println("--------------------------------");
+    }
+} 

examples/CheerLightsExample/secrets.h renamed to examples/CheerLights_Basic/secrets.h

@@ -1,7 +1,7 @@
 /*
-'CheerLightsExample' demonstrates how to use the CheerLights Arduino library to fetch and display the current CheerLights color on an Adafruit NeoPixel LED strip.
+'CheerLights_NeoPixel_Strip' example demonstrates how to use the CheerLights Arduino library to fetch and display the current CheerLights color on an Adafruit NeoPixel LED strip.
 
-To learn more about CheerLights, visit https://cheerlights.com.
+To join the CheerLights community, visit https://cheerlights.com.
 */
 
 // Include the Adafruit NeoPixel library and initialize the strip
@@ -44,14 +44,20 @@ unsigned long previousMillis = 0;
 const long updateInterval = 15000;
 
 void setup() {
-    Serial.begin(115200);
+    // Initialize serial communication
+    Serial.begin(115200); 
+
+    // Initialize the CheerLights library
     CheerLights.begin(SECRET_SSID, SECRET_PASSWORD);
+
+    // Initialize the NeoPixel strip
     strip.begin();
 
     // Get the current CheerLights color and set the LEDs to that color
     CheerLights.getCurrentColor();
     Serial.print("Current CheerLights Color: ");
     Serial.println(CheerLights.currentColorName());
+    Serial.println("--------------------------------");
     setLEDColors(CheerLights.currentRed(), CheerLights.currentGreen(), CheerLights.currentBlue());
 }
 
@@ -66,6 +72,7 @@ void loop() {
         CheerLights.getCurrentColor();
         Serial.print("Current CheerLights Color: ");
         Serial.println(CheerLights.currentColorName());
+        Serial.println("--------------------------------");
         setLEDColors(CheerLights.currentRed(), CheerLights.currentGreen(), CheerLights.currentBlue());
     }
 }

examples/CheerLightsExample/CheerLightsExample.ino renamed to examples/CheerLights_NeoPixel_Strip/CheerLights_NeoPixel_Strip.ino

@@ -0,0 +1,2 @@
+#define SECRET_SSID     "MySSID"		// replace MySSID with your WiFi network name
+#define SECRET_PASSWORD "MyPassword"	// replace MyPassword with your WiFi password

examples/CheerLights_NeoPixel_Strip/secrets.h

@@ -6,3 +6,6 @@ currentRed		    KEYWORD2
 currentGreen		KEYWORD2
 currentBlue		    KEYWORD2
 begin		        KEYWORD2
+isConnected		    KEYWORD2
+hasColorChanged		KEYWORD2
+reconnect		    KEYWORD2

keywords.txt

@@ -1,18 +1,13 @@
 #include "CheerLights.h"
 
-#define MIN_UPDATE_INTERVAL 5000
-#define TIMEOUT             5000
-#define BUFFER_SIZE         128
-
 CheerLights::CheerLights() {
     strncpy(_colorName, "black", sizeof(_colorName) - 1);
     _colorName[sizeof(_colorName) - 1] = '\0';
     _colorHex = 0x000000;
+    _previousColorHex = 0x000000;
 }
 
 void CheerLights::begin(const char* ssid, const char* password) {
-  Serial.begin(115200);
-
   // Store WiFi credentials
   _ssid = ssid;
   _password = password;
@@ -21,34 +16,44 @@ void CheerLights::begin(const char* ssid, const char* password) {
   _connectToWiFi();
 }
 
+void CheerLights::begin() {
+  _ssid = nullptr;
+  _password = nullptr;
+}
+
+bool CheerLights::reconnect() {
+  if (WiFi.status() == WL_CONNECTED) {
+    return true;
+  }
+  
+  _connectToWiFi();
+  return WiFi.status() == WL_CONNECTED;
+}
+
 void CheerLights::_connectToWiFi() {
-  Serial.print("Connecting to WiFi");
+  if (_ssid == nullptr || _password == nullptr) {
+    return;
+  }
 
   WiFi.begin(_ssid, _password);
   while (WiFi.status() != WL_CONNECTED) {
     delay(500);
-    Serial.print(".");
   }
-
-  Serial.println("\nConnected to WiFi");
 }
 
 void CheerLights::_fetchColor() {
   static unsigned long lastUpdate = 0;
   unsigned long currentTime = millis();
 
   if (currentTime - lastUpdate < MIN_UPDATE_INTERVAL) {
-    Serial.println("Update interval not reached, skipping request.");
     return;
   }
   lastUpdate = currentTime;
 
   // Check WiFi connection and attempt to reconnect if necessary
   if (WiFi.status() != WL_CONNECTED) {
-    Serial.println(F("WiFi not connected, attempting to reconnect..."));
     _connectToWiFi();
     if (WiFi.status() != WL_CONNECTED) {
-      Serial.println(F("Failed to reconnect to WiFi."));
       return;
     }
   }
@@ -59,7 +64,6 @@ void CheerLights::_fetchColor() {
 
   WiFiClient client;
   if (!client.connect(host, httpPort)) {
-    Serial.println(F("Connection to ThingSpeak failed"));
     client.stop();
     return;
   }
@@ -75,7 +79,6 @@ void CheerLights::_fetchColor() {
   unsigned long timeout = millis();
   while (client.connected() && !client.available()) {
     if (millis() - timeout > TIMEOUT) {
-      Serial.println(F(">>> Client Timeout!"));
       client.stop();
       return;
     }
@@ -136,6 +139,7 @@ void CheerLights::_fetchColor() {
   for (const auto& color : colorMap) {
     if (strcasecmp(_colorName, color.name) == 0) {
       _colorHex = color.color;
+      _previousColorHex = _colorHex;
       break;
     }
   }
@@ -165,3 +169,11 @@ uint8_t CheerLights::currentGreen() {
 uint8_t CheerLights::currentBlue() {
   return _colorHex & 0xFF;
 }
+
+bool CheerLights::isConnected() {
+  return WiFi.status() == WL_CONNECTED;
+}
+
+bool CheerLights::hasColorChanged() {
+  return _colorHex != _previousColorHex;
+}

src/CheerLights.cpp

@@ -4,6 +4,10 @@
 #include <Arduino.h>
 #include <WiFiClient.h>
 
+#define MIN_UPDATE_INTERVAL 5000
+#define TIMEOUT             5000
+#define BUFFER_SIZE         128
+
 // Include the correct WiFi library based on the board
 #if defined(ESP8266)
   #include <ESP8266WiFi.h>
@@ -29,20 +33,24 @@ class CheerLights {
   public:
     CheerLights();
     void begin(const char* ssid, const char* password);
+    void begin();
+    bool reconnect();
     const char* getCurrentColor();
     const char* currentColorName();
     uint32_t currentColorHex();
     uint8_t currentRed();
     uint8_t currentGreen();
     uint8_t currentBlue();
-
+    bool isConnected();
+    bool hasColorChanged();
   private:
     void _connectToWiFi();
     void _fetchColor();
     const char* _ssid;
     const char* _password;
     char _colorName[32];
     uint32_t _colorHex;
+    uint32_t _previousColorHex;
 };
 
 #endif // CHEERLIGHTS_H