Merge pull request #5 from sparkfun/release/v01.02.00

Release/v01.02.00

Author: gigapod

README.md

@@ -85,7 +85,8 @@ The following examples are provided with the library
 
 ## Documentation
 
-The full API and use documentation for this library is provided [here](http://docs.sparkfun.com/SparkFun_Qwiic_Ultrasonic_Arduino_Library/). For a quick reference, the main methods available in the library are listed [here](https://docs.sparkfun.com/SparkFun_Qwiic_Ultrasonic_Arduino_Library/functions.html).
+
+The full API and use documentation for this library is provided [here](http://docs.sparkfun.com/SparkFun_Qwiic_Ultrasonic_Arduino_Library/). For a quick reference, the main methods available in the library are listed [here](https://docs.sparkfun.com/SparkFun_Qwiic_Ultrasonic_Arduino_Library/class_qwiic_ultrasonic.html).
 
 Curious about the hardware this board works with - visit the SparkFun Qwiic Ultrasonic Distance Sensor [hardware repository](https://github.com/sparkfun/SparkFun_Ultrasonic_Distance_Sensor-Qwiic).
 

examples/Example4_ChangeAddress/Example4_ChangeAddress.ino

@@ -1,11 +1,11 @@
 /* SparkFun Ulrasonic Distance Sensor - Example 4 Changing the Ultrasonic's Address
  * To reset the original I2C address, ground the "RST" pad on the backside of the board.
  * by touching a wire to the pad and then to ground. The address will be reset to 0x2F.
- * 
- * Product: 
+ *
+ * Product:
  *  *  SparkFun Qwiic Ultrasonic Distance Sensor - HC-SR04 (SEN-1XXXX)
  *  *  https://www.sparkfun.com/1XXXX
- * 
+ *
  * Written By: Elias Santistevan
  * Date: 06/2024
  *
@@ -22,7 +22,7 @@ QwiicUltrasonic myUltrasonic;
 // sensor, then uncomment the line below and comment out the line above.
 // You can check the version in copper by the "R" on the front of the board.
 // Newer versions are >v10 and older versions simply do not have a version number.
-//QwiicUltrasonic myUltrasonic(kQwiicUltrasonicFWOld);
+// QwiicUltrasonic myUltrasonic(kQwiicUltrasonicFWOld);
 
 // Here we set the device address. Note that an older version of the Qwiic
 // Ultrasonic firmware used a default address of 0x00. If yours uses 0x00,
@@ -33,71 +33,67 @@ uint8_t deviceAddress = kQwiicUltrasonicDefaultAddress; // 0x2F
 
 // New addres is 7-bit unshifted.
 uint8_t newAddr = 0x20;
-//If using an older version of the Qwiic Ultrasonic, your address range is: 0x20 - 0x2F
-//uint8_t newAddr = 0x2F;
-
+// If using an older version of the Qwiic Ultrasonic, your address range is: 0x20 - 0x2F
+// uint8_t newAddr = 0x2F;
 
 void setup()
 {
     // Start serial
-  Serial.begin(115200);
-  Serial.println("Ultrasonic Distance Sensor - Example 4 - Change Address");
-
-  Wire.begin();
+    Serial.begin(115200);
+    Serial.println("Ultrasonic Distance Sensor - Example 4 - Change Address");
 
-  // This sketch wont' run until you open the serial monitor
-  while(!Serial)
-    ; 
+    Wire.begin();
 
-  // Attempt to begin the sensor
-  while (myUltrasonic.begin(deviceAddress) == false)
-  {
-    Serial.println("Ultrasonic sensor not connected, check your wiring and I2C address!");
-    delay(2000);
-  }
+    // This sketch wont' run until you open the serial monitor
+    while (!Serial)
+        ;
 
-  Serial.println("Ready to change address.");
-  delay(1000);
-
-  Serial.print("Changing Address To: ");
-  Serial.println(newAddr, HEX);
+    // Attempt to begin the sensor
+    while (myUltrasonic.begin(deviceAddress) == false)
+    {
+        Serial.println("Ultrasonic sensor not connected, check your wiring and I2C address!");
+        delay(2000);
+    }
 
+    Serial.println("Ready to change address.");
+    delay(1000);
 
-  // Call change address.....
-  sfeTkError_t err =  myUltrasonic.changeAddress(newAddr);
+    Serial.print("Changing Address To: ");
+    Serial.println(newAddr, HEX);
 
+    // Call change address.....
+    sfTkError_t err = myUltrasonic.changeAddress(newAddr);
 
-  if(err)
-  {
-    while(1)
+    if (err != ksfTkErrOk)
     {
-      Serial.print("Error changing address: ");
-      Serial.println(err);
-      delay(1000);
+        while (1)
+        {
+            Serial.print("Error changing address: ");
+            Serial.println(err);
+            delay(1000);
+        }
     }
-  }
-
-  Serial.println("Address changed successfully!");
-  Serial.println("Reading Distance at new address......");
-  delay(3000);
 
+    Serial.println("Address changed successfully!");
+    Serial.println("Reading Distance at new address......");
+    delay(3000);
 }
 
 void loop()
 {
-  uint16_t distance = 0;
-  myUltrasonic.triggerAndRead(distance);
+    uint16_t distance = 0;
+    myUltrasonic.triggerAndRead(distance);
 
-  // Print measurement
-  Serial.print("Distance (mm): ");
-  Serial.println(distance);
+    // Print measurement
+    Serial.print("Distance (mm): ");
+    Serial.println(distance);
 
-  //Serial.println("Distance (cm): "); 
-  //Serial.print((distance / 10.0), 2);         
+    // Serial.println("Distance (cm): ");
+    // Serial.print((distance / 10.0), 2);
 
-  //Serial.println("Distace (in): "); 
-  //Serial.print((distance / 25.4), 2);         
+    // Serial.println("Distace (in): ");
+    // Serial.print((distance / 25.4), 2);
 
-  // Wait a bit
-  delay(100);
+    // Wait a bit
+    delay(100);
 }

library.properties

@@ -1,10 +1,10 @@
 name=SparkFun Qwiic Ultrasonic Arduino Library
-version=1.1.2
+version=1.2.0
 author=SparkFun Electronics <techsupport@sparkfun.com>
 maintainer=SparkFun Electronics <sparkfun.com>
 sentence=A library to use the SparkFun Qwiic Ultrasonic Distance Sensor
 paragraph=The SparkFun Qwiic Ultrasonic Distance Sensor, a user-friendly upgrade to the popular HC-SR04 sensor, offers non-contact distance measurement from 2cm to 400cm with an accuracy of 3mm. This sensor is designed to seamlessly integrate with the Qwiic ecosystem for I2C communication, making it a breeze to add to your existing projects and daisy-chain with other Qwiic components.
 category=Sensors
 url=https://github.com/sparkfun/SparkFun_Qwiic_Ultrasonic_Arduino_Library
 architectures=*
-depends=SparkFun Toolkit (<1.0.0)
+depends=SparkFun Toolkit (>=1.0.0)

src/SparkFun_Qwiic_Ultrasonic_Arduino_Library.h

@@ -1,43 +1,66 @@
-/* SparkFun Ulrasonic Distance Sensor 
- * 
- * Product: 
- *  *  SparkFun Qwiic Ultrasonic Distance Sensor - HC-SR04 (SEN-1XXXX)
- *  *  https://www.sparkfun.com/1XXXX
- * 
- * SPDX-License-Identifier: MIT
+/*!
+ * @file SparkFun_Qwiic_Ultrasonic_Arduino_Library.h
+ * @brief Arduino header file for the SparkFun Qwiic Ultrasonic Arduino library
+ *
+ * This file contains the class definitions for the SparkFun Qwiic Ultrasonic Arduino library,
+ * including methods for initialization, reading ultrasonic values, and changing the I2C address.
  *
- * Copyright (c) 2024 SparkFun Electronics
+ * @author SparkFun Electronics
+ * @date 2024
+ * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License.
+ *
+ * SPDX-License-Identifier: MIT
  */
 
 #pragma once
 
+// clang-format off
+#include <SparkFun_Toolkit.h>
+#include "sfTk/sfDevUltrasonicDist.h"
 #include "Arduino.h"
-#include "sfeQwiicUltrasonic.h"
 #include <Wire.h>
+// clang-format on
 
-class QwiicUltrasonic : public sfeQwiicUltrasonic
+class QwiicUltrasonic : public sfDevUltrasonicDist
 {
   public:
-    /// @brief Begins the Qwiic Ultrasonic sensor
-    /// @param address I2C device address to use for the sensor
-    /// @param wirePort Wire port to use for I2C communication
-    /// @return True if successful, false otherwise
+    /**
+     * @brief Begins the Qwiic Ultrasonic sensor
+     *
+     * This method initializes the Qwiic Ultrasonic sensor by setting up the I2C bus
+     * and starting communication with the sensor.
+     *
+     * @param address I2C device address to use for the sensor
+     * @param wirePort Wire port to use for I2C communication
+     * @return True if successful, false otherwise
+     */
     bool begin(uint8_t address = kQwiicUltrasonicDefaultAddress, TwoWire &wirePort = Wire)
     {
-        // Setup Arudino I2C bus
+        // Setup Arduino I2C bus
         _theI2CBus.init(wirePort, address);
 
         // Begin the sensor
-        return sfeQwiicUltrasonic::begin(&_theI2CBus) == kSTkErrOk;
+        return sfDevUltrasonicDist::begin(&_theI2CBus) == ksfTkErrOk;
     }
 
-    /// @brief Checks if the Qwiic Ultrasonic sensor is connected
-    /// @return True if the sensor is connected, false otherwise
+    /**
+     * @brief Checks if the Qwiic Ultrasonic sensor is connected
+     *
+     * This method verifies if the Qwiic Ultrasonic sensor is properly connected
+     * by checking the communication status.
+     *
+     * @return True if the sensor is connected, false otherwise
+     */
     bool isConnected()
     {
-        return sfeQwiicUltrasonic::isConnected() == kSTkErrOk;
+        return sfDevUltrasonicDist::isConnected() == ksfTkErrOk;
     }
 
   private:
-    sfeTkArdI2C _theI2CBus;
+    /**
+     * @brief I2C bus instance for communication with the sensor
+     *
+     * This variable holds the I2C bus instance used for communication with the Qwiic Ultrasonic sensor.
+     */
+    sfTkArdI2C _theI2CBus;
 };

src/sfeQwiicUltrasonic.cpp renamed to src/sfTk/sfDevUltrasonicDist.cpp

@@ -1,22 +1,25 @@
-/* SparkFun Ulrasonic Distance Sensor
+/**
+ * @file sfDevUltrasonicDist.cpp
+ * @brief Implementation file for the Ultrasonic Distance sensor class
  *
- * Product:
- *  *  SparkFun Qwiic Ultrasonic Distance Sensor - HC-SR04 (SEN-1XXXX)
- *  *  https://www.sparkfun.com/1XXXX
+ * This file contains the implementation of the ultrasonic distance sensor class, including
+ * methods for initialization, measuring distance values, and setting the I2C address.
  *
- * SPDX-License-Identifier: MIT
+ * @author SparkFun Electronics
+ * @date 2024
+ * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License.
  *
- * Copyright (c) 2024 SparkFun Electronics
+ * SPDX-License-Identifier: MIT
  */
 
-#include "sfeQwiicUltrasonic.h"
-#include "sfeTk/sfeTkError.h"
+#include "sfDevUltrasonicDist.h"
 
-sfeTkError_t sfeQwiicUltrasonic::begin(sfeTkII2C *theBus)
+//------------------------------------------------------------------------
+sfTkError_t sfDevUltrasonicDist::begin(sfTkII2C *theBus)
 {
     // Nullptr check
     if (theBus == nullptr)
-        return kSTkErrFail;
+        return ksfTkErrFail;
 
     // Check the device address
     if (_fwVersion == kQwiicUltrasonicFWOld)
@@ -27,7 +30,7 @@ sfeTkError_t sfeQwiicUltrasonic::begin(sfeTkII2C *theBus)
             // It's not really a valid address, but we need to allow it. Any other
             // address can't be used
             if (theBus->address() != 0x00)
-                return kSTkErrFail;
+                return ksfTkErrFail;
         }
     }
     // Set bus pointer
@@ -37,78 +40,79 @@ sfeTkError_t sfeQwiicUltrasonic::begin(sfeTkII2C *theBus)
     return isConnected();
 }
 
-sfeTkError_t sfeQwiicUltrasonic::isConnected()
+//------------------------------------------------------------------------
+sfTkError_t sfDevUltrasonicDist::isConnected()
 {
     // Just ping the device address, there's no product ID register to check
     return _theBus->ping();
 }
 
-sfeTkError_t sfeQwiicUltrasonic::triggerAndRead(uint16_t &distance)
+//------------------------------------------------------------------------
+sfTkError_t sfDevUltrasonicDist::triggerAndRead(uint16_t &distance)
 {
     size_t bytesRead;
     size_t numBytes = 2;
     uint8_t rawData[2] = {};
 
     // Get the distance
-    sfeTkError_t err = _theBus->readRegisterRegion(kUltrasonicDistanceReadCommand, rawData, numBytes, bytesRead);
+    sfTkError_t err = _theBus->readRegister(kUltrasonicDistanceReadCommand, rawData, numBytes, bytesRead);
 
     // Check whether the read was successful
-    if (err != kSTkErrOk)
+    if (err != ksfTkErrOk)
         return err;
 
     // Store raw data
     distance = (rawData[0] << 8) | rawData[1];
 
     // Done!
-    return kSTkErrOk;
+    return ksfTkErrOk;
 }
 
-sfeTkError_t sfeQwiicUltrasonic::changeAddress(uint8_t &address)
+//------------------------------------------------------------------------
+sfTkError_t sfDevUltrasonicDist::changeAddress(uint8_t &address)
 {
     // Check whether the address is valid
 
-    sfeTkError_t err;
+    sfTkError_t err;
 
     if (_fwVersion == kQwiicUltrasonicFWOld)
     {
         // Old firmware only supports a limited range of addresses.
         if (address < kQwiicUltrasonicMinAddress || address > kQwiicUltrasonicMaxAddress)
-            return kSTkErrFail;
+            return ksfTkErrFail;
 
         // Write the new address to the device. The first bit must be set to 1
-        err = _theBus->writeByte(address | 0x80);
+        err = _theBus->writeUInt8(address | 0x80);
     }
     else if (_fwVersion == kQwiicUltrasonicFWLatest)
     {
         size_t numBytes = 2;
         // Latest firmware versions supports all of the available I2C addresses.
         if (address < kQwiicUltrasonicI2CAddressMin || address > kQwiicUltrasonicI2CAddressMax)
-            return kSTkErrFail;
+            return ksfTkErrFail;
 
         // We want to shift the address left before we send it.
         uint8_t tempAddress = address << 1;
         const uint8_t toWrite[2] = {kUltrasonicAddressChangeCommand, tempAddress};
 
         // Write the new address to the device
-        err = _theBus->writeRegion(toWrite, numBytes);
+        err = _theBus->writeData(toWrite, numBytes);
     }
     else
     {
         // There was some error setting the version in the constructor
         // return an error.
-        return kSTkErrFail;
+        return ksfTkErrFail;
     }
 
     _theBus->setAddress(address);
-    // Check whether the write was successful
-    if (err != kSTkErrOk)
-        return err;
 
-    // Done!
-    return kSTkErrOk;
+    // return err
+    return err;
 }
 
-uint8_t sfeQwiicUltrasonic::getAddress()
+//------------------------------------------------------------------------
+uint8_t sfDevUltrasonicDist::getAddress()
 {
     return _theBus->address();
 }