Merge pull request #2507 from kattni/canary-nightlight

Updated for customisability, readability.

Author: kattni

Canary_Nightlight/code.py

@@ -4,14 +4,13 @@
 """
 CircuitPython Canary Day and Night Light with Optional Network-Down Detection
 
-This project uses the QT Py ESP32-S3 with the NeoPixel 5x5 LED Grid BFF in a 3D printed bird.
-The LEDs light up blue or red based on a user-definable time.
+This project uses the QT Py ESP32-S3 with the NeoPixel 5x5 LED Grid BFF, along with
+a 3D printed bird. The LEDs light up different colors based on the time.
 
 In the event that the internet connection fails, it will begin blinking red to notify you.
 If the initial test ping fails, and the subsequent pings fail over 30 times, the board
 will reset. Otherwise, the blinking will continue until the connection is back up. This
-feature is enabled by default. It can easily be disabled at the beginning of the code,
-if desired.
+feature is enabled by default. It can easily be disabled at the beginning of the code.
 """
 import os
 import ssl
@@ -26,49 +25,90 @@
 import neopixel
 from adafruit_io.adafruit_io import IO_HTTP
 
-# This determines whether to run the network-down detection code, and therefore
-# whether to run the code that blinks when the network is down.
-# Defaults to True. Set to False to disable.
+# ============ CUSTOMISATIONS ============
+# Network-down detection enable or disable.
+# By default, the network-down detection code, and the code that blinks when the
+# network is down, are both enabled. If you wish to disable this feature,
+# including the blinking, update this to False.
 NETWORK_DOWN_DETECTION = True
 
-# This is the number of times ping should fail before it begins blinking.
-# If the blinking is happening too often, or if the network is often flaky,
-# this value can be increased to extend the number of failures it takes to
-# begin blinking. Defaults to 10.
-PING_FAIL_NUMBER_TO_BLINK = 10
+# The basic canary colors.
+# Red light at night is more conducive to sleep. Blue light in the morning is more
+# conducive to waking up. The sleep color defaults to red to promote sleep. The wake
+# color defaults to blue to promote wakefulness.
+SLEEP_COLOR = (255, 0, 0)  # Red
+WAKE_COLOR = (0, 0, 255)  # Blue
 
-# Red light at night is more conducive to sleep. This light is designed
-# to turn red at the chosen time to not disrupt sleep.
-# This is the hour in 24-hour time at which the light should change to red.
+# The blink color.
+# This is the color that the canary will blink to notify you that the network is down.
+# Defaults to red.
+BLINK_COLOR = (255, 0, 0)
+
+# Canary brightness customisation.
+# Both the options below must be a float between 0.0 and 1.0, where 0.0 is off, and 1.0 is max.
+# This is the brightness of the canary during sleep time. It defaults to 0.2, or "20%".
+# Increase or decrease this value to change the brightness.
+SLEEP_BRIGHTNESS = 0.2
+# This is the brightness of the canary during wake time. It defaults to 0.7, or "70%".
+# Increase or decrease this value to change the brightness.
+WAKE_BRIGHTNESS = 0.7
+
+# Consecutive ping fail to blink.
+# This value is the number of times ping will consecutively fail before the canary begins blinking.
+# If the blinking is happening too often, or if the network is often flaky, this value can be
+# increased to extend the number of failures it takes to begin blinking.
+# Defaults to 10. Must be an integer greater than 1.
+CONSECUTIVE_PING_FAIL_TO_BLINK = 10
+
+# Ping interval while ping is successful.
+# This is the interval at which the code will send a ping while the network is up and the pings
+# are successful. If for any reason you would prefer to slow down the ping interval, this value
+# can be updated. Defaults to 1 second. Must be a float greater than 1. Increase this value to
+# increase the ping interval time. Do not decrease this value!
+UP_PING_INTERVAL = 1
+
+# Checks whether the successful ping interval is below the minimum value.
+if UP_PING_INTERVAL < 1:
+    # If is below the minimum, raise this error and stop the code.
+    raise ValueError("UP_PING_INTERVAL must be a float greater than 1!")
+
+# Sleep time.
+# This is the hour in 24-hour time at which the light should change to the
+# desired color for the time you intend to sleep.
 # Must be an integer between 0 and 23. Defaults to 20 (8pm).
