diff --git a/libraries/LTR390_DFR/CHANGELOG.md b/libraries/LTR390_DFR/CHANGELOG.md index 1b8a0066..912e0dcc 100644 --- a/libraries/LTR390_DFR/CHANGELOG.md +++ b/libraries/LTR390_DFR/CHANGELOG.md @@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). +## [0.1.1] - 2024-09-23 +- extend functionality and documentation +- add return value in **setGain()** 0..4 +- add param check in **bool setMeasurement(resolution,time)** +- refactored code for readability (e.g. magic numbers). +- add **bool setUVsensitivity(float s)** and **float getUVsensitivity()()** +- update keywords.txt (prepare) + + ## [0.1.0] - 2024-04-29 - initial version diff --git a/libraries/LTR390_DFR/LTR390_DFR.h b/libraries/LTR390_DFR/LTR390_DFR.h index ece4ee5d..5cbba288 100644 --- a/libraries/LTR390_DFR/LTR390_DFR.h +++ b/libraries/LTR390_DFR/LTR390_DFR.h @@ -3,7 +3,7 @@ // FILE: LTR390_DFR.h // AUTHOR: Rob Tillaart // DATE: 2024-04-29 -// VERSION: 0.1.0 +// VERSION: 0.1.1 // PURPOSE: Arduino library for the I2C LTR390 UV sensor (DF Robotics edition). // URL: https://github.com/RobTillaart/LTR390_DFR @@ -12,10 +12,10 @@ #include "Wire.h" -#define LTR390_DFR_LIB_VERSION (F("0.1.0")) +#define LTR390_DFR_LIB_VERSION (F("0.1.1")) // LTR390 ERROR CODES -// TODO +#define LTR390_OK 0x00 // DF_ROBOTICS LTR390 REGISTERS (16 bits) @@ -77,12 +77,16 @@ public: // void setALSMode() { - writeRegister(LTR390_MAIN_CTRL, 0x02); + uint8_t raw = readRegister(LTR390_MAIN_CTRL); + raw &= ~0x08; + writeRegister(LTR390_MAIN_CTRL, raw); } void setUVSMode() { - writeRegister(LTR390_MAIN_CTRL, 0x0A); + uint8_t raw = readRegister(LTR390_MAIN_CTRL); + raw |= 0x08; + writeRegister(LTR390_MAIN_CTRL, raw); } uint8_t reset() @@ -116,7 +120,9 @@ public: // uint32_t getALSData() { - return readRegister(8) * 65536UL + readRegister(7); + uint32_t raw = readRegister(LTR390_ALS_DATA_1) * 65536UL; + raw += readRegister(LTR390_ALS_DATA_0); + return raw; } // page 22 datasheet @@ -129,7 +135,9 @@ public: uint32_t getUVSData() { - return readRegister(10) * 65536UL + readRegister(9); + uint32_t raw = readRegister(LTR390_UVS_DATA_1) * 65536UL; + raw += readRegister(LTR390_UVS_DATA_0); + return raw; } // page 22 datasheet @@ -145,20 +153,17 @@ public: // // MEASUREMENT CONFIGURATION // - // experimental... - // - // TODO does not work as expected yet - // - void setGain(uint8_t gain) // 0..4 + uint8_t setGain(uint8_t gain = 1) // 0..4 { uint16_t value = gain; if (value > 4) value = 4; writeRegister(LTR390_GAIN, value); _gain = 1; - if (value == 1) _gain = 3; - if (value == 2) _gain = 6; - if (value == 3) _gain = 9; - if (value == 4) _gain = 18; + if (value == 1) _gain = 3; + else if (value == 2) _gain = 6; + else if (value == 3) _gain = 9; + else if (value == 4) _gain = 18; + return value; } uint8_t getGain() @@ -169,17 +174,22 @@ public: // resolution = 0..5 See datasheet P14. // time = 0..7 See datasheet P14. - void setMeasurement(uint8_t resolution, uint8_t time) + bool setMeasurement(uint8_t resolution, uint8_t time) { + if (resolution > 5) return false; + if (time > 7 ) return false; + uint16_t value = (resolution << 4) | time; writeRegister(LTR390_ALS_UVS_MEAS_RATE, value); - _time = 2.000; + + _time = 2.000; // time = 6 0r 7 if (time == 0) _time = 0.025; if (time == 1) _time = 0.050; if (time == 2) _time = 0.100; if (time == 3) _time = 0.200; if (time == 4) _time = 0.500; if (time == 5) _time = 1.000; + return true; } uint8_t getResolution() @@ -194,28 +204,59 @@ public: return reg & 0x07; } + bool setUVsensitivity(float s) + { + if ((s <= 0.0) || (s > 1.0))return false; + _UVsensitivity = s; + return true; + } + + float getUVsensitivity() + { + return _UVsensitivity; + } + + +// +// Code below this line is not tested yet. +// Use carefully, feel free to experiment. +// Please let me know if it works or not. +// + +/* + void enable() + { + uint8_t raw = readRegister(LTR390_MAIN_CTRL); + raw != 0x02; + writeRegister(LTR390_MAIN_CTRL, raw); + } + + void disable() + { + uint8_t raw = readRegister(LTR390_MAIN_CTRL); + raw &= ~0x02; + writeRegister(LTR390_MAIN_CTRL, raw); + } +*/ + /* ////////////////////////////////////////////// // // MAIN STATUS - // TODO elaborate - need split? or masks? // uint8_t getStatus() { - uint8_t reg = readRegister(LTR390_MAIN_STATUS); + uint8_t reg = readRegister(LTR390_MAIN_STATUS); ? no such register. return reg & 0x38; } -*/ - -/* ////////////////////////////////////////////// // // INTERRUPT // - int setInterruptConfig(uint8_t value) + int setInterruptConfig(uint8_t value = 0x10) { return writeRegister(LTR390_INT_CFG, value); } @@ -225,7 +266,7 @@ public: return readRegister(LTR390_INT_CFG); } - int setInterruptPersist(uint8_t value) + int setInterruptPersist(uint8_t value = 0x00) { return writeRegister(LTR390_INT_PST, value); } @@ -234,57 +275,47 @@ public: { return readRegister(LTR390_INT_PST); } -*/ -/* ////////////////////////////////////////////// // // THRESHOLD // - void setHighThreshold(uint32_t value) + // note registers are 16 bit. + // + void setHighThreshold(uint32_t value = 0x000FFFFF) { - writeRegister(LTR390_ALS_UVS_THRES_UP_0, value & 0xFF); - value >>= 8; - writeRegister(LTR390_ALS_UVS_THRES_UP_1, value & 0xFF); - value >>= 8; - writeRegister(LTR390_ALS_UVS_THRES_UP_2, value & 0x0F); + writeRegister(LTR390_ALS_UVS_THRES_UP_0, value & 0xFFFF); + writeRegister(LTR390_ALS_UVS_THRES_UP_1, value >> 16); } uint32_t getHighThreshold() { - uint32_t value = readRegister(LTR390_ALS_UVS_THRES_UP_2) & 0x0F; - value <<= 8; - value += readRegister(LTR390_ALS_UVS_THRES_UP_1); - value <<= 8; + uint32_t value = readRegister(LTR390_ALS_UVS_THRES_UP_1) << 16; value += readRegister(LTR390_ALS_UVS_THRES_UP_0); return value; } - void setLowThreshold(uint32_t value) + void setLowThreshold(uint32_t value = 0) { - writeRegister(LTR390_ALS_UVS_THRES_LOW_0, value & 0xFF); - value >>= 8; - writeRegister(LTR390_ALS_UVS_THRES_LOW_1, value & 0xFF); - value >>= 8; - writeRegister(LTR390_ALS_UVS_THRES_LOW_2, value & 0x0F); + writeRegister(LTR390_ALS_UVS_THRES_LOW_0, value & 0xFFFF); + writeRegister(LTR390_ALS_UVS_THRES_LOW_1, value >> 16); } uint32_t getLowThreshold() { - uint32_t value = readRegister(LTR390_ALS_UVS_THRES_LOW_2) & 0x0F; - value <<= 8; - value += readRegister(LTR390_ALS_UVS_THRES_LOW_1); - value <<= 8; + uint32_t value = readRegister(LTR390_ALS_UVS_THRES_LOW_1) << 16; value += readRegister(LTR390_ALS_UVS_THRES_LOW_0); return value; } */ +// END OF PUBLIC PART + ////////////////////////////////////////////// // - // PRIVATE TODO move. + // PRIVATE // int writeRegister(uint8_t reg, uint16_t value) { @@ -295,6 +326,7 @@ public: int n = _wire->endTransmission(); if (n != 0) { + // _error = LTR390_I2C_ERROR; // Serial.print("write:\t"); // Serial.println(n); } @@ -309,6 +341,7 @@ public: int n = _wire->endTransmission(); if (n != 0) { + // _error = LTR390_I2C_ERROR; // Serial.print("read:\t"); // Serial.println(n); return n; @@ -337,7 +370,5 @@ private: }; - - // -- END OF FILE -- diff --git a/libraries/LTR390_DFR/README.md b/libraries/LTR390_DFR/README.md index 12ee81f3..a6cdea2d 100644 --- a/libraries/LTR390_DFR/README.md +++ b/libraries/LTR390_DFR/README.md @@ -11,14 +11,14 @@ # LTR390_DFR -Arduino library for the I2C LTR390 UV sensor (DF Robotics edition). +Arduino library for the I2C LTR390 LUX / UV sensor (DF Robotics edition). ## Description **Experimental** -This library is to read the LTR390 UV sensor on the DF Robotics +This library is to read the LTR390 LUX / UV sensor on the DF Robotics break-out board. Operating voltage range: **3.0V .. 5.0V** (tolerant). @@ -26,16 +26,16 @@ Operating voltage range: **3.0V .. 5.0V** (tolerant). ## I2C -The break-out has an address of 0x1C == 28 decimal. +The break-out has a fixed address of 0x1C == 28 decimal. -#### I2C Speed +### I2C Speed The device should work on 100 kHz and 400 kHz I2C bus. To be tested. -#### Multiplexing +### Multiplexing Sometimes you need to control more devices than possible with the default address range the device provides. @@ -54,7 +54,7 @@ too if they are behind the multiplexer. -#### Related +### Related - https://github.com/RobTillaart/LTR390_RT (native LTR390) - https://github.com/RobTillaart/LTR390_DFR (DF Robotics variant) @@ -66,43 +66,84 @@ too if they are behind the multiplexer. #include "LTR390_DFR.h" ``` -#### Constructor +### Constructor - **LTR390_DFR(TwoWire \* wire = &Wire)** Constructor with optional Wire interface. -- **bool begin()** returns true if device 0x1C can be seen on the I2C bus. -- **bool isConnected()** returns true if device 0x1C can be seen on I2C bus. +As the device has a fixed I2C address it cannot be set. +- **bool begin()** returns true if device address 0x1C can be seen on the I2C bus. +- **bool isConnected()** returns true if device address 0x1C can be seen on I2C bus. - **uint8_t getAddress()** returns 0x1C, fixed address, for convenience. -#### Main control +### Main control -- **void setALSMode()** -- **void setUVSMode()** -- **void reset()** blocks for 100 ms. +- **void setALSMode()** set the Ambient Light Sensor mode. +- **void setUVSMode()** set the Ultra Violet Sensor mode. +- **void reset()** resets the sensor. This call blocks for 100 ms. -#### Measurement configuration +### Gain configuration -- **void setGain(uint8_t gain)** gain = 0..4, -- **uint8_t getGain()** returns set value. -- **void setMeasurement(uint8_t resolution, uint8_t time)** -- **uint8_t getResolution()** -- **uint8_t getTime()** +- **uint8_t setGain(uint8_t gain = 1)** gain = 0..4, values larger than 4 are +clipped to 4. Default value = 1. +Returns 0..4. +- **uint8_t getGain()** returns set value, 0..4. -#### Part and revision ID +| Gain | factor | Notes | +|:------:|:--------:|:-------:| +| 0 | 1 | +| 1 | 3 | default +| 2 | 6 | +| 3 | 9 | +| 4 | 18 | + + +### Resolution and time + +- **bool setMeasurement(uint8_t resolution, uint8_t time)** +Resolution = 0..5, Time = 0..7. See table below. +Returns false if one of the parameters is out of range. +- **uint8_t getResolution()** returns 0..5, default 2. +- **uint8_t getTime()** returns 0..7, default 2. + + +| Reso | bits | | Time | millis | Notes | +|:------:|:------:|:-:|:------:|:--------:|:-------:| +| 0 | 20 | | 0 | 25 | +| 1 | 19 | | 1 | 50 | +| 2 | 18 | | 2 | 100 | default both. +| 3 | 17 | | 3 | 200 | +| 4 | 16 | | 4 | 500 | +| 5 | 13 | | 5 | 1000 | +| 6 | na | | 6 | 2000 | +| 7 | na | | 7 | 2000 | + +14, 15 bits is not supported. + + +### UV sensitvity + +- **bool setUVsensitivity(float s)** Sets the UV sesitivity +between 0..1. Returns false if the parameter s is out of range. +- **float getUVsensitivity()** returns set value. default 1.0. + + +### Part and revision ID - **uint8_t getPartID()** returns 11. - **uint8_t getRevisionID()** returns 2. -#### Get data +### Get data -- **uint32_t getALSData()** -- **float getLUX(float wfac = 1)** wfac = window factor, -- **uint32_t getUVSData()** -- **float getUVI(float wfac = 1)** wfac = window factor, +- **uint32_t getALSData()** returns 18 bit data +- **float getLUX(float wfac = 1.0)** wfac = window factor, typical 0..1.0. +Returns the ambient light in LUX. +- **uint32_t getUVSData()** returns 18 bit data +- **float getUVI(float wfac = 1.0)** wfac = window factor, typical 0..1.0. +Returns the UV index in ??? (TODO units). ## Future @@ -117,10 +158,12 @@ with optional Wire interface. #### Should - add examples -- fix / elaborate TODO's in code. - - status and error codes - - interrupts and thresholds -- add setUVsensitivity() +- add error codes +- split **getStatus()** or ?? +- add **uint16_t getTimeMillis()** return time in millseconds. +- add **uint8_t getResolutionBits()** idem. +- add **uint8_t getGainFactor()** idem. + #### Could diff --git a/libraries/LTR390_DFR/keywords.txt b/libraries/LTR390_DFR/keywords.txt index 70c98cb9..2a4d50bd 100644 --- a/libraries/LTR390_DFR/keywords.txt +++ b/libraries/LTR390_DFR/keywords.txt @@ -13,6 +13,9 @@ setALSMode KEYWORD2 setUVSMode KEYWORD2 reset KEYWORD2 +enable KEYWORD2 +disable KEYWORD2 + getPartID KEYWORD2 getRevisionID KEYWORD2 @@ -28,6 +31,21 @@ setMeasurement KEYWORD2 getResolution KEYWORD2 getTime KEYWORD2 +setUVsensitivity KEYWORD2 +getUVsensitivity KEYWORD2 + +getStatus KEYWORD2 + +setInterruptConfig KEYWORD2 +getInterruptConfig KEYWORD2 +setInterruptPersist KEYWORD2 +getInterruptPersist KEYWORD2 + +setHighThreshold KEYWORD2 +getHighThreshold KEYWORD2 +setLowThreshold KEYWORD2 +getLowThreshold KEYWORD2 + # Constants (LITERAL1) LTR390_DFR_LIB_VERSION LITERAL1 diff --git a/libraries/LTR390_DFR/library.json b/libraries/LTR390_DFR/library.json index c61d2264..a9b22a11 100644 --- a/libraries/LTR390_DFR/library.json +++ b/libraries/LTR390_DFR/library.json @@ -15,7 +15,7 @@ "type": "git", "url": "https://github.com/RobTillaart/LTR390_DFR.git" }, - "version": "0.1.0", + "version": "0.1.1", "license": "MIT", "frameworks": "*", "platforms": "*", diff --git a/libraries/LTR390_DFR/library.properties b/libraries/LTR390_DFR/library.properties index 4ed3d310..22f45f97 100644 --- a/libraries/LTR390_DFR/library.properties +++ b/libraries/LTR390_DFR/library.properties @@ -1,5 +1,5 @@ name=LTR390_DFR -version=0.1.0 +version=0.1.1 author=Rob Tillaart maintainer=Rob Tillaart sentence=Arduino library for the I2C LTR390 UV sensor (DF Robotics edition).