0.2.0 A1301

This commit is contained in:
Rob Tillaart 2023-04-25 10:25:42 +02:00
parent b16048c86b
commit 3cdd0e5a43
12 changed files with 292 additions and 56 deletions

View File

@ -1,23 +1,29 @@
//
// FILE: A1301.cpp
// AUTHOR: Rob Tillaart
// VERSION: 0.1.2
// VERSION: 0.2.0
// DATE: 2010-07-22
// PURPOSE: Arduino library for A1301 A1302 magnetometer.
// URL: https://github.com/RobTillaart/A1301
#include "A1301.h"
/////////////////////////////////////////////////////////////////////////////
//
// CONSTRUCTOR
//
HALL::HALL(uint8_t pin)
{
_pin = pin;
_midPoint = 512;
_maxADC = 1023;
_mVStep = 5000.0 / _maxADC; // default 10 bit 5V ADC (UNO)
_midPoint = _maxADC * 0.5; // default middle
_prevGauss = 0;
_lastGauss = 0;
_mVGauss = 2.5;
_mVStep = 5000.0 / 1023; // default 10 bit 5V ADC
_maxADC = 1023;
_maxGauss = 500.0;
}
@ -25,9 +31,14 @@ void HALL::begin(float voltage, uint16_t steps)
{
_maxADC = steps;
_mVStep = voltage / steps;
_midPoint = steps * 0.5;
}
/////////////////////////////////////////////////////////////////////////////
//
// MIDPOINT
//
void HALL::setMidPoint(float midPoint)
{
_midPoint = midPoint;
@ -40,6 +51,10 @@ float HALL::getMidPoint()
}
/////////////////////////////////////////////////////////////////////////////
//
// SENSITIVITY
//
void HALL::setSensitivity(float sensitivity)
{
_mVGauss = sensitivity;
@ -62,6 +77,7 @@ float HALL::raw(uint8_t times)
if (times == 0) times = 1;
for (int i = 0; i < times; i++)
{
// yield();
sum += analogRead(_pin);
}
if (times > 1) sum /= times;
@ -91,6 +107,12 @@ float HALL::readExt(float raw)
//
// ANALYSE
//
bool HALL::isNull()
{
return (_lastGauss == 0);
}
bool HALL::isNorth()
{
return (_lastGauss > 0);
@ -115,7 +137,10 @@ float HALL::prevGauss()
}
// CONVERTORs
/////////////////////////////////////////////////////////////////////////////
//
// CONVERTORS
//
float HALL::Tesla(float Gauss)
{
return Gauss * 0.0001;
@ -136,11 +161,11 @@ float HALL::uTesla(float Gauss)
/////////////////////////////////////////////////////////////////////////////
//
// EXPERIMENTAL
// SATURATION LEVEL
//
void HALL::setMaxGauss(uint16_t maxGauss)
void HALL::setMaxGauss(float maxGauss)
{
_maxGauss = maxGauss;
_maxGauss = abs(maxGauss);
}
@ -152,11 +177,16 @@ float HALL::getMaxGauss()
bool HALL::isSaturated()
{
// experimental, depends on sensor? to elaborate
return (abs(_lastGauss) >= _maxGauss);
}
float HALL::saturationLevel()
{
return 100.0 * abs(_lastGauss / _maxGauss);
}
/////////////////////////////////////////////////////////////////////////////
//
// DERIVED

View File

@ -2,9 +2,11 @@
//
// FILE: A1301.h
// AUTHOR: Rob Tillaart
// VERSION: 0.1.2
// VERSION: 0.2.0
// DATE: 2010-07-22
// PURPOSE: Arduino library for A1301 A1302 magnetometer.
// URL: https://github.com/RobTillaart/A1301
// always check datasheet.
// PIN A1301
@ -16,7 +18,7 @@
#include "Arduino.h"
#define A1301_LIB_VERSION (F("0.1.2"))
#define A1301_LIB_VERSION (F("0.2.0"))
class HALL
@ -27,6 +29,7 @@ public:
// ADC parameters
void begin(float voltage, uint16_t steps);
// midpoint depends on ADC.
void setMidPoint(float midPoint);
float getMidPoint();
@ -34,6 +37,7 @@ public:
void setSensitivity(float sensitivity);
float getSensitivity();
// READ
// times > 1 ==> more stable read / averaging.
// uses internal ADC
@ -42,37 +46,43 @@ public:
// for external ADC
float readExt(float raw);
// ANALYSE
bool isNull();
bool isNorth();
bool isSouth();
float lastGauss();
float prevGauss();
// CONVERTERs
float Tesla(float Gauss);
float mTesla(float Gauss);
float uTesla(float Gauss);
// EXPERIMENTAL
// SATURATION LEVEL = EXPERIMENTAL
// manual override default maxGauss
void setMaxGauss(uint16_t maxGauss);
void setMaxGauss(float maxGauss);
float getMaxGauss();
bool isSaturated();
float saturationLevel();
protected:
uint8_t _pin = 0;
float _midPoint = 512;
float _prevGauss = 0;
float _lastGauss = 0;
float _mVGauss = 2.5;
float _mVStep = 5000.0 / 1023;
uint16_t _maxADC = 1023;
uint8_t _pin;
float _midPoint;
float _prevGauss;
float _lastGauss;
float _mVGauss;
float _mVStep;
uint16_t _maxADC;
// Experimental
float _maxGauss = 500;
float _maxGauss;
};
////////////////////////////////////////////////////
//
// DERIVED

View File

@ -6,18 +6,30 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).
## [0.2.0] - 2023-04-24
- add **isNull()** is no magnetic field is detected.
- add **saturationLevel()** returns 0..100%
- update examples (plotter + test)
- fix midPoint in **begin()**
- fix constructor **maxGauss**
- update readme.md
- update unit test
- update keywords.txt
- minor edits
----
## [0.1.2] - 2023-03-01
- update GitHub actions
- update license
- minor edits
## [0.1.1] - 2022-12-02
- update keywords
- update keywords.txt
- boolean => bool
- add isSaturated();
- add **isSaturated()**
- update readme.md
- add A1324/25/26 derived classes.
- add A1324/A1325/A1326 derived classes.
- update unit test
## [0.1.0] - 2022-12-01

