Add comments for the tmp117 web server python code

Author: malcolm-sparkfun

examples/mpy_tmp117_web_server/tmp117_server_ap.py

@@ -1,6 +1,6 @@
 
 ##
-# @file mpy_rgb_ramp.py
+# @file mpy_tmp117_server_ap.py
 # @brief This MicroPython file contains a full implementation of a web server that reads 
 # temperature data from a TMP117 sensor and sends it to a client via a websocket.
 # The complementary client code that is served can be found in the static directory.
@@ -19,69 +19,93 @@
 # @license MIT
 #
 
+# -------------------- Import the necessary modules -------------------- 
 from microdot import Microdot, send_file
 from microdot.websocket import with_websocket
 import json
 import asyncio
 import wlan_ap
 import qwiic_tmp117
 
-# defines
+# -------------------- Constants -------------------- 
 kDoAlerts = True # Set to False to disable checking alerts. This will speed up temperature reads.
-kApSsid = "iot_redboard_tmp117"
-kApPass = "thermo_wave2"
+kApSsid = "iot_redboard_tmp117" # This will be the SSID of the AP, the "Network Name" that you'll see when you scan for networks on your client device
+kApPass = "thermo_wave2" # This will be the password for the AP, that you'll use when you connect to the network from your client device
 
-# fahrenheit to celcius
+# -------------------- Shared Variables -------------------- 
+# Create instance of our TMP117 device
+myTMP117 = qwiic_tmp117.QwiicTMP117()
+
+# Use the Microdot framework to create a web server
+app = Microdot()
+
+# -------------------- Fahrenheit to Celcius -------------------- 
 def f_to_c(degreesF):
     return (degreesF - 32) * 5/9
 
 def c_to_f(degreesC):
     return (degreesC * 9/5) + 32
 
-# Set up the AP
-print("Formatting WIFI")
-accessPointIp = wlan_ap.config_wlan_as_ap(kApSsid, kApPass)
-print("WiFi Configured!")
-# print("Active config: ", config)
-
-# Set up the TMP117
-print("Setting up TMP117")
-# Create instance of device
-myTMP117 = qwiic_tmp117.QwiicTMP117()
+# --------------------  Set up the TMP117 -------------------- 
+def config_TMP117(tmp117Device, doAlerts):
+    """
+    @brief Function to configure the TMP117 sensor
 
-# Check if it's connected
-if myTMP117.is_connected() == False:
-    print("The TMP117 device isn't connected to the system. Please check your connection")
-    exit()
+    @param tmp117Device The QwiicTMP117 object to be configured.
 
-print("TMP117 device connected!")
-    
-# Initialize the device
-myTMP117.begin()
+    @details
+    - This function initializes the TMP117 sensor and sets the high and low temperature limits.
+    - If doAlerts is set to True, the TMP117 will be set to alert mode.
+    """
+    print("Setting up TMP117")
+    # Create instance of device
+    tmp117Device = qwiic_tmp117.QwiicTMP117()
 
-if kDoAlerts:
-    myTMP117.set_high_limit(25.50)
-    myTMP117.set_low_limit(25)
+    # Check if it's connected
+    if tmp117Device.is_connected() == False:
+        print("The TMP117 device isn't connected to the system. Please check your connection")
+        exit()
 
-    # Set to kAlertMode or kThermMode
-    myTMP117.set_alert_function_mode(myTMP117.kAlertMode)
+    print("TMP117 device connected!")
+        
+    # Initialize the device
+    tmp117Device.begin()
 
-print("TMP117 Configured!")
+    if doAlerts:
+        tmp117Device.set_high_limit(25.50)
+        tmp117Device.set_low_limit(25)
 
-print("\nNavigate to http://" + accessPointIp + ":5000/ to view the TMP117 temperature readings\n")
+        # Set to kAlertMode or kThermMode
+        tmp117Device.set_alert_function_mode(tmp117Device.kAlertMode)
 
-# Use the Microdot framework to create a web server
-app = Microdot()
+    print("TMP117 Configured!")
 
-# Route our root page to the index.html file
+# -------------------- Asynchronous Microdot Functions -------------------- 
 @app.route('/')
 async def index(request):
