diff --git a/README.md b/README.md
index d5bea69793de14b667669e08673a1a9d98dd7bdd..f7b2ba7859a78bcb8204e4dc92b862b303307b2a 100644
--- a/README.md
+++ b/README.md
@@ -5,13 +5,19 @@
## Introduction
-This package provides the `mapcontroller` daemon, which is responsible for
-distributing wireless credentials, vlan configuration and more.
+This package provides the mapcontroller daemon, which implements the WiFi
+Alliances Easymesh Controller component.
## Overview
This README will show how to properly setup the mapcontroller configuration file
-and trigger mapcontroller functionality.
+and explain some features of map-controller:
+
+* Policy Configuration
+* AP-Autoconfig Renew
+* Channel Planning
+* STA Steering
+* Dynamic Controller Sync
## UCI Configuration
@@ -29,196 +35,190 @@ config controller 'controller'
option use_usta_metrics '0'
option primary_vid '1'
option primary_pcp '0'
-
-config interface 'lan'
- option proto 'dhcp'
+ option allow_bgdfs '0'
+ option channel_plan '0'
config ap
option band '5'
- option ssid 'MAP-EC6C9A52B027-5GHz'
+ option ssid 'iopsysWrt-021000000001'
option encryption 'sae-mixed'
+ option key '7NTx-APvX-pba7-tvd7'
option vid '1'
option type 'fronthaul'
- option network 'lan'
- option key '7NTx-APvX-pba7-tvd7'
config ap
option band '2'
- option ssid 'MAP-EC6C9A52B027-2.4GHz'
+ option ssid 'iopsysWrt-021000000001'
option encryption 'sae-mixed'
+ option key '7NTx-APvX-pba7-tvd7'
option vid '1'
option type 'fronthaul'
- option network 'lan'
- option key '7NTx-APvX-pba7-tvd7'
config ap
option band '5'
- option ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option ssid 'MAP-021000000001-BH-5GHz'
option encryption 'sae'
option type 'backhaul'
option vid '1'
- option network 'lan'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
+ option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
config ap
option band '2'
- option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option ssid 'MAP-021000000001-BH-2.4GHz'
option encryption 'sae'
option type 'backhaul'
list disallow_bsta '0'
option vid '1'
- option network 'lan'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
-
-config policy 'policy'
- list steer_exclude '00:11:22:33:44:55'
- list steer_exclude_btm '00:aa:bb:cc:dd:ee'
- option steer_policy '2'
- option util_threshold '200'
- option rcpi_threshold '30'
- option report_scan '0'
- option report_sta_assocfails '1'
- option report_sta_assocfails_rate '2'
- option report_metric_periodic '0'
- option report_rcpi_threshold '0'
- option report_util_threshold '0'
- option rcpi_hysteresis_margin '0'
- option include_sta_stats '0'
- option include_sta_metric '0'
- option disallow_bsta_p1 '0'
- option disallow_bsta_p2 '0'
+ option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
```
-The important part of this configuration file is to properly setup the wireless
-credentials.
### Credentials
-The section `ap` holds the wireless credentials that will be passed to agents in
+The `ap` sections are access point credentials that will be passed to agents in
the network, which will setup the local wireless configuration accordingly.
-
### Fronthaul Credentials
-Fronthaul AP credentials are identified by `type 'fronthaul'`. In the wireless
-uci configuration, these are mapped to the option `multi_ap '2'`, which will
-be the APs that regular clients connect to.
+Fronthaul AP credentials are identified by the human readable option
+`type 'fronthaul'`. Once propagated to agents, these interfaces are written with
+`option multi_ap '2'` to the wireless configuration.
-As such, the following mapagent sections will be correspodning to the respective
-wireless sections:
+As such, the following mapcontroller sections will generate to the respective
+wireless sections, after handled by an agent:
```
config ap
option band '5'
- option ssid 'MAP-EC6C9A52B027-5GHz'
+ option ssid 'iopsysWrt-021000000001'
option encryption 'sae-mixed'
+ option key '7NTx-APvX-pba7-tvd7'
option vid '1'
option type 'fronthaul'
- option network 'lan'
- option key '7NTx-APvX-pba7-tvd7'
config ap
option band '2'
- option ssid 'MAP-EC6C9A52B027-2.4GHz'
+ option ssid 'iopsysWrt-021000000001'
option encryption 'sae-mixed'
+ option key '7NTx-APvX-pba7-tvd7'
option vid '1'
option type 'fronthaul'
- option network 'lan'
- option key '7NTx-APvX-pba7-tvd7'
+
```
```
-config wifi-iface 'wl1_ap'
- option ifname 'wl1'
+config wifi-iface 'default_wl0'
+ option device 'wl0'
option network 'lan'
- option ssid 'MAP-EC6C9A52B027-5GHz'
- option key '7NTx-APvX-pba7-tvd7'
- option encryption 'sae-mixed+aes'
+ option ifname 'wl0'
option mode 'ap'
- option device 'wl1'
- option multi_ap '2'
- option ieee80211k '1'
- option ieee80211v '1'
- option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
option wps '1'
option wps_pushbutton '1'
- option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-5GHz'
- option multi_ap_backhaul_key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
-
-config wifi-iface 'wl0_ap'
- option ifname 'wl0'
- option network 'lan'
- option ssid 'MAP-EC6C9A52B027-2.4GHz'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
+ option multi_ap '2'
+ option ssid 'iopsysWrt-021000000001'
option key '7NTx-APvX-pba7-tvd7'
option encryption 'sae-mixed+aes'
+ option ieee80211w '1'
+ option start_disabled '0'
+ option multicast_to_unicast '1'
+ option isolate '0'
+ option multi_ap_backhaul_ssid 'MAP-021000000001-BH-5GHz'
+ option multi_ap_backhaul_key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
+
+config wifi-iface 'default_wl1'
+ option device 'wl1'
+ option network 'lan'
+ option ifname 'wl1'
option mode 'ap'
- option device 'wl0'
- option multi_ap '2'
- option ieee80211k '1'
- option ieee80211v '1'
- option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
option wps '1'
option wps_pushbutton '1'
- option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
- option multi_ap_backhaul_key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
+ option multi_ap '2'
+ option ssid 'iopsysWrt-021000000001'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'sae-mixed+aes'
+ option ieee80211w '1'
+ option start_disabled '0'
+ option multicast_to_unicast '1'
+ option isolate '0'
+ option multi_ap_backhaul_ssid 'MAP-021000000001-BH-2.4GHz'
+ option multi_ap_backhaul_key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
```
### Backhaul Credentials
-Backhaul AP credentials are identified by `type 'backhaul'`. In the wireless
-uci configuration, these are mapped to the option `multi_ap '1'`, which will
-be the APs that backhaul STA clients will connect to, in a Multi-AP environment.
+Backhaul AP credentials are identified by `type 'backhaul'`. Once propagated to
+agents, these interfaces are written with `option multi_ap '1'` to the wireless
+configuration. These will be the APs that backhaul stations will connect to,
+in a Multi-AP environment.
-The following mapagent sections will be correspodning to the respective
-wireless sections:
+The following mapcontroller sections will be corresponding to the respective
+wireless sections, after handled by an agent:
```
config ap
- option band '5'
- option ssid 'MAP-EC6C9A52B027-BH-5GHz'
- option encryption 'sae'
- option type 'backhaul'
+ option band '2'
+ option ssid 'iopsysWrt-021000000001'
+ option encryption 'sae-mixed'
+ option key '7NTx-APvX-pba7-tvd7'
option vid '1'
- option network 'lan'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
+ option type 'fronthaul'
config ap
- option band '2'
- option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option band '5'
+ option ssid 'MAP-021000000001-BH-5GHz'
option encryption 'sae'
option type 'backhaul'
- list disallow_bsta '0'
option vid '1'
- option network 'lan'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
+ option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
+
```
```
-config wifi-iface 'wl1_1_ap'
- option ifname 'wl1.1'
- option network 'lan'
- option ssid 'MAP-EC6C9A52B027-BH-5GHz'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
- option encryption 'sae+aes'
- option mode 'ap'
+config wifi-iface 'default_wl1_1'
option device 'wl1'
+ option mode 'ap'
+ option ifname 'wl1.1'
option multi_ap '1'
+ option network 'lan'
+ option hidden '1'
+ option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
option ieee80211k '1'
option ieee80211v '1'
- option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
-
-config wifi-iface 'wl0_1_ap'
- option ifname 'wl0.1'
- option network 'lan'
- option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
+ option ssid 'MAP-021000000001-BH-2.4GHz'
+ option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
option encryption 'sae+aes'
- option mode 'ap'
+ option ieee80211w '2'
+ option start_disabled '0'
+ option wps_device_type '6-0050f204-1'
+ option multicast_to_unicast '0'
+ option isolate '0'
+
+config wifi-iface 'default_wl0_1'
option device 'wl0'
+ option mode 'ap'
+ option ifname 'wl0.1'
option multi_ap '1'
+ option network 'lan'
+ option hidden '1'
+ option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
option ieee80211k '1'
option ieee80211v '1'
- option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
+ option ssid 'MAP-021000000001-BH-5GHz'
+ option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
+ option encryption 'sae+aes'
+ option ieee80211w '2'
+ option start_disabled '0'
+ option wps_device_type '6-0050f204-1'
+ option multicast_to_unicast '0'
+ option isolate '0'
```
### Combined Front/Back
@@ -228,62 +228,261 @@ section with the option `type 'combined'` shall be provided:
```
config ap
- option band '5'
- option ssid 'MAP-EC6C9A52B027-COMBINED-5GHz'
- option encryption 'sae'
- option type 'combined'
+ option band '2'
+ option ssid 'iopsysWrt-021000000001'
+ option encryption 'sae-mixed'
+ option key '7NTx-APvX-pba7-tvd7'
option vid '1'
- option network 'lan'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
+ option type 'combined'
```
In turn map-agent will create the interface with the option `multi_ap '3'`,
meaning combined fronthaul/backhaul interface.
```
-config wifi-iface 'wl0_ap'
- option ifname 'wl0'
+config wifi-iface 'default_wl0'
+ option device 'wl0'
option network 'lan'
- option ssid 'MAP-EC6C9A52B027-COMBINED-5GHz'
- option key '0138a5f1b2bea4941be88001a55954ca228629eeaf51d66656893791a60bfed'
- option encryption 'sae+aes'
+ option ifname 'wl0'
option mode 'ap'
- option device 'wl0'
- option multi_ap '3'
- option ieee80211k '1'
- option ieee80211v '1'
- option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
option wps '1'
option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
+ option multi_ap '3'
+ option ssid 'iopsysWrt-021000000001'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'sae-mixed+aes'
+ option ieee80211w '1'
+ option start_disabled '0'
+ option multicast_to_unicast '1'
+ option isolate '0'
```
+### Policy Configuration
+
+Agent, and agent radio specific configuration can be set from mapcontroller
+configuration, and propagated via Multi-AP Policy Configuration Request CMDU.
+
+#### Agent Specific Configuration
+
+Whenever the mapcontroller discovers an agent (via AP-Autoconfig Search
+messages), it will add a skeleton configuration sections with the bare minimum,
+assuming default values for the rest:
+
+```
+config node 'node_ee6c9a52b027'
+ option agent_id 'ee:6c:9a:52:b0:27'
+# the following values are not explicitly set and the default values are used
+ option backhaul_ul_macaddr '00:00:00:00:00:00'
+ option backhaul_dl_macaddr '00:00:00:00:00:00'
+ option backhaul_type 'none'
+ option primary_vid '1'
+ option primary_pcp '0'
+ option report_sta_assocfails '0'
+ option report_sta_assocfails_rate '0'
+ option report_metric_periodic '0'
+ option report_scan '0'
+ option steer_exclude '0'
+ option steer_exclude_btm '0'
+ option steer_disallow '0'
+ option coordinated_cac '0'
+ option traffic_separation '0'
+ option sta_steer '0'
+```
+
+If these values are modified, a `SIGHUP` can be triggered to mapcontroller and
+the options will be propagated to the agent(s).
+
+#### Radio Specific Configuration
+
+When an agent is discovered it will proceed to complete AP-Autoconfiguration.
+During AP-Autoconfiguration, each radio on the agent will send an
+AP-Autoconfiguration WSC (M1), these radios will have their own sections created
+in the mapcontroller configuration with necessary policies. Each section maps to
+an agent section by `agent_id`.
+
+```
+config radio 'radio_ec6c9a52acb9'
+ option agent_id 'ee:6c:9a:52:ac:b7'
+ option macaddr 'ec:6c:9a:52:ac:b9'
+ option band '5'
+# the following values are not explicitly set and the default values are used
+ option steer_policy '0'
+ option util_threshold '0'
+ option rcpi_threshold '86' # 70 for 2.4GHz band
+ option report_rcpi_threshold '96' # 80 for 2.4GHz band
+ option report_util_threshold '0'
+ option report_rcpi_hysteresis_margin '0'
+ option include_sta_stats '1'
+ option include_sta_metric '1'
+```
+
+If these values are modified, a `SIGHUP` can be triggered to mapcontroller and
+the options will be propagated to the agent(s).
+
## AP-Autoconfig Renew
Autoconfig Renew will trigger all agents to be reconfigured with updated
credentials.
-### Prerequisites
+### Trigger
+
+Mapcontroller will re-read the mapcontroller credentials and policies upon
+receiving `SIGHUP`. In order to trigger AP-Autoconfig Renew the mapcontroller
+credentials loaded in memory at runtime, must differ from the ones in the
+config, causing mapcontroller to generate a AP-Autoconfig Renew for all agents
+to be reconfigured.
+
+It should be noted that AP-Autoconfig Renew can be triggered by mapcontroller
+on its own, as it may reload its configuration at runtime, based on events.
+
+## Channel Planning
+
+Map-controller supports channel planning in the form of channel selection, and
+background CAC (if supported) to clear channels. Each locked behind their own
+UCI configuration options.
+
+Additionally, there are ubus methods available to do it manually:
+
+* ubus call map.controller scan '{"agent":"46:d4:37:71:be:80", "radio":["44:d4:37:71:be:8f"], "channel":[[]]}' - best call before channel_pref – to get fresh preference counters
+* ubus call map.controller channel_pref – get/update channel preferences from all nodes
+* ubus call map.controller channel_cleanup – run background CAC (preCAC) on nodes if required
+* ubus call map.controller channel_recalc – base on channel preference score choose best channel for each node and radio and request node to switch to this channel
+
+### Channel Selection
+
+Map-controller will send a Channel Preference Query to its agents and collect
+the results. Whenever the channel selection periodic timer is hit,
+map-controller will calculate the best channel for the network.
+
+This feature is enabled by the UCI configuration:
+```
+config controller 'controller'
+ option channel_plan '0'
+```
+
+The `channel_plan` value corresponds to the timeout in seconds at which channel
+planning will be triggered. Any value less than 180 will be treated as invalid
+and default to 3600 * 3 seconds (three hours). Setting to 0 means disabled.
+
+Do note that this feature will not kick in for any radio which has a downstream
+agent wirelessly connected.
+
+### Background DFS
+
+If enabled, map-controller will periodically trigger background dfs in each
+agent that supports it, based on bandwidth, channel and DFS availability.
+
+This feature is enabled by the UCI configuration:
+```
+config controller 'controller'
+ option allow_bgdfs '0'
+```
+
+The `allow_bgdfs` value corresponds to the timeout in seconds at which
+background DFS will be triggered. Any value less than 120 will be treated as
+invalid and default to 120 seconds (two minutes). Setting to 0 means disabled.
+
+
+## STA Steering
+
+Map-controller initiated mandate steering based on beacon measurement is
+supported. For STA to be able to be steered its drivers must support 802.11k
+(RRM for beacon measurements) and 802.11v.
+
+To enable STA steering feature one must set following in map-controller UCI
+config:
+```
+config controller 'controller'
+ option enable_sta_steer '1'
+ option use_bcn_metrics '1'
+```
+
+The steering decision is based upon drop of the STA RCPI below certain
+threshold, which can be modified per radio via UCI config:
+
+```
+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 rcpi_threshold '86'
+ option report_rcpi_threshold '96'
+```
+
+In case the rcpi_threshold is not set it defaults in code to 86 for 5GHz and
+70 for 2.4GHz.
+
+Once the signal strength goes below the report_rcpi_threshold it’ll trigger
+link metrics response from agent to controller, causing controller to send
+beacon metrics request for the given STA on all operating classes/channels of
+nodes in the mesh. The beacon metrics results will be parsed and if there’s a
+better (at least 10dB difference in RSSI) BSS found for given STA, controller
+will try to to move STA to that BSS using BTM.
+
+### Steer Exclude
+
+There are two steering disallowed lists maintained in the controller:
+- steer_exclude (per node) – exclude STA from steering completely
+- steer_exclude_btm (per node) – do not allow to steer of the STA using BTM
+steering (but association control based steering will be possible in the future – once implemented).
+
+To put the STA on either of two lists one must just add a list entry per node in
+mapcontroller UCI config as in example:
+
+```
+config node 'node_46d4376af4c0'
+ option agent_id '46:d4:37:6a:f4:c0'
+ list steer_exclude 'e0:d4:e8:79:c4:ee'
+ list steer_exclude 'e0:d4:e8:79:c4:11'
+ list steer_exclude_btm 'aa:bb:cc:dd:ee:ff'
+```
+Removing STA MAC from the list will result in immediate allowing of the STA to
+be (BTM) steered again.
+
+
+## Dynamic Controller Sync
+
+In a mesh where the controller node may change and taken by any device in the
+network, it is important to keep all mapcontroller configs in-sync. If not, the
+credentials, polices etc. may change upon a new device taking the controller
+role resulting in disruption for the clients in the network. While the logic for
+this primarily resides in the map-agent, it does have to be compile-time
+selected into mapcontroller in order for it to be supported.
-* Mapcontroller must be running
+This compile-time flag for map-controller is
+`CONTROLLER_SYNC_DYNAMIC_CNTLR_CONFIG`.
-### How to Trigger
+Additionally, in ieee1905 and map-agent:
+* map-agent - `AGENT_SYNC_DYNAMIC_CNTLR_CONFIG`
+* ieee1905 - `MULTIAP_DYNAMIC_CNTLR_SYNC_CONFIG`
-Mapcontroller will re-read the mapcontroller network credentials (and vlan
-section) upon receiving `SIGHUP`. In order to trigger AP-Autoconfig Renew the
-mapcontroller credentials loaded in memory at runtime, must differ from what
-are in its config, causing mapcontroller to generate a AP-Autoconfig Renew for
-all agents to be reconfigured.
+## UBUS APIs
-## uBus
+Map-controller offers a variety of UBUS APIs, most of them map to CMDU request
+messages. The exceptions to this are:
+* `status` - Shows mapcontrollers view of the network and some stored data for
+each agent
+* `timers` - Will show time remaining till certain internal timers are triggered
+(so far only channel planning timers are added)
+* `steer_summary` and `steer_history` - Maps to TR-181 data model.
```
-root@iopsys:~# ubus -v list map.controller
-'map.controller' @601d80a0
+root@iopsys-021000000001:~# ubus -v list map.controller
+'map.controller' @35515cda
"status":{}
+ "timers":{}
+ "steer_summary":{"sta":"String"}
+ "steer_history":{"sta":"String"}
"ap_caps":{"agent":"String"}
"sta_caps":{"agent":"String","sta":"String","bssid":"String"}
"channel_pref":{"agent":"String"}
+ "channel_recalc":{"agent":"String","skip_dfs":"Boolean"}
+ "channel_cleanup":{"agent":"String"}
"bk_steer":{"agent":"String","bssid":"String","channel":"Integer","op_class":"Integer","bksta":"String"}
"agent_policy":{"agent":"String","radiolist":"Array","bsslist":"Array"}
"channel_select":{"agent":"String","radio_id":"String","class_id":"Integer","channel":"Array","preference":"Integer","transmit_power":"Integer"}
@@ -300,4 +499,5 @@ root@iopsys:~# ubus -v list map.controller
"cac_req":{"agent":"String","radiolist":"Array"}
"cac_term":{"agent":"String","radiolist":"Array"}
"higher_layer_data":{"agent":"String","protocol":"Integer","data":"String"}
+ "send_combined_metrics":{"agent":"String","bssid":"String"}
```