View File

@ -13,13 +13,14 @@ Arduino library for A1301 and A1302 magnetometer.
## Description
The A1301 and A1302 are continuous-time, ratiometric, linear
Hall-effect sensors. They are optimized to accurately provide
a voltage output that is proportional to an applied magnetic
field. These devices have a quiescent output voltage that is
50% of the supply voltage. Two output sensitivity options are
provided: 2.5 mV/G typical for the A1301, and 1.3 mV/G
typical for the A1302. (from datasheet)
The A1301 and A1302 are continuous-time, Ratio-metric, linear Hall-effect sensors.
They are optimized to accurately provide a voltage output that is proportional to
an applied magnetic field.
These devices have a quiescent output voltage that is 50% of the supply voltage.
This voltage level is a.k.a. the midPoint.
Two output sensitivity options are provided: 2.5 mV/G typical for the A1301,
and 1.3 mV/G typical for the A1302. (from datasheet)
The following 5 classes are supported:
@ -54,6 +55,11 @@ Please open an issue on GitHub.
## Interface
```cpp
#include "A1301.h"
```
#### Constructor
- **HALL(uint8_t pin)** base class constructor.
@ -90,7 +96,7 @@ Returns Gauss.
Note: **raw** is an ADC measurement, not a voltage.
Can be positive (North) or negative (South).
Returns Gauss.
Can also be used for testing, e.g. replay of a series of data.
#### Analyse
@ -101,9 +107,15 @@ Returns Gauss.
- **float prevGauss()** returns previous measurement in Gauss.
#### Experimental
#### Saturation.
- **bool isSaturated()** true when ADC (lastRead) seems to max out. Experimental for now.
Experimental saturation level.
- **void setMaxGauss(float maxGauss)** set the saturation level.
If maxGauss < 0 the absolute value is set.
- **float getMaxGauss()** returns the set saturation level.
- **bool isSaturated()** true when ADC (lastRead) seems to max out.
- **float saturationLevel()** returns value between 0..100%.
#### Tesla
@ -122,23 +134,54 @@ The examples show the basic working of the functions.
## Future
#### Must
- improve documentation
- buy hardware A1301 / A1302 / ...
- buy hardware A1301 / A1302 / etc...
- test with hardware (again)
#### Should
- plotter example
- unit tests
- test **isSaturated()**
- test **isSaturated()** + **saturationLevel()**
- limits might be sensor dependant.
- optimize math
- multiplications instead of divisions.
- other constants needed?
#### Could
- **float findZero()** how exactly.
- **float determineNoise()** related
- printable interface
- **float findZero()** how exactly => ACS712 **autoMidPoint()**
- investigate **float determineNoise()** (set/get)
- add examples.
- performance read()
- Possible compatible
- HoneyWell - SS39ET/SS49E/SS59ET
- HoneyWell - SS490 Series
- temperature correction functions?
- see datasheet.
#### Ideas
(thinking out loud section)
- isEast() and isWest() meaning?
- **isEast()** field strength is "rising" ==> lastGauss > prevGauss
- **isWest()** field strength is "sinking" ==> lastGauss < prevGauss
- should that be absolute or not? or just **bool isRising()**
- **float readDelta(uint8_t times = 1)** returns the relative change.
- atan2(prevGauss, lastGauss)?
- angle indicates relative delta compared to magnitude and direction.
- 45 135 degrees is no change.
- can the strength of the signal be converted to distance?
- for a given magnet
- repeatability + noise.
- influence of angle of the field-lines?
- defaults for parameters of some functions?
#### Won't
- printable interface
- does not add much.

