adjustSettings

adjustSettings

This Function is used to implement auto ranging.
Based of the last measurement, the settings for the next measurement are adjusted, to achieve a specified resolution and full scale sensitivity (0.11 Lux to 121557 Lux). This corresponds to a resolution of about 20 bit!

This function also allows to start a short test measurement (~10 ms) and calculate the optimum parameter for a following high resolution measurement.

bool adjustSettings(byte percent = 50, bool forcePreShot = false);

result Boolean

true if communication was successful.

---

Parameter byte percent = 50

This parameter adjusts the sensitivity. With 50% (default), 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, 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%

---

Parameter bool forcePreShot = false

If this parameter is false, the function will behave as described above.
if forcePreShot is true, then every time a short measurement with lowest quality and lowest MTreg will be started first. From this result the optimum MTreg will be calculated. This is useful if the time intervals between the measurements are large, as larger fluctuations in brightness can occur.

---

Examples and hints:

void loop()
{
  if (BH1750.hasValue() == true) {    // non blocking reading
    unsigned int raw = BH1750.getRaw();    
    float V = BH1750.getLux();
    Serial.println(V);
    if (raw == BH1750_SATURATED) Serial.print("*");    
    BH1750.adjustSettings(90);    
    BH1750.start();
  }
  //  do a lot of other stuff here...
}

In this non-blocking example we get the last Lux value with float V = BH1750.getLux().
To check if the value is saturated, it is easiest to check the raw value with unsigned int raw = BH1750.getRaw();
If the Sensor was saturated, we print a asterisk (*) after the value. if (raw == BH1750_SATURATED) Serial.print("*");
BH1750_SATURATED is a constant with value 65535. But you can write it shorter and more elegantly:

void loop()
{
  if (BH1750.hasValue() == true) {    // non blocking reading
  if (!BH1750.saturated()) Serial.println(BH1750.getLux());    
  BH1750.adjustSettings(90);    
  BH1750.start();
  }
  //  do a lot of other stuff here...
}

Here we use a function saturated() and ask the sensor if the last value is saturated.
Instead of printing a asterisk here we ignore the saturated value from printing.

For an example see calcSettings()

If you use auto ranging with the MTreg hack you should take that remark into account.