Develop (#47)

- add yield() to improve the behaviour under RTOS
- update readme.md (add compatibility table).
- minor edits

ACS712.cpp

@@ -1,7 +1,7 @@
 //
 // FILE: ACS712.cpp
 // AUTHOR: Rob Tillaart, Pete Thompson
-// VERSION: 0.3.8
+// VERSION: 0.3.9
 // DATE: 2020-08-02
 // PURPOSE: ACS712 library - current measurement
 // URL: https://github.com/RobTillaart/ACS712
@@ -81,8 +81,8 @@ float ACS712::mA_AC(float frequency, uint16_t cycles)
  uint16_t samples = 0;
  uint16_t zeros = 0;
 
- int _min, _max;
- _min = _max = _analogRead(_pin);
+ int minimum, maximum;
+ minimum = maximum = _analogRead(_pin);
 
  // find minimum and maximum and count the zero-level "percentage"
  uint32_t start = micros();
@@ -95,12 +95,12 @@ float ACS712::mA_AC(float frequency, uint16_t cycles)
  value = (value + _analogRead(_pin))/2;
  }
  // determine extremes
- if (value < _min) _min = value;
- else if (value > _max) _max = value;
+ if (value < minimum) minimum = value;
+ else if (value > maximum) maximum = value;
  // count zeros
  if (abs(value - _midPoint) <= zeroLevel ) zeros++;
  }
- int peak2peak = _max - _min;
+ int peak2peak = maximum - minimum;
 
  // automatic determine _formFactor / crest factor
  float D = 0;
@@ -179,6 +179,11 @@ float ACS712::mA_DC(uint16_t cycles)
  {
  value = (value + _analogRead(_pin))/2;
  }
+ // for RTOS
+ if ((i & 0x0001) == 0x0001) // every 2nd iteration
+ {
+ yield();
+ }
  sum += (value - _midPoint);
  }
  float mA = sum * _mAPerStep;

ACS712.h

@@ -2,7 +2,7 @@
 //
 // FILE: ACS712.h
 // AUTHOR: Rob Tillaart, Pete Thompson
-// VERSION: 0.3.8
+// VERSION: 0.3.9
 // DATE: 2020-08-02
 // PURPOSE: ACS712 library - current measurement
 // URL: https://github.com/RobTillaart/ACS712
@@ -14,7 +14,7 @@
 #include "Arduino.h"
 
 
-#define ACS712_LIB_VERSION (F("0.3.8"))
+#define ACS712_LIB_VERSION (F("0.3.9"))
 
 
 // ACS712_FF_SINUS == 1.0/sqrt(2) == 0.5 * sqrt(2)
@@ -42,24 +42,32 @@ class ACS712
  // 30A 66.0
  ACS712(uint8_t analogPin, float volts = 5.0, uint16_t maxADC = 1023, float mVperAmpere = 100);
 
- // returns mA peak2peak current.
+ // returns mA peak2peak current.
+ // blocks ~20-21 ms per cycle to sample a whole 50 or 60 Hz period.
+ // does NOT call yield() as that would disrupt measurement
  float mA_peak2peak(float frequency = ACS712_DEFAULT_FREQ, uint16_t cycles = 1);
 
+
  // returns mA
- // blocks 20-21 ms to sample a whole 50 or 60 Hz period.
+ // blocks ~20-21 ms per cycle to sample a whole 50 or 60 Hz period.
  // works with peak2peak level and (crest) Form Factor.
  // lower frequencies block longer.
+ // does NOT call yield() as that would disrupt measurement
  float mA_AC(float frequency = ACS712_DEFAULT_FREQ, uint16_t cycles = 1);
 
+
  // returns mA
- // blocks 20-21 ms to sample a whole 50 or 60 Hz period.
+ // blocks 20-21 ms per cycle to sample a whole 50 or 60 Hz period.
  // works with sampling.
  // lower frequencies block longer.
+ // does NOT call yield() as that would disrupt measurement
  float mA_AC_sampling(float frequency = ACS712_DEFAULT_FREQ, uint16_t cycles = 1);
 
+
  // returns mA
- // blocks < 1 ms
- float mA_DC(uint16_t samples = 1);
+ // blocks < 1 ms (depending on # cycles and ADC used)
+ // does call yield() for RTOS.
+ float mA_DC(uint16_t cycles = 1);
 
 
  // midPoint functions

