From b327cd709aee11983492b6fc517e082c9383d681 Mon Sep 17 00:00:00 2001 From: Kirk Benell Date: Sun, 16 Feb 2025 08:03:00 -0700 Subject: [PATCH] moved to support SparkFun_Toolkit v1.0; re-orged and renamed core classes to fit v1.0 naming pattern and structure --- .../Example4_ChangeAddress.ino | 94 +++++++++---------- library.properties | 4 +- ...parkFun_Qwiic_Ultrasonic_Arduino_Library.h | 63 +++++++++---- .../sfDevUltrasonicDist.cpp} | 58 ++++++------ .../sfDevUltrasonicDist.h} | 43 +++++---- 5 files changed, 147 insertions(+), 115 deletions(-) rename src/{sfeQwiicUltrasonic.cpp => sfTk/sfDevUltrasonicDist.cpp} (59%) rename src/{sfeQwiicUltrasonic.h => sfTk/sfDevUltrasonicDist.h} (65%) diff --git a/examples/Example4_ChangeAddress/Example4_ChangeAddress.ino b/examples/Example4_ChangeAddress/Example4_ChangeAddress.ino index f91af34..cb974fd 100644 --- a/examples/Example4_ChangeAddress/Example4_ChangeAddress.ino +++ b/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); } diff --git a/library.properties b/library.properties index fac5d2f..9c56495 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=SparkFun Qwiic Ultrasonic Arduino Library -version=1.1.2 +version=1.2.0 author=SparkFun Electronics maintainer=SparkFun Electronics sentence=A library to use the SparkFun Qwiic Ultrasonic Distance Sensor @@ -7,4 +7,4 @@ paragraph=The SparkFun Qwiic Ultrasonic Distance Sensor, a user-friendly upgrade 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) diff --git a/src/SparkFun_Qwiic_Ultrasonic_Arduino_Library.h b/src/SparkFun_Qwiic_Ultrasonic_Arduino_Library.h index 138065d..9959fb7 100644 --- a/src/SparkFun_Qwiic_Ultrasonic_Arduino_Library.h +++ b/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 +#include "sfTk/sfDevUltrasonicDist.h" #include "Arduino.h" -#include "sfeQwiicUltrasonic.h" #include +// 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; }; diff --git a/src/sfeQwiicUltrasonic.cpp b/src/sfTk/sfDevUltrasonicDist.cpp similarity index 59% rename from src/sfeQwiicUltrasonic.cpp rename to src/sfTk/sfDevUltrasonicDist.cpp index e3a1f48..bd2e90d 100644 --- a/src/sfeQwiicUltrasonic.cpp +++ b/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,43 +40,46 @@ 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->readRegisterRegion(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); @@ -83,7 +89,7 @@ sfeTkError_t sfeQwiicUltrasonic::changeAddress(uint8_t &address) 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; @@ -96,19 +102,17 @@ sfeTkError_t sfeQwiicUltrasonic::changeAddress(uint8_t &address) { // 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(); } diff --git a/src/sfeQwiicUltrasonic.h b/src/sfTk/sfDevUltrasonicDist.h similarity index 65% rename from src/sfeQwiicUltrasonic.h rename to src/sfTk/sfDevUltrasonicDist.h index 4a9e2f4..9c832e6 100644 --- a/src/sfeQwiicUltrasonic.h +++ b/src/sfTk/sfDevUltrasonicDist.h @@ -1,23 +1,32 @@ -/* SparkFun Ulrasonic Distance Sensor +/** + * @file sfDevUltrasonicDist.h + * @brief Header 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 class definition for the ultrasonic distance sensor, 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 */ #pragma once -#include "SparkFun_Toolkit.h" +#include + +// include the sparkfun toolkit headers +#include + +// Bus interfaces +#include // Available I2C addresses of the Qwiic Ultrasonic const uint8_t kQwiicUltrasonicDefaultAddress = 0x2F; // Firmware versions. The later hardware version is v10 and so the "latest" here -// refers to that. The previous version is randomnly given the value v01. +// refers to that. The previous version is randomly given the value v01. const uint8_t kQwiicUltrasonicFWLatest = 0x10; const uint8_t kQwiicUltrasonicFWOld = 0x01; @@ -34,47 +43,47 @@ const uint8_t kQwiicUltrasonicMaxAddress = 0x2F; const uint8_t kUltrasonicDistanceReadCommand = 0x01; const uint8_t kUltrasonicAddressChangeCommand = 0x04; -class sfeQwiicUltrasonic +class sfDevUltrasonicDist { public: /// @brief Default constructor /// - sfeQwiicUltrasonic() : _theBus(nullptr), _fwVersion(kQwiicUltrasonicFWLatest) + sfDevUltrasonicDist() : _theBus(nullptr), _fwVersion(kQwiicUltrasonicFWLatest) { } /// @brief Alternate constructor /// @param fwVersion Firmware version of the Qwiic Ultrasonic Sensor. If using an older version /// of the sensor, the list of available I2C addresses differs. - sfeQwiicUltrasonic(const uint8_t fwVersion) : _theBus(nullptr), _fwVersion(fwVersion) + sfDevUltrasonicDist(const uint8_t fwVersion) : _theBus(nullptr), _fwVersion(fwVersion) { } /// @brief Begins the Qwiic Ultrasonic sensor /// @param theBus I2C bus to use for communication - /// @return 0 for succuss, negative for errors, positive for warnings - sfeTkError_t begin(sfeTkII2C *theBus = nullptr); + /// @return 0 for success, negative for errors, positive for warnings + sfTkError_t begin(sfTkII2C *theBus = nullptr); /// @brief Checks if the Qwiic Ultrasonic sensor is connected /// @return 0 for succuss, negative for errors, positive for warnings - sfeTkError_t isConnected(); + sfTkError_t isConnected(); /// @brief Triggers a new measurement and reads the previous one /// @param distance Distance in mm /// @return 0 for succuss, negative for errors, positive for warnings - sfeTkError_t triggerAndRead(uint16_t &distance); + sfTkError_t triggerAndRead(uint16_t &distance); /// @brief Changes the I2C address of older Qwiic Ultrasonic sensors. /// @param address New address, must be in the range 0x20 to 0x2F /// @return 0 for succuss, negative for errors, positive for warnings - sfeTkError_t changeAddress(uint8_t &address); + sfTkError_t changeAddress(uint8_t &address); /// @brief Gets the current I2C address being used by the library for the Qwiic Ultrasonic sensor /// @return The current I2C address, 7-bit unshifted uint8_t getAddress(); protected: - sfeTkII2C *_theBus; + sfTkII2C *_theBus; private: uint8_t _fwVersion = 0x00;