From 6b79c0bdebb087fb10dae16f8944376dee94a7d9 Mon Sep 17 00:00:00 2001 From: rob tillaart Date: Thu, 17 Nov 2022 20:12:05 +0100 Subject: [PATCH] 0.1.9 ML8511 --- libraries/ML8511/.arduino-ci.yml | 16 +++++++ libraries/ML8511/CHANGELOG.md | 50 +++++++++++++++++++++ libraries/ML8511/ML8511.cpp | 62 +++++++++++++------------- libraries/ML8511/ML8511.h | 66 +++++++++++++++------------- libraries/ML8511/library.json | 2 +- libraries/ML8511/library.properties | 2 +- libraries/ML8511/readme.md | 67 +++++++++++++---------------- 7 files changed, 167 insertions(+), 98 deletions(-) create mode 100644 libraries/ML8511/CHANGELOG.md diff --git a/libraries/ML8511/.arduino-ci.yml b/libraries/ML8511/.arduino-ci.yml index cecf5850..25980972 100644 --- a/libraries/ML8511/.arduino-ci.yml +++ b/libraries/ML8511/.arduino-ci.yml @@ -1,3 +1,18 @@ +platforms: + rpipico: + board: rp2040:rp2040:rpipico + package: rp2040:rp2040 + gcc: + features: + defines: + - ARDUINO_ARCH_RP2040 + warnings: + flags: + +packages: + rp2040:rp2040: + url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json + compile: # Choosing to run compilation tests on 2 different Arduino platforms platforms: @@ -9,3 +24,4 @@ compile: - esp32 # - esp8266 # - mega2560 + - rpipico diff --git a/libraries/ML8511/CHANGELOG.md b/libraries/ML8511/CHANGELOG.md new file mode 100644 index 00000000..6295d895 --- /dev/null +++ b/libraries/ML8511/CHANGELOG.md @@ -0,0 +1,50 @@ +# Change Log ML8511 + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/) +and this project adheres to [Semantic Versioning](http://semver.org/). + + +## [0.1.9] - 2022-11-17 +- add RP2040 in build-CI +- add changelog.md +- moved all code to .cpp file +- edit readme.md +- minor edits + + +## [0.1.8] - 2021-12-21 +- update library.json +- update license +- minor edits + +## [0.1.7] - 2021-11-09 +- update Arduino-CI, badges +- add voltage2mW() for external ADC + + +## [0.1.6] - 2021-06-19 +- add get/setDUVfactor() +- rewrite estimateDUVindex() +- add reset() + +## [0.1.5] - 2021-05-27 +- fix Arduino-lint + +## [0.1.4] - 2021-04-23 +- fix for platformIO + +## [0.1.3] - 2021-01-01 +- Arduino-CI + unit test + +## [0.1.2] - 2020-06-21 +- refactor +- add estimateDUVindex() + +## [0.1.1] - 2020-02-17 +- added \_voltPerStep() to support more boards + +## [0.1.0] - 2020-02-03 +- initial version. + diff --git a/libraries/ML8511/ML8511.cpp b/libraries/ML8511/ML8511.cpp index b8d5a4f3..22094a2a 100644 --- a/libraries/ML8511/ML8511.cpp +++ b/libraries/ML8511/ML8511.cpp @@ -1,22 +1,8 @@ // // FILE: ML8511.cpp // AUTHOR: Rob.Tillaart@gmail.com -// VERSION: 0.1.8 +// VERSION: 0.1.9 // PURPOSE: ML8511 - UV sensor - library for Arduino -// -// HISTORY: -// 0.1.0 2020-02-03 initial version -// 0.1.1 2020-02-17 added _voltPerStep() to support more boards -// 0.1.2 2020-06-21 refactor; add estimateDUVindex() -// 0.1.3 2021-01-01 Arduino-CI + unit test -// 0.1.4 2021-04-23 fix for platformIO -// 0.1.5 2021-05-27 fix Arduino-lint -// 0.1.6 2021-06-19 add get/setDUVfactor(), -// rewrite estimateDUVindex(), -// add reset(); -// 0.1.7 2021-11-09 update Arduino-CI, badges -// add voltage2mW() for external ADC -// 0.1.8 2021-12-21 update library.json, license, minor edits #include "ML8511.h" @@ -24,7 +10,7 @@ ///////////////////////////////////////////////////// // -// PUBLIC +// PUBLIC // ML8511::ML8511(uint8_t analogPin, uint8_t enablePin) { @@ -48,7 +34,7 @@ ML8511::ML8511(uint8_t analogPin, uint8_t enablePin) void ML8511::reset() { _voltsPerStep = 5.0/1023; - _DUVfactor = 1.61; // https://github.com/RobTillaart/ML8511/issues/4 + _DUVfactor = 1.61; // https://github.com/RobTillaart/ML8511/issues/4 } @@ -57,7 +43,7 @@ float ML8511::getUV(uint8_t energyMode) if (!_enabled) { enable(); - // datasheet page 5 states wait for max 1 millisecond + // datasheet page 5 states wait for max 1 millisecond uint32_t start = micros(); while (micros() - start < 1000) yield(); } @@ -76,10 +62,10 @@ float ML8511::getUV(uint8_t energyMode) // to be used by external ADC float ML8511::voltage2mW(float voltage) { - // see datasheet - page 4 - // mW/cm2 @ 365 nm - // @ 25 Celsius - // formula estimated on graph + // see datasheet - page 4 + // mW/cm2 @ 365 nm + // @ 25 Celsius + // formula estimated on graph if (voltage <= 1.0) { return 0.0; @@ -90,26 +76,32 @@ float ML8511::voltage2mW(float voltage) } -// experimental estimate DUV index ( ==> USE WITH CARE !!) -// use setDUVfactor(float w) to calibrate +// experimental estimate DUV index ( ==> USE WITH CARE !!) +// use setDUVfactor(float w) to calibrate // -// input is power in mW per cm2 +// input is power in mW per cm2 float ML8511::estimateDUVindex(float mWcm2) { - // rewrite in 0.1.6 - // https://github.com/RobTillaart/ML8511/issues/4 + // rewrite in 0.1.6 + // https://github.com/RobTillaart/ML8511/issues/4 return mWcm2 * _DUVfactor; }; bool ML8511::setDUVfactor(float factor) { - if (factor < 0.01) return false; // enforce positive values + if (factor < 0.01) return false; // enforce positive values _DUVfactor = factor; return true; }; +float ML8511::getDUVfactor() +{ + return _DUVfactor; +}; + + void ML8511::setVoltsPerStep(float voltage, uint32_t steps) { if (steps == 0) return; @@ -117,6 +109,12 @@ void ML8511::setVoltsPerStep(float voltage, uint32_t steps) } +float ML8511::getVoltsPerStep() +{ + return _voltsPerStep; +} + + void ML8511::enable() { if (_enablePin != 0xFF) digitalWrite(_enablePin, HIGH); @@ -131,5 +129,11 @@ void ML8511::disable() }; -// -- END OF FILE -- +bool ML8511::isEnabled() +{ + return _enabled; +}; + + +// -- END OF FILE -- diff --git a/libraries/ML8511/ML8511.h b/libraries/ML8511/ML8511.h index 584b9e33..fec9319d 100644 --- a/libraries/ML8511/ML8511.h +++ b/libraries/ML8511/ML8511.h @@ -2,64 +2,69 @@ // // FILE: ML8511.h // AUTHOR: Rob Tillaart -// VERSION: 0.1.8 +// VERSION: 0.1.9 // PURPOSE: ML8511 - UV sensor - library for Arduino // URL: https://github.com/RobTillaart/ML8511 // -// HISTORY: -// see ML8511.cpp file -// -// NOTES -// ML8511 is a 3.3 Volt device, -// so do not connect to a 5V device (e.g. UNO) -// this includes the ENABLE PIN !! +// NOTES +// ML8511 is a 3.3 Volt device, +// so do not connect to a 5V device (e.g. UNO) +// this includes the ENABLE PIN !! // +// +-------+--+ +// VIN |o +-+| mounting hole +// 3V3 |o +-+| +// GND |o | +// OUT |o | +// EN |o S | Sensor +// +----------+ #include -#define ML8511_LIB_VERSION (F("0.1.8")) +#define ML8511_LIB_VERSION (F("0.1.9")) class ML8511 { public: - // if enablePin is omitted, one must connect EN to 3V3. + // if enablePin is omitted, one must connect EN to 3V3. ML8511(uint8_t analogPin, uint8_t enablePin = 0xFF); - void reset(); // reset internal variables to initial value. + void reset(); // reset internal variables to initial value. - // energyMode = HIGH or LOW; - // returns mW per cm2 + // energyMode = HIGH or LOW; + // returns mW per cm2 float getUV(uint8_t energyMode = HIGH); - // for external ADC + // for external ADC float voltage2mW(float voltage); - // voltage must be > 0 otherwise it is not set + // voltage must be > 0 otherwise it is not set void setVoltsPerStep(float voltage, uint32_t steps); - float getVoltsPerStep() { return _voltsPerStep; }; + float getVoltsPerStep(); - // manually enable / disable + // manually enable / disable void enable(); void disable(); - bool isEnabled() { return _enabled; }; + bool isEnabled(); - // experimental estimate DUV index - // WARNING: USE WITH CARE + // experimental estimate DUV index + // WARNING: USE WITH CARE // - // input in mW per cm2 == typical the output of getUV() + // input in mW per cm2 == typical the output of getUV() float estimateDUVindex(float mWcm2); + + + // https://github.com/RobTillaart/ML8511/issues/4 + // discusses the calibration + // see readme.md how to reverse engineer the factor for + // the estimateDUVindex() conversion function. + // a value of 1.61 was found to be far more accurate // - // https://github.com/RobTillaart/ML8511/issues/4 - // discusses the calibration - // see readme.md how to reverse engineer the factor for - // the estimateDUVindex() conversion function. - // a value of 1.61 was found to be far more accurate - // - // returns false if f < 0.01 (to force positive only) + // returns false if f < 0.01 (to force positive factor only) bool setDUVfactor(float factor); - float getDUVfactor() { return _DUVfactor; }; + float getDUVfactor(); private: @@ -68,10 +73,9 @@ private: float _voltsPerStep; bool _enabled; - float _DUVfactor; }; -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/libraries/ML8511/library.json b/libraries/ML8511/library.json index c06de034..8f6b7268 100644 --- a/libraries/ML8511/library.json +++ b/libraries/ML8511/library.json @@ -15,7 +15,7 @@ "type": "git", "url": "https://github.com/RobTillaart/ML8511.git" }, - "version": "0.1.8", + "version": "0.1.9", "license": "MIT", "frameworks": "arduino", "platforms": "*", diff --git a/libraries/ML8511/library.properties b/libraries/ML8511/library.properties index d987cb91..e01c019c 100644 --- a/libraries/ML8511/library.properties +++ b/libraries/ML8511/library.properties @@ -1,5 +1,5 @@ name=ML8511 -version=0.1.8 +version=0.1.9 author=Rob Tillaart maintainer=Rob Tillaart sentence=ML8511 - UV sensor - library for Arduino diff --git a/libraries/ML8511/readme.md b/libraries/ML8511/readme.md index 72118b1a..67f445f9 100644 --- a/libraries/ML8511/readme.md +++ b/libraries/ML8511/readme.md @@ -8,7 +8,7 @@ # ML8511 -Arduino library for ML8511 UV sensor. +Arduino library for the ML8511 UV sensor. ## Warning @@ -24,17 +24,20 @@ When using artificial UV light (TL LED laser a.o.) use appropriate shielding. ML8511 - UV sensor - library for Arduino UNO. +- 3V3 Sensor so do **NOT** connect to 5V directly. +- do not forget to connect the EN to either an enablePIN or to 3V3 (constantly enabled). -## Breakout + +#### Breakout ``` -// +-------+--+ -// VIN |o +-+| mounting hole -// 3V3 |o +-+| -// GND |o | -// OUT |o | -// EN |o S | Sensor -// +----------+ +// +-------+--+ +// VIN |o +-+| mounting hole +// 3V3 |o +-+| +// GND |o | +// OUT |o | +// EN |o S | Sensor +// +----------+ ``` @@ -47,18 +50,18 @@ reference of 5.0 Volt == 1023 steps as default. If one wants to use other ratio e.g. 3.3 volts == 4095 steps, one can set those with **setVoltagePerStep()**. -``` +```cpp ML8511 light(A0, 7); light.setVoltagePerStep(3.3, 4095); ``` It is possible to always enable the sensor by connecting the EN pin to 3V3. The value of the enablePin in the constructor should then be omitted -or set to a negative value; +or set to a negative value. -When connecting to an Arduino UNO one can use the 3V3 of the Arduino to power -the sensor. However it is not possible to connect the enable pin directly to the -sensor. Use a voltage divider (10K + 20K) to convert the 5 Volts to ~3.3 Volts. +When connecting to an Arduino UNO one can use the 3V3 of the Arduino to power the sensor. +However it is not possible to connect the enable pin directly to the sensor. +Use a voltage divider (10K + 20K) to convert the 5 Volts to ~3.3 Volts. ## Interface @@ -85,13 +88,13 @@ WARNING: USE WITH CARE - **void setDUVfactor(float factor)** set the conversion factor - **float getDUVfactor()** returns the set conversion factor (default 1.61) -See below how to determine the DUV factor for your sensor. +See below (Experimental DUVindex) how to determine the DUV factor for your sensor. -Note: +_Note: The UV index can be very high, in La Paz, Bolivia, one of the highest cities in the world the DUV index can go above 20. See link below. This is really extreme and it is unknown how the ML8511 sensor (and this library) behaves under such conditions, and how long the sensor would survive. -Datasheet goes up to 15 mW per cm2, with a default DUVfactor of ~1.61 the measurements could handle DUV of ~24 in theory. +Datasheet goes up to 15 mW per cm2, with a default DUVfactor of ~1.61 the measurements could handle DUV of ~24 in theory._ https://edition.cnn.com/2021/11/03/americas/bolivia-heatwave-highlands-intl/index.html @@ -150,6 +153,8 @@ Hardcode this found value in the library (in the constructor) or better use the **setDUVfactor(factor)** call in **setup()** to calibrate your sensor. +## Version info + #### 0.1.5 and before The formula for the experimental **estimateDUVindex(mWcm2)** is based on @@ -169,24 +174,14 @@ The formula is simplified to a single factor that the user needs to determine. Below is described how to do the calibration. -#### 0.1.7 - -- update Arduino-CI, badges -- add voltage2mW() for external ADC - - -#### 0.1.8 - -- update library.json, license, minor edits - ## External ADC **float voltage2mW(float voltage)** can be used for an external ADC e.g ADS1015, ADS1115 or one of the (fast) MCP_ADC's. -https://github.com/RobTillaart/ADS1X15 -https://github.com/RobTillaart/MCP_ADC +- https://github.com/RobTillaart/ADS1X15 +- https://github.com/RobTillaart/MCP_ADC ## More about UV @@ -194,20 +189,20 @@ https://github.com/RobTillaart/MCP_ADC https://en.wikipedia.org/wiki/Ultraviolet_index -## Notes - -- 3V3 Sensor so do **NOT** connect to 5V directly. -- do not forget to connect the EN to either an enablePIN or to 3V3 (constantly enabled). - - ## Future +#### must +- improve documentation - refactor / reorganize readme.md + +#### should - test more - get unit tests up and running - investigate in calibration - check performance + +#### could - investigate serial UV communication with UV led - voltage2mW -> handle negative voltages by taking abs value? -- +