calcSettings

calcSettings

With this function you can calculate new acquisition parameters from given acquisition parameters.
This is useful to implement a auto ranging function.
There already exists an auto ranging function adjustSettings().
This function is only useful if you want to create your own auto ranging function.

 void calcSettings(unsigned int value, BH1750Quality &qual, byte &mtreg, byte percent);

---

result void

Only math stuff. No access to the sensor is required.

---

Parameter unsigned int value

The internal representation of a Lux value. You can get this value with getRaw().

Parameter BH1750Quality &qual

This is a reference value. Before calling the function, you has to declare this variable. After execution of the function that variable will contain an new value. Please refer to setQuality().

---

Parameter byte &mtreg

This is a reference value. Before calling the function, you has to declare this variable. After execution of the function that variable will contain an new value. Please refer to writeMtreg().

---

Parameter byte percent

This parameter adjusts the sensitivity. For example with 50% the MTreg is adjusted so that the expected value is in the middle of the range.
If you set the value to 90% the MTreg is set so that the value is near the upper limit of the range.
This provides better resolution, but it is easier for the next value to exeed the upper limit.
Please refer to [auto ranging](./working-principle#auto ranging-function) for more information.
If this happens, this function does a short measurement in lowest sensitivity in order to get a rough idea of the value and adjusts the MTreg and quality to achieve the required accuracy.
Of course, at the minimum of 0.11 lux the even the highest MTreg can not guarantee the desired percent.
So the percentage would be 1/65535*100= 0.00015%
The same applies to the highest value. Here the percent will be 100%

---

Example:

From a measurement we got 27306.6 Lux.
The MTreg was 69 and the Quality was BH1750_QUALITY_HIGH.
With the function getRaw() we get the raw value of 32768.
As the whole range of raw data is from 0 to 65535, 32768 is perfectly in the middle (50%) of our range.
To enhance the resolution we want that next raw value is 90% of the range.
For this we have to adjust MTreg and Quality:

unsigned int raw = 32768;
byte mtreg = 69;
BH1750Quality qual = BH1750_QUALITY_HIGH;

BH1750.calcSettings(raw, qual, mtreg, 90);

BH1750.start(qual, mtreg);

After calling the function calcSettings the variable mtreg will contain 62 and the Quality changed from BH1750_QUALITY_HIGH to BH1750_QUALITY_HIGH2.
If we initiate a new measurement with the same brightness, we will of course get the same Lux.
But the raw value will be 58881. And this is 90% of 65535.

You're probably wondering why the MTreg dropped from 69 to 62? Normally it should be increasing.
The smart function has realized that we can measure with a higher quality. BH1750_QUALITY_HIGH2 instead of BH1750_QUALITY_HIGH.
This doubles the sensitivity. Thereby the MTreg is halved.
With the same initial quality we would get an MTreg of 125.

And what is the essence of this demonstration?

With the first settings we only get a resolution of 0.83 Lux per digit. With the new settings we are 10% faster (lower MTreg) and we obtain a resolution of 0.46 Lux. That's nearly twice as good!