Update STA steering documentation

Signed-off-by: Filip Matusiak <filip.matusiak@iopsys.eu>

docs/STA-Steering.md

@@ -12,8 +12,12 @@ There're also other UCI parameters that will be used for steering:
 
 ``` shell
 ...
-config controller 'controller'
+config sta_steering
 ...
+        option steer_module 'rcpi'
+        # the name must match the /usr/lib/mapcontroller/<name>.so plugin file
+        option enabled '1'
+        # load this plugin if 1, skip loading otherwise
         option enable_sta_steer '1'
         # enable steering of (non-bsta) client stations
         option enable_bsta_steer '0'
@@ -22,12 +26,14 @@ config controller 'controller'
         # use rcpi from beacon metrics to decide on best bssid to steer to
         option use_usta_metrics '0'
         # use ul_rcpi measured as an unassociated sta as additional trigger for steering (experimental)
-        list steer_module 'rcpi'
-        # the name must match the /usr/lib/mapcontroller/<name>.so plugin file
+        option bandsteer '0'
+		# if 1 then steering from 5g/6g to 2.4g is alowed
+        option diffsnr '8'
+		# minimal RSSI diff (dest RSSI - src RSSI) for the BTM to kick in (default 8dB)
 ...
 ```
 
-Please note, that the steer_module must be present in the system, that is the map-controller is expecting to find rcpi plugin in /usr/lib/mapcontroller/rcpi.so. Otherwise it will not be able to load the steering decision plugin, and therefore the steering will be effectively disabled.
+Please note, that the steer_module must be present in the system, that is the map-controller is expecting to find rcpi plugin in /usr/lib/mapcontroller/rcpi.so. Otherwise it will not be able to load the steering decision plugin, and therefore the steering will be effectively disabled. More than one plugin can be present in system and in config file - each with own set of steering parameters, first one will be used for steering.
 
 **/etc/config/mapcontroller**
 
@@ -37,6 +43,7 @@ config radio 'radio_44d4376af4cf'
         option agent_id '46:d4:37:6a:f4:c0'  
         option macaddr '44:d4:37:6a:f4:cf'   
         option band '5'
+        option report_rcpi_threshold '96'
         option rcpi_threshold '86'
 ...
 ```
@@ -48,17 +55,19 @@ This will be synchronized to mapagents in the mesh – radio sections in /etc/co
 ``` shell
 ...
 config wifi-radio
-	...
+...
         option util_threshold '0'
         # radio utilization - if non-zero, then checked every 5 seconds
         # it may cause sending of associated sta link metrics to the controller
         # mandate steering may be trigerred by controller in handler of the above
-        ...
-        option rcpi_threshold '86'
-        # defaults to 130 (if unset), checked every 5 seconds
+...
+        option report_rcpi_threshold '96'
         # going below threshold value will trigger sending of associated sta link metrics to the controller
         # mandate steering may be trigerred by controller in handler of the above
-	...
+...
+        option rcpi_threshold '86'
+		# steer once ul rcpi goes below this threshold, providing there's enough bcn metrics data available
+...
         option include_sta_metric '1'
         # additional trigger point on top of the previous two
         # notify controller on current link metrics (send link metrics) along the AP metrics response
@@ -71,14 +80,16 @@ In case the rcpi_threshold is not set explicitly in configuration file it will d
 #define CONFIG_DEFAULT_RCPI_TH_5G 86
 #define CONFIG_DEFAULT_RCPI_TH_2G 70
 
+In case the report_rcpi_threshold is not set explicitly in configuration file it will default to:
+**report_rcpi_threshold = rcpi_threshold + 10**
 
 ## Working functionality (automatic beacon metrcis based BTM steering)
 
 Controller initiated mandate steering is now working as follows:
 
-Once the STA – AP rcpi goes below given value, map-agent sends the Associated STA Link Metrics Response to the map-controller. This in turn will cause map-controller to send beacon metrics request for given STA on all operating classes/channels of nodes operating in the mesh and SSID value set to current network. After some time (depends on number of opclass/channel pairs) – the beacon metrics results will be parsed. Once there’s a better (at least 10 diffsnr - difference in RSSI) BSS found for given STA, controller will try to to move STA to that BSS using BTM request.
+Once the STA – AP rcpi goes below given value, map-agent sends the Associated STA Link Metrics Response to the map-controller. This in turn will cause map-controller to send beacon metrics request for given STA on all operating classes/channels of nodes operating in the mesh and SSID value set to current network. After some time (depends on number of opclass/channel pairs) – the beacon metrics results will be parsed. Once there’s a better (diffsnr of at least 8dB is a default) BSS found for given STA, controller will try to to move STA to that BSS using BTM request.
 
