example complete - works

gigapod · gigapod · commit 576690a7a299 · 2025-03-20T13:44:34.000-06:00
diff --git a/examples/mpy_sdcard_log/mpy_sdcard_log.py b/examples/mpy_sdcard_log/mpy_sdcard_log.py
@@ -1,4 +1,23 @@
 
+##
+# @file mpy_sdcard_log.py
+# @brief This MicroPython file contains functions to manage SD card logging on SparkFun MicroPython
+# enabled boards.
+#
+# @details
+# This module provides functionality to mount an SD card, read data from sensors, and log
+# the data to a file on the SD card.
+#
+# @note This code is designed to work with compatible microcontrollers, such as the
+# SparkFun IoT RedBoard - ESP32, or the SparkFun IoT RedBoard - RP2350
+#
+# @author SparkFun Electronics
+# @date March 2025
+# @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc.
+#
+# SPDX-License-Identifier: MIT
+# @license MIT
+#
 
 import machine
 from machine import Pin, SPI
@@ -8,6 +27,8 @@
 import os
 import uos
 import time
+import random
+import json
 
 # Define the boards we support with this deme - This is a dictionary the key being
 # the board uname.machine value, and value a tuple that contains SPI bus number and CS ping number.
@@ -16,8 +37,20 @@
     "SparkFun IoT RedBoard ESP32 with ESP32": (2, 5)
 }
 
+# ------------------------------------------------------------
+
 
 def mount_sd_card():
+    """
+    Mounts an SD card to the filesystem.
+
+    This function checks if the current board is supported, initializes the SPI bus and CS pin,
+    creates the SD card object, and mounts the SD card to the filesystem.
+
+    Returns:
+        bool: True if the SD card was successfully mounted, False otherwise.
+
+    """
 
     # is this a supported board?
     board_name = os.uname().machine
@@ -51,3 +84,170 @@ def mount_sd_card():
     print("SD Card mounted successfully")
 
     return True
+
+# ------------------------------------------------------------
+
+
+def read_data(observation):
+    """
+    Simulates the collection of data and adds values to the observation dictionary.
+
+    This function generates simulated data for time, temperature, humidity, and pressure,
+    and adds these values to the provided observation dictionary. If connecting to an actual
+    sensor, you would take readings from the sensor and add them to the observation dictionary
+    within this function.
+
+    Args:
+        observation (dict): A dictionary to store the simulated sensor data.
+
+    Returns:
+        bool: Always returns True to indicate successful data collection.
+    """
+
+    # Note: If connecting to a actual sensor, you would take readings from the sensor and add them to the
+    # observation dictionary here.
+
+    # Add the time
+    observation["time"] = time.time()
+
+    # Add the temperature
+    observation["temperature"] = random.randrange(-340, 1000)/10
+
+    # Add the humidity
+    observation["humidity"] = random.randrange(0, 1000)/10.
+
+    # Add the pressure
+    observation["pressure"] = random.randrange(10, 1000)/10.
+
+    # Success !
+    return True
+
+# ------------------------------------------------------------
+# Setup the log file
+# This function opens the log file for writing
+# and returns the file object.
+# If the file cannot be opened, it returns None.
+
+
+def setup_log_file(filename):
+    """
+    Sets up a log file on the SD card with the given filename.
+
+    This function attempts to open a file on the SD card for writing. If the file
+    cannot be opened, an error message is printed and None is returned.
+
+    Args:
+        filename (str): The name of the log file to be created on the SD card.
+
+    Returns:
+        file object: A file object for the opened log file if successful, or None if an error occurred.
+    """
+
+    try:
+        fs = open("/sd/" + filename, "w")
+    except Exception as e:
+        print("[Error] Failed to open log file:", e)
+        return None
+
+    return fs
+
+# ------------------------------------------------------------
+
+
+def log_data(filename, count=30, interval=50, to_console=True):
+    """
+    Logs data to a specified file and optionally prints it to the console.
+
+    Parameters:
+    filename (str): The name of the file to log data to.
+    count (int, optional): The number of times to log data. Default is 30.
+    interval (int, optional): The interval (in milliseconds) between each log entry. Default is 50.
+    to_console (bool, optional): If True, prints the data to the console. Default is True.
+
+    Returns:
+    None
+    """
+
+    # Create the observation dictionary
+    observation = {}
+
+    # Open the log file
+    fs = setup_log_file(filename)
+    if fs is None:
+        return
+
+    # Loop for the number of times specified
+    for i in range(count):
+
+        observation.clear()
+        observation["iteration"] = i
+
+        # Read the data
+        read_data(observation)
+
+        # Write the data to the log file
+        fs.write(json.dumps(observation) + "\n")
+
+        if to_console:
+            # Print the data to the console
+            print(json.dumps(observation))
+
+        # Wait for the specified interval
+        time.sleep(interval)
+
+    # Close the log file
+    fs.close()
+
+# ------------------------------------------------------------
+
+
+def sdcard_log_example(filename="mpy_sdcard_log.txt", count=20, interval=2):
+    """
+    Logs data to an SD card at specified intervals and prints the data to the console.
+
+    Args:
+        filename (str): The name of the file to log data to. Defaults to "mpy_sdcard_log.txt".
+        count (int): The number of iterations to log data for. Defaults to 20.
+        interval (int): The interval in seconds between each log entry. Defaults to 2.
+
+    Returns:
+        None
+    """
+
+    print("Logging to: {filename}, every {interval} seconds for {count} iterations.\n".format(
+        filename=filename, interval=interval, count=count))
+    # Mount the SD card
+    if not mount_sd_card():
+        print("Failed to mount SD card")
+        return
+
+    print("\nLogging Data to SD Card and Console:")
+
+    # Log the data
+    log_data(filename, count=count, interval=interval, to_console=True)
+
+    # Unmount the SD card
+    uos.umount("/sd")
+
+    print("\nSD Card unmounted successfully")
+
+# ------------------------------------------------------------
+# Run method for the example
+
+
+def run():
+    """
+    Executes the SparkFun SD card logging example.
+
+    """
+    print("-----------------------------------------------------------")
+    print("Running the SparkFun sd card logging example...")
+    print("-----------------------------------------------------------")
+
+    sdcard_log_example()
+    print()
+    print("Done!")
+
+
+# run the demo/example on load
+run()
