Merge pull request #1 from sparkfun/v1.0.0

First implementation

Author: sfe-SparkFro

README.md

@@ -1,4 +1,4 @@
-# SparkFun_Template_Arduino_Library
+# SparkFun_Qwiic_Ultrasonic_Arduino_Library
 ========================================
 
 <table class="table table-hover table-striped table-bordered">

documents/HC_SR04_Datasheet.pdf

@@ -0,0 +1,44 @@
+#include "SparkFun_Qwiic_Ultrasonic_Arduino_Library.h"
+
+// Create an ultrasonic sensor object
+QwiicUltrasonic myUltrasonic;
+
+// 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,
+// you'll need to change the address below. It is also recommended to run
+// Example 2 to change the address to the new default.
+uint8_t deviceAddress = kQwiicUltrasonicDefaultAddress; // 0x2F
+// uint8_t deviceAddress = 0x00;
+
+void setup()
+{
+    // Start serial
+    Serial.begin(115200);
+    Serial.println("Qwiic Ultrasonic Example 1 - Basic Readings");
+
+    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(1000);
+    }
+
+    Serial.println("Ultrasonic sensor connected!");
+}
+
+void loop()
+{
+    // Get measurement from sensor. Note that the mesaured distance actually
+    // comes from the previous trigger, so measurements will be slightly delayed
+    uint16_t distance = 0;
+    myUltrasonic.triggerAndRead(distance);
+
+    // Print measurement
+    Serial.print("Distance (mm): ");
+    Serial.println(distance);
+
+    // Wait a bit
+    delay(100);
+}

documents/add_documents_here.md

@@ -0,0 +1,94 @@
+#include "SparkFun_Qwiic_Ultrasonic_Arduino_Library.h"
+
+// Create an ultrasonic sensor object
+QwiicUltrasonic myUltrasonic;
+
+// 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,
+// you'll need to change the address below. It is also recommended to run
+// Example 2 to change the address to the new default.
+uint8_t deviceAddress = kQwiicUltrasonicDefaultAddress; // 0x2F
+// uint8_t deviceAddress = 0x00;
+
+void setup()
+{
+    // Start serial
+    Serial.begin(115200);
+    Serial.println("Qwiic Ultrasonic Example 2 - Change Address");
+
+    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(1000);
+    }
+
+    Serial.println("Ultrasonic sensor connected!");
+
+    // Repeat until the address has been successfully changed
+    bool addressChanged = false;
+    while (addressChanged == false)
+    {
+        // Print instructions
+        Serial.println();
+        Serial.println("Please enter a new address for the sensor.");
+        Serial.println("Any value between 0x20 and 0x2F is valid.");
+        Serial.println("Enter the address in hexadecimal without the `0x`.");
+        Serial.println();
+
+        // Clear serial buffer and wait for input
+        while (Serial.available() > 0)
+            Serial.read();
+        while (Serial.available() == 0)
+            ;
+
+        // Read input from user
+        char input[4]; // Only expecting a few characters
+        size_t numBytesRead = Serial.readBytesUntil('\n', input, 4);
+
+        // Parse input using strtoul (STRing TO Unsigned Long integer)
+        uint8_t newAddress = strtoul(input, nullptr, 16);
+
+        Serial.print("Parsed address: ");
+        Serial.println(newAddress, HEX);
+
+        // Check if the address is valid
+        if (newAddress < kQwiicUltrasonicMinAddress || newAddress > kQwiicUltrasonicMaxAddress)
+        {
+            Serial.println("Invalid address!");
+            continue;
+        }
+
+        // Address is valid, attempt to change it on the device
+        sfeTkError_t err = myUltrasonic.changeAddress(newAddress);
+
+        // Check whether the address was changed successfully
+        if (err)
+            Serial.println("Failed to change address!");
+
+        // Success, we're done here!
+        addressChanged = true;
+    }
+
+    Serial.println("Address changed successfully! Continuing...");
+
+    // Wait a moment so user can read the messages
+    delay(1000);
+}
+
+void loop()
+{
+    // Get measurement from sensor. Note that the mesaured distance actually
+    // comes from the previous trigger, so measurements will be slightly delayed
+    uint16_t distance = 0;
+    myUltrasonic.triggerAndRead(distance);
+
+    // Print measurement
+    Serial.print("Distance (mm): ");
+    Serial.println(distance);
+
+    // Wait a bit
+    delay(100);
+}

examples/Example01_BasicUsage/Example01_BasicUsage.ino

@@ -1,29 +1,27 @@
 #########################################################
-# Syntax Coloring Map for TODO: Add name                #
+# Syntax Coloring Map for the Qwiic Ultrasonic Sensor   #
 #########################################################
 # Class
 #########################################################
 
-# TODO: Add this
-TemplateClass KEYWORD1
+QwiicUltrasonic KEYWORD1
 
 #########################################################
 # Methods and Functions
 #########################################################
 
-# TODO: Add these
 begin KEYWORD2
+isConnected KEYWORD2
+triggerAndRead KEYWORD2
+changeAddress KEYWORD2
 
 #########################################################
 # Constants
 #########################################################
 