View File

@ -2,6 +2,7 @@
// FILE: A1301_demo
// AUTHOR: Rob Tillaart
// PURPOSE: demo A1301 A1302 magnetometer.
// URL: https://github.com/RobTillaart/A1301
#include "Arduino.h"

View File

@ -2,6 +2,7 @@
// FILE: A1301_plotter.ino
// AUTHOR: Rob Tillaart
// PURPOSE: demo A1301 A1302 magnetometer.
// URL: https://github.com/RobTillaart/A1301
//
// to be used with Arduino Serial plotter

View File

@ -0,0 +1,61 @@
//
// FILE: A1301_test.ino
// AUTHOR: Rob Tillaart
// PURPOSE: demo A1301 A1302 magnetometer.
#include "Arduino.h"
#include "A1301.h"
A1301 mm(A0);
uint32_t lastTime = 0;
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.println(__FILE__);
Serial.print("A1301_LIB_VERSION: ");
Serial.println(A1301_LIB_VERSION);
mm.begin(5000, 1023);
for (float r = 505; r < 515; r += 0.5)
{
test(r);
}
Serial.println("\ndone...");
}
void loop()
{
}
void test(float raw)
{
Serial.print(raw);
Serial.print("\t");
Serial.print(mm.readExt(raw));
Serial.print("\t");
Serial.print(mm.isNull());
Serial.print("\t");
Serial.print(mm.isNorth());
Serial.print("\t");
Serial.print(mm.isSouth());
Serial.print("\t");
Serial.print(mm.isSaturated());
Serial.print("\t");
Serial.print(mm.prevGauss());
Serial.print("\t");
Serial.print(mm.lastGauss());
Serial.print("\t");
Serial.print(mm.saturationLevel());
Serial.print("\n");
}
// -- END OF FILE --

View File

@ -0,0 +1,61 @@
//
// FILE: A1301_test_saturation.ino
// AUTHOR: Rob Tillaart
// PURPOSE: demo A1301 A1302 magnetometer.
#include "Arduino.h"
#include "A1301.h"
A1301 mm(A0);
uint32_t lastTime = 0;
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.println(__FILE__);
Serial.print("A1301_LIB_VERSION: ");
Serial.println(A1301_LIB_VERSION);
mm.begin(5000, 1023);
for (float r = 0; r < 1023; r += 10)
{
test(r);
}
Serial.println("\ndone...");
}
void loop()
{
}
void test(float raw)
{
Serial.print(raw);
Serial.print("\t");
Serial.print(mm.readExt(raw));
Serial.print("\t");
Serial.print(mm.isNull());
Serial.print("\t");
Serial.print(mm.isNorth());
Serial.print("\t");
Serial.print(mm.isSouth());
Serial.print("\t");
Serial.print(mm.isSaturated());
Serial.print("\t");
Serial.print(mm.prevGauss());
Serial.print("\t");
Serial.print(mm.lastGauss());
Serial.print("\t");
Serial.print(mm.saturationLevel());
Serial.print("\n");
}
// -- END OF FILE --

View File

