Merge pull request #16 from sparkfun/release/v02.00.00

Moving Release to Main

Author: gigapod

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 SparkFun Electronics
+Copyright (c) 2024-2025 SparkFun Electronics
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,49 +1,112 @@
-SparkFun XM125 A121 Arduino Library
-========================================
 
-[![SparkFun Pulsed Coherent Radar Sensor – Acconeer XM125 (Qwiic)](https://cdn.sparkfun.com/r/600-600/assets/parts/2/4/8/6/5/SEN-24540-Pulsed-Coherent-Radar-Sensor-Feature.jpg)](https://www.sparkfun.com/products/24540)
+![SparkFun Pulsed Coherent Radar Sensor – Acconeer XM125 (Qwiic)](docs/images/gh-banner-2025-xm125.png "SparkFun Pulsed Coherent Radar Sensor")
 
-[*SparkFun Pulsed Coherent Radar Sensor – Acconeer XM125 (Qwiic) (SEN-24540)*](https://www.sparkfun.com/products/24540)
+# SparkFun Pulsed Coherent Radar Sensor – Acconeer XM125
 
-This is the SparkFun library for the Acconeer Entry+ Module XM125 with the A121 60GHz Pulsed Coherent Radar sensor and I<sup>2</sup>C interface.
+Arduino Library for the SparkFun Pulsed Coherent Radar Sensor
 
+![License](https://img.shields.io/github/license/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
+![Release](https://img.shields.io/github/v/release/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
+![Release Date](https://img.shields.io/github/release-date/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
+![Documentation - build](https://img.shields.io/github/actions/workflow/status/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library/build-deploy-ghpages.yml?label=doc%20build)
+![Compile - Test](https://img.shields.io/github/actions/workflow/status/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library/compile-sketch.yml?label=compile%20test)
+![GitHub issues](https://img.shields.io/github/issues/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
 
-Repository Contents
--------------------
+The [SparkFun Pulsed Coherent Radar Sensor - Acconeer XM125 (SEN-24540)](https://www.sparkfun.com/sparkfun-pulsed-coherent-radar-sensor-acconeer-xm125-qwiic.html) brings powerful 60 GHz radar technology to your projects. This sensor isn't limited to surface detection; it can see through walls, cabinets, and even pockets (depending on the material), making it perfect for unique applications. Measure distances with millimeter precision, detect motion, the speed of an object, or even gestures!
 
-* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE.
-* **/src** - Source files for the library (.cpp, .h).
-* **/docs** - Datasheet and application note for the XM125 and A121.
-* **keywords.txt** - Keywords from this library that will be highlighted in the Arduino IDE.
-* **library.properties** - General library properties for the Arduino package manager.
-* **[CONTRIBUTING.md](./CONTRIBUTING.md)** - guidance on how to contribute to this library.
+The XM125 boasts an impressive range of up to 20 meters, allowing you to create long-range sensing projects. The actual measurable distance is dependent on the object size, shape, dielectric properties, and lens (e.g. water level measurements up to 20 meters with lens utilization, human presence detection up to 7 meters with lens-free utilization). Despite its power, the sensor has remarkably low in power consumption, which is ideal for battery-powered applications. The real magic lies in the sensor's ability to do more than measure distance; the XM125 can differentiate between stationary objects and moving targets using pulsed coherent radar. This means you can sense an object's presence and how fast something is moving!
 
+Looking for the board that matches this library - pick up a [SparkFun Pulsed Coherent Radar Sensor - Acconeer XM125 (Qwiic)](https://www.sparkfun.com/sparkfun-pulsed-coherent-radar-sensor-acconeer-xm125-qwiic.html) at <www.sparkfun.com>.
 
-Documentation
---------------
+> [!NOTE]
+>
+> If upgrading from **Version 1** of this library, some changes are required before moving to **Version 2.0+**. The detals of this are outlined in the section titled [Upgrading to Version 2 from Version 1](#upgrading-to-version-2-from-version-1) later in this document.
 
-* **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library.
-* **[Hookup Guide](https://docs.sparkfun.com/SparkFun_Qwiic_Pulsed_Radar_Sensor_XM125)** - Basic hookup guide for the SparkFUn Qwiic Pulsed Coherent Radar Sensor - XM125.
-* **[Product Repository](https://github.com/sparkfun/SparkFun_Qwiic_Pulsed_Radar_Sensor_XM125)** - Main repository for the SparkFun Qwiic XM125 (including hardware files)
+## Functionality
 
+The SparkFun Pulsed Coherent Radar sensor can run as an I2C client device, or as a standalone development board. This library is used when the sensor is operating as a standalone I2C device.
 
-Products that use this Library 
----------------------------------
+When running as a I2C client device, the Acconeer XM125 is loaded with a specific firmware application from Acconeer.
 
-* [*SEN-24540*](https://www.sparkfun.com/products/24540)
+The *SparkFun Pulsed Coherent Radar Sensor - Acconeer XM125* comes with the ***Presence Detector*** firmware loaded, which is accessible using the ***Presence*** focused methods in this library.
 
+This library also supports the ***Distance Detection*** application firmware from Acconeer. To enable this functionally, the ***Distance Detection*** firmware must be loaded onto the *SparkFun Pulsed Coherent Radar Sensor - Acconeer XM125* board. The firmware is available from [Acconeer](https://developer.acconeer.com/home/a121-docs-software/xm125-xe125/) as part of the XM125/A121 SDK. The files are located in the `out/` folder - with naming patter of `i2c_*_detector.bin`. Install instructions are noted in our [Hook Up Guide](https://docs.sparkfun.com/SparkFun_Qwiic_Pulsed_Radar_Sensor_XM125/introduction/) for the product.
 
-License Information
--------------------
+This library provides a extensive interface that enables the following functionality/interaction with the SparkFun Pulsed Coherent Radar Sensor when the sensor is operating as an I2C sensor device:
 
-This product is _**open source**_! 
+|Function|Firmware| Library Class To Use|
+|---|---|--|
+|Distance Detection | `i2c_distance_detector` | `SparkFunXM125Distance`|
+|Presence Detection | `i2c_presence_detector` | `SparkFunXM125Presence`|
 
-Please review the LICENSE.md file for license information. 
+## Documentation
 
-If you have any questions or concerns on licensing, please contact technical support on our [SparkFun forums](https://forum.sparkfun.com/viewforum.php?f=152).
+|Reference | Description |
+|---|---|
+|[Quick Reference](https://docs.sparkfun.com/SparkFun_Qwiic_XM125_Arduino_Library/class_qw_dev_x_m125.html)| A quick reference API for the the main library object ```QwDevXM125```|
+|[Full Documentation](https://docs.sparkfun.com/SparkFun_Qwiic_XM125_Arduino_Library/)| The full documentation and API for this Arduino library|
+|[SparkFun Pulsed Coherent Radar Sensor](https://github.com/sparkfun/SparkFun_Qwiic_Pulsed_Radar_Sensor_XM125)| Hardware GitHub Repository|
+|[Hook Up Guide](https://docs.sparkfun.com/SparkFun_Qwiic_Pulsed_Radar_Sensor_XM125/introduction/) | Hardware Overview and Quick Start for the XM125 Qwiic Development Board |
 
-Distributed as-is; no warranty is given.
+## Examples
 
-- Your friends at SparkFun.
+The following examples are provided with the library
 
-_<COLLABORATION CREDIT>_
+| Example | Description |
+|---|---|
+|[Presence Basic Readings](examples/Example01_PresenceBasicReadings/Example01_PresenceBasicReadings.ino)| The sensor is initialized, then the presence distance values will print out to the terminal.|
+| [Presence GPIO 0 Usage](examples/Example02_PresenceGPIO0Usage/Example02_PresenceGPIO0Usage.ino)|The sensor is initialized, then the presence values will print out to the terminal and trigger the GPIO0 pin high when there is a presence detected. |
+|[Presence Serial Plotter](examples/Example03_PresenceSerialPlotter/Example03_PresenceSerialPlotter.ino)|The sensor is initialized, then the presence values will print out to the terminal and the serial monitor.|
+|[Presence Advanced Readings](examples/Example04_PresenceAdvancedReadings/Example04_PresenceAdvancedReadings.ino)|The sensor is initialized, then the presence distance, intra-presence, and inter-presence values will be printed to the terminal.|
+|[Presence Advanced Settings](examples/Example05_PresenceAdvancedSettings/Example05_PresenceAdvancedSettings.ino)|The sensor is initialized, then the presence distance values will print out to the terminal just as they do in example one. If you wish to change the settings of the device, do so before applying the configuration.|
+|[Distance Basic Readings](examples/Example06_DistanceBasicReadings/Example06_DistanceBasicReadings.ino)|The sensor is initialized, then the distance values will print out to the terminal in mm. |
+|[Distance Threshold Settings](examples/Example07_DistanceThresholdSettings/Example07_DistanceThresholdSettings.ino)|The sensor is initialized, then the distance amplitude, and strength , fixed amplitude, and sensitivity thresholds are set. |
+|[Distance Serial Plotter](examples/Example08_DistanceSerialPlotter/Example08_DistanceSerialPlotter.ino)|This example prints out the distance values of the 0 distance channels to the serial plotter tool in Arduino.|
+|[Distance Advanced Settings](examples/Example09_DistanceAdvancedSettings/Example09_DistanceAdvancedSettings.ino)|The sensor is initialized, then the distance (mm) and advanced values are output to the terminal. |
+  
+## Documentation
+
+The full API and use documentation for this library is provided [here](https://docs.sparkfun.com/SparkFun_Qwiic_XM125_Arduino_Library/). For a quick reference, the main methods available in the library are listed [here](https://docs.sparkfun.com/SparkFun_Qwiic_XM125_Arduino_Library/class_qw_dev_x_m125.html).
+
+Curious about the hardware this board works with - visit the SparkFun Pulsed Coherent Radar Sensor [hardware repository](https://github.com/sparkfun/SparkFun_Qwiic_Pulsed_Radar_Sensor_XM125).
+
+The Hookup Guide for the SparkFun Qwiic Soil Moisture Sensor is available [here](https://docs.sparkfun.com/SparkFun_Qwiic_Pulsed_Radar_Sensor_XM125/introduction/).
+
+## License Information
+
+This product is ***open source***!
+
+This product is licensed using the [MIT Open Source License](https://opensource.org/license/mit).
+
+## Upgrading to Version 2 from Version 1
+
+Version 2.0+ of this library is not compatible with Version 1.* implementations/use. For Version 2.0, the single class defined by the library, `SfeXM125`, was divided into two distinct classes for schemantic clarity and code simplification.
+
+### Version 2.0 Changes
+
+#### Classes
+
+The device single class was devided into two classes - one for each specific I2C application that the Acconeer XM125 can run. These classes are:
+
+* SparkFunXM125Distance - Used when the XM125 is running the ***Distance*** application
+* SparkFunXM125Presence - Used when the XM125 is running the ***Presence*** application
+
+#### Method Names
+
+Additionally, the method naming pattern for each application was simplified - removing *Distance* and *Presence* from method names.  
+
+### Supporting Version 1.* Implementations
+
+To simplify the transition from an application written using the Version 1.* library, two compatiblity classes are provided:
+
+* SparkFunXM125DistanceV1 - Used when the XM125 is running the ***Distance*** application
+* SparkFunXM125PresenceV1 - Used when the XM125 is running the ***Presence*** application
+
+These classes implement the version 1.*method names for the library, to minimize the porting requirements when upgrading to Version 2.*.
+
+To upgrade to Version 2.0 of the library, perform one of the following:
+
+* If the Acconeer XM125 is running the I2C Distance Application: Rename the device class from `SfeXM125` to `SparkFunXM125DistanceV1`
+* If the Acconeer XM125 is running the I2C Presence Application: Rename the device class from `SfeXM125` to `SparkFunXM125PresenceV1`
+
+Once the class name is changed, your application is ready to use version 2.* of this library.

docs/images/gh-banner-2025-xm125.png

@@ -4,14 +4,14 @@
   Using the Acconeer XM125 A121 60GHz Pulsed Coherent Radar Sensor.
 
   This example shows how operate the XM125 when the device is in Presence Reading Mode.
-  The sensor is initialized, then the presence distance values will print out 
+  The sensor is initialized, then the presence distance values will print out
   to the terminal.
 
   By: Madison Chodikov
   SparkFun Electronics
   Date: 2024/1/22
   SparkFun code, firmware, and software is released under the MIT License.
-	Please see LICENSE.md for further details.
+    Please see LICENSE.md for further details.
 
   Hardware Connections:
   QWIIC --> QWIIC
@@ -21,15 +21,15 @@
   Feel like supporting our work? Buy a board from SparkFun!
   https://www.sparkfun.com/products/ - Qwiic XM125 Breakout
 */
-#include <Arduino.h>
 #include "SparkFun_Qwiic_XM125_Arduino_Library.h"
+#include <Arduino.h>
 
-SfeXM125 radarSensor;
+SparkFunXM125Presence radarSensor;
 
 // I2C default address
 uint8_t i2cAddress = SFE_XM125_I2C_ADDRESS;
 
-// Presence distance values 
+// Presence distance values
 uint32_t distance = 0;
 
 // Error statuses
@@ -39,69 +39,79 @@ int32_t setupError = 0;
 int32_t presValError = 0;
 int32_t detectorError = 0;
 
+// Presence range in mm used
+#define MY_XM125_RANGE_START 200
+#define MY_XM125_RANGE_END 1000
 void setup()
 {
     // Start serial
     Serial.begin(115200);
+
+    Serial.println("");
+    Serial.println("-------------------------------------------------------");
     Serial.println("XM125 Example 1: Basic Presence Readings");
+    Serial.println("-------------------------------------------------------");
     Serial.println("");
 
     Wire.begin();
 
     // If begin is successful (1), then start example
-    int startErr = radarSensor.begin(i2cAddress, Wire);
-    if(startErr == 1)
-    {
-        Serial.println("Begin");
-    }
-    else // Otherwise, infinite loop
+    bool success = radarSensor.begin(i2cAddress, Wire);
+    if (success == false)
     {
-        Serial.print("Start Error Code: ");
-        Serial.println(startErr);
         Serial.println("Device failed to setup - Freezing code.");
-        while(1); // Runs forever
+        while (1)
+            ; // Runs forever
     }
 
     // Start the sensor with default register values
-    int32_t setupError = radarSensor.presenceDetectorStart();
-    if(setupError != 0)
+    int32_t setupError = radarSensor.detectorStart(MY_XM125_RANGE_START, MY_XM125_RANGE_END);
+    if (setupError != 0)
     {
-      Serial.print("Presence Detection Start Setup Error: ");
-      Serial.println(setupError); 
+        Serial.print("Presence Detection Start Setup Error: ");
+        Serial.println(setupError);
     }
-
-    // New line and delay for easier reading
+    Serial.print("Presense Detection Started - range: ");
+    Serial.print(MY_XM125_RANGE_START);
+    Serial.print("mm to ");
+    Serial.print(MY_XM125_RANGE_END);
+    Serial.println("mm");
     Serial.println();
+
     delay(500);
 }
 
 void loop()
 {
     // Busy wait loop until data is ready
-    radarSensor.presenceBusyWait();
+    radarSensor.busyWait();
 
-    // Get the presence distance value and print out if no errors
-    presValError = radarSensor.getPresenceDistanceValuemm(distance);
+    // Get the presence distance value and print out if no errors.
+    // Note - this returns if Presence is detected now, or since last check (sticky)
+    presValError = radarSensor.getDistanceValuemm(distance);
 
-    if(presValError == 0)
+    if (presValError == 0)
     {
-      Serial.print("Presence Detected: ");
-      Serial.print(distance);
-      Serial.println("mm");
-      //Serial.print(distance * .01);
-      //Serial.println("cm");
-      //Serial.print(distance * .001);
-      //Serial.println("m");
-      //Serial.print(distance * .001);
-      //Serial.println("m");
-      //Serial.print(distance * .03937008);
-      //Serial.println("In");
+        Serial.print("Presence Detected: ");
+        // if distance is > 0, presence is detected, else it is not
+        if (distance > 0)
+        {
+            Serial.print("YES  -  Distance: ");
+            Serial.print(distance);
+            Serial.print("mm, ");
+            Serial.print(distance * .1);
+            Serial.print("cm, ");
+            Serial.print(distance * .001);
+            Serial.print("m, ");
+            Serial.print(distance * .03937008);
+            Serial.println("In");
+        }
+        else
+            Serial.println("NO");
     }
     else
-    {
-      Serial.println("Error returning presence distance value");
-    }
+        Serial.println("Error returning presence distance value");
 
-    // Delay 0.5 seconds between readings
-    delay(500);
+    // Delay 2.5 seconds between readings
+    delay(2500);
 }