-# TODO: Add these
-TEMPALTE_CONSTANT LITERAL1
-
-#########################################################
-# Structs
-#########################################################
-
-# TODO: Add these
-template_struct_t LITERAL3
+QWIIC_ULTRASONIC_ADDRESSES LITERAL1
+QWIIC_ULTRASONIC_NUM_ADDRESSES LITERAL1
+QWIIC_ULTRASONIC_MIN_ADDRESS LITERAL1
+QWIIC_ULTRASONIC_MAX_ADDRESS LITERAL1
+QWIIC_ULTRASONIC_DEFAULT_ADDRESS LITERAL1
+QWIIC_ULTRASONIC_REGISTER_TRIGGER LITERAL1

examples/Example1_BasicReadings/Example1_BasicReadings.ino

@@ -1,9 +1,9 @@
-name=SparkFun Template Arduino Library
+name=SparkFun Qwiic Ultrasonic Arduino Library
 version=1.0.0
 author=SparkFun Electronics <techsupport@sparkfun.com>
 maintainer=SparkFun Electronics <sparkfun.com>
-sentence=TODO: Add short description
-paragraph=TODO: Add long description
-category=TODO: Add category (Sensors, Display, Communication, etc.)
-url=TODO: Add URL
-architectures=TODO: Add architectures (*, esp32, teensy, stm32, megaavr, etc.)
+sentence=A library to use the SparkFun Qwiic Ultrasonic Distance Sensor
+paragraph=
+category=Sensors
+url=https://github.com/sparkfun/SparkFun_Qwiic_Ultrasonic_Arduino_Library
+architectures=*

examples/Example2_ChangeAddress/Example2_ChangeAddress.ino

@@ -0,0 +1,32 @@
+#pragma once
+
+#include "Arduino.h"
+#include "sfeQwiicUltrasonic.h"
+#include <Wire.h>
+
+class QwiicUltrasonic : public sfeQwiicUltrasonic
+{
+  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
+    bool begin(uint8_t address = kQwiicUltrasonicDefaultAddress, TwoWire &wirePort = Wire)
+    {
+        // Setup Arudino I2C bus
+        _theI2CBus.init(wirePort, address);
+
+        // Begin the sensor
+        return sfeQwiicUltrasonic::begin(&_theI2CBus) == kSTkErrOk;
+    }
+
+    /// @brief Checks if the Qwiic Ultrasonic sensor is connected
+    /// @return True if the sensor is connected, false otherwise
+    bool isConnected()
+    {
+        return sfeQwiicUltrasonic::isConnected() == kSTkErrOk;
+    }
+
+  private:
+    sfeTkArdI2C _theI2CBus;
+};

keywords.txt

@@ -0,0 +1,74 @@
+#include "sfeQwiicUltrasonic.h"
+
+sfeTkError_t sfeQwiicUltrasonic::begin(sfeTkII2C *theBus)
+{
+    // Nullptr check
+    if (theBus == nullptr)
+        return kSTkErrFail;
+
+    // Check the device address
+    if (theBus->address() < kQwiicUltrasonicMinAddress || theBus->address() > kQwiicUltrasonicMaxAddress)
+    {
+        // An older version of the firmware used 0x00 as the default address.
+        // 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;
+    }
+
+    // Set bus pointer
+    _theBus = theBus;
+
+    // Just check if the device is connected, no other setup is needed
+    return isConnected();
+}
+
+sfeTkError_t sfeQwiicUltrasonic::isConnected()
+{
+    // Just ping the device address, there's no product ID register to check
+    return _theBus->ping();
+}
+
+sfeTkError_t sfeQwiicUltrasonic::triggerAndRead(uint16_t &distance)
+{
+    size_t bytesRead = 0;
+    uint8_t rawData[2] = {0, 0};
+
+    // Attempt to read the distance
+    sfeTkError_t err = _theBus->readRegisterRegion(kQwiicUltrasonicRegisterTrigger, rawData, 2, bytesRead);
+
+    // Check whether the read was successful
+    if (err != kSTkErrOk)
+        return err;
+
+    // Store raw data
+    distance = (rawData[0] << 8) | rawData[1];
+
+    // Done!
+    return kSTkErrOk;
+}
+
+sfeTkError_t sfeQwiicUltrasonic::changeAddress(const uint8_t &address)
+{
+    // Check whether the address is valid
+    if (address < kQwiicUltrasonicMinAddress || address > kQwiicUltrasonicMaxAddress)
+        return kSTkErrFail;
+
+    // Write the new address to the device. The first bit must be set to 1
+    sfeTkError_t err = _theBus->writeByte(address | 0x80);
+
+    // Check whether the write was successful
+    if (err != kSTkErrOk)
+        return err;
+
+    // Update the address in the bus
+    _theBus->setAddress(address);
+
+    // Done!
+    return kSTkErrOk;
+}
+
+uint8_t sfeQwiicUltrasonic::getAddress()
+{
+    return _theBus->address();
+}