CHANGELOG.md

@@ -6,11 +6,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.3.9] - 2024-01-11
+- add yield() to improve the behaviour under RTOS
+- update readme.md (add compatibility table).
+- minor edits
+
+
 ## [0.3.8] - 2023-09-19
 - add badges to readme.md
 - minor edits
 
-
 ## [0.3.7] - 2023-05-20
 - add example **estimateMidPointAC.ino** #37
 - update readme.md (sampling trick #38).

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-2023 Rob Tillaart
+Copyright (c) 2020-2024 Rob Tillaart
 
 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

@@ -71,6 +71,16 @@ could be obtained with such an ADC. It triggered the experimental supporting
 of external ADC's with this library.
 
 
+#### Calibration and accuracy
+
+The library has no means to calibrate the output or use an offset.
+However sort of calibrating can relatively easy be done by using 
+the MultiMap library.
+MultiMap approaches a non-linear mapping by multiple linear mappings.
+
+See https://github.com/RobTillaart/MultiMap.
+
+
 #### Tests
 
 The library is at least confirmed to work with the following boards:
@@ -91,12 +101,25 @@ Please let me know of other working platforms / processors (and failing ones!).
 Robodyn has a breakout for the ACS758 - 50 A. - See resolution below.
 This sensor has versions up to 200 Amps, so use with care!
 
-Allegromicro offers a lot of different current sensors that might be compatible.
+AllegroMicro offers a lot of different current sensors that might be compatible.
 These include bidirectional and unidirectional ones.
 The unidirectional seem to be for DC only.
 
 https://www.allegromicro.com/en/products/sense/current-sensor-ics/current-sensors-innovations
 
+
+Devices that could be compatible:
+
+| | ACS720 | ACS724 | ACS725 | ACS732 | ACS733| ACS758 | ACS772 | ACS773 | ACS780 | ACS781 |
+|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|
+| tested | | | #44 | | | | | | | |
+
+
+| | ACS37002 | ACS37003 | ACS71240 | ACS3761X | ACS37800 | ACS72981 |
+|:------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|
+| tested | | | | | | |
+
+
 If you have tested a compatible sensor, please share your experiences.
 (can be done by opening an issue to update documentation)
 
@@ -151,6 +174,7 @@ This function is intended for signals with unknown Form Factor.
 - **float mA_DC(uint16_t samples = 1)** blocks < 1 ms (Arduino UNO) as it calls **analogRead()** twice.
 A negative value indicates the current flows in the opposite direction.
  - 0.2.8 the parameter samples allow to average over a number of samples.
+ - 0.3.9 calls yield() every 2nd iteration to improve behaviour under RTOS.
 
 
 #### mA_AC_sampling performance trick.
@@ -342,15 +366,24 @@ ACS.setADC(NULL, 5.0, 1023);
 - example ACS712_20_DC_external_ADC.ino
 - https://github.com/RobTillaart/ACS712/issues/31
 
+- example ACS712_ESP32_external_ADC.ino
+- https://github.com/RobTillaart/ACS712/issues/46
+
 
 Note that the use of an external ADC should meet certain performance requirements,
 especially for measuring **ma-AC()**.
-To 'catch' the peaks well enough one needs at least 2 samples per millisecond
-for a 60 Hz signal.
+
+To 'catch' the peaks well enough one needs at least 2 samples per millisecond (2000 sps)
+for a 60 Hz signal. That gives 34 samples for 360 degrees => 10.6 degrees, which 
+results in a max deviation of 5.3 degrees from peak => max 0.5% off.
+
+As a 50 Hz signal is a bit slower, 2000 sps would give 40 samples for => 9 degrees,
+which results in a max deviation of 4.5 degrees from peak => max 0.4% off.
+
 
 The 16 bit I2C **ADS1115** in continuous mode gives max 0.8 samples per millisecond.
 This will work perfect for high resolution **mA-DC()** but is not fast enough for
-doing **mA-AC()**.
+doing **mA-AC()**. It will get an accuracy around ~2%.
 
 The SPI based **MCP3202** ao can do up to 100 samples per millisecond at 12 bit.
 These ADC's are perfect both **mA-DC()** and **mA-AC()**.
@@ -419,6 +452,22 @@ Schema with PULL-UP.
 The library does not support this "extreme values" detection.
 
 
+## RTOS
+
+The library can be used in an RTOS environment, however a few functions of this
+library are blocking for relative long times.
+
+In version 0.3.9 the **mA_DC()** calls **yield()** between every three calls of analogRead.
+This is done both for the external and intern ADC to prevent blocking of other threads.
+
+For the **mA_AC()** and **mA_peak2peak()** a call to yield() is not desirable 
+as the samples are all needed to make a decent measurement.
+For the applications that need proper scheduling one should put the sampling of the 
+INA226 at least for **AC** in a separate thread. 
+
+There is no RTOS example. If you have and willing to share you are welcome.
+
+
 ## ESPhome
 
 For people who want to use this library for ESPhome, there exists a wrapper 

examples/ACS712_20_AC_DEMO/ACS712_20_AC_DEMO.ino

@@ -54,5 +54,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/ACS712_20_AC_SAMPLING_DEMO/ACS712_20_AC_SAMPLING_DEMO.ino

@@ -49,4 +49,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_AC_average/ACS712_20_AC_average.ino

@@ -41,7 +41,7 @@ void loop()
  uint32_t start = millis();
  for (int i = 0; i < 100; i++)
  {
- // select sppropriate function
+ // select appropriate function
  // average += ACS.mA_AC_sampling();
  average += ACS.mA_AC();
  }
@@ -56,4 +56,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_AC_compare/ACS712_20_AC_compare.ino

@@ -47,4 +47,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_AC_low_pass/ACS712_20_AC_low_pass.ino

@@ -38,16 +38,16 @@ void setup()
  Serial.print("Amp/Step: ");
  Serial.println(ACS.getAmperePerStep(), 4);
 
- value = ACS.mA_AC(); // get good initial value
+ value = ACS.mA_AC();  //  get good initial value
 }
 
 
 void loop()
 {
- // select sppropriate function
+ // select appropriate function
  float mA = ACS.mA_AC_sampling();
- // float mA = ACS.mA_AC();
- value += weight * (mA - value); // low pass filtering
+ //  float mA = ACS.mA_AC();
+ value += weight * (mA - value); //  low pass filtering
 
  Serial.print("weight: ");
  Serial.print(weight);
@@ -61,4 +61,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_AC_midPoint_compare/ACS712_20_AC_midPoint_compare.ino

@@ -51,4 +51,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_AC_midPoint_performance/ACS712_20_AC_midPoint_performance.ino

@@ -71,4 +71,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_AC_suppress_noise/ACS712_20_AC_suppress_noise.ino

@@ -70,4 +70,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_DC/ACS712_20_DC.ino

@@ -3,9 +3,10 @@
 // AUTHOR: Rob Tillaart
 // PURPOSE: demo to measure mA DC
 // URL: https://github.com/RobTillaart/ACS712
-
+//
 // use with Arduino Serial Plotter
 
+
 #include "ACS712.h"
 
 
@@ -41,4 +42,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_DC_DEMO/ACS712_20_DC_DEMO.ino

@@ -52,5 +52,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/ACS712_20_DC_external_ADC/ACS712_20_DC_external_ADC.ino

@@ -3,7 +3,8 @@
 // AUTHOR: Rob Tillaart
 // PURPOSE: demo to measure mA DC with external ADC
 // URL: https://github.com/RobTillaart/ACS712
-
+//
+// see also ACS712_ESP32_external_ADC.ino
 // use with Arduino Serial Plotter
 
 #include "ACS712.h"
@@ -43,7 +44,7 @@ void loop()
 }
 
 // wrapper needed for external analogRead()
-// as casting behavior is undefined between different function signatures.
+// as casting behaviour is undefined between different function signatures.
 uint16_t testADC(uint8_t p)
 {
  // simulation
@@ -54,4 +55,4 @@ uint16_t testADC(uint8_t p)
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_determine_form_factor/ACS712_20_determine_form_factor.ino

@@ -52,4 +52,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/ACS712_20_mV_noise_level/ACS712_20_mV_noise_level.ino

@@ -44,4 +44,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --