[RFC] doc: Document new BSS affinity method calls

Commit Message

James Prestwood July 23, 2024, 2:45 p.m. UTC

This documents new DBus methods that expose a bit more control to how
IWD roams. The new methods are:

SetConnectedBssAffinity()
UnsetConnectedBssAffinity()

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.

A new main.conf option would also be added:

[General].CriticalRoamThreshold

This would be the new roam threshold set after
SetConnectedBssAffinity() is called. If the RSSI continues to drop
below this level IWD would (attempt to) roam.
---
 doc/station-api.txt | 22 ++++++++++++++++++++++
 src/iwd.config.rst  |  8 ++++++++
 2 files changed, 30 insertions(+)

Patch

diff --git a/doc/station-api.txt b/doc/station-api.txt
index 05dd137e..3dc2376b 100644
--- a/doc/station-api.txt
+++ b/doc/station-api.txt
@@ -135,6 +135,28 @@  Methods		void Scan()
 			Possible Errors: [service].Error.InvalidArguments
 					 [service].Error.NotFound
 
+		void SetConnectedBssAffinity()
+
+			Sets a high affinity/preference to the currently
+			connected BSS. Specifically, calling this will reduce
+			the roam threshold down to a critical level set by
+			[General].CriticalRoamThreshold. This effectively locks
+			the client onto the current BSS unless the signal
+			quality becomes extremely poor.
+
+			If IWD roams or disconnects the affinity will be reset.
+
+			Possible Errors: net.connman.iwd.NotConnected
+
+		void UnsetConnectedBssAffinity()
+
+			Unset a prior call to SetConnectedBssAffinity(). This
+			moves the roaming threshold back up to the default level
+			(RoamThreshold/RoamThreshold5GHz).
+
+			Possible Errors: net.connman.iwd.NotConnected
+					 net.connman.iwd.NotConfigured
+
 Properties	string State [readonly]
 
 			Reflects the general network connection state.  One of:
diff --git a/src/iwd.config.rst b/src/iwd.config.rst
index e31b1ffa..232337ae 100644
--- a/src/iwd.config.rst
+++ b/src/iwd.config.rst
@@ -130,6 +130,14 @@  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: **-82**
+
+       The threshold at which IWD will roam regardless of the affinity set to
+       the current BSS. This is only used if the SetConnectedBssAffinity() DBus
+       method is called, at which point this value becomes the new roam
+       threshold.
+
    * - RoamRetryInterval
      - Value: unsigned int value in seconds (default: **60**)