[1/9] doc: Document station Affinities property

Commit Message

James Prestwood Aug. 13, 2024, 3:56 p.m. UTC

This documents new DBus property that expose a bit more control to
how IWD roams.

Setting the affinity on the connected BSS effectively "locks" IWD to
that BSS (except at critical RSSI levels, explained below). This can
be useful for clients that have access to more information about the
environment than IWD. For example, if a client is stationary there
is likely no point in trying to roam until it has moved elsewhere.

Setting the affinity on a BSS (regardless if the connected BSS) will
also cause a modified ranking factor to be applied to the BSS. This
could be used to push IWD to certain BSS's over others. Similar to
above, the affinity ranking factor for a BSS will only be applied if
that BSS's signal is above the crtical roaming threshold.

A new main.conf option would also be added:

[General].CriticalRoamThreshold

This would be the new roam threshold set if the currently connected
BSS is in the Affinities list. If the RSSI continues to drop below
this level IWD will still attempt to roam.
---
 doc/station-api.txt | 19 +++++++++++++++++++
 src/iwd.config.rst  | 20 ++++++++++++++++++++
 2 files changed, 39 insertions(+)

Patch

diff --git a/doc/station-api.txt b/doc/station-api.txt
index 84f1b7bf..c22c57d4 100644
--- a/doc/station-api.txt
+++ b/doc/station-api.txt
@@ -170,6 +170,25 @@  Properties	string State [readonly]
 			BSS the device is currently connected to or to which
 			a connection is in progress.
 
+		ao Affinities [optional]
+
+			Array of net.connman.iwd.BasicServiceSet object paths
+			that will be treated with higher affinity compared to
+			other BSS's. The affinity comes into play in two
+			scenarios:
+
+			1. If the connected BSS is in the Affinities list the
+			   roaming threshold will be lowered to loosly lock IWD
+			   to its current BSS. This prevents IWD from roaming
+			   unless the signal drops below the critical threshold
+			   (i.e. main.conf: [General].CriticalRoamThreshold).
+
+			2. A ranking factor will be applied to all BSS in the
+			   Affinities list while choosing a roaming candidate.
+			   The only exception here is if the BSS's signal
+			   is below the critical roaming threshold.
+			   (i.e. main.conf: [General].CriticalRoamTreshold)
+
 SignalLevelAgent hierarchy
 ==========================
 
diff --git a/src/iwd.config.rst b/src/iwd.config.rst
index d9c94e01..7221c149 100644
--- a/src/iwd.config.rst
+++ b/src/iwd.config.rst
@@ -130,6 +130,26 @@  The group ``[General]`` contains general settings.
        This value can be used to control how aggressively **iwd** roams when
        connected to a 5GHz access point.
 
+   * - CriticalRoamThreshold
+     - Value: rssi dBm value, from -100 to 1, default: **-80**
+
+       The threshold (for 2.4GHz) at which IWD will roam regardless of the
+       affinity set to the current BSS. This is used in two ways:
+
+       1. If the connected BSS has affinity (set in Station's Affinities list)
+          the roam threshold will be lowed to this value and IWD will not
+          attempt to roam (or roam scan) until either the affinity is cleared,
+          or the signal drops below this threshold.
+
+       2. The affinity ranking factor will not be appled if the BSS's signal is
+          below this threshold.
+
+   * - CriticalRoamThreshold5G
+     - Value: rssi dBm value, from -100 to 1, default: **-82**
+
+       This has the same effect as ``CriticalRoamThreshold``, but for the 5GHz
+       band.
+
    * - RoamRetryInterval
      - Value: unsigned int value in seconds (default: **60**)