Add calibration guide and settings overview to documentation

Author: DTTerastar

configuration/calibration.md

@@ -0,0 +1,65 @@
+---
+layout: page
+title: Calibration
+permalink: /configuration/calibration
+parent: "Configuration"
+nav_order: 3
+---
+
+# Calibration
+
+Calibrating your ESPresense nodes helps each device estimate distance consistently, even when they use different antennas or are installed in different rooms. The settings below are available from the full Settings view on the device web UI.
+
+![Calibration section of the ESPresense settings UI](/images/calibration_settings.png){: width="360" }
+
+## Quick calibration procedure
+
+1. Pick a **reference node** that will stay at its default `rxAdj` of `0` and set it up in an open area.
+2. Place a beacon that transmits **exactly 0 dBm** one meter away and record the average RSSI reported by the reference node.
+3. Enter that value in **Rssi expected from a 0dBm transmitter at 1 meter** on every node that will track non-calibrated devices.
+4. For each additional node, compare its reading of the same beacon at the same location and adjust **rxAdj** as described below until its reported RSSI matches the reference node.
+5. If the signal passes through walls or dense materials between rooms, increase the **Factor** slightly (for example, from `2.55` to `3.0`) and test whether calculated distances align better with reality.
+6. Repeat the measurements in a second location to confirm the offsets before rolling the settings out across your deployment.
+
+## Rssi expected from a 0dBm transmitter at 1 meter
+
+This value establishes the reference point for devices that do not broadcast a calibrated `rssi@1m` (for example, many non-beacon wearables). To determine it:
+
+1. Use a beacon transmitting at exactly 0 dBm.
+2. Place the beacon 1 meter away from the ESP32.
+3. Observe the RSSI reading on the Settings page and record the average value.
+4. Enter that number as the reference.
+
+Devices that already advertise `rssi@1m` keep their own calibration; others use this reference plus any additional adjustments below.
+
+## Factor used to account for absorption, reflection, or diffraction
+
+This factor adjusts for walls, furniture, or other environmental obstacles between rooms. Higher numbers assume more attenuation; lower numbers assume minimal obstruction. Increase the factor if reported distances are too small when signals pass through dense materials (brick, concrete, metal framing).
+
+## rxAdj (Receiver Adjustment)
+
+Different ESP32 boards and external antennas can report RSSI differently, even with identical firmware settings. The **rxAdj** value is an offset (in dB) applied to *all* RSSI readings from a node so that mixed hardware stays aligned.
+
+Typical use cases include:
+
+* Balancing a node that uses a high-gain external antenna against nodes with built-in antennas.
+* Normalizing readings between dev boards that ship with slightly different radio front-end tuning.
+
+To tune `rxAdj`:
+
+1. Pick a reference node (leave its `rxAdj` at 0) and place a known beacon at a fixed distance from both the reference and the node you want to adjust.
+2. Compare their reported RSSI values for the same beacon.
+3. On the node that reads stronger, set a **negative** `rxAdj` equal to the difference; on a weaker-reading node, set a **positive** `rxAdj` until both nodes report approximately the same RSSI.
+4. Repeat with a second location to verify consistency, then apply the same offset to nodes that share the same antenna or board type.
+
+Because `rxAdj` is an additive offset, it does not change the relative movement of a device within a single room, but it keeps multi-room trilateration and occupancy decisions fair between nodes with different hardware.
+
+## Forget beacon if not seen for (in milliseconds)
+
+Controls how long a MAC address stays in the internal tracking list. Shorter durations remove stale devices sooner but may cause the same device to be re-added frequently if it only broadcasts occasionally. The default is 300000 ms (5 minutes).
+
+## Calibration tips
+
+* Re-run the reference measurement if you change antennas or enclosure materials.
+* Perform `rxAdj` comparisons with beacons at least a few meters away to avoid near-field effects.
+* When installing multiple nodes in one room, calibrate them together to avoid uneven presence detection at room boundaries.

configuration/settings.md

@@ -37,9 +37,12 @@ This is a beta feature, it is for the usecase where a device fingerprint doesn't
 
 ## Calibration
 
-* Rssi expected from a 0dBm transmitter at 1 meter - This is an average value for your particular base station. In order to figure it out you need a beacon transmitting at exactly 0dBm and your ESP exactly 1 meter away. This value is the base value we use to calculate rss@1m for every beacon that doesn't broadcast a calibrated rssi@1m. (Basically Alt/iBeacons and Eddystones all broadcast a calibrated rssi, everything else uses this w/ a correction factor)
-* Factor used to account for absorption, reflection, or diffraction - An average value that accounts for the amount of "stuff" in between rooms in your house. Use a higher number for dense materials, lower for assuming no walls.
-* Forget beacon if not seen for (in milliseconds) - Specifies how long to retain MAC addresses in the internal tracking list. If a device is not seen within this timeframe, it will be removed from tracking. Setting this value too low may cause unnecessary removal and re-addition of devices. Default: 300000 (5 minutes)
+These settings control how ESPresense interprets signal strength. See the full [Calibration](calibration) guide for detailed steps and examples, including how to use `rxAdj` to balance different antennas or dev boards.
+
+* Rssi expected from a 0dBm transmitter at 1 meter - Reference RSSI for non-calibrated devices.
+* Factor used to account for absorption, reflection, or diffraction - Adjusts for walls and other obstacles.
+* rxAdj (receiver adjustment) - Per-node offset to align RSSI across different antennas or hardware.
+* Forget beacon if not seen for (in milliseconds) - How long to keep idle devices before removing them.
 
 ## Misc