add oneshot example and more comments.

Author: FoamyGuy

examples/opt4048_fulltest.py

@@ -1,7 +1,14 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 Tim C for Adafruit Industries
 # SPDX-License-Identifier: MIT
+"""
+A comprehensive demo for using the OPT4048 tristimulus XYZ color sensor,
+showing all capabilities.
+
+This example reads the sensor values from all four channels (X, Y, Z, W),
+demonstrates setting and getting threshold values, and displays the results.
+"""
+
 import time
-from time import sleep
 
 import board
 
@@ -22,12 +29,13 @@
 
 print("Adafruit OPT4048 Tristimulus XYZ Color Sensor Test")
 
+# Initialize the sensor
 i2c = board.I2C()  # uses board.SCL and board.SDA
 # i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller
 sensor = OPT4048(i2c)
-
 print("OPT4048 sensor found!")
 
+# Set low and high thresholds for interrupts
 low_threshold_val = 1000
 print(f"Setting low threshold to: {low_threshold_val}")
 sensor.threshold_low = low_threshold_val
@@ -36,11 +44,15 @@
 print(f"Setting high threshold to: {high_threshold_val}")
 sensor.threshold_high = high_threshold_val
 
+# Read back the thresholds to verify
 print(f"Read back low threshold: {sensor.threshold_low}")
 print(f"Read back high threshold: {sensor.threshold_high}")
 
+# Enable Quick Wake feature
 print("\nEnabling Quick Wake feature...")
 sensor.qick_wake = True
+
+# Read back Quick Wake status
 print(f"Quick Wake status: {sensor.quick_wake}")
 
 # Set range to auto
@@ -69,16 +81,21 @@
 print("\nConfiguring interrupt settings...")
 sensor.interrupt_latch = True
 sensor.interrupt_polarity = True
+
+# Read back interrupt settings
 print(f"Interrupt latch mode: {'Latched' if sensor.interrupt_latch else 'Transparent'}")
 print(f"Interrupt polarity: {'Active-high' if sensor.interrupt_polarity else 'Active-low'}")
 
+# Configure fault count
 print("\nSetting fault count to 4 consecutive faults...")
 sensor.fault_count = FaultCount.COUNT_4
+# Read back fault count setting
 print(
     f"Fault count setting value: {sensor.fault_count} "
     + f"name: {FaultCount.get_name(sensor.fault_count)}"
 )
 
+# Configure threshold channel
 print("\nSetting threshold channel to Channel 1 (Y)...")
 sensor.threshold_channel = 1
 channels = {
@@ -87,10 +104,14 @@
     2: "(Z)",
     3: "(W)",
 }
+# Read back threshold channel setting
 print(f"Threshold channel setting: Channel {channels[sensor.threshold_channel]}")
 
+# Configure interrupt configuration
 print("\nSetting interrupt configuration to data ready for all channels...")
 sensor.interrupt_config = IntConfig.DATA_READY_ALL
+
+# Read back interrupt configuration setting
 print(
     f"Interrupt configuration value: {sensor.interrupt_config} "
     + f"name: {IntConfig.get_name(sensor.interrupt_config)}"
@@ -135,4 +156,4 @@
     except RuntimeError:
         print("Error reading sensor data")
 
-    time.sleep(1)
+    time.sleep(1)  # read once per second

examples/opt4048_oneshot.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Tim C for Adafruit Industries
+# SPDX-License-Identifier: MIT
+"""
+A basic one shotdemo for using the OPT4048 tristimulus XYZ color sensor
+
+This example reads the sensor values from all four channels (X, Y, Z, W),
+demonstrates setting and getting threshold values, and displays the results.
+
+Readints are taken in oneshot mode and then the next one is triggered when
+the power down mode status is detected.
+"""
+
+import time
+from time import sleep
+
+import board
+
+from adafruit_opt4048 import OPT4048, ConversionTime, Mode, Range
+
+timestamp = 0
+
+print("Adafruit OPT4048 Tristimulus XYZ Color Sensor Oneshot Test")
+
+i2c = board.I2C()  # uses board.SCL and board.SDA
+# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller
+sensor = OPT4048(i2c)
+print("OPT4048 sensor found!")
+
+sensor.range = Range.AUTO
+sensor.conversion_time = ConversionTime.TIME_100MS
+sensor.mode = Mode.AUTO_ONESHOT
+while True:
+    if sensor.mode == Mode.POWERDOWN:
+        # ok we finished the reading!
+        try:
+            CIEx, CIEy, lux = sensor.get_cie()
+        except RuntimeError:
+            print("Error reading sensor data")
+
+        print("\nCIE Coordinates:")
+        print(f"CIE x:{CIEx}, y:{CIEy}, lux: {lux}", end=" ")
+
+        # Calculate and display color temperature
+        color_temp = sensor.calculate_color_temperature(CIEx, CIEy)
+        print(f"Color Temperature: {color_temp} K")
+        print(f"Time since last read: {time.monotonic() - timestamp} sec")
+        timestamp = time.monotonic()
+
+        sensor.mode = Mode.AUTO_ONESHOT

examples/opt4048_simpletest.py

@@ -1,5 +1,12 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 Tim C for Adafruit Industries
 # SPDX-License-Identifier: MIT
+"""
+A basic demo for using the OPT4048 tristimulus XYZ color sensor
+
+This example reads the sensor values from all four channels (X, Y, Z, W),
+demonstrates setting and getting threshold values, and displays the results.
+"""
+
 import time
 from time import sleep
 

examples/opt4048_webserial.py

@@ -1,5 +1,16 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 Tim C for Adafruit Industries
 # SPDX-License-Identifier: MIT
+"""
+This example reads color data from the OPT4048 sensor and outputs it
+in a format suitable for displaying on a web page using Web Serial API.
+
+It continuously measures CIE x,y coordinates, lux, and color temperature.
+
+This example works with the web interface in the /webserial directory of the
+gh-pages branch of the Arduino driver repo: https://github.com/adafruit/Adafruit_OPT4048/tree/gh-pages,
+which can be accessed at: https://adafruit.github.io/Adafruit_OPT4048/webserial/
+"""
+
 import time
 from time import sleep