README.md

# MAP Agent

[Map-agent](https://dev.iopsys.eu/iopsys/map-agent)


## Introduction

This package provides the mapagent daemon, which implements the WiFi Alliances
Easymesh Agent component.

## Overview

This README will show how to properly setup the mapagent configuration file
and explain some key features of map-agent:

* Onboarding
* AP-Autoconfiguration
* Controller Discovery
* Dynamic Controller Sync
* Dynamic Backhaul Upgrade
* Island Prevention

## UCI Configuration

For full documentation of UCI configuration options, see
[UCI docs](./docs/api/mapagent.md).

When starting map-agent, the only _mandated_ section is the global agent
section:

```
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 island_prevention '0'
	option eth_onboards_wifi_bhs '1'
	option guest_isolation '1'
	option scan_on_boot_only '0'
```

All the remaining mandatory (`radio`) and optionally mandatory (`ap`) may
be generated by map-agent at start-up. Whereas the non-mandatory sections may
use their default values.

The `ap` sections will be automatically generated based on the presence of a
`multi_ap` flag in the wireless configuration file under the `wifi-iface`
sections. If such a flag is set, map-agent assumes it is a multi_ap interface.
Nonetheless, it is recommended that the map-agent configuration is aligned
with the respective `ap` section for each interface that is to be a part of the
mesh and managed by map-agent. For more information on how to align the
map-agent and wireless configuration file, see the quick start [guide](./docs/QUICK_START.md).
Additional interfaces may be generated at runtime, as dictated by mapcontroller.

Existing interfaces *not* included in the configuration will not be a part of
the mesh, meaning no statistics will be gathered, clients steered and the
interface will never be torn down or otherwise configured by mapagent.

To summarize:
* Mapagent may automatically generate mandatory `radio` and optionally mandatory
`ap` sections
* Mapagent will manage all interface provided within its configuration file
* Mapagent will not touch interfaces not in its configuration file. They will
be left intact (and outside of the mesh) and be interleaved with any additional
interfaces provided by mapcontroller
* Mapagent will create interfaces as necessary, adding them to both mapagent
and wireless configuration files

**Some notes concerning multiap configuration files.**
While preparing the */etc/config/wireless* configuration, please note that some options may be changed during autoconfiguration proces.
Such options are wps_pushbutton and hidden of wifi-iface section. Actions taken and final value of those options depends mainly on type
of multi_ap interface (value of option multi_ap in current wifi-iface section).

For backhaul interfaces where
```
option multi_ap '1'
```
following rules apply:
* 'hidden' option when provided stays as it is,
* if 'hidden' option is not provided in that wifi-iface section, it is set to hidden=1 by adding
```
option hidden '1'
```

For fronthaul and combined interfaces where
```
option multi_ap '2'
or
option multi_ap '3'
```
following rules apply:
* 'wps_pushbutton' option when provided stays as it is,
* if 'wps_pushbutton' option is not provided in that wifi-iface section, it is set to wps_pushbutton=1 by adding
```
option wps_pushbutton '1'
```

Additional rule apply when traffic separation is enabled in */etc/config/mapcontroller* by
```
option enable_ts '1'
```
in controller section of that config.

Additional rule concerns guest network which should be added in */etc/config/mapcontroller* file always after already existing networks.
This rule is that guest network will always have wps_pushbutton disabled by
```
option wps_pushbutton '0'
```
always placed in that wifi-iface section.

### Example Start Configurations

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'
	option island_prevention '0'

config dynamic_backhaul
	option missing_bh_timer '60'

config controller_select
	option local '0'
	option id 'auto'
	option probe_int '20'
	option retry_int '9'
	option autostart '1'

config ap
	option ifname 'wl0.1'
	option band '5'
	option device 'wl0'

config ap
	option ifname 'wl1.1'
	option band '2'
	option device 'wl1'

config bsta
	option ifname 'wl0'
	option band '5'
	option device 'wl0'
	option priority '1'

config bsta
	option ifname 'wl1'
	option band '2'
	option device 'wl1'
	option priority '2'

config bsta
	option ifname 'wl2'
	option band '5'
	option device 'wl2'
	option priority '0'

config radio
	option device 'wl2'
	option band '5'
	option dedicated_backhaul '1
```

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 'auto'
	option hwmode '11a'
	option country 'DE'
	option htmode 'HE80'
	option apsta '1'
	option phy 'phy0'

config wifi-iface 'default_wl0'
	option device 'wl0'
	option network 'lan'
	option ifname 'wl0.1'
	option mode 'ap'
	option ssid 'iopsysWrt-EC6C9A52ACB7'
	option encryption 'psk2'
	option key 'wifiEC6C9A52ACB7'
	option wps '1'
	option wps_pushbutton '1'
	option ieee80211k '1'
	option bss_transition '1'
	option multi_ap '2'

config wifi-device 'wl1'
	option type 'mac80211'