Calibration

To start with, don't stress too much about calibration. You can do it later, and everything might work just fine for you without it. Bermuda mostly considers the "relative" distances between proxies, so it works pretty well even without calibration.

If you are feeling a bit frustrated with how Bermuda is operating, like switching between areas etc, I'd suggest trying out the Troubleshooting page first, then trying Calibration.

Some things that calibration can help with:

• You have one proxy (usually a built-in or USB bluetooth adaptor on your host) that swamps every other proxy
• You have a mixture of proxies with varying antenna/receiver performance (like a mixture of Shellys, esp32-S3's, classic ESP32 etc)
• You have devices with widely varying TX powers, but want to compare distances between them.

Enough parenting from me though... how to calibrate:

Calibration 1: Global Settings

The idea here is to decide on what your "most common" configuration looks like, and set your initial global calibration up to suit that. Say if you have mostly Shelly devices, and a lot of Xiaomi BLE thermometers, and a smattering of other miscellaneous devices, then I'd suggest that you select a Shelly device and a thermometer as your "base pair".

That way you create your global calibration with your most common devices, then you have fewer things you need to apply a per-device calibration to.

• In Homeassistant, go to Settings, Devices and Services, Bermuda.
• Click on CONFIGURE
• Have a moment reflecting on the beauty of the first info screen. This gives you a good overall picture of the health of your bluetooth back-end. A check-mark ✅ tells you this proxy has very recently sent in scan results, great! Warning ⚠️ signs indicate a proxy that is being a bit sluggish with the updates. Skullibones ☠️ means this proxy is not delivering the goods! These measurements are taken at the instant you clicked CONFIGURE, not averages. So they might be different every time you look.
• Click Calibration 1: Global
• Again we are abusing the normal forms, so this workflow is a bit unusual. There are instructions available if you click the expandy arrow thingy ▶️ which say something a lot like:

  • Choose a device and a scanner below to use as your 'reference pair'

  • Physically place your chosen device at one metre (about 39") from the chosen scanner.

    • Yes, it really does need to be 1 metre. At one metre, the attenuation factor doesn't apply to the formula, so we can isolate and set the reference_power by itself.
    • Ensure they have a clear line of sight to each other, and avoid having them close to any organic life-forms or big metal surfaces / objects which might interfere with the signal.

  • Click SUBMIT and note the RSSI values in the table that will magically appear. You can click 'SUBMIT' again at any time to refresh the values.

  • Calibrate the reference_power setting:

    • Once you see multiple readings with a fairly similar RSSI Actual value, put that value into the reference_power field and click 'SUBMIT'.
    • You should now see the estimated distances values update, and hopefully they should be close to 1 metre. Entering a "less negative" value increases the distance estimate, a "more negative" value decreases the distance.
    • Repeat updating the reference_power and clicking SUBMIT until you are happy with the result. Here's a screenshot of an "OK" result. There will always be a bit of noise, and an important part of the calibration process is to calibrate your expectations ;-)
    • Don't tick the save box yet, we're ready to move on the attenuation setting in the same screen...

  • Calibrate the attenuation setting:

    • Now move the device so that it is further from the scanner and measure this distance with a tape measure or calibrated bananas meeting UNECE Codex Standard 205 section 4.1.2, Tolerances for Class I bananas. Around 5 metres might be a good distance - the particular distance you choose doesn't matter, but keeping a clear line of sight is important (so remove the bananas before taking your readings), and while longer distances will give you more accuracy, it will be more finicky to adjust as there will be more noise.

    • With the device at the new distance, click 'SUBMIT' again and you should see that the most recent measurements will reflect the new distance, but will probably be wildly inaccurate.

    • Experiment with different values for attenuation and clicking 'SUBMIT', until you get the estimated measurements to agree with your physical measurement.

      • Higher attenuation values will decrease the estimated distance
      • Lower attenuation values will increase the estimated distance

    • Here's another "OKish" calibration result for 4 metres - you can see how even at this distance noise can be increasingly impactful:

      

  • Once you are happy with the calibration, tick the Save and Close box, then click SUBMIT.

  • You have now set a global default for reference_power and attenuation. Go you!

Calibration 2: Per-Scanner RSSI Offsets

This is the step that will make each of your scanners respond the same way to a given signal. This is also the way to "hobble" a proxy that you want to never "win" a distance contest, by giving it a huge offset so it's never in the running to affect the results.

• Follow the same steps into HA, Settings, Devices and Services, Bermuda, CONFIGURE.

• Select `Calibration 2: Scanner RSSI Offsets

• Select the same device you used in Step 1 as your "reference device" and click SUBMIT

• Visit each proxy in turn with your "reference device" and see how it responds with distances.

• Adjust the offsets to get each proxy sending reasonable distances for the reference device.

  • Larger (positive) offsets will decrease the distance estimate

  • Smaller (negative) offsets will increase the distance estimate

  • Leave your "reference proxy" offset at 0, or things will get confusing.

    

• Once you have a set of offsets you are happy with, tick the "Save and Close" box and SUBMIT

Calibration 3: Per-Device Reference_power settings

For the per-device calibration, we don't use an offset like we do for Proxies(scanners). Instead, per-device calibration uses 0 (zero) to use the default global reference_power, or have it set to their own value for reference power (eg, -64).

This is set on the device page for each Bermuda device.

• Homeassistant, Settings, Devices and Services, Bermuda
• Click on the "devices" link where Bermuda says it has "n devices and k entities"
• Find and click on the device you wish to calibrate
• In the Settings group, there is a number input titled Calibration Ref Power @ 1m. 0 for default. Did you know that HA doesn't support tool-tips for entities? That would be quite lovely.
• Approach the proxy you wish to calibrate the device against (ideally you "reference proxy" but it doesn't matter as long as you've done the previous steps)
• Once the Area sensor indicates you are close enough to the proxy, adjust the Calibration Ref Power input until you get the distance reading you are after. The readings update near-instantly, bypassing any filtering or rate-limiting normally applied to distance readings.
• The value saves automatically in HA periodically, and should be restored on start-up.

Repeat this entire procedure until you decide nothing works, the universe is pure chaos and it's time to give up.