Skip to content

Commit 48e0e80

Browse files
gigapodgigapod
committed
update for version 2.0
1 parent c069ff2 commit 48e0e80

File tree

1 file changed

+107
-22
lines changed

1 file changed

+107
-22
lines changed

‎README.md‎

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

44
# SparkFun TMAG5273 Arduino Library
55

6-
This is the SparkFun library for the Texas Instruments TMAG5273 low-power linear 3D Hall-effect sensor with I<sup>2</sup>C interface.
6+
This is the SparkFun Arduino library for the Texas Instruments TMAG5273 low-power linear 3D Hall-effect sensor with I<sup>2</sup>C interface.
77

88
![GitHub License](https://img.shields.io/github/license/sparkfun/SparkFun_TMAG5273_Arduino_Library)
99
![Release](https://img.shields.io/github/v/release/sparkfun/SparkFun_TMAG5273_Arduino_Library)
@@ -12,34 +12,119 @@ This is the SparkFun library for the Texas Instruments TMAG5273 low-power linear
1212
[![Compile Test](https://github.com/sparkfun/SparkFun_FPC2534_Arduino_Library/actions/workflows/test-compile-sketch.yml/badge.svg)](https://github.com/sparkfun/SparkFun_TMAG5273_Arduino_Library/actions/workflows/test-compile-sketch.yml)
1313
![GitHub issues](https://img.shields.io/github/issues/sparkfun/SparkFun_TMAG5273_Arduino_Library)
1414

15-
Repository Contents
16-
-------------------
15+
This SparkFun Arduino Library for the Texas Instruments TMAG5273 linear 3D Hall-effect sensor provides access to the core functionality of the sensor. The sensor itself includes three Hall-effect sensors, providing readings around the X, Y and Z axes of the device.
1716

18-
* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE.
19-
* **/src** - Source files for the library (.cpp, .h).
20-
* **/Documentation** - Datasheet for the TMAG5273.
21-
* **keywords.txt** - Keywords from this library that will be highlighted in the Arduino IDE.
22-
* **library.properties** - General library properties for the Arduino package manager.
23-
* **[CONTRIBUTING.md](./CONTRIBUTING.md)** - guidance on how to contribute to this library.
17+
The Texas Instruments TMAG5273 is available on the following SparkFun breakout development boards:
2418

25-
Documentation
26-
--------------
19+
- [SparkFun IoT Brushless Motor Driver (ESP32 WROOM, TMC6300)](https://www.sparkfun.com/sparkfun-iot-brushless-motor-driver-esp32-wroom-tmc6300.html#content-documentation)
20+
- [SparkFun Linear 3D Hall-Effect Sensor - TMAG5273 (Qwiic)](https://www.sparkfun.com/sparkfun-linear-3d-hall-effect-sensor-tmag5273-qwiic.html)
21+
- [SparkFun Mini Linear 3D Hall-Effect Sensor - TMAG5273 (Qwiic)](https://www.sparkfun.com/sparkfun-mini-linear-3d-hall-effect-sensor-tmag5273-qwiic.html)
2722

28-
* **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library.
29-
* **[Hookup Guide](https://docs.sparkfun.com/SparkFun_IoT_Brushless_Motor_Driver)** - Basic hookup guide for the SparkFun IoT Motor Driver Breakout (ESP32, TMC6300).
30-
* **[Product Repository](https://github.com/sparkfun/SparkFun_IoT_Brushless_Motor_Driver)** - Main repository for the IoT Motor Driver (including hardware files)
23+
## Functionality
3124

32-
License Information
33-
-------------------
25+
SparkFun Arduino Library for the TMAG5273 provides access to the a majority of the functionality provided by the the TMAG5273 device. This includes:
3426

35-
This product is _**open source**_!
27+
- Access to X, Y and Z Hall-effect sensor readings
28+
- Data digitized via an integrated 12-bit ADC
29+
- Integrated temperature sensor
30+
- Configurable to enable any combination of magnetic axes and temperature measurements
31+
- Integrated angle calculation engine (CORDIC) provides full 360 degree position information
32+
- Magnetic gain and offset correction settings
33+
- Configurable I2C address, with a default value of `0x22`
3634

37-
Please review the LICENSE.md file for license information.
35+
### Implemented, but not supported functionality
3836

39-
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).
37+
The TMAG5273 supports several advance features that this library does not support. These are namely:
4038

41-
Distributed as-is; no warranty is given.
39+
| Feature | Notes |
40+
| -- | -- |
41+
|CRC Communication Checks| This library contains a method to enable and disable this feature on the device, but the I2C communication implemented by the library will not read or check any provided CRS values|
42+
| I2C Read/Write Methods | The TMAG5273 supports different format options for I2C operations. While this library provides a method to change the I2C configuration on the device, this library only uses standard I2C operations|
4243

43-
* Your friends at SparkFun.
44+
While the library include configuration methods for the above features, these features are not supported. The methods are maintained only to provide backward compatibility with earlier versions (< 2.0) of this library.
4445

45-
_<COLLABORATION CREDIT>_
46+
## Notes on Library Versions 2.0 and Above
47+
48+
Version 2.0 of this library involved a large "refactor" of the library to address existing issues, improve the overall implementation and form a foundation for easier library maintenance in the future. As part of this effort, several existing library methods were modified such that they are not backward compatible with earlier (1.*) library versions. These changes include the following:
49+
50+
- The method ```readWakeUpAndSleepData()``` no longer takes pointers as parameters. References are used to simplify use.
51+
- Various methods that used `float` type parameters and return values, now use `int8_t` types to reflect the actual sensor data.
52+
- Equations for data values, sensor temperature and offsets were validated and updated based on the TMAG5273 datasheet. Key intermediate data typing was also validated as needed to provide correct results.
53+
54+
## Using the Library
55+
56+
The first step is to add the class named `TMAG5273` to the implementation. An example of how to declare the sensor object is as follows:
57+
58+
```c++
59+
60+
TMAG5273 sensor; // Declare the hall-effect sensor
61+
62+
```
63+
64+
In the startup section of the implementation, the sensor is initialized by calling the ```begin()``` method with the address of the sensor and the Arduino ```Wire``` port to use.
65+
66+
```c++
67+
// If begin is successful (0), then start example
68+
if (sensor.begin(TMAG5273_I2C_ADDRESS_INITIAL, Wire) == 1)
69+
{
70+
Serial.println("Sensor Detected and Initialized");
71+
}
72+
else
73+
{
74+
Serial.println("Sensor failed to start!");
75+
}
76+
```
77+
78+
Note: If using the defaults, the begin method can be called with no parameters.
79+
80+
At this point the sensor can be configured for your specific use.
81+
82+
Values from the sensor are read as follows:
83+
84+
```c++
85+
// read data values
86+
float magX = sensor.getXData();
87+
float magY = sensor.getYData();
88+
float magZ = sensor.getZData();
89+
float temp = sensor.getTemp();
90+
91+
// output the values to the serial console
92+
Serial.print("Data - Magnetic: [ X: ");
93+
Serial.print(magX);
94+
Serial.print(", Y: ");
95+
Serial.print(magY);
96+
Serial.print(", Z: ");
97+
Serial.print(magZ);
98+
Serial.print(" ] mT, Temp: ");
99+
Serial.print(temp);
100+
Serial.println(" C");
101+
```
102+
103+
## Documentation
104+
105+
|Reference | Description |
106+
|---|---|
107+
|[Quick Reference](https://docs.sparkfun.com/SparkFun_TMAG5273_Arduino_Library/class_t_m_a_g5273.html)| A quick reference API for the the main library object |
108+
|[Full Documentation](https://docs.sparkfun.com/SparkFun_TMAG5273_Arduino_Library/)| The full documentation and API for this Arduino library|
109+
|[SparkFun Hall-Effect Sensor - TMAG5273](https://github.com/sparkfun/SparkFun_Qwiic_Hall_Effect_Sensor_TMAG5273)| Hardware GitHub Repository|
110+
|[Hall-Effect Sensor Hook Up Guide](https://docs.sparkfun.com/SparkFun_Qwiic_Hall_Effect_Sensor_TMAG5273) | Hardware Overview and Quick Start for the SparkFun Hall-Effect Sensor - TMAG5273 |
111+
|[SparkFun IoT Brushless Motor Driver (ESP32 WROOM, TMC6300)](https://github.com/sparkfun/SparkFun_IoT_Brushless_Motor_Driver)| Hardware GitHub Repository|
112+
|[SparkFun IoT Brushless Motor DriverHook Up Guide](https://docs.sparkfun.com/SparkFun_IoT_Brushless_Motor_Driver/introduction/) | Hardware Overview and Quick Start for the SparkFun IoT Brushless Motor Driver |
113+
114+
## Examples
115+
116+
The following examples are provided with the library
117+
118+
| Example | Description |
119+
|---|---|
120+
| [Basic Readings](examples/Example1_BasicReadings/Example1_BasicReadings.ino) | Shows basic sensor setup and value reading|
121+
| [Interrupt Triggered Reading](examples/Example2_Interrupts/Example2_Interrupts.ino)| Demostraights how to use a interrupt to trigger data reading|
122+
| [Angle Calculations](examples/Example3_AngleCalculations/Example3_AngleCalculations.ino) | Setting up and reading Angle Calculations from the sensor|
123+
| [I2C Address Setting](examples/Example4_I2CSettings/Example4_I2CSettings.ino) | How to change the I2C address of the sensor|
124+
| [IOT Motor Driver Readings](examples/Example5_IoT_Motor_Driver_Readings/Example5_IoT_Motor_Driver_Readings.ino) | Using the TMAG5273 with the SparkFun IoT Brushless Motor development board|
125+
126+
## License Information
127+
128+
This product is ***open source***!
129+
130+
This product is licensed using the [MIT Open Source License](https://opensource.org/license/mit).

0 commit comments

Comments
 (0)