@ -1,8 +1,12 @@
# Syntax Colouring Map For A1301
# Data types (KEYWORD1)
HALL KEYWORD1
A1301 KEYWORD1
A1302 KEYWORD1
A1324 KEYWORD1
A1325 KEYWORD1
A1326 KEYWORD1
# Methods and Functions (KEYWORD2)
@ -18,6 +22,7 @@ raw KEYWORD2
read KEYWORD2
readExt KEYWORD2
isNull KEYWORD2
isNorth KEYWORD2
isSouth KEYWORD2
lastGauss KEYWORD2
@ -30,6 +35,7 @@ uTesla KEYWORD2
setMaxGauss KEYWORD2
getMaxGauss KEYWORD2
isSaturated KEYWORD2
saturationLevel KEYWORD2
# Constants (LITERAL1)

View File

@ -1,6 +1,6 @@
{
"name": "A1301",
"keywords": "A1301,A1302,A1324,A1325,A1326, magnetic",
"keywords": "A1301,A1302,A1324,A1325,A1326, magnetic, HALL",
"description": "Arduino library for A1301, A1302, A1324, A1325, A1326 magnetometer.",
"authors":
[
@ -15,7 +15,7 @@
"type": "git",
"url": "https://github.com/RobTillaart/A1301.git"
},
"version": "0.1.2",
"version": "0.2.0",
"license": "MIT",
"frameworks": "arduino",
"platforms": "*",

View File

@ -1,9 +1,9 @@
name=A1301
version=0.1.2
version=0.2.0
author=Rob Tillaart <rob.tillaart@gmail.com>
maintainer=Rob Tillaart <rob.tillaart@gmail.com>
sentence=Arduino library for A1301 et al magnetometer.
paragraph=A1301, A1302, A1324, A1325, A1326, magnetic.
paragraph=A1301, A1302, A1324, A1325, A1326, magnetic, HALL.
category=Signal Input/Output
url=https://github.com/RobTillaart/A1301
architectures=*

View File

@ -3,7 +3,7 @@
// AUTHOR: Rob Tillaart
// DATE: 2022-12-01
// PURPOSE: unit tests for the A1301 magnetic sensor
// https://github.com/RobTillaart/A1301
// URL: https://github.com/RobTillaart/A1301
// https://www.adafruit.com/product/2857
// https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md
//
@ -75,7 +75,15 @@ unittest(test_midPoint)
H.begin(3.3, 4095);
H.setMidPoint(2020);
assertEqual(2020, H.getMidPoint());
assertEqualFloat(2020, H.getMidPoint(), 0.1);
H.begin(2.5, 1000);
assertEqualFloat(500, H.getMidPoint(), 0.1);
H.begin(2.5, 1023);
assertEqualFloat(511.5, H.getMidPoint(), 0.1);
}
@ -100,10 +108,13 @@ unittest(test_read_external_ADC)
assertEqualFloat(-0.337494, H.readExt(1000.0), 0.01);
assertTrue(H.isSouth());
assertEqualFloat(-0.176322, H.readExt(1500.0), 0.01);
assertTrue(H.isSouth());
assertEqualFloat(-0.0151502, H.readExt(2000.0), 0.01);
assertTrue(H.isSouth());
assertEqualFloat(0.307194, H.readExt(3000.0), 0.01);
assertTrue(H.isNorth());
}
@ -114,11 +125,12 @@ unittest(test_converters)
HALL H(4);
H.begin(3.3, 4095);
H.setMidPoint(2047);
assertEqualFloat(0.005, H.Tesla(50), 0.01);
assertEqualFloat(5.00, H.mTesla(50), 0.01);
assertEqualFloat(5000, H.uTesla(50), 0.01);
float Gauss = 50;
assertEqualFloat(0.005, H.Tesla(Gauss), 0.01);
assertEqualFloat(5.00, H.mTesla(Gauss), 0.01);
assertEqualFloat(5000, H.uTesla(Gauss), 0.01);
}
@ -127,11 +139,10 @@ unittest(test_maxGauss)
HALL H(4);
H.begin(3.3, 4095);
H.setMidPoint(2047);
assertEqual(500, H.getMaxGauss());
assertEqualFloat(500, H.getMaxGauss(), 0.1);
H.setMaxGauss(400);
assertEqual(400, H.getMaxGauss());
assertEqualFloat(400, H.getMaxGauss(), 0.1);
}