+    """
+    @brief Function/Route to the index.html file to serve it as the root page
+
+    @param request The Microdot "Request" object containing details about a client HTTP request.
+
+    @details
+    - This function is asynchronous and is called when a client requests the root "/" path from our server.
+    - The requested file is located in the "static" directory.
+    - The requested file is sent to the client.
+    """
     return send_file('static/index.html')
- 
-gTempSocket = None
 
 # Create server-side coroutine for websocket to send temperature data to the client 
-async def send_temperature():
+async def send_temperature(tempSocket):
+    """
+    @brief Server-side coroutine for websocket to send temperature data to the client.
+
+    @param tempSocket The Microdot "WebSocket" object containing details about the websocket connection.
+
+    @details
+    - This coroutine is asynchronous and is started when the client connects to the websocket.
+    - It sends temperature data to the client every 0.5 seconds.
+    """
     print("Spawned send_temperature coroutine")
     while True:
         if myTMP117.data_ready():
@@ -99,23 +123,35 @@ async def send_temperature():
                 data['limitH'] = c_to_f(myTMP117.get_high_limit())
 
             data = json.dumps(data) # Convert to a json string to be parsed by client
-            await gTempSocket.send(data)
+            await tempSocket.send(data)
             await asyncio.sleep(0.5)
 
-# Create server-side coroutine for websocket to receive changes to the high and low temperature limits from the client
-# Since our client code creates a websocket connection to the /temperature route, we'll define our websocket coroutine there
 @app.route('/temperature')
 @with_websocket
 async def handle_limits(request, ws):
+    """
+    @brief Server-side coroutine for websocket to receive changes to the high and low temperature limits from the client
+            
+    Since our client code creates a websocket connection to the /temperature route, we'll define our websocket coroutine there
+
+    @param request The Microdot "Request" object containing details about a client HTTP request.
+    @param ws The Microdot "WebSocket" object containing details about the websocket connection.
+
+    @details
+    - This function is asynchronous and is called when a client requests a file from the server.
+    - The requested file is located in the "static" directory.
+    - The requested file is sent to the client.
+    """
     print("Spawned handle_limits coroutine")
-    global gTempSocket
-    gTempSocket = ws # Let's save the websocket object so we can send data to it from our send_temperature coroutine
     # We won't start sending data until now, when we know the client has connected to the websocket
-    asyncio.create_task(send_temperature())
+    # Let's start the send_temperature coroutine and pass it the websocket object
+    asyncio.create_task(send_temperature(ws))
     while True:
+            # Lets block here until we receive a message from the client
             data = await ws.receive()
             print("Received new limit: " + data)
             limitJson = json.loads(data)
+            # Check if the client sent a new high or low limit, and update the TMP117 accordingly
             if 'low_input' in limitJson:
                 toSet = f_to_c(limitJson['low_input'])
                 print("setting low limit to: " + str(toSet))
@@ -127,18 +163,41 @@ async def handle_limits(request, ws):
                 myTMP117.set_high_limit(toSet)
                 print("New high limit: " + str(myTMP117.get_high_limit()))
 
-# Route to the static folder to serve up the HTML and CSS files
 @app.route('/static/<path:path>')
 async def static(request, path):
+    """
+    @brief Function/Route to the static folder to serve up the HTML and CSS files
+
+    @param request The Microdot "Request" object containing details about a client HTTP request.
+    @param path The path to the requested file.
+
+    @details
+    - This function is asynchronous and is called when a client requests a file from the server.
+    - The requested file is located in the "static" directory.
+    - The requested file is sent to the client.
+    """
     if '..' in path:
         # directory traversal is not allowed
         return 'Not found', 404
     return send_file('static/' + path)
 
 def run():
     """
-    @brief Run the web server
-    """   
+    @brief Configure the WLAN, and TMP117 and run the web server
+    """
+    # Set up the AP
+    print("Formatting WIFI")
+    accessPointIp = wlan_ap.config_wlan_as_ap(kApSsid, kApPass)
+    print("WiFi Configured!")
+
+    # Set up the TMP117
+    config_TMP117(myTMP117, kDoAlerts)
+
+    # Print the IP address of the server, port 5000 is the default port for Microdot
+    print("\nNavigate to http://" + accessPointIp + ":5000/ to view the TMP117 temperature readings\n")
+
+    # Start the web server
     app.run()
 
+# Finally after we've defined all our functions, we'll call the run function to start the server!
 run()