mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
148 lines
4.8 KiB
Markdown
148 lines
4.8 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/TSL260R/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/TSL260R/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/TSL260R/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/TSL260R/releases)
|
|
|
|
|
|
# TSL260R
|
|
|
|
Arduino library for the TSL260R IR to voltage convertor
|
|
|
|
|
|
## Description
|
|
|
|
The TSL260R (TSL261R, TSL262R) is a IR sensor that outputs a voltage depending on the irradiation.
|
|
|
|
This library does convert the output voltage to uW/cm2.
|
|
|
|
As the type sensor differ by sensitivity the library has three distinct classes.
|
|
The table below is an approximation for the max irradiation at 3.3 Volt (output).
|
|
For an Arduino UNO 3.3 V is about 650 ADC steps.
|
|
When using e.g. an external 16 bit ADS1115, one definitely has far more steps.
|
|
|
|
| Type | max uW/cm2 |
|
|
|:---------:|:------------:|
|
|
| TSL260R | 30 |
|
|
| TSL261R | 70 |
|
|
| TSL262R | 125 |
|
|
|
|
|
|
**Warning** this library is experimental so you should use it with care.
|
|
It is written on the datasheet, and I have no hardware yet to test it.
|
|
Of course I am very interested in your experiences and feedback to improve
|
|
the library.
|
|
|
|
|
|
## Hardware Connection
|
|
|
|
#### Power supply
|
|
|
|
The maximum output voltage depends on the power supply voltage.
|
|
This implies that the output range (uW/cm2) depends on power supply voltage.
|
|
To maximize the measurement range a voltage of at leat 4.5 V is advised.
|
|
|
|
See datasheet figure 14: Maximum Output Voltage vs Supply Voltage
|
|
|
|
|
|
#### Schema
|
|
|
|
Always check datasheet
|
|
|
|
```
|
|
// Front view
|
|
//
|
|
// PIN 1 - GND
|
|
// PIN 2 - VDD 2.7 V .. 5.5 V
|
|
// PIN 3 - SIGNAL voltage out
|
|
```
|
|
|
|
|
|
## Interface
|
|
|
|
#### Internal ADC
|
|
|
|
- **TSL260R(uint8_t pin, uint16_t maxADC, float voltage)** Constructor when using an
|
|
internal ADC and just one sample to measure the output voltage of the sensor.
|
|
- pin = analogRead() pin
|
|
- maxADC = max value of the internal ADC, UNO = 1023.
|
|
- voltage = max voltage of the internal ADC.
|
|
- **TSL261R(uint8_t pin, uint16_t maxADC, float voltage)** idem for TSL261R.
|
|
- **TSL262R(uint8_t pin, uint16_t maxADC, float voltage)** idem for TSL262R.
|
|
- **float irradiance()** returns the irradiance in uW/cm2.
|
|
Uses the analogRead() of the internal ADC.
|
|
**Fails** by returning 0 when object is created with the other constructor.
|
|
|
|
|
|
#### External ADC
|
|
|
|
- **TSL260R()** constructor when using an external ADC or more than one internal samples
|
|
to measure the voltage.
|
|
When using this constructor one cannot use the parameterless **irradiance()**, see above.
|
|
- **TSL261R()** idem for TSL261R.
|
|
- **TSL262R()** idem for TSL262R.
|
|
- **float irradiance(float voltage)** returns the irradiance in uW/cm2 based upon voltage
|
|
parameter. Does not use an internal analogRead().
|
|
Note the user can average 8 internal ADC measurements to reduce noise and then use
|
|
this function based upon the average voltage.
|
|
|
|
|
|
#### WaveLength
|
|
|
|
- **void setWaveLength(uint16_t waveLength = 940)** sets the wave length so the conversion
|
|
can use a correction factor.
|
|
At 900 - 940 nm the wave length correction factor == 1.0.
|
|
Wave length should be between 830 and 1100.
|
|
- **uint16_t getWaveLength()** returns the configured wave length.
|
|
- **float getWaveLengthFactor()** returns the wave length correction factor.
|
|
Note the sensor is most sensitive around 940 nm. See datasheet.
|
|
- **calculateWaveLengthFactor(uint16_t waveLength)** calculates the factor to compensate
|
|
for less sensitivity at other wave lengths.
|
|
E.g. if the sensor is 0.5 x as sensitive at a given wave length the factor should be 2.
|
|
|
|
|
|
#### Calibration
|
|
|
|
Since version 0.1.2 the following functions are added to calibrate the irradiance formula
|
|
to some extend. The formula is ```irradiance = AA * voltage + BB```.
|
|
|
|
See datasheet figure 12: Output Voltage vs Irradiance
|
|
|
|
Use with care.
|
|
|
|
- **void setAA(float aa)** set a new value for AA.
|
|
- **float getAA()** return the current value.
|
|
- **void setBB(float bb)** set a new value for BB.
|
|
- **float getBB()** return the current value.
|
|
|
|
|
|
## Operations
|
|
|
|
See examples.
|
|
|
|
|
|
## Future
|
|
|
|
#### must
|
|
- improve documentation
|
|
- buy hardware (where)
|
|
- test test test test
|
|
|
|
|
|
#### should
|
|
- extend unit tests
|
|
- write examples
|
|
- fix the dependency of **irradiance()**
|
|
- derived class?
|
|
- optimize code
|
|
-
|
|
|
|
#### could
|
|
- test with different IR LEDS (e.g. remote)
|
|
- Normalized Output Voltage vs Angular Displacement correction
|
|
- figure 11
|
|
- temperature correction
|
|
-
|
|
|