Skip to content

Commit dc69216

Browse files
gigapodgigapod
committed
updated the section on moving to version 2.0 of the library
1 parent 5f5de1f commit dc69216

File tree

1 file changed

+38
-24
lines changed

1 file changed

+38
-24
lines changed

‎README.md

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
# SparkFun Pulsed Coherent Radar Sensor – Acconeer XM125
55

6-
Arduino Library for the SparkFun Pulsed Coherent Radar Sensor
6+
Arduino Library for the SparkFun Pulsed Coherent Radar Sensor
77

88
![License](https://img.shields.io/github/license/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
99
![Release](https://img.shields.io/github/v/release/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
@@ -12,44 +12,61 @@ Arduino Library for the SparkFun Pulsed Coherent Radar Sensor
1212
![Compile - Test](https://img.shields.io/github/actions/workflow/status/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library/test-compile-sketch.yml?label=compile%20test)
1313
![GitHub issues](https://img.shields.io/github/issues/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
1414

15-
1615
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!
1716

1817
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!
1918

20-
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.
19+
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>.
2120

22-
### *Upgrading to Version 2.\* from Version 1.\**
21+
## Note: *Upgrading to Version 2.\* from Version 1.\**
2322

24-
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, `SparkFunXM125`, was divided into two distinct classes:
23+
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.
2524

26-
* SparkFunXM125Distance - Used when the XM125 is running the ***Distance*** application
27-
* SparkFunXM125Presence - Used when the XM125 is running the ***Presence*** application
25+
### Version 2.0 Changes
2826

29-
Moving to use Version 2.0 of the library just requires changing the class name used in your sketch - from `SparkFunXM125` to either `SparkFunXM125Distance` or `SparkFunXM125Presence`
27+
#### Classes
3028

31-
## Functionality
29+
The device single class was devided into two classes - one for each specific I2C application that the Acconeer XM125 can run. These classes are:
3230

33-
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.
31+
* SparkFunXM125Distance - Used when the XM125 is running the ***Distance*** application
32+
* SparkFunXM125Presence - Used when the XM125 is running the ***Presence*** application
3433

35-
When running as a I2C client device, the Acconeer XM125 is loaded with a specific firmware application from Acconeer.
34+
#### Method Names
3635

37-
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.
36+
Additionally, the method naming pattern for each application was simplified - removing *Distance* and *Presence* from method names.
3837

39-
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.
38+
### Supporting Version 1.* Implementations
4039

40+
To simplify the transition from an application written using the Version 1.* library, two compatiblity classes are provided:
4141

42-
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:
42+
* SparkFunXM125DistanceV1 - Used when the XM125 is running the ***Distance*** application
43+
* SparkFunXM125PresenceV1 - Used when the XM125 is running the ***Presence*** application
4344

44-
|Function|Firmware|
45-
|---|---|
46-
|Distance Detection | `i2c_distance_detector` |
47-
|Presence Detection | `i2c_presence_detector` |
45+
These classes implement the version 1.*method names for the library, to minimize the porting requirements when upgrading to Version 2.*.
46+
47+
To upgrade to Version 2.0 of the library, perform one of the following:
48+
49+
* If the Acconeer XM125 is running the I2C Distance Application: Rename the device class from `SfeXM125` to `SparkFunXM125DistanceV1`
50+
* If the Acconeer XM125 is running the I2C Presence Application: Rename the device class from `SfeXM125` to `SparkFunXM125PresenceV1`
51+
52+
Once the class name is changed, your application is ready to use version 2.* of this library.
53+
54+
## Functionality
55+
56+
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.
4857

49-
## General Use
58+
When running as a I2C client device, the Acconeer XM125 is loaded with a specific firmware application from Acconeer.
5059

51-
### TO DO
60+
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.
5261

62+
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.
63+
64+
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:
65+
66+
|Function|Firmware| Library Class To Use|
67+
|---|---|--|
68+
|Distance Detection | `i2c_distance_detector` | `SparkFunXM125Distance`|
69+
|Presence Detection | `i2c_presence_detector` | `SparkFunXM125Presence`|
5370

5471
## Examples
5572

@@ -67,7 +84,6 @@ The following examples are provided with the library
6784
|[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.|
6885
|[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. |
6986

70-
7187
## Documentation
7288

7389
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).
@@ -80,6 +96,4 @@ The Hookup Guide for the SparkFun Qwiic Soil Moisture Sensor is available [here]
8096

8197
This product is ***open source***!
8298

83-
This product is licensed using the [MIT Open Source License](https://opensource.org/license/mit).
84-
85-
99+
This product is licensed using the [MIT Open Source License](https://opensource.org/license/mit).

0 commit comments

Comments
 (0)