-RED_TIME = 20
+SLEEP_TIME = 20
 
-# Blue light in the morning is more conducive to waking up. This light is designed
-# to turn blue at the chosen time to promote wakefulness.
-# This is the hour in 24-hour time at which the light should change to blue.
+# Wake time.
+# This is the hour in 24-hour time at which the light should change to the
+# desired color for the time you intend to be awake.
 # Must be an integer between 0 and 23. Defaults to 6 (6am).
-BLUE_TIME = 6
+WAKE_TIME = 6
 
-# NeoPixel brightness configuration.
-# Both the options below must be a float between 0.0 and 1.0, where 0.0 is off, and 1.0 is max.
-# This is the brightness of the LEDs when they are red. As this is expected to be
-# during a time when you are heading to sleep, it defaults to 0.2, or "20%".
-# Increase or decrease this value to change the brightness.
-RED_BRIGHTNESS = 0.2
+# Time check interval.
+# This sets the time interval at which the code checks Adafruit IO for the current time.
+# This is included because Adafruit IO has rate limiting. It ensures that you do not
+# hit the rate limit, and the time check does not get throttled.
+# Defaults to 300 seconds (5 minutes). Must be a float greater than 300. Increase
+# this value to increase the time check interval. Do not decrease this value!
+TIME_CHECK_INTERVAL = 300
 
-# This is the brightness of the LEDs when they are blue. As this is expected to be
-# during a time when you want wakefulness, it defaults to 0.7, or "70%".
-# Increase or decrease this value to change the brightness.
-BLUE_BRIGHTNESS = 0.7
+# Checks whether the time check interval is below the minimum value.
+if TIME_CHECK_INTERVAL < 300:
+    # If is below the minimum, raise this error and stop the code.
+    raise ValueError("TIME_CHECK_INTERVAL must be a float greater than 300!")
 
-# Define the light colors. The default colors are blue and red.
-BLUE = (0, 0, 255)
-RED = (255, 0, 0)
+# IP address.
+# This is the IP address used to ping to verify that network connectivity is still present.
+# To switch to a different IP, update the following. Must be a valid IPV4 address as a
+# string (in quotes). Defaults to one of the OpenDNS IPs.
+PING_IP = "208.67.222.222"
 
+# ============ HARDWARE AND CODE SET UP ============
 # Instantiate the NeoPixel object.
 pixels = neopixel.NeoPixel(board.A3, 25)
 
 
+# Create helper functions
 def reload_on_error(delay, error_content=None, reload_type="reload"):
     """
     Reset the board when an error is encountered.
@@ -102,17 +142,17 @@ def color_time(current_hour):
     :param current_hour: Provide a time, hour only. The `tm_hour` part of the
                          `io.receive_time()` object is acceptable here.
     """
-    if BLUE_TIME < RED_TIME:
-        if BLUE_TIME <= current_hour < RED_TIME:
-            pixels.brightness = BLUE_BRIGHTNESS
-            return BLUE
-        pixels.brightness = RED_BRIGHTNESS
-        return RED
-    if RED_TIME <= current_hour < BLUE_TIME:
-        pixels.brightness = RED_BRIGHTNESS
-        return RED
-    pixels.brightness = BLUE_BRIGHTNESS
-    return BLUE
+    if WAKE_TIME < SLEEP_TIME:
+        if WAKE_TIME <= current_hour < SLEEP_TIME:
+            pixels.brightness = WAKE_BRIGHTNESS
+            return WAKE_COLOR
+        pixels.brightness = SLEEP_BRIGHTNESS
+        return SLEEP_COLOR
+    if SLEEP_TIME <= current_hour < WAKE_TIME:
+        pixels.brightness = SLEEP_BRIGHTNESS
+        return SLEEP_COLOR
+    pixels.brightness = WAKE_BRIGHTNESS
+    return WAKE_COLOR
 
 
 def blink(color):
