Add file header comments

Author: sfe-SparkFro

examples/Example1_BasicReadings/Example1_BasicReadings.ino

@@ -4,6 +4,18 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 1 - Basic Readings
+
+    This example demonstrates how to read the position and heading from the
+    SparkFun Qwiic Optical Tracking Odometry Sensor (OTOS).
+
+    This example should be used to verify that the OTOS is connected and
+    functioning correctly. It will just print the position and heading tracked
+    by the OTOS to the serial monitor. It is recommended that you check out the
+    other examples before using the OTOS in your own project.
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 

examples/Example2_SetUnits/Example2_SetUnits.ino

@@ -4,6 +4,16 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 2 - Set Units
+
+    This example demonstrates how to change the units of the SparkFun Qwiic
+    Optical Tracking Odometry Sensor (OTOS).
+
+    The OTOS library defaults to inches and degrees, but you can change the
+    units to suit the needs of your project.
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 

examples/Example3_Calibration/Example3_Calibration.ino

@@ -4,6 +4,21 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 3 - Calibration
+
+    This example demonstrates how to calibrate the SparkFun Qwiic Optical
+    Tracking Odometry Sensor (OTOS).
+
+    This example should be used to calibrate the linear and angular scalars of
+    the OTOS to get the most accurate tracking performance. The linear scalar
+    can be used to compensate for scaling issues with the x and y measurements,
+    while the angular scalar can be used to compensate for scaling issues with
+    the heading measurement. Note that if the heading measurement is off, that
+    can also cause the x and y measurements to be off, so it's recommended to
+    calibrate the angular scalar first.
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 

examples/Example4_SetOffsetAndPosition/Example4_SetOffsetAndPosition.ino

@@ -4,6 +4,20 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 4 - Set Offset and Position
+
+    This example demonstrates how to set the offset and position of the SparkFun
+    Qwiic Optical Tracking Odometry Sensor (OTOS).
+
+    If your OTOS is mounted to a robot and is not centered, you can specify the
+    offset for the sensor relative to the center of the robot; rather than
+    returning the position of the sensor, the OTOS will calculate and return the
+    position of the robot's center. If you know where your robot is located,
+    such as the starting location or from another sensor, you can send that
+    position to the OTOS and it will continue to track from there.
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 

examples/Example5_VelocityAndAcceleration/Example5_VelocityAndAcceleration.ino

@@ -4,6 +4,18 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 5 - Velocity and Acceleration
+
+    This example demonstrates how to read the velocity and acceleration from the
+    SparkFun Qwiic Optical Tracking Odometry Sensor (OTOS).
+
+    The primary purpose of the OTOS is to track position, but it also provides
+    velocity and acceleration measurements for more advanced applications. Note
+    that these measurements can be noisy and inaccurate, especially if the
+    sensor is not flat to the ground.
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 
@@ -60,14 +72,38 @@ void loop()
     myOtos.getVelocity(vel);
     myOtos.getAcceleration(acc);
 
-    // Or all at once with the following:
+    // Or burst read them all at once with the following:
     // myOtos.getPosVelAcc(pos, vel, acc);
 
-    // Print measurements
-    Serial.printf("Pos: X: %.3f\tY: %.3f\tH: %.3f\n", pos.x, pos.y, pos.h);
-    Serial.printf("Vel: X: %.3f\tY: %.3f\tH: %.3f\n", vel.x, vel.y, vel.h);
-    Serial.printf("Acc: X: %.3f\tY: %.3f\tH: %.3f\n", acc.x, acc.y, acc.h);
+    // Print position
+    Serial.println();
+    Serial.println("Position:");
+    Serial.print("X (Inches): ");
+    Serial.println(pos.x);
+    Serial.print("Y (Inches): ");
+    Serial.println(pos.y);
+    Serial.print("Heading (Degrees): ");
+    Serial.println(pos.h);
+    
+    // Print velocity
+    Serial.println();
+    Serial.println("Position:");
+    Serial.print("X (Inches): ");
+    Serial.println(vel.x);
+    Serial.print("Y (Inches): ");
+    Serial.println(vel.y);
+    Serial.print("Heading (Degrees): ");
+    Serial.println(vel.h);
+    
+    // Print acceleration
     Serial.println();
+    Serial.println("Position:");
+    Serial.print("X (Inches): ");
+    Serial.println(acc.x);
+    Serial.print("Y (Inches): ");
+    Serial.println(acc.y);
+    Serial.print("Heading (Degrees): ");
+    Serial.println(acc.h);
 
     // Wait a bit so we don't spam the serial port
     delay(500);

examples/Example6_StandardDeviation/Example6_StandardDeviation.ino