-Depending on the settings there'll be more or less frequent checks done by the controller. - Frequency of the checks depends on the frequency of the associated sta link metrics responses received from the nodes, which depends on the settings as explained earlier (util_threshold, rcpi_threshold, include_sta_metric). Controller will check if RCPI goes below the reporting threshold. If so, then controller will request for beacon metrics and/or unassociated STA link metrics for given client. After some time it will then compare current RCPI of that given station with the values obtained in metrics and only try to (BTM) steer that station if there's a better candidate found. - The delta RCPI of at least 8 is required.
+Depending on the settings there'll be more or less frequent checks done by the controller. - Frequency of the checks depends on the frequency of the associated sta link metrics responses received from the nodes, which depends on the settings as explained earlier (util_threshold, report_rcpi_threshold, rcpi_threshold, include_sta_metric). Controller will check if RCPI goes below the reporting threshold. If so, then controller will request for beacon metrics and/or unassociated STA link metrics for given client. After some time it will then compare current RCPI of that given station with the values obtained in metrics and only try to (BTM) steer that station if there's a better candidate found. - The delta RCPI of at least 8 is required (difference in beacon metrics RCPI of source and target). Additionally the current uplink RCPI will be always compared with rcpi_threshold in the plugin, and steering will not take place if it's above that trigger.
 
 ## Unassociated STA link metrics (experimental)
 Additionally one can try to use unassociated STA link metrics on top or instead of beacon metrics for getting of the (uplink) rcpi of given STA, for that one must set following in map-controller config
@@ -86,7 +97,8 @@ Additionally one can try to use unassociated STA link metrics on top or instead
 **/etc/config/mapcontroller**
 
 ``` shell
-option use_usta_metrics '1'
+config sta_steering
+	option use_usta_metrics '1'
 ```
 
 This will enable unassociated STA link metrics as an additional trigger for mandate steering.
@@ -110,16 +122,17 @@ config node 'node_46d4376af4c0'
 Removing STA MAC from the list will result in immediate allowing of the STA to be (BTM) steered again.
 
 ## RCPI plugin
-The plugin is used for separating steering decision algorithm from the steering code itself. Current example implementation is using diffsnr and rcpi_threshold values (hardcoded in map-controller, but to be passed as additional parameters in the future) in order for the map-controller rcpi plugin to decide if there’s a better bssid found in per-STA measurements list.
+The plugin is used for separating steering decision algorithm from the steering code itself. Current example implementation is using diffsnr and rcpi_threshold values in order for the map-controller rcpi plugin to decide if there’s a better bssid found in per-STA measurements list.
 The source for the default rcpi plugin can be found in map-controller source under plugins/steer/rcpi. If one wants to use their own decision algorithm they need to create new directory under plugins/steer/<plugin name> and update appropriate Makefiles.
 
 ## Band steer
-There’s an additional option in controller section of map-controller config
+There’s an additional option in sta_steering section of map-controller config
 
 **(/etc/config/mapcontroller)**
 
 ``` shell
-option bandsteer ‘1’
+config sta_steering
+	option bandsteer ‘1’
 ```
 
 This option is also passed down to rcpi plugin. If set then rcpi plugin will allow for steering between bands (from 2.4 to 5 and from 5 to 2.4), basing its decision only on the difference in rssi. If not set then only steering across BSSs operating on current band will be allowed.
@@ -160,20 +173,20 @@ ubus call map.controller bcn_metrics_resp '{"sta":"e0:d4:e8:79:c4:ee"}
 
 ## Known issues & limitations
 