@@ -121,10 +161,10 @@ def blink(color):
 
     :param tuple color: The color the LEDs will blink.
     """
-    if color_time(sundial.tm_hour) == RED:
-        pixels.brightness = RED_BRIGHTNESS
+    if color_time(sundial.tm_hour) == SLEEP_COLOR:
+        pixels.brightness = SLEEP_BRIGHTNESS
     else:
-        pixels.brightness = BLUE_BRIGHTNESS
+        pixels.brightness = WAKE_BRIGHTNESS
     pixels.fill(color)
     time.sleep(0.5)
     pixels.fill((0, 0, 0))
@@ -138,20 +178,23 @@ def blink(color):
     pool = socketpool.SocketPool(wifi.radio)
     requests = adafruit_requests.Session(pool, ssl.create_default_context())
 except Exception as error:  # pylint: disable=broad-except
-    # The exceptions raised by the wifi module are not always clear. If you're receiving errors,
+    # The exceptions raised by the `wifi` module are not always clear. If you're receiving errors,
     # check your SSID and password before continuing.
     print("Wifi connection failed.")
     reload_on_error(5, error)
 
-# Set up IP address to ping to test internet connection, and do an initial ping.
-# This address is an OpenDNS IP.
-ip_address = ipaddress.IPv4Address("208.67.222.222")
+# Set up IP address to use for pinging, as defined above.
+ip_address = ipaddress.IPv4Address(PING_IP)
+# Set up ping, and send initial ping.
 wifi_ping = wifi.radio.ping(ip=ip_address)
-if wifi_ping is None:  # If the initial ping is unsuccessful...
-    print("Setup test-ping failed.")  # ...print this message...
-    initial_ping = False  # ...and set initial_ping to False to indicate the failure.
-else:  # Otherwise...
-    initial_ping = True  # ...set initial_ping to True to indicate success.
+# If the initial ping is unsuccessful, print the message.
+if wifi_ping is None:
+    print("Setup test-ping failed.")
+    # Set `initial_ping` to False to indicate the failure.
+    initial_ping = False
+else:
+    # Otherwise, set `initial_ping` to True to indicate success.
+    initial_ping = True
 
 # Set up Adafruit IO. This will provide the current time through `io.receive_time()`.
 io = IO_HTTP(os.getenv("aio_username"), os.getenv("aio_key"), requests)
@@ -162,45 +205,44 @@ def blink(color):
 try:
     sundial = io.receive_time()  # Create the sundial variable to keep the time.
 except Exception as error:  # pylint: disable=broad-except
-    # If the time retrieval fails with an error...
-    print(
-        "Adafruit IO set up and/or time retrieval failed."
-    )  # ...print this message...
-    reload_on_error(5, error)  # ...wait 5 seconds, and soft reload the board.
-
-# Set up various time intervals for tracking non-blocking time intervals
-time_check_interval = 300
-ping_interval = 1
+    # If the time retrieval fails with an error, print the message.
+    print("Adafruit IO set up and/or time retrieval failed.")
+    # Then wait 5 seconds, and soft reload the board.
+    reload_on_error(5, error)
 
-# Initialise various time tracking variables
+# Initialise various time tracking variables.
 ping_time = 0
 check_time = 0
 ping_fail_time = time.monotonic()
 
-# Initialise ping fail count tracking
+# Initialise ping fail count tracking.
 ping_fail_count = 0
+
+# ============ LOOP ============
 while True:
     # Resets current_time to the current time.monotonic() value every time through the loop.
     current_time = time.monotonic()
     # WiFi and IO connections can fail arbitrarily. The bulk of the loop is included in a
     # try/except block to ensure the project will continue to run unattended if any
     # failures do occur.
     try:
-        # If the first run of the code, or ping_interval time has passed...
-        if not ping_time or current_time - ping_time > ping_interval:
+        # If this is the first run of the code or `UP_PING_INTERVAL` time has passed, continue.
+        if not ping_time or current_time - ping_time > UP_PING_INTERVAL:
             ping_time = time.monotonic()
-            wifi_ping = wifi.radio.ping(ip=ip_address)  # ...ping to verify network connection.
-            if wifi_ping is not None:  # If the ping is successful...
-                # ...print IP address and ping time.
+            # Ping to verify network connection.
+            wifi_ping = wifi.radio.ping(ip=ip_address)
+            if wifi_ping is not None:
+                # If the ping is successful, print IP address and ping time.
                 print(f"Pinging {ip_address}: {wifi_ping} ms")
 
-        # If the ping is successful...
+        # If the ping is successful, continue with this code.
         if wifi_ping is not None:
             ping_fail_count = 0
-            # If the first run of the code or time_check_interval has passed...
-            if not check_time or current_time - check_time > time_check_interval:
+            # If this is the first run of the code or `TIME_CHECK_INTERVAL` has passed, continue.
+            if not check_time or current_time - check_time > TIME_CHECK_INTERVAL:
                 check_time = time.monotonic()
-                sundial = io.receive_time()  # Retrieve the time and save it to sundial.
+                # Retrieve the time and save it to sundial.
+                sundial = io.receive_time()
                 # Print the current date and time to the serial console.
                 print(f"LED color time-check. Date and time: {sundial.tm_year}-{sundial.tm_mon}-" +
                       f"{sundial.tm_mday} {sundial.tm_hour}:{sundial.tm_min:02}")
@@ -209,32 +251,29 @@ def blink(color):
                 # to `fill()` to set the LED color.
                 pixels.fill(color_time(sundial.tm_hour))
 
-        if wifi_ping is None and current_time - ping_fail_time > ping_interval:
-            # If the ping has failed, and it's been one second (the same interval as the ping)...
-            ping_fail_time = time.monotonic()  # Reset the ping fail time to continue tracking.
-            ping_fail_count += 1  # Increase the fail count by one.
+        # If the ping has failed, and it's been one second, continue with this code.
+        if wifi_ping is None and current_time - ping_fail_time > 1:
+            ping_fail_time = (time.monotonic())  # Reset the ping fail time to continue tracking.
+            ping_fail_count += 1  # Add one to the fail count tracking.
             print(f"Ping failed {ping_fail_count} times")
             # If network down detection is enabled, run the following code.
             if NETWORK_DOWN_DETECTION:
-                # If the ping fail count exceeds the number configured above...
-                if ping_fail_count > PING_FAIL_NUMBER_TO_BLINK:
-                    blink(RED)  # ...begin blinking the LEDs red to indicate the network is down.
+                # If the ping fail count exceeds the value defined above, begin blinking the LED
+                # to indicate that the network is down.
+                if ping_fail_count > CONSECUTIVE_PING_FAIL_TO_BLINK:
+                    blink(BLINK_COLOR)
                 # If the initial setup ping failed, it means the network connection was failing
                 # from the beginning, and might require reloading the board. So, if the initial
-                # ping failed and the ping_fail_count is greater than 30...
+                # ping failed and the ping_fail_count is greater than 30, immediately soft reload
+                # the board.
                 if not initial_ping and ping_fail_count > 30:
-                    reload_on_error(0)  # ...immediately soft reload the board.
+                    reload_on_error(0)
                 # If the initial ping succeeded, the blinking will continue until the connection
                 # is reestablished and the pings are once again successful.
 
-    # There is rarely an issue with pinging which causes the board to fail with a MemoryError.
-    # The MemoryError is not necessarily related to the code, and the code continues to run
-    # when this error is ignored. So, in this case, it catches this error separately...
-    except MemoryError as error:
-        pass  # ...ignores it, and tells the code to continue running.
+    # ============ ERROR HANDLING ============
     # Since network-related code can fail arbitrarily in a variety of ways, this final block is
-    # included to reset the board when an error (other than the MemoryError) is encountered.
-    # When the error is thrown...
+    # included to reset the board when an error is encountered.
+    # When the error is thrown, wait 10 seconds, and hard reset the board.
     except Exception as error:  # pylint: disable=broad-except
-        # ...wait 10 seconds and hard reset the board.
         reload_on_error(10, error, reload_type="reset")