@@ -4,6 +4,24 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 6 - Standard Deviation
+
+    This example demonstrates how to read the standard deviation of the
+    measurements of the SparkFun Qwiic Optical Tracking Odometry Sensor (OTOS).
+
+    The OTOS uses Kalman filters to estimate the position, velocity, and
+    acceleration of the x, y, and heading. The square root of the diagonal
+    elements of the covariance matrices are provided for the standard deviation
+    of each measurement. THEY DO NOT REPRESENT THE ACTUAL TRACKING ERROR! These
+    are statistical quantities that assume a correct model of the system, but
+    there could be unmodelled error sources that cause the physical error to
+    become larger than these statistical error (eg. improper calibration, or
+    tilting the OTOS to not be flat against the tracking surface). These are
+    provided primarily for anyone wanting to perform sensor fusion with
+    additional sensors.
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 
@@ -69,22 +87,21 @@ void loop()
     // REPRESENT THE ACTUAL TRACKING ERROR! These are statistical quantities
     // that assume a correct model of the system, but there could be unmodelled
     // error sources that cause the physical error to become larger than these
-    // statistical error (eg. improper calibration, or rotating the OTOS to not
+    // statistical error (eg. improper calibration, or tilting the OTOS to not
     // be flat against the tracking surface). These are provided primarily for
-    // anyone wanting to perform sensor fusion with additional sensors, but they
-    // can be used to at least "get an idea" of the quality of the accuracy.
+    // anyone wanting to perform sensor fusion with additional sensors.
     myOtos.getPositionStdDev(posStdDev);
     // myOtos.getVelocityStdDev(velStdDev);
     // myOtos.getAccelerationStdDev(accStdDev);
 
-    // These values can instead be read out in chunks:
+    // These values can instead be burst read out in chunks:
     // myOtos.getPosVelAcc(pos, vel, acc);
     // myOtos.getPosVelAccStdDev(posStdDev, velStdDev, accStdDev);
 
-    // Or all at once:
+    // Or burst read them all at once:
     // myOtos.getPosVelAccAndStdDev(pos, vel, acc, posStdDev, velStdDev, accStdDev);
 
-    // Print measurements
+    // Print position and standard deviation
     Serial.println();
     Serial.println("Sensor pose:");
     Serial.print("X (Inches): ");
@@ -100,6 +117,7 @@ void loop()
     Serial.print(" +/- ");
     Serial.println(posStdDev.h);
 
+    // Print velocity and standard deviation
     // Serial.println();
     // Serial.println("Sensor velocity:");
     // Serial.print("X (Inches/sec): ");
@@ -115,6 +133,7 @@ void loop()
     // Serial.print(" +/- ");
     // Serial.println(velStdDev.h);
 
+    // Print acceleration and standard deviation
     // Serial.println();
     // Serial.println("Sensor acceleration:");
     // Serial.print("X (Inches/sec^2): ");

examples/Example7_GetVersion/Example7_GetVersion.ino

@@ -4,6 +4,19 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 7 - Get Version
+
+    This example demonstrates how to get the hardware and firmware version
+    numbers from the SparkFun Qwiic Optical Tracking Odometry Sensor (OTOS).
+
+    There may be future hardware and/or firmware changes of the OTOS, so you can
+    use this example to check which version you have. See the product page or
+    hardware repository to see what the latest version is:
+    https://www.sparkfun.com/products/24904
+    https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 

examples/Example8_SelfTest/Example8_SelfTest.ino

@@ -4,6 +4,17 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    Example 8 - Self Test
+
+    This example demonstrates how to perform a self test of the SparkFun Qwiic
+    Optical Tracking Odometry Sensor (OTOS).
+
+    The self test triggers the OTOS to perform a series of tests to ensure the
+    sensor is functioning correctly. This is performed during QC testing, but
+    you can also perform this test yourself.
+*******************************************************************************/
+
 #include "SparkFun_Qwiic_OTOS_Arduino_Library.h"
 #include "Wire.h"
 

src/SparkFun_Qwiic_OTOS_Arduino_Library.h

@@ -4,6 +4,14 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    SparkFun_Qwiic_OTOS_Arduino_Library.h - Arduino wrapper of the C++ driver
+    for the SparkFun Qwiic Optical Tracking Odometry Sensor (OTOS).
+
+    This is a simple wrapper around the C++ driver to make it easier to use with
+    Arduino.
+*******************************************************************************/
+
 #pragma once
 
 #include "Arduino.h"

src/sfeQwiicOtos.cpp

@@ -4,6 +4,11 @@
     Copyright (c) 2024 SparkFun Electronics
 */
 
+/*******************************************************************************
+    sfeQwiicOtos.h - C++ driver implementation for the SparkFun Qwiic Optical
+    Tracking Odometry Sensor (OTOS).
+*******************************************************************************/
+
 #include "sfeQwiicOtos.h"
 
 sfeQwiicOtos::sfeQwiicOtos()