diff --git a/README.md b/README.md
index 70148593fc5095169b486a69903f1942fa5229f1..21b095d2c5731beaaa6f68f7e8a29e291c181027 100644
--- a/README.md
+++ b/README.md
@@ -1,86 +1,670 @@
# MAP Agent
-Multi-AP Agent
+[Map-agent](https://dev.iopsys.eu/iopsys/map-controller)
+
+
+## Introduction
+
+This package provides the `mapagent` daemon, which is responsible for
+configuring wireless credentials, vlan etc.
+
+Today map-agent is bridge centered, and it is expected that there is a 'main'
+bridge which holds the uplink interface, as specified by `al_bridge` in the
+mapagent config.
+
+## Overview
+
+This README will show how to properly setup the mapagent configuration file
+and explain some key features of map-agent.
+
+## UCI Configuration
+
+A default configuration file may look as such:
+
+```
+config agent 'agent'
+ option enabled '1'
+ option debug '0'
+ option profile '2'
+ option brcm_setup '1'
+ option al_bridge 'br-lan'
+ option netdev 'wl'
+
+config controller_select
+ option local '0'
+ option id 'auto'
+ option probe_int '20'
+ option retry_int '15'
+ option autostart '1'
+
+config wifi-radio
+ option device 'wl0'
+ option band '5'
+
+config wifi-radio
+ option device 'wl1'
+ option band '2'
+
+
+config fh-iface
+ option ifname 'wl0.2'
+ option band '5'
+ option device 'wl0'
+
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+
+config bk-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+
+config fh-iface
+ option ifname 'wl1.1'
+ option band '2'
+ option device 'wl1'
+
+config bk-iface
+ option ifname 'wl1'
+ option band '2'
+ option device 'wl1'
+```
+
+The important part of this configuration file is to properly align the
+wireless configuration with the mapagent configuration for the default setup.
+
+Mapagent expects all interfaces that are present in its config to be up and
+running when mapagent is started as these interfaces are managed by mapagent.
+
+Interface which are not included in the config will never be torn down or
+modified by mapagent, thus if desired, interfaces may left out of multi-ap
+management
+
+The above example of a mapagent config would map properly against the
+following wireless configuration file:
+
+```
+config wifi-device 'wl0'
+ option type 'mac80211'
+ option channel '36'
+ option hwmode '11a'
+ option country 'DE'
+ option htmode 'HE80'
+ option apsta '1'
+ option phy 'phy0'
+
+config wifi-iface 'default_sta_wl0'
+ option device 'wl0'
+ option mode 'sta'
+ option ifname 'wl0'
+ option multi_ap '1'
+ option disabled '0'
+
+config wifi-iface 'default_wl0'
+ option device 'wl0'
+ option network 'lan'
+ option ifname 'wl0.1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-44D4376AF7F0-5GHz'
+ option encryption 'psk2'
+ option key '12345678'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+ option multi_ap_backhaul_ssid 'iopsysWrt-BACKHAUL-5GHz'
+ option multi_ap_backhaul_key '12345678BACKHAUL'
+
+config wifi-iface 'default_wl0'
+ option device 'wl0'
+ option network 'lan'
+ option ifname 'wl0.1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-BACKHAUL-5GHz'
+ option encryption 'psk2'
+ option key '12345678BACKHAUL'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '1'
+
+config wifi-device 'wl1'
+ option type 'mac80211'
+ option channel '11'
+ option hwmode '11g'
+ option country 'DE'
+ option htmode 'HE20'
+ option apsta '1'
+ option phy 'phy1'
+
+config wifi-iface 'default_sta_wl1'
+ option device 'wl1'
+ option mode 'sta'
+ option ifname 'wl1'
+ option multi_ap '1'
+ option disabled '0'
+
+config wifi-iface 'default_wl1'
+ option device 'wl1'
+ option network 'lan'
+ option ifname 'wl1.1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-44D4376AF7F0-2.4GHz'
+ option encryption 'psk2'
+ option key '12345678'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+```
+
+### Radios
+
+The `wifi-radio` section will primarily hold the band, device and whether the
+radio is a dedicated backhaul, meaning no fronthaul interfaces will be
+configured on this radio via AP-Autoconfig. This section will be auto-generated
+on startup by mapagent if not present.
+
+An example config:
+```
+config wifi-radio
+ option device 'wl2'
+ option band '5'
+ option dedicated_backhaul '1'
+```
+
+### Interfaces
+
+When specifying an interface in the mapagent configuration file, there are four
+parameters that must be kept in consideration:
+
+1. Whether the interface is backhaul/fronthaul (`fh-iface`) or backhaul station
+interfaces (`bk-iface`).
+2. Band of the interface, to be provided as i.e. `option band '2'`
+3. Interface name, to be provided as i.e. `option ifname 'wl0.1'`
+4. Device that the interface belongs to, to be provided as i.e. `option device 'wl0'`
+
+
+#### Fronthaul Interfaces
+
+Fronthaul interfaces are `fh-iface` sections with `multi_ap '2'` set. This
+section may also include the options `ssid`, `key`, `encryption`, and `vid`.
+Today these are not mandatory.
+
+```
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-44D4376AF7F0-5GHz'
+ option key 'IFJBD2RGYLZ3NE'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+```
+
+
+#### Backhaul Interfaces
+
+Backhaul interfaces are `fh-iface` sections with `multi_ap '1'` set. This
+section may also include the options `ssid`, `key`, `encryption`, and `vid`.
+Today these are not mandatory.
+
+```
+config fh-iface
+ option ifname 'wl0.2'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-44D4376AF7F0-BH-5GHz'
+ option key 'd6971d59b096ba3906d20f50dde7e19e7159dfe6eea1765a414e17c90aaefe7a'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+```
+
+
+
+#### Combined Front/Back Interfaces
+
+Combined fronthaul/backhaul interfaces are `fh-iface` sections with
+`multi_ap '3'` set. This section may also include the options `ssid`, `key`,
+`encryption`, and `vid`. Today these are not mandatory.
+
+```
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-44D4376AF7F0-COMBINED-5GHz'
+ option key 'IFJBD2RGYLZ3NE'
+ option encryption 'psk2+aes'
+ option multi_ap '3'
+ option vid '1'
+```
+
+
+#### Backhaul Station Interfaces
+
+Backhaul station interfaces are `bk-iface` sections.
+
+Backhaul interface sections will be generated automatically by map-agent upon
+startup. This is because it is assumed a backhaul station is only relevant in
+a multi-ap network scenario.
+
+Once onboarded, a bk-iface may be marked as `option onboarded '1'` by map-agent,
+along with the respective `wifi-radio` section. An onboarded backhaul station
+may look as follows:
+
+```
+config bk-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+ option onboarded '1'
+```
+
+
+## Onboarding
+
+Onboarding encompasses WPS pushbutton event, backhaul credential exchange and
+establishment of the wireless link between two devices.
+
+The prerequisites will be written from a dedicated backhaul and fronthaul
+interface. If using a combined fronthaul/backhaul interface the steps still
+apply, with the exception of the uci options `multi_ap_backhaul_ssid` and
+`multi_ap_backhaul_key` may be left out, and WPS be started on the combined
+interface.
+
+### Prerequisites
+
+* To perform onboarding, mapagent must be running at both the registrar
+and enrollee node.
+* The registrar radio and enrollee radio must be running in a
+compatible band and channel for the WPS exchange to take place.
+* The wireless uci configuration must have the backhaul credentials in the
+fronthaul secition under the keys `multi_ap_backhaul_ssid` and
+`multi_ap_backhaul_key`.
+* Enrollee backhaul sta interface must not be a part of a bridge
+* Enrollee and registrar interface must both have the multi_ap options set
+in the wireless config (1 and 2 respectively) for the multiap IE to be passed.
+
+
+### How to Start
+
+With the prerequisites in place, on the registrar, WPS must be started on the
+fronthaul interface with role registrar (default), as backhaul interfaces do not
+support WPS. However, with the `multi_ap` options set appropriately in the
+wireless configuration file a multiap IE will be passed with the WPS and the
+backhaul credentials be provided to the enrollee.
+
+Registrar:
+* `ubus call wifi.wps start '{"ifname":"wl0"}'`
+
+On the enrollee side, wps must be performed over the backhaul station interface,
+and the role `bsta` must be passed.
+
+Enrollee:
+* `ubus call wifi.wps start '{"ifname":"wl0", "role":"bsta"}'`
+
+When the devices pair, the credentials will be published as ubus event:
+```
+{ "wps_credentials": {"ifname":"wl0","encryption":"psk2", "ssid":"iopsysWrt-BACKHAUL-5GHz","key":"12345678BACKHAUL" }}
+```
+
+Mapagent will pick up this ubus event and add these credential to the uci
+wireless section and reload wifi, after which wpa_supplicant will establish a
+connection to the backhaul interface, over the backhaul station interface.
+When the `wifi.bsta` connection event comes over ubus:
+
+```
+{ "wifi.bsta": {"ifname":"wl0","event":"connected","data":{"macaddr":"0a:10:00:00:00:03","ssid":"iopsysWrt-BACKHAUL-5GHz"}} }
+
+```
+mapagent will issue DHCP to verify that it has entered 4address mode
+(wds link is up and added to the bridge on registrar) before adding the backhaul
+station to the bridge.
+
+Once backhaul station is in the bridge, onboarding is complete.
+
+
+## AP-Autoconfig
+
+AP-Autoconfig includes the triggering of AP-Autoconfig Search, AP-Autoconfig
+Response and AP-Autoconfig WSC and the configuration of the credentials provided
+with the AP-Autoconfig WSC.
+
+This will not include how to configure mapcontroller.
+
+### Prerequisites
+
+* Mapcontroller must be active in the network.
+
+
+### Mechanics
+
+AP-Autoconfig has a certain set of triggers with slight behavior differences.
+When understanding the different triggers, it is necessary to understand that
+during AP-Autoconfig, every radio will do its independent process, meaning
+AP-Autoconfig Search, Response and WSC.
+
+#### Radio State
+
+When a radio is available to be configured, will be consiered in an 'active'
+state, and when it is periodically probing it is considered to be in a
+'heartbeat' state.
+
+Some conditions that will set map-agent to an 'active' state
+* Upon mapagent (re)start
+* Establishing a connection over backhaul interface
+* No mapcontroller is observed for `probe_int` * `retry_int`
+* New mapcontroller is discovered
+
+#### Search Triggers
+
+All the triggers listed in [Radio State](#radio-state) will trigger
+AP-Autoconfig Search within a set time out (at most 5 seconds, depending on
+the event). Additionally it may be triggered by:
+* Periodic interval `probe_int` (defaults to 20s)
+* Connecting ethwan port.
+
+
+#### Upon Completion
+
+After AP-Autoconfig is completed, for a respective radio, there will be an event
+published over ubus:
+
+```
+{ "wifi.radio": {"ifname":"wl0","event":"ap-autoconfiguration","data":{"status":"success","reason":"completed"}} }
+```
+
+
+Map-agent will wait for 5 seconds to account for any disruption and delayed
+CMDUs and then restart wifi - to be sure that all WSC that are coming over the
+link are received and processed.
+
+After processing of the WSC CMDUs the mapagent config will have changed
+according to the received WSC:
+
+```
+config agent 'agent'
+ option enabled '1'
+ option debug '0'
+ option profile '2'
+ option brcm_setup '1'
+ option al_bridge 'br-lan'
+ option netdev 'wl'
+ option controller_mac 'ee:6c:9a:52:b0:27'
+
+config controller_select
+ option local '0'
+ option id 'auto'
+ option probe_int '20'
+ option retry_int '9'
+ option autostart '1'
+
+config bk-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+ option onboarded '1'
+
+config wifi-radio
+ option device 'wl0'
+ option band '5'
+
+config wifi-radio
+ option device 'wl1'
+ option band '2'
+
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-EC6C9A52B027-5GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl0.2'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl1'
+ option band '2'
+ option device 'wl1'
+ option ssid 'MAP-EC6C9A52B027-2.4GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl1.1'
+ option band '2'
+ option device 'wl1'
+ option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+```
+
+And similarily the wireless config:
+
+
+```
+config wifi-iface 'wl1_ap'
+ option ifname 'wl1'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-2.4GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option multi_ap_backhaul_key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+
+config wifi-iface 'wl1_1_ap'
+ option ifname 'wl1.1'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option hidden '1'
+
+config wifi-iface 'default_sta_wl2'
+ option device 'wl0'
+ option mode 'sta'
+ option ifname 'wl0'
+ option multi_ap '1'
+ option disabled '0'
+ option encryption 'psk2'
+ option ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option wds '1'
+
+config wifi-iface 'wl0_ap'
+ option ifname 'wl0.1'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-5GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option multi_ap_backhaul_key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+
+config wifi-iface 'wl0_1_ap'
+ option ifname 'wl0.2'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option hidden '1'
+
+config wifi-device 'wl0'
+ option type 'mac80211'
+ option channel '100'
+ option hwmode '11a'
+ option country 'DE'
+ option htmode 'HE80'
+ option apsta '0'
+ option phy 'phy0'
+
+config wifi-device 'wl1'
+ option type 'mac80211'
+ option channel '11'
+ option hwmode '11g'
+ option country 'DE'
+ option htmode 'HE20'
+ option apsta '0'
+ option phy 'phy1'
+
+```
+
+Do note that a backhaul station interface will never be torn down by mapagent.
+
+## Controller Discovery
+
+
+### UCI
+
+The following UCI config section in “mapagent” config is used to control how a
+MAP Controller is discovered and (auto)started/stopped on demand in a MAP
+network.
+
+```
+config controller_select
+ option local ‘true’
+ option id ‘auto’
+ option probe_int ‘20’
+ option retry_int ‘3’
+ option autostart ‘true’
+```
+
+| Name | Type | Required | Default | Description |
+| ------------- |---------------| ----------|-------------|---------------|
+| local | Boolean | yes | false | When set to true, the MAP Controller running in the same 1905 device as the MAP Agent, will be treated as the main or primary Controller. It takes precedence over others discovered in the network. |
+| id | Mac address | no | auto-detect | User can provide the 1905 ALID of the device that will have the MAP Controller service. When set to ‘auto’, the MAP Agent will discover the MAP Controller ID. OPTION NOT YET SUPPORTED. |
+| probe_int | Integer | no | 20s |The time interval in seconds between controller discovery by the MAP Agent |
+| retry_int | Integer | no | 15 |After these many failed attempts to discover a controller in the network, the agent will infer that the controller is not available and accordingly takes the next action. |
+| autostart | Boolean | no | false |When this is set to ‘true’, the agent will try to start the controller after not finding one in the network. |
+
+
+### Algorithm
+
+During startup and at run-time, the MAP Agent will probe for the presence of a
+MAP Controller in the network.
+
+If it finds another, then take one of the following actions:
+
+1. If a MAP Controller is NOT running in the own device, then update its
+Controller-ID and the last-seen timestamp.
+
+2. If a MAP Controller is running in its own device, and local = true, then
+notify the detected Controller to user (e.g.: over UBUS).
+
+3. If a MAP controller is running in its own device, and local = false, then
+stop the local Controller. Update the Controller-ID and the last-seen timestamp.
+
+If after ‘retry_int’ number of times, the MAP Agent cannot discover a MAP
+Controller in the network, then take one of the following actions:
+
+1. When autostart = true, the MAP Agent will try to start the MAP Controller
+locally (*). Report status of the MAP Controller start to user (e.g.: over UBUS).
+
+2. When autostart = false, the MAP Agent will simply report to user (over UBUS)
+that no Controller has been detected in the network.
+
+Notes:
+ * The default time interval in seconds between controller discovery by the
+ MAP Agent will increase to 70 seconds once Agent enters the heartbeat state
+ (that is after controller discovery finished successfully).
+ * Maximum time w/o controller in the network will be (probe_int * retry_int)
+ - but not less than 75 seconds.
+* After detecting no Controller in the network, the MAP-Agent will try to start
+its local Controller after a random time chosen from a time window (10s). This
+helps to reduce the chance of multiple MAP-Agents trying to run the controller
+at the same time.
+
+### Example
+
+While the aim for this controller discovery is to support the same configuration
+across all devices, one may want to have a designated mapcontroller device, then
+the following configuration may be used:
+
+Main Device (i.e. SmartHub3/Fibertwist): Controller to be run in a designated
+node only.
+
+```
+config controller_select
+ option local ‘true’
+```
+
+Repeater Device (Disc/EX600): Controller start/stop automatically if another is
+not detected in the network.
+
+```
+config controller_select
+ option local ‘false’
+ option autostart ‘true’
+```
+
## uBus
```
root@iopsys:~# ubus -v list map.agent
-'map.agent' @6d619bde
- "apconfig":{"band":"Integer"}
- "steer_policy":{"vif":"String","rule":"String","order":"String"}
- "steer":{"vif":"String","type":"String","sta":"String","to_bss":"Array","optime":"Integer"}
- "assoc_control":{"vif":"String","sta":"String","enable":"Boolean","time":"Integer"}
- "cmd":{"id":"Integer","data":"String"}
- "cmd_async":{"id":"Integer","data":"String"}
- "status":{}
-```
-
-```
-root@iopsys:~# ubus call map.agent status
-{
- "fronthaul": [
- {
- "name": "wl0",
- "bssid": "ec:6c:9a:79:fc:11",
- "ssid": "MAP-EC6C9A79FCA8-5GHz",
- "channel": 135,
- "load": 0,
- "neighbor": [
-
- ],
- "stations": [
-
- ]
- },
- {
- "name": "wl0.1",
- "bssid": "ee:6c:9a:79:fc:12",
- "ssid": "MAP-EC6C9A79FCA8-BH-5GHz",
- "channel": 135,
- "load": 0,
- "neighbor": [
-
- ],
- "stations": [
- {
- "addr": "ec:6c:9a:52:ae:0a",
- "rssi": -44,
- "bcnreport_capable": 0,
- "btmreq_steers": 0,
- "legacy_steers": 0,
- "neighbor": [
-
- ]
- }
- ]
- },
- {
- "name": "wl1",
- "bssid": "ec:6c:9a:79:fc:22",
- "ssid": "MAP-EC6C9A79FCA8-2.4GHz",
- "channel": 135,
- "load": 0,
- "neighbor": [
-
- ],
- "stations": [
-
- ]
- },
- {
- "name": "wl1.1",
- "bssid": "ee:6c:9a:79:fc:23",
- "ssid": "MAP-EC6C9A79FCA8-BH-2.4GHz",
- "channel": 135,
- "load": 0,
- "neighbor": [
-
- ],
- "stations": [
-
- ]
- }
- ]
-}
+'map.agent' @41d34dcd
+ "apconfig":{"band":"Integer"}
+ "steer_policy":{"vif":"String","rule":"String","order":"String"}
+ "steer":{"vif":"String","type":"String","sta":"String","to_bss":"Array","optime":"Integer"}
+ "assoc_control":{"vif":"String","sta":"String","enable":"Boolean","time":"Integer"}
+ "bcn_metrics_query":{"agent":"String","sta":"String","opclass":"Integer","channel":"Integer","bssid":"String","reporting_detail":"Integer","ssid":"String","channel_report":"Array","request_element":"Array"}
+ "cmd":{"id":"Integer","data":"String"}
+ "cmd_async":{"id":"Integer","data":"String"}
+ "status":{}
```
diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md
new file mode 100644
index 0000000000000000000000000000000000000000..1efb3d555b5a588ef058d797623ef67305712486
--- /dev/null
+++ b/docs/QUICK_START.md
@@ -0,0 +1,545 @@
+# Multi-AP Environment
+
+## Introduction
+
+This will be a short version of how to setup a Multi-AP environment.
+
+For more detailed information on UCI options and overgrasping READMEs, see
+individual repositories at:
+
+* [Map-agent](https://dev.iopsys.eu/iopsys/map-agent)
+* [Map-controller](https://dev.iopsys.eu/iopsys/map-controller)
+* [Ieee1905](https://dev.iopsys.eu/iopsys/ieee1905)
+
+## Overview
+
+The first chapter will show how to setup a singular device to be the 'master'
+device in the network and prepare it for AP-Autoconfiguration and onboarding.
+
+The second chapter will setup a repeater device which wil connect to it.
+
+## Setting up Controller device
+
+In this example, I will be setting up a smarthub3 with wl0 (5GHz) and wl1 (2.4GHz)
+
+### Prerequisites
+
+* Map-controller, map-agent and ieee1905 package installed
+* IEEE1905 must be loaded with MAP extension, preferably set via config.
+```
+config ieee1905 'ieee1905'
+ option enabled '1'
+ option extension '1'
+ list extmodule 'map'
+```
+* **** Mapagent config should *NOT* contain interfaces that will not be started, or
+do not exist, at the time that mapagent is started. ****
+* Mapcontroller has to have `registrar` set for bands it should configure
+* Mapagent expects there to be one 'main' bridge in the network, which is
+also used as an ieee1905 interface, set by uci option `al_bridge`.
+
+#### Notes
+* If ieee1905d is restarted during run time, mapagent and mapcontroller should
+also be restarted.
+* Only mapagent is expected to modify interfaces specified in mapagent config
+
+### Setting up Mapagent
+
+* Align wireless and mapagent default configuration
+
+In this default setup we have one fronthaul on each radio, named wl0 and wl1 respectively
+
+UCI Wireless excerpt:
+```
+config wifi-iface 'default_wl0'
+ option device 'wl0'
+ option network 'lan'
+ option ifname 'wl0'
+ option mode 'ap'
+ option ssid 'iopsysWrt-TEST5'
+ option encryption 'psk2'
+ option key '1234567890'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+
+config wifi-iface 'default_wl1'
+ option device 'wl1'
+ option network 'lan'
+ option ifname 'wl1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-TEST2'
+ option encryption 'psk2'
+ option key '1234567890'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+```
+
+Align mapagent:
+```
+config agent 'agent'
+ option enabled '1'
+ option debug '0'
+ option profile '2'
+ option brcm_setup '1'
+ option al_bridge 'br-lan'
+ option netdev 'wl'
+
+config controller_select
+ option local '1'
+ option id 'auto'
+ option probe_int '20'
+ option retry_int '15'
+ option autostart '1'
+
+config fh-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+
+config fh-iface
+ option ifname 'wl1'
+ option band '2'
+ option device 'wl1'
+```
+
+#### Notes
+* `multi_ap` should be set on map-agent managed interfaces
+* `brcm_setup` must be used for broadcom platform
+* This default config will not support backhaul connections
+* `wifi-radio` sections will be generated automatically if absent
+
+
+### Setting up Mapcontroller
+
+* Setup credentials
+In this use case mapcontroller will be setup to provide one dedicated fronthaul
+and one backhaul for every 2.4GHz radio and 5GHz radio on the configured device.
+
+```
+config controller 'controller'
+ option enabled '1'
+ option registrar '5 2' #bands on which wps registrar supported
+ option debug '0'
+ option al_bridge 'br-lan'
+
+config vlan 'lan'
+ option network 'lan'
+ option id '1'
+
+config fh-credentials
+ option band '5'
+ option ssid 'MAP-TEST-5GHz'
+ option encryption 'psk2'
+ option key '1234567890'
+ option vlan '1'
+
+config fh-credentials
+ option band '2'
+ option ssid 'MAP-TEST-2.4GHz'
+ option encryption 'psk2'
+ option key '1234567890'
+ option vlan '1'
+
+config bk-credentials
+ option band '5'
+ option ssid 'MAP-TEST-BH-5GHz'
+ option encryption 'psk2'
+ option key '1234567890'
+ option multi_ap '1'
+ option vlan '1'
+
+config bk-credentials
+ option band '2'
+ option ssid 'MAP-TEST-BH-2.4GHz'
+ option encryption 'psk2'
+ option key '1234567890'
+ option multi_ap '1'
+ option vlan '1'
+```
+
+
+#### Notes
+* **** Mapcontroller config `bk-credentials` should *NOT* be confused with `bk-iface`
+of map-agent config. `bk-iface` will in the future be renamed. ****
+
+
+### AP-Autoconfiguration
+
+With these configurations at boot, AP-Autoconfig should automatically trigger.
+However, if setup at runtime, ieee1905d should be started first.
+
+1. ieee1905d &
+2. mapcontroller -d &
+3. mapagent -d &
+
+Or via procd:
+
+1. /etc/init.d/ieee1905 start
+2. /etc/init.d/mapagent start
+3. /etc/init.d/mapcontroller start
+
+Order of mapagent and mapcontroller is not important, but by starting mapcontroller
+first we will immediately trigger AP-Autoconfig upon mapagent start.
+
+Config files after AP-Autoconfig:
+```
+root@iopsys:~# cat /etc/config/mapagent
+
+config agent 'agent'
+ option enabled '1'
+ option debug '0'
+ option profile '2'
+ option brcm_setup '1'
+ option al_bridge 'br-lan'
+ option netdev 'wl'
+ option controller_mac 'ee:6c:9a:52:b0:27'
+
+config controller_select
+ option local '1'
+ option id 'auto'
+ option probe_int '20'
+ option retry_int '3'
+ option autostart '1'
+
+config wifi-radio
+ option device 'wl0'
+ option band '5'
+
+config wifi-radio
+ option device 'wl1'
+ option band '2'
+
+config fh-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-TEST-5GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-TEST-BH-5GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl1'
+ option band '2'
+ option device 'wl1'
+ option ssid 'MAP-TEST-2.4GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl1.1'
+ option band '2'
+ option device 'wl1'
+ option ssid 'MAP-TEST-BH-2.4GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+
+root@iopsys:~# cat /etc/config/wireless
+
+config wifi-iface 'wl1_ap'
+ option ifname 'wl1'
+ option network 'lan'
+ option ssid 'MAP-TEST-2.4GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52b027'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-TEST-BH-2.4GHz'
+ option multi_ap_backhaul_key '1234567890'
+
+config wifi-iface 'wl1_1_ap'
+ option ifname 'wl1.1'
+ option network 'lan'
+ option ssid 'MAP-TEST-BH-2.4GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52b027'
+ option hidden '1'
+
+config wifi-iface 'wl0_ap'
+ option ifname 'wl0'
+ option network 'lan'
+ option ssid 'MAP-TEST-5GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52b027'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-TEST-BH-5GHz'
+ option multi_ap_backhaul_key '1234567890'
+
+config wifi-iface 'wl0_1_ap'
+ option ifname 'wl0.1'
+ option network 'lan'
+ option ssid 'MAP-TEST-BH-5GHz'
+ option key '1234567890'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52b027'
+ option hidden '1'
+
+config wifi-device 'wl0'
+ option type 'mac80211'
+ option channel '36'
+ option hwmode '11a'
+ option country 'DE'
+ option htmode 'HE80'
+ option apsta '0'
+ option phy 'phy0'
+
+config wifi-device 'wl1'
+ option type 'mac80211'
+ option channel '11'
+ option hwmode '11g'
+ option country 'DE'
+ option htmode 'HE20'
+ option apsta '0'
+ option phy 'phy1'
+```
+
+#### Notes
+* For extra debug:
+ * provide `-dd` to ieee1905
+ * provide `-vvvv` to mapagent and/or mapcontroller
+* To re-trigger a *FRESH* AP-Autoconfig, mapagent can be restarted at any given
+time. However, multiple triggers are available at runtime by mapagent, see
+map-agent README for more info.
+
+### AP-Autoconfig Renew
+
+To trigger AP-Autoconfig Renew, credentials in /etc/config/mapcontroller must
+differ from the config loaded in memory by mapcontroller *AND* mapcontroller
+must receive `SIGHUP`.
+
+A `SIGUHP` can be triggered via preferred method, i.e.:
+* `kill -1 \`pidof mapcontroller\``
+* `ubus call uci commit '{"config":"mapcontroller"}'` which will trigger an init.d hook.
+
+Some example steps:
+```
+root@iopsys:~# uci set mapcontroller.@bk-credentials[1].ssid="MAP-NEW-BH-2.4GHz"
+root@iopsys:~# uci commit mapcontroller
+root@iopsys:~# ubus call uci commit '{"config":"mapcontroller"}'
+root@iopsys:~# sleep 10
+root@iopsys:~# wlctl -i wl1.1 status | grep SSID
+SSID: "MAP-NEW-BH-2.4GHz"
+BSSID: 0E:10:00:00:00:04 Capability: ESS ShortPre ShortSlot RRM
+```
+
+## Setting up Repeater Device
+
+In this example, I will be setting up a disc with wl0 (5GHz), wl1 (2.4GHz) and
+wl2 (5GHz).
+
+### Prerequisites
+
+* Map-agent and ieee1905 package installed
+* IEEE1905 must be loaded with MAP extension, preferably set via config.
+```
+config ieee1905 'ieee1905'
+ option enabled '1'
+ option extension '1'
+ list extmodule 'map'
+```
+* **** Mapagent config should *NOT* contain interfaces that will not be started, or
+do not exist, at the time that mapagent is started. ****
+* Mapagent expects there to be one 'main' bridge in the network, which is
+also used as an ieee1905 interface, set by uci option `al_bridge`.
+* If wireless connection is to be used, a backhaul STA interface *MUST* be
+present on a radio with the same band and channel range as the controller device.
+* **** Any backhaul STA interface *MUST* be the first interface on the radio. ****
+* For the backhaul STA radio `apsta` option should be set in the wireless
+configuration for the radio.
+```
+config wifi-device 'wl2'
+ option type 'mac80211'
+ option channel '36'
+ option hwmode '11a'
+ option country 'DE'
+ option htmode 'HE80'
+ option apsta '1'
+ option phy 'phy2'
+```
+
+#### Notes
+* If ieee1905d is restarted during run time, mapagent and mapcontroller should
+also be restarted.
+* Only mapagent is expected to modify interfaces specified in mapagent config
+
+
+### Setting up Mapagent
+
+* Align wireless and mapagent default configuration
+
+In this default setup we have one fronthaul on each radio, named wl0 and wl1
+respectively and one backhaul STA on wl2.
+
+UCI Wireless excerpt:
+```
+config wifi-iface 'default_wl0'
+ option device 'wl0'
+ option network 'lan'
+ option ifname 'wl0'
+ option mode 'ap'
+ option ssid 'iopsysWrt-TEST5'
+ option encryption 'psk2'
+ option key '1234567890'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+
+config wifi-iface 'default_wl1'
+ option device 'wl1'
+ option network 'lan'
+ option ifname 'wl1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-TEST2'
+ option encryption 'psk2'
+ option key '1234567890'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+
+config wifi-iface 'default_sta_wl2'
+ option device 'wl2'
+ option mode 'sta'
+ option ifname 'wl2'
+ option multi_ap '1'
+ option disabled '0'
+```
+
+Align mapagent:
+```
+config agent 'agent'
+ option enabled '1'
+ option debug '0'
+ option profile '2'
+ option brcm_setup '1'
+ option al_bridge 'br-lan'
+ option netdev 'wl'
+
+config controller_select
+ option local '0'
+ option id 'auto'
+ option probe_int '20'
+ option retry_int '15'
+ option autostart '0'
+
+config fh-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+
+config fh-iface
+ option ifname 'wl1'
+ option band '2'
+ option device 'wl1'
+
+config wifi-radio
+ option device 'wl2'
+ option band '5'
+ option dedicated_backhaul '1'
+
+config bk-iface
+ option ifname 'wl2'
+ option band '5'
+ option device 'wl2'
+```
+
+#### Notes
+
+* Mapagent will never overwrite bsta interfaces during AP-Autoconfig
+* With `dedicated_backhaul` set on the radio, AP-Autoconfiguration will not
+take place on this radio (optional).
+
+### Onboarding
+
+To trigger onboarding, WPS must be triggered with registrar role (default) on
+controller node (smarthub3), on the autoconfigured fronthaul:
+
+* `ubus call wifi.wps start '{"ifname":"wl0"}'`
+
+On the repeater (disc), WPS must be started on the bsta interface, with the
+enrollee role, as well as providing the multiap IE, this is done by using the
+`bsta role`.
+
+* `ubus call wifi.wps start '{"ifname":"wl2"}'`
+
+Once the credential exchange is complete you will see a ubus event published
+on the repeater side:
+
+```
+{ "wps_credentials": {"ifname":"wl0","encryption":"psk2", "ssid":"MAP-TEST-BH-5GHz","key":"1234567890" }}
+```
+
+After some time you should see wl2 added to the main bridge and receive an IP.
+
+### AP-Autoconfig
+
+AP-Autoconfig will take place within, usually 30 seconds, after receiving the WPS
+credentials, but this may depend on probe_int.
+
+### AP-Autoconfig Renew
+
+Works the same way as a singular device, as AP-Autoconfig Renew is relayed multicast.
+
+### Dynamic Backhaul/Loop Detection
+
+Only one backhaul should be active at any given time, on a device that is already
+onboarded, plugging an ethernet cable will dynamically swap to that link. Similarily,
+unplugging it will automatically enable the wireless backhaul again.
+
+### Controller Discovery
+
+For controller discovery, see map-agent README.
diff --git a/docs/api/mapagent.md b/docs/api/mapagent.md
new file mode 100644
index 0000000000000000000000000000000000000000..0985b24113c16bb3218dbd43774ad8411377453f
--- /dev/null
+++ b/docs/api/mapagent.md
@@ -0,0 +1 @@
+<tbody><tr><td colspan="2"><div style="font-weight: bold">mapagent</div><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">section</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td><td><div style="font-weight: bold; font-size: 14px">multi</div></td><td><div style="font-weight: bold; font-size: 14px">options</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">mapagent</div></td><td class="td_row_even"><div class="td_row_even">Mapagent daemon Configuration</div></td><td class="td_row_even"><div class="td_row_even">false</div></td><td class="td_row_even"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">enabled</div></td><td class="td_row_even"><div class="td_row_even">boolean</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">true</div></td><td class="td_row_even"><div class="td_row_even">Enables mapagent daemon</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">debug</div></td><td class="td_row_odd"><div class="td_row_odd">integer</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">0</div></td><td class="td_row_odd"><div class="td_row_odd">Mapagent debug level</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">profile</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">2</div></td><td class="td_row_even"><div class="td_row_even">Currently unused</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">brcm_setup</div></td><td class="td_row_odd"><div class="td_row_odd">boolean</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">false</div></td><td class="td_row_odd"><div class="td_row_odd">For broadcom platforms, mapagent is responsible for adding the wds interface to the bridge</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">al_bridge</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">br-lan</div></td><td class="td_row_even"><div class="td_row_even">The bridge which the wds interface will be attached to.</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">netdev</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">wl if brcm_setup is set, else wlan</div></td><td class="td_row_odd"><div class="td_row_odd">The interface names that will be created by mapagent are using the specified netdev</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">controller_mac</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Will be set at runtime by mapagent</div></td></tr></tbody></table></td><td class="td_row_even"><div class="td_row_even"> </div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">controller_select</div></td><td class="td_row_odd"><div class="td_row_odd">Configure controller selection parameters</div></td><td class="td_row_odd"><div class="td_row_odd">false</div></td><td class="td_row_odd"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">local</div></td><td class="td_row_even"><div class="td_row_even">boolean</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">false</div></td><td class="td_row_even"><div class="td_row_even">Enforce local controller. If set, the device will not be configurable by a non-local controller. If set, it also enables autostart</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">id</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">auto</div></td><td class="td_row_odd"><div class="td_row_odd">Lock mapagent to a specific controller AL-ID. NOT YET IMPLEMENTED</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">probe_int</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">20</div></td><td class="td_row_even"><div class="td_row_even">The interval at which AP-Autoconfig Search (discovery) will be sent</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">retry_int</div></td><td class="td_row_odd"><div class="td_row_odd">integer</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">15</div></td><td class="td_row_odd"><div class="td_row_odd">After these many failed attempts mapagent infers no controller is active and accordingly takes next action</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">autostart</div></td><td class="td_row_even"><div class="td_row_even">boolean</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">true</div></td><td class="td_row_even"><div class="td_row_even">When this is set to true, the agent will try to start the controller after not finding one in the network.</div></td></tr></tbody></table></td><td class="td_row_odd"><div class="td_row_odd"> </div></td></tr><tr><td class="td_row_even"><div class="td_row_even">wifi-radio</div></td><td class="td_row_even"><div class="td_row_even">Represents a radio</div></td><td class="td_row_even"><div class="td_row_even">true</div></td><td class="td_row_even"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">device</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Radio name</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">band</div></td><td class="td_row_odd"><div class="td_row_odd">integer</div></td><td class="td_row_odd"><div class="td_row_odd">yes</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">Band on which the radio operates</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">onboarded</div></td><td class="td_row_even"><div class="td_row_even">boolean</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">false</div></td><td class="td_row_even"><div class="td_row_even">Set by mapagent if the radio has been onboarded (credentials received)</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">dedicated_backhaul</div></td><td class="td_row_odd"><div class="td_row_odd">boolean</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">false</div></td><td class="td_row_odd"><div class="td_row_odd">This radio will not be configured with fronthaul interfaces</div></td></tr></tbody></table></td><td class="td_row_even"><div class="td_row_even"> </div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">bk-iface</div></td><td class="td_row_odd"><div class="td_row_odd">Represents a backhaul station interface</div></td><td class="td_row_odd"><div class="td_row_odd">true</div></td><td class="td_row_odd"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">ifname</div></td><td class="td_row_even"><div class="td_row_even">boolean</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Interface name of backhaul station interface</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">band</div></td><td class="td_row_odd"><div class="td_row_odd">integer</div></td><td class="td_row_odd"><div class="td_row_odd">yes</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">Frequency of the interface</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">device</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Radio on which the interface is operating</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">onboarded</div></td><td class="td_row_odd"><div class="td_row_odd">boolean</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">false</div></td><td class="td_row_odd"><div class="td_row_odd">Reference list of datamodel objects</div></td></tr></tbody></table></td><td class="td_row_odd"><div class="td_row_odd">no</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">fh-iface</div></td><td class="td_row_even"><div class="td_row_even">An AP interface (front or backhaul)</div></td><td class="td_row_even"><div class="td_row_even">true</div></td><td class="td_row_even"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">ifname</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Interface name</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">band</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">yes</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">Frequency on which the interface operates</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">device</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Radio of which the interface belongs</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">ssid</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">SSID of the interface</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">key</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Password to the SSID</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">encryption</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">Encryption for the SSID</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">multi_ap</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">The multi_ap option of the interface. 1(backhaul), 2(fronthaul) or 3(combined)</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">disallow_bsta</div></td><td class="td_row_odd"><div class="td_row_odd">integer</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">0</div></td><td class="td_row_odd"><div class="td_row_odd">Whether to disallow an backhaul connections for certain profiles. 1(profile 1), 2(profile 2) 3 (both). NOT YET IMPLEMENTED</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">vid</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Vlan ID of this interface NOT YET IMPLEMENTED</div></td></tr></tbody></table></td><td class="td_row_even"><div class="td_row_even"> </div></td></tr></tbody></table></td></tr></tbody>
\ No newline at end of file
diff --git a/schemas/uci/mapagent.json b/schemas/uci/mapagent.json
new file mode 100644
index 0000000000000000000000000000000000000000..7f1a751e41d23cf36ff1b3d534a43f95cca50578
--- /dev/null
+++ b/schemas/uci/mapagent.json
@@ -0,0 +1,243 @@
+{
+ "mapagent": [
+ {
+ "section": "mapagent",
+ "description": "Mapagent daemon Configuration",
+ "multi": false,
+ "options": [
+ {
+ "name": "enabled",
+ "type": "boolean",
+ "required": "no",
+ "default": true,
+ "description": "Enables mapagent daemon"
+ },
+ {
+ "name": "debug",
+ "type": "integer",
+ "required": "no",
+ "default": "0",
+ "description": "Mapagent debug level"
+ },
+ {
+ "name": "profile",
+ "type": "integer",
+ "required": "no",
+ "default": "2",
+ "description": "Currently unused"
+ },
+ {
+ "name": "brcm_setup",
+ "type": "boolean",
+ "required": "no",
+ "default": false,
+ "description": "For broadcom platforms, mapagent is responsible for adding the wds interface to the bridge"
+ },
+ {
+ "name": "al_bridge",
+ "type": "string",
+ "required": "no",
+ "default": "br-lan",
+ "description": "The bridge which the wds interface will be attached to."
+ },
+ {
+ "name": "netdev",
+ "type": "string",
+ "required": "no",
+ "default": "wl if brcm_setup is set, else wlan",
+ "description": "The interface names that will be created by mapagent are using the specified netdev"
+ },
+ {
+ "name": "controller_mac",
+ "type": "string",
+ "required": "no",
+ "default": "",
+ "description": "Will be set at runtime by mapagent"
+ }
+ ]
+ },
+ {
+ "section": "controller_select",
+ "description": "Configure controller selection parameters",
+ "multi": false,
+ "options": [
+ {
+ "name":"local",
+ "type":"boolean",
+ "required":"no",
+ "default": false,
+ "description": "Enforce local controller. If set, the device will not be configurable by a non-local controller. If set, it also enables autostart"
+ },
+ {
+ "name":"id",
+ "type":"string",
+ "required":"no",
+ "default": "auto",
+ "description": "Lock mapagent to a specific controller AL-ID. NOT YET IMPLEMENTED"
+ },
+ {
+ "name":"probe_int",
+ "type":"integer",
+ "required":"no",
+ "default": "20",
+ "description": "The interval at which AP-Autoconfig Search (discovery) will be sent"
+ },
+ {
+ "name":"retry_int",
+ "type":"integer",
+ "required":"no",
+ "default": "15",
+ "description": "After these many failed attempts mapagent infers no controller is active and accordingly takes next action"
+ },
+ {
+ "name":"autostart",
+ "type":"boolean",
+ "required":"no",
+ "default": true,
+ "description": "When this is set to true, the agent will try to start the controller after not finding one in the network."
+ }
+ ]
+ },
+ {
+ "section": "wifi-radio",
+ "description": "Represents a radio",
+ "multi": true,
+ "options":[
+ {
+ "name": "device",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "Radio name"
+ },
+ {
+ "name": "band",
+ "type": "integer",
+ "required": "yes",
+ "default": "",
+ "description": "Band on which the radio operates"
+ },
+ {
+ "name": "onboarded",
+ "type": "boolean",
+ "required": "no",
+ "default": false,
+ "description": "Set by mapagent if the radio has been onboarded (credentials received)"
+ },
+ {
+ "name": "dedicated_backhaul",
+ "type": "boolean",
+ "required": "no",
+ "default": false,
+ "description": "This radio will not be configured with fronthaul interfaces"
+ }
+ ]
+ },
+ {
+ "section":"bk-iface",
+ "description": "Represents a backhaul station interface",
+ "required": "no",
+ "multi": true,
+ "options": [
+ {
+ "name":"ifname",
+ "type":"boolean",
+ "required":"yes",
+ "default": "",
+ "description": "Interface name of backhaul station interface"
+ },
+ {
+ "name":"band",
+ "type":"integer",
+ "required":"yes",
+ "default": "",
+ "description": "Frequency of the interface"
+ },
+ {
+ "name":"device",
+ "type":"string",
+ "required":"yes",
+ "default": "",
+ "description": "Radio on which the interface is operating"
+ },
+ {
+ "name":"onboarded",
+ "type":"boolean",
+ "required":"no",
+ "default": false,
+ "description": "Reference list of datamodel objects"
+ }
+ ]
+ },
+ {
+ "section": "fh-iface",
+ "description": "An AP interface (front or backhaul)",
+ "multi": true,
+ "options": [
+ {
+ "name": "ifname",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "Interface name"
+ },
+ {
+ "name": "band",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "Frequency on which the interface operates"
+ },
+ {
+ "name": "device",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "Radio of which the interface belongs"
+ },
+ {
+ "name": "ssid",
+ "type": "string",
+ "required": "no",
+ "default": "",
+ "description": "SSID of the interface"
+ },
+ {
+ "name": "key",
+ "type": "string",
+ "required": "no",
+ "default": "",
+ "description": "Password to the SSID"
+ },
+ {
+ "name": "encryption",
+ "type": "string",
+ "required": "no",
+ "default": "",
+ "description": "Encryption for the SSID"
+ },
+ {
+ "name": "multi_ap",
+ "type": "integer",
+ "required": "no",
+ "default": "",
+ "description": "The multi_ap option of the interface. 1(backhaul), 2(fronthaul) or 3(combined)"
+ },
+ {
+ "name": "disallow_bsta",
+ "type": "integer",
+ "required": "no",
+ "default": "0",
+ "description": "Whether to disallow an backhaul connections for certain profiles. 1(profile 1), 2(profile 2) 3 (both). NOT YET IMPLEMENTED"
+ },
+ {
+ "name": "vid",
+ "type": "integer",
+ "required": "no",
+ "default": "",
+ "description": "Vlan ID of this interface NOT YET IMPLEMENTED"
+ }
+ ]
+ }
+ ]
+ }
diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3eb578cf1e465e1d1c8e096dfb98d984ae953435
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,671 @@
+# MAP Agent
+
+[Map-agent](https://dev.iopsys.eu/iopsys/map-agent)
+
+
+## Introduction
+
+This package provides the `mapagent` daemon, which is responsible for
+configuring wireless credentials, vlan etc.
+
+Today map-agent is bridge centered, and it is expected that there is a 'main'
+bridge which holds the uplink interface, as specified by `al_bridge` in the
+mapagent config.
+
+## Overview
+
+This README will show how to properly setup the mapagent configuration file
+and explain some key features of map-agent.
+
+## UCI Configuration
+
+A default configuration file may look as such:
+
+```
+config agent 'agent'
+ option enabled '1'
+ option debug '0'
+ option profile '2'
+ option brcm_setup '1'
+ option al_bridge 'br-lan'
+ option netdev 'wl'
+
+config controller_select
+ option local '0'
+ option id 'auto'
+ option probe_int '20'
+ option retry_int '15'
+ option autostart '1'
+
+config wifi-radio
+ option device 'wl0'
+ option band '5'
+
+config wifi-radio
+ option device 'wl1'
+ option band '2'
+
+
+config fh-iface
+ option ifname 'wl0.2'
+ option band '5'
+ option device 'wl0'
+
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+
+config bk-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+
+config fh-iface
+ option ifname 'wl1.1'
+ option band '2'
+ option device 'wl1'
+
+config bk-iface
+ option ifname 'wl1'
+ option band '2'
+ option device 'wl1'
+```
+
+The important part of this configuration file is to properly align the
+wireless configuration with the mapagent configuration for the default setup.
+
+Mapagent expects all interfaces that are present in its config to be up and
+running when mapagent is started as these interfaces are managed by mapagent.
+
+Interface which are not included in the config will never be torn down or
+modified by mapagent, thus if desired, interfaces may left out of multi-ap
+management
+
+The above example of a mapagent config would map properly against the
+following wireless configuration file:
+
+```
+config wifi-device 'wl0'
+ option type 'mac80211'
+ option channel '36'
+ option hwmode '11a'
+ option country 'DE'
+ option htmode 'HE80'
+ option apsta '1'
+ option phy 'phy0'
+
+config wifi-iface 'default_sta_wl0'
+ option device 'wl0'
+ option mode 'sta'
+ option ifname 'wl0'
+ option multi_ap '1'
+ option disabled '0'
+
+config wifi-iface 'default_wl0'
+ option device 'wl0'
+ option network 'lan'
+ option ifname 'wl0.1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-44D4376AF7F0-5GHz'
+ option encryption 'psk2'
+ option key '12345678'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+ option multi_ap_backhaul_ssid 'iopsysWrt-BACKHAUL-5GHz'
+ option multi_ap_backhaul_key '12345678BACKHAUL'
+
+config wifi-iface 'default_wl0'
+ option device 'wl0'
+ option network 'lan'
+ option ifname 'wl0.1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-BACKHAUL-5GHz'
+ option encryption 'psk2'
+ option key '12345678BACKHAUL'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '1'
+
+config wifi-device 'wl1'
+ option type 'mac80211'
+ option channel '11'
+ option hwmode '11g'
+ option country 'DE'
+ option htmode 'HE20'
+ option apsta '1'
+ option phy 'phy1'
+
+config wifi-iface 'default_sta_wl1'
+ option device 'wl1'
+ option mode 'sta'
+ option ifname 'wl1'
+ option multi_ap '1'
+ option disabled '0'
+
+config wifi-iface 'default_wl1'
+ option device 'wl1'
+ option network 'lan'
+ option ifname 'wl1.1'
+ option mode 'ap'
+ option ssid 'iopsysWrt-44D4376AF7F0-2.4GHz'
+ option encryption 'psk2'
+ option key '12345678'
+ option wps '1'
+ option wps_pushbutton '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option bss_transition '1'
+ option multi_ap '2'
+```
+
+### Radios
+
+The `wifi-radio` section will primarily hold the band, device and whether the
+radio is a dedicated backhaul, meaning no fronthaul interfaces will be
+configured on this radio via AP-Autoconfig. This section will be auto-generated
+on startup by mapagent if not present.
+
+An example config:
+```
+config wifi-radio
+ option device 'wl2'
+ option band '5'
+ option dedicated_backhaul '1'
+```
+
+### Interfaces
+
+When specifying an interface in the mapagent configuration file, there are four
+parameters that must be kept in consideration:
+
+1. Whether the interface is backhaul/fronthaul (`fh-iface`) or backhaul station
+interfaces (`bk-iface`).
+2. Band of the interface, to be provided as i.e. `option band '2'`
+3. Interface name, to be provided as i.e. `option ifname 'wl0.1'`
+4. Device that the interface belongs to, to be provided as i.e. `option device 'wl0'`
+
+
+#### Fronthaul Interfaces
+
+Fronthaul interfaces are `fh-iface` sections with `multi_ap '2'` set. This
+section may also include the options `ssid`, `key`, `encryption`, and `vid`.
+Today these are not mandatory.
+
+```
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-44D4376AF7F0-5GHz'
+ option key 'IFJBD2RGYLZ3NE'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+```
+
+
+#### Backhaul Interfaces
+
+Backhaul interfaces are `fh-iface` sections with `multi_ap '1'` set. This
+section may also include the options `ssid`, `key`, `encryption`, and `vid`.
+Today these are not mandatory.
+
+```
+config fh-iface
+ option ifname 'wl0.2'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-44D4376AF7F0-BH-5GHz'
+ option key 'd6971d59b096ba3906d20f50dde7e19e7159dfe6eea1765a414e17c90aaefe7a'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+```
+
+
+
+#### Combined Front/Back Interfaces
+
+Combined fronthaul/backhaul interfaces are `fh-iface` sections with
+`multi_ap '3'` set. This section may also include the options `ssid`, `key`,
+`encryption`, and `vid`. Today these are not mandatory.
+
+```
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-44D4376AF7F0-COMBINED-5GHz'
+ option key 'IFJBD2RGYLZ3NE'
+ option encryption 'psk2+aes'
+ option multi_ap '3'
+ option vid '1'
+```
+
+
+#### Backhaul Station Interfaces
+
+Backhaul station interfaces are `bk-iface` sections.
+
+Backhaul interface sections will be generated automatically by map-agent upon
+startup. This is because it is assumed a backhaul station is only relevant in
+a multi-ap network scenario.
+
+Once onboarded, a bk-iface may be marked as `option onboarded '1'` by map-agent,
+along with the respective `wifi-radio` section. An onboarded backhaul station
+may look as follows:
+
+```
+config bk-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+ option onboarded '1'
+```
+
+
+## Onboarding
+
+Onboarding encompasses WPS pushbutton event, backhaul credential exchange and
+establishment of the wireless link between two devices.
+
+The prerequisites will be written from a dedicated backhaul and fronthaul
+interface. If using a combined fronthaul/backhaul interface the steps still
+apply, with the exception of the uci options `multi_ap_backhaul_ssid` and
+`multi_ap_backhaul_key` may be left out, and WPS be started on the combined
+interface.
+
+### Prerequisites
+
+* To perform onboarding, mapagent must be running at both the registrar
+and enrollee node.
+* The registrar radio and enrollee radio must be running in a
+compatible band and channel for the WPS exchange to take place.
+* The wireless uci configuration must have the backhaul credentials in the
+fronthaul secition under the keys `multi_ap_backhaul_ssid` and
+`multi_ap_backhaul_key`.
+* Enrollee backhaul sta interface must not be a part of a bridge
+* Enrollee and registrar interface must both have the multi_ap options set
+in the wireless config (1 and 2 respectively) for the multiap IE to be passed.
+
+
+### How to Start
+
+With the prerequisites in place, on the registrar, WPS must be started on the
+fronthaul interface with role registrar (default), as backhaul interfaces do not
+support WPS. However, with the `multi_ap` options set appropriately in the
+wireless configuration file a multiap IE will be passed with the WPS and the
+backhaul credentials be provided to the enrollee.
+
+Registrar:
+* `ubus call wifi.wps start '{"ifname":"wl0"}'`
+
+On the enrollee side, wps must be performed over the backhaul station interface,
+and the role `bsta` must be passed.
+
+Enrollee:
+* `ubus call wifi.wps start '{"ifname":"wl0", "role":"bsta"}'`
+
+When the devices pair, the credentials will be published as ubus event:
+```
+{ "wps_credentials": {"ifname":"wl0","encryption":"psk2", "ssid":"iopsysWrt-BACKHAUL-5GHz","key":"12345678BACKHAUL" }}
+```
+
+Mapagent will pick up this ubus event and add these credential to the uci
+wireless section and reload wifi, after which wpa_supplicant will establish a
+connection to the backhaul interface, over the backhaul station interface.
+When the `wifi.bsta` connection event comes over ubus:
+
+```
+{ "wifi.bsta": {"ifname":"wl0","event":"connected","data":{"macaddr":"0a:10:00:00:00:03","ssid":"iopsysWrt-BACKHAUL-5GHz"}} }
+
+```
+mapagent will issue DHCP to verify that it has entered 4address mode
+(wds link is up and added to the bridge on registrar) before adding the backhaul
+station to the bridge.
+
+Once backhaul station is in the bridge, onboarding is complete.
+
+
+## AP-Autoconfig
+
+AP-Autoconfig includes the triggering of AP-Autoconfig Search, AP-Autoconfig
+Response and AP-Autoconfig WSC and the configuration of the credentials provided
+with the AP-Autoconfig WSC.
+
+This will not include how to configure mapcontroller.
+
+### Prerequisites
+
+* Mapcontroller must be active in the network.
+
+
+### Mechanics
+
+AP-Autoconfig has a certain set of triggers with slight behavior differences.
+When understanding the different triggers, it is necessary to understand that
+during AP-Autoconfig, every radio will do its independent process, meaning
+AP-Autoconfig Search, Response and WSC.
+
+#### Radio State
+
+When a radio is available to be configured, will be consiered in an 'active'
+state, and when it is periodically probing it is considered to be in a
+'heartbeat' state.
+
+Some conditions that will set map-agent to an 'active' state
+* Upon mapagent (re)start
+* Establishing a connection over backhaul interface
+* No mapcontroller is observed for `probe_int` * `retry_int`
+* New mapcontroller is discovered
+
+#### Search Triggers
+
+All the triggers listed in [Radio State](#radio-state) will trigger
+AP-Autoconfig Search within a set time out (at most 5 seconds, depending on
+the event). Additionally it may be triggered by:
+* Periodic interval `probe_int` (defaults to 20s)
+* Connecting ethwan port.
+
+
+#### Upon Completion
+
+After AP-Autoconfig is completed, for a respective radio, there will be an event
+published over ubus:
+
+```
+{ "wifi.radio": {"ifname":"wl0","event":"ap-autoconfiguration","data":{"status":"success","reason":"completed"}} }
+```
+
+
+Map-agent will wait for 5 seconds to account for any disruption and delayed
+CMDUs and then restart wifi - to be sure that all WSC that are coming over the
+link are received and processed.
+
+After processing of the WSC CMDUs the mapagent config will have changed
+according to the received WSC:
+
+```
+config agent 'agent'
+ option enabled '1'
+ option debug '0'
+ option profile '2'
+ option brcm_setup '1'
+ option al_bridge 'br-lan'
+ option netdev 'wl'
+ option controller_mac 'ee:6c:9a:52:b0:27'
+
+config controller_select
+ option local '0'
+ option id 'auto'
+ option probe_int '20'
+ option retry_int '9'
+ option autostart '1'
+
+config bk-iface
+ option ifname 'wl0'
+ option band '5'
+ option device 'wl0'
+ option onboarded '1'
+
+config wifi-radio
+ option device 'wl0'
+ option band '5'
+
+config wifi-radio
+ option device 'wl1'
+ option band '2'
+
+config fh-iface
+ option ifname 'wl0.1'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-EC6C9A52B027-5GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl0.2'
+ option band '5'
+ option device 'wl0'
+ option ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl1'
+ option band '2'
+ option device 'wl1'
+ option ssid 'MAP-EC6C9A52B027-2.4GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option multi_ap '2'
+ option vid '1'
+
+config fh-iface
+ option ifname 'wl1.1'
+ option band '2'
+ option device 'wl1'
+ option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vid '1'
+```
+
+And similarily the wireless config:
+
+
+```
+config wifi-iface 'wl1_ap'
+ option ifname 'wl1'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-2.4GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option multi_ap_backhaul_key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+
+config wifi-iface 'wl1_1_ap'
+ option ifname 'wl1.1'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option hidden '1'
+
+config wifi-iface 'default_sta_wl2'
+ option device 'wl0'
+ option mode 'sta'
+ option ifname 'wl0'
+ option multi_ap '1'
+ option disabled '0'
+ option encryption 'psk2'
+ option ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option wds '1'
+
+config wifi-iface 'wl0_ap'
+ option ifname 'wl0.1'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-5GHz'
+ option key '7NTx-APvX-pba7-tvd7'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option multi_ap_backhaul_key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+
+config wifi-iface 'wl0_1_ap'
+ option ifname 'wl0.2'
+ option network 'lan'
+ option ssid 'MAP-EC6C9A52B027-BH-5GHz'
+ option key '8e91bbf3959dfc17866aee7cd7813d30bc8bb75ac40345be6d72f896ee230d5a'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
+ option hidden '1'
+
+config wifi-device 'wl0'
+ option type 'mac80211'
+ option channel '100'
+ option hwmode '11a'
+ option country 'DE'
+ option htmode 'HE80'
+ option apsta '0'
+ option phy 'phy0'
+
+config wifi-device 'wl1'
+ option type 'mac80211'
+ option channel '11'
+ option hwmode '11g'
+ option country 'DE'
+ option htmode 'HE20'
+ option apsta '0'
+ option phy 'phy1'
+
+```
+
+Do note that a backhaul station interface will never be torn down by mapagent.
+
+## Controller Discovery
+
+
+### UCI
+
+The following UCI config section in “mapagent” config is used to control how a
+MAP Controller is discovered and (auto)started/stopped on demand in a MAP
+network.
+
+```
+config controller_select
+ option local ‘true’
+ option id ‘auto’
+ option probe_int ‘20’
+ option retry_int ‘3’
+ option autostart ‘true’
+```
+
+| Name | Type | Required | Default | Description |
+| ------------- |---------------| ----------|-------------|---------------|
+| local | Boolean | yes | false | When set to true, the MAP Controller running in the same 1905 device as the MAP Agent, will be treated as the main or primary Controller. It takes precedence over others discovered in the network. |
+| id | Mac address | no | auto-detect | User can provide the 1905 ALID of the device that will have the MAP Controller service. When set to ‘auto’, the MAP Agent will discover the MAP Controller ID. OPTION NOT YET SUPPORTED. |
+| probe_int | Integer | no | 20s |The time interval in seconds between controller discovery by the MAP Agent |
+| retry_int | Integer | no | 15 |After these many failed attempts to discover a controller in the network, the agent will infer that the controller is not available and accordingly takes the next action. |
+| autostart | Boolean | no | false |When this is set to ‘true’, the agent will try to start the controller after not finding one in the network. |
+
+
+### Algorithm
+
+During startup and at run-time, the MAP Agent will probe for the presence of a
+MAP Controller in the network.
+
+If it finds another, then take one of the following actions:
+
+1. If a MAP Controller is NOT running in the own device, then update its
+Controller-ID and the last-seen timestamp.
+
+2. If a MAP Controller is running in its own device, and local = true, then
+notify the detected Controller to user (e.g.: over UBUS).
+
+3. If a MAP controller is running in its own device, and local = false, then
+stop the local Controller. Update the Controller-ID and the last-seen timestamp.
+
+If after ‘retry_int’ number of times, the MAP Agent cannot discover a MAP
+Controller in the network, then take one of the following actions:
+
+1. When autostart = true, the MAP Agent will try to start the MAP Controller
+locally (*). Report status of the MAP Controller start to user (e.g.: over UBUS).
+
+2. When autostart = false, the MAP Agent will simply report to user (over UBUS)
+that no Controller has been detected in the network.
+
+Notes:
+
+* The default time interval in seconds between controller discovery by the
+ MAP Agent will increase to 70 seconds once Agent enters the heartbeat state
+ (that is after controller discovery finished successfully).
+* Maximum time w/o controller in the network will be (probe_int * retry_int)
+ - but not less than 75 seconds.
+* After detecting no Controller in the network, the MAP-Agent will try to start
+its local Controller after a random time chosen from a time window (10s). This
+helps to reduce the chance of multiple MAP-Agents trying to run the controller
+at the same time.
+
+### Example
+
+While the aim for this controller discovery is to support the same configuration
+across all devices, one may want to have a designated mapcontroller device, then
+the following configuration may be used:
+
+Main Device (i.e. SmartHub3/Fibertwist): Controller to be run in a designated
+node only.
+
+```
+config controller_select
+ option local ‘true’
+```
+
+Repeater Device (Disc/EX600): Controller start/stop automatically if another is
+not detected in the network.
+
+```
+config controller_select
+ option local ‘false’
+ option autostart ‘true’
+```
+
+
+## uBus
+
+```
+root@iopsys:~# ubus -v list map.agent
+'map.agent' @41d34dcd
+ "apconfig":{"band":"Integer"}
+ "steer_policy":{"vif":"String","rule":"String","order":"String"}
+ "steer":{"vif":"String","type":"String","sta":"String","to_bss":"Array","optime":"Integer"}
+ "assoc_control":{"vif":"String","sta":"String","enable":"Boolean","time":"Integer"}
+ "bcn_metrics_query":{"agent":"String","sta":"String","opclass":"Integer","channel":"Integer","bssid":"String","reporting_detail":"Integer","ssid":"String","channel_report":"Array","request_element":"Array"}
+ "cmd":{"id":"Integer","data":"String"}
+ "cmd_async":{"id":"Integer","data":"String"}
+ "status":{}
+```