-- The rssi delta of 8dB ('diffsnr') is currently hardcoded.
 - report_rcpi_threshold & rcpi_threshold are set separately per radio in controller config and can only be set after succesfull onboarding.
 - hysteresis parameter is not implemented.
 - There's no initial channel scan - independent channel scan must be executed on each node.
   i.e. `ubus call wifi.radio.wl0 list_neighbor` must include target (to:) bss when run on src (from:) node
 One shall set the
 ``` shell
-option initial_channel_scan ‘1’
+config controller 'controller'
+	option initial_channel_scan ‘1’
 ```
 in controller section of the controller config (/etc/config/mapcontroller) in order for the BTM steering to work robustly all the times.
 Otherwise the neighbor_list on target interface may be empty, causing the BTM steering to that given BSSID to fail by ESL (“bssid not on neighbor list” type of error).
 We’re currently working on removal of that check in ESL, so that neighbor_list can be empty on given interface (ubus call wifi.ap.wlX list_neighbor), as we already know the neighbors in map. We’ll then provide all the necessary neighbor data directly from the map daemons (bssid, channel, opclass, phy & bssid_info) – without depending on the channel scan functionality that would normally cause the neighbor list in wifi to be filled in.
 - Only beacon metrics that were obtained after steering request sent are being used as steering data base. Others are marked 'stale'.
-- One must set RCPI (report_rcpi_threshold) using /etc/config/mapcontroller separately for each device & radio.
+- One must set RCPI (report_rcpi_threshold & rcpi_threshold) using /etc/config/mapcontroller separately for each device & radio.
 - One must remember to set up following configuration in controller, as it's not there by default:
 ``` shell
   list steer_module 'rcpi'
@@ -251,26 +264,63 @@ if ((b->rcpi - s->best->rcpi) > sctrl->diffsnr)
     return 0;
 ```
 
-Functions where the conditions for reporting a probable STA steering candidate is set
-- We only configure bandsteer (allow steering to another band) via config for now.
-- The RCPI we use in config is only used for STA Link trigger in agents, the rcpi_threshold is however not directly used in example plugin code as of now.
-- diffsnr is hardcoded to 10, not set by config yet.
+Functions for setting reporting conditions
+
+Limitations:
+- Currently it's possible to configure bandsteer (allow steering to another band) and diffsnr via config.
+- The RCPI we use in config is only used for STA Link trigger in agents (report_rcpi_threshold).
 - these are the only configurable checks we have in plugin:
-	a. if (b->rcpi - s->best->rcpi) > sctrl->diffsnr)
-	b. if (sctrl->bandsteer)
+	a. if (current_bss_rcpi >= sctrl->rcpi_threshold)
+	don't try to steer until RCPI goes below some threshold
+	b. if (b->rcpi > s->best->rcpi)
+	find out best BSS in the mesh based on the RCPI
+	c. if (sctrl->bandsteer)
+	allow/disallow steering to lower band BSS
+	d. if (s->best->rcpi - current_bss_rcpi < sctrl->diffsnr)
+	steer only if the best found BSS has RCPI good enough
+	e. if (!memcmp(s->best->bssid, s->s->bssid, 6))
+	do not steer to current BSS
+
 
 **src/cntlr.c**
 ``` C
 void run_controller(void)
 
-if (!list_empty(&c->sclist)) {
+	if (!list_empty(&c->sclist)) {
+		cntlr_assign_steer_module_default(c);
+```
+
+``` C
+static void cntlr_bcn_metrics_parse(struct uloop_timeout *t)
+
+	if (c->cfg.enable_sta_steer) {
+        cntlr_configure_steer(c, s);
+        cntlr_try_steer_sta(c, s);
+    }
+```
+
+``` C
+static void cntlr_configure_steer(struct controller *c, struct sta *s)
+
+    /* RCPI threshold */
+    if (rp->rcpi_threshold > 0)
+        scfg.rcpi_threshold = rp->rcpi_threshold;
+    else
+        scfg.rcpi_threshold = DEFAULT_RCPI_THRESHOLD; /* 86 */
+
+    scfg.rcpi_hysteresis = 5; /* TODO: unused */
+
+    /* diffsnr */
+    if (c->cfg.diffsnr > 0)
+        scfg.rcpi_diffsnr = c->cfg.diffsnr;
+    else
+        scfg.rcpi_diffsnr = DEFAULT_RCPI_DIFFSNR; /* 8dB */
+
+    /* bandsteer */
+    scfg.bandsteer = c->cfg.bandsteer; /* default disabled */
 
-        scfg.rcpi_threshold = 100; /* unused! */
-        scfg.rcpi_hysteresis = 5; /* unused! */
-        scfg.rcpi_diffsnr = 10; /* hardcoded */
-        scfg.bandsteer = c->cfg.bandsteer;
+    cntlr_configure_steer_module(c, &scfg);
 
-        cntlr_configure_steer_module(c, &scfg);
 ```
 
 **src/steer_module.c**