external/DAWN
1
0
Fork 0
mirror of https://github.com/berlin-open-wireless-lab/DAWN.git synced 2025-02-12 08:41:51 +00:00
Code Issues Releases Wiki Activity

documentation: Heavily revised Markdown documentation files:

Browse source 
- README.md: Top level intro
- INSTALL.md: Typical user installation
- CONFIGURE.md: Detailed description of how parameters work together, and how to set each one
- DEVELOPER.md: How to build a local version, some notes on dev time "helpers", etc

[fix commit message]
Signed-off-by: Nick Hainke <vincent@systemli.org>
This commit is contained in:
Ian Clowes 2022-02-06 17:58:20 +00:00 committed by Nick Hainke
parent 850a75c182
commit 0e4fc507cb
4 changed files with 390 additions and 155 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

179
CONFIGURE.md Normal file
View file

@ -0,0 +1,179 @@
# Configuring DAWN
## Making Configuraton Changes
Edit settings under
/etc/config/dawn
After changes, restart daemon
/etc/init.d/dawn restart
The updated configuration can be shared with other DAWN instances via ubus:
ubus call dawn reload_config
## What Can Be Configured?
The parameters that control DAWN are listed alphabetically below. This section describes how they are grouped to provide various features.
### Client 'Kicking'
DAWN's primary purpose is to move (aka "kick") client devices to the best AP. This is enabled via the `kicking` parameter. If it is zero you will see no devices being moved, but can use the log messages to see what would happen.
See also "Note 1: Legacy Clients"
### Client Connection Scoring
DAWN calculates a "score" for the actual or potential connection between an AP and a client device. These values ar ehten compared to decide whether to move a client. The score includes several factors:
- The radio connection quality, see "Note 2: RSSI Scoring"
- Support for 802.11 features that improve throughput, see `ht_support`, `no_ht_support`, `vht_support` and `no_vht_support`
- How heavily the relevant radio is being used across all clients, see `chan_util`, `chan_util_val`, `max_chan_util` and `max_chan_util_val`
- How busy the current cliet-AP connection is, see `bandwidth_threshold`
- How many clients are connected to the AP, see `use_station_count` and `max_station_diff`
- Whether sufficiently better APs for the client have been consistently found (rather than for example as a one-off due to walking past a wall), see `kicking_threshold` and `min_number_to_kick`
### Other Features
The following are less likely to need attention:
- The way 802.11v Neighbor Reports are generated can be adjusted.
- `disassoc_nr_length` controls the number of entries in the list.
- `set_hostapd_nr` controls the mechanism used to build the AP NR
- "Static" will be sufficient for a small network, and contain all the AP entries
- "Dynamic" will allow a large network to automatically determine the optimal set for each AP, and contain a set of nearby APs
- 802.11k has a number of methods for gathering BEACON reports. The preference for Passive, Active or Table can be set via `rrm_mode`
## Configuration Notes
### Note 1: Legacy Clients
802.11v introduced the capability for clients to be "politely" asked to move to a different AP, and DAWN uses this capability for clients that appear to support it.
By definition, there is no way to do this for clients that don't implement 802.11v. For these "legacy clients" DAWN can attempt to steer them away during the PROBE / ASSOCIATE / AUTHENTICATE process by returning status codes that indicate errors or unwillingness to accept. It can also force disconnection of a connected client by "tearing down" the connection, however this is quite brutal as the client then has to start a search for a new AP, and it may just want to come back to the same AP. If DAWN continues to try to not accept the client it is effectively denied wifi access.
If you enable this legacy client behaviour via parameters indicated then you may hit challenges as it is less tested and reliable than the 802.11v supported steering. Reports on its success or otherwise are welcomed so it can be refined if necessary and possible (within the constriants of 802.11).
See: `eval_probe_req`, `eval_auth_req`, `eval_assoc_req`, `deny_auth_reason`, `deny_assoc_reason`, `min_probe_count` and `kicking`
### Note 2: RSSI Scoring
As a part of the scoring mechanism DAWN provides two mechanisms for evaluating the client-AP RSSI (radio signal) quality. Although DAWN does not prevent both mechanisms being enabled at the same time (via the relevant increment parameters) it may be difficult to obtain desired behaviour.
Mechanism 1 is "stepped". If the RSSI value is better than the `rssi_val` value (or worse than the `low_rssi_val` value) then the AP score has the `rssi` (or `low_rssi`) increment values applied. This effective creates three "zones" of RSSI score, which may be sufficient for many cases. To disable this mode set both increment values to zero.
Mechanism 2 is "graduated". For each dB that the RSSI signal differs from the `rssi_centre` value the increment `rssi_weight` is applied. This can provide a more refined score, but may require more effort to get the parameters optimised. To disable this mode set the increment value to zero.
## Feature Parameters
These parameters go in the following section:
config metric 'global'
And if marked with '+' are specified / repeated in each of these band specific sections (but not the 'global' section):
config metric '802_11a'
config metric '802_11g'
<!-- Use the following shell command to auto-generate the table rows from DAWN source code:
grep 'CONFIG-[FS]:' `find . -type f -name "*.[ch]"`|sed 's/^.*CONFIG-.: *\(.*\)$/|\1|/'|sort
-->
|Parameter|Purpose|Notes|
|---------|-------|-----|
|bandwidth_threshold|Maximum reported AP-client bandwidth permitted when kicking|Default = 6 (Mbits/s)|
|chan_util_avg_period|Number of sampling periods to average channel utilization values over|Default = 3|
|chan_util+|Score increment if channel utilization is below chan_util_val|Default = 0|
|chan_util_val+|Threshold for good channel utilization|Default = 140|
|deny_assoc_reason|802.11 code used when ASSOCIATION is denied|17 = AP_UNABLE_TO_HANDLE_NEW_STA. See Note 1.|
|deny_auth_reason|802.11 code used when AUTHENTICATION is denied|1 = UNSPECIFIED_FAILURE. See Note 1.|
|disassoc_nr_length|Number of entries to include in a 802.11v DISASSOCIATE Neighbor Report|Default = 6, as documented for use by iOS|
|duration|802.11k BEACON request DURATION parameter|Default = 0|
|eval_assoc_req|Control whether ASSOCIATION frames are evaluated for rejection|0 = No evaluation; 1 = Evaluated. See Note 1.|
|eval_auth_req|Control whether AUTHENTICATION frames are evaluated for rejection|0 = No evaluation; 1 = Evaluated. See Note 1.|
|eval_probe_req|Control whether PROBE frames are evaluated for rejection|0 = No evaluation; 1 = Evaluated. See Note 1.|
|ht_support+|Score increment if HT is supported|Default = 10|
|initial_score+|Base score for AP based on operating band|2.4GHz = 0; 5Ghz = 100|
|kicking|Actively move clients to the best AP|0 = Disabled; 1 = Enabled for 802.11v clients; 2 = Also enabled for pre-802.11v clients. See note 1.|
|kicking_threshold|Minimum score difference to consider kicking to alternate AP|Default = 20|
|low_rssi+|Score addition when signal is below threshold|Default = -500. See note 2.|
|low_rssi_val+|Threshold for bad RSSI|Default = -80. See note 2.|
|max_chan_util+|Score increment if channel utilization is above max_chan_util_val|Default = -500|
|max_chan_util_val+|Threshold for bad channel utilization|Default = 170|
|max_station_diff|Number of connected stations to consider "better" for use_station_count|Default = 1|
|min_number_to_kick|Number of consecutive times a client should be evaluated as ready to kick before actually doing it|Default = 3|
|min_probe_count|Number of times a client should retry PROBE before acceptance| Default of 3. See Note 1.|
|neighbors+|Space seperated list of MACS to use in "static" AP Neighbor Report| None|
|no_ht_support+|Score incrment if HT is not supported|Default = 0 (Deprecated)|
|no_vht_support+|Score incrment if VHT is not supported|Default = 0 (Deprecated)|
|rrm_mode|Preferred order for using Passive, Active or Table 802.11k BEACON information|String of 'P', 'A' and / or 'T'|
|rssi_center+|Midpoint for weighted RSSI evaluation|Default = -70. See note 2.|
|rssi+|Score addition when signal exceeds threshold|Default = 10. See note 2.|
|rssi_val+|Threshold for an good RSSI|Default = -60. See note 2.|
|rssi_weight+|Per dB increment for weighted RSSI evaluation|Default = 0. See note 2.|
|set_hostapd_nr|Method used to set Neighbor Report on AP|0 = Disabled; 1 = "Static" based on all APs in network (plus set from configuration); 2 = "Dynamic" based on next nearest AP seen by current clients|
|use_station_count|Compare connected station counts when considering kicking|0 = Disabled; 1 = Enabled|
|vht_support+|Score increment if VHT is supported|Default = 100|
## Networking Parameters
TCP networking with UMDNS and without encryption is the most tested and stable configuration.
Encryption has been reported to be broken, so use it with caution.
Other parameters have fallen out of use, but remain in the code. A tidy up of them is due.
These parameters go in the following section:
config network
<!-- Use the following shell command to auto-generate the table rows from DAWN source code:
grep 'CONFIG-N:' `find . -type f -name "*.[ch]"`|sed 's/^.*CONFIG-.: *\(.*\)$/|\1|/'|sort
-->
|Parameter|Purpose|Notes [Default is bracketed]|
|---------|-------|-----|
|bandwidth|Unused|N/A|
|broadcast_ip|IP address for broadcast and multicast|No default|
|broadcast_port|IP port for broadcast and multicast|[1026]|
|collision_domain|Unused|N/A|
|iv|Unused|N/A|
|network_option|Method of networking between DAWN instances|0 = Broadcast; 2 = Multicast; [2 = TCP with UMDNS discovery]; 3 = TCP w/out UMDNS discovery|
|server_ip|IP address when not using UMDNS|No default|
|shared_key|Unused|N/A|
|tcp_port|Port for TCP networking|[1025]|
|use_symm_enc|Enable encryption of network traffic|[0 = Disabled]; 1 = Enabled|
## Local Parameters
Local parameters are not shared with other DAWN instances.
These parameters go in the following section:
config local
<!-- Use the following shell command to auto-generate the table rows from DAWN source code:
grep 'CONFIG-L:' `find . -type f -name "*.[ch]"`|sed 's/^.*CONFIG-.: *\(.*\)$/|\1|/'|sort
-->
|Parameter|Purpose|Notes [Default is bracketed]|
|---------|-------|-----|
|loglevel|Verbosity of messages in syslog|[0 = Important only - very few messages]; 1 = Show what DAWN is processing in a user friendly way; 2 = Trace certain operations - for debugging; 3 = Broad low level tracing - for debugging|
## Timing / Scheduling Parameters
All timer values are in secinds. They are the main mechanism for DAWN collecting and managing much of the data that it relies on.
These parameters go in the following section:
config times
<!-- Use the following shell command to auto-generate the table rows from DAWN source code:
grep 'CONFIG-T:' `find . -type f -name "*.[ch]"`|sed 's/^.*CONFIG-.: *\(.*\)$/|\1|/'|sort
-->
|Parameter|Purpose|Notes [Default is bracketed]|
|---------|-------|-----|
|remove_ap|Timer to remove expired AP entries from core data set|[460]|
|remove_client|Timer to remove expired client entries from core data set|[15]|
|remove_probe|Timer to remove expired PROBE and BEACON entries from core data set|[30]|
|update_beacon_reports|Timer to ask all connected clients for a new BEACON REPORT|[20]|
|update_chan_util|Timer to get recent channel utilisation figure for each local BSSID|[5]|
|update_client|Timer to send revised NEIGHBOR REPORT to all clients|[10]|
|update_hostapd|Timer to (re-)register for hostapd messages for each local BSSID|[10]|
|update_tcp_con|Timer to refresh / remove the TCP connections to other DAWN instances found via uMDNS|[10]|
## hostapd Parameters
These parameters go in the following section:
config hostapd
<!-- Use the following shell command to auto-generate the table rows from DAWN source code:
grep 'CONFIG-H:' `find . -type f -name "*.[ch]"`|sed 's/^.*CONFIG-.: *\(.*\)$/|\1|/'|sort
-->
|Parameter|Purpose|Notes [Default is bracketed]|
|---------|-------|-----|
|hostapd_dir|Path to hostapd runtime information|[/var/run/hostapd]|

102
DEVELOPER.md Normal file
View file

@ -0,0 +1,102 @@
# DAWN Developer Guide
This is an introduction to DAWN for developers that want to understand how it works so that they can modify, fix, etc its behaviour.
## Component Overview
DAWN collects and shares information about the APs and clients in the network by using a number of standard components. The below assumes it is running on an OpenWrt device.
![OpenWrtInANuthshell](https://raw.githubusercontent.com/PolynomialDivision/upload_stuff/master/dawn_pictures/openwrt_in_a_nutshell_dawn.png)
Information about capability of the AP and current clients is discovered via the hostapd and iwinfo. The task to do this is scheduled by a timer.
hostapd also shares information about potential clients that are trying to connect, as received in 802.11 PROBE, AUTH and ASSOC requests, plus BEACON frames for 802.11k capable devices.
Communication with hostapd is via UBUS messages and callbacks.
This data is then exchanged with other DAWN instances that have been discovered via uMDNS. This means that every DAWN instance has a list of all clients and APs in the network, plus which APs have seen a clients (even if it is not a client). The most tested and stable method of doing this is via TCP. There are options for multicast and broadcast, but these are less tested and may fail.
Internally to DAWN these sets of data are stored as linked lists, which allow scalability while ensuring that memory usage is reduced in a small network. Additional timers are used to remove "expired" data from these lists, so only a reasonably recent set is retained.
Another timer triggers periodically to ask the AP to look at each locally connected client and see if a better AP might be available. This is achieved by calculating a score for every AP that has a recent BEACON or PROBE entry for the client based on signal strength, band, etc. The scoring mechanism is described in the Configuration page.
If one or more other APs have a sufficiently better score then the current AP the device is asked to move using an 802.11 frame that DAWN requests (via UBUS) hostapd to send. For an 802.11v capable device a Disassociation Imminent frame is sent to encourage it to select one of the better APs in a DAWN generated Neighbor Report. For pre-802.11k devices a Deauthentication can be forced [TODO: Check this].
Additionally, for an 802.11k capable AP DAWN will use the BEACON reports from other APs to create a Neighbor Report for the AP. For instance if clients CL-A, CL-B and CL-C of AP-X report that they have reasonable signal strength to AP-M, AP-Q and AP-T then the NR for AP-X will be AP-M + AP-Q + AP-T. Other APs in the network that those clients can't see will not be in the NR.
# Creating a DAWN Development Environment
The code base for the main DAWN applicaton is C. It makes heavy use of pointers and pointer related structures such as linked lists. Although it is a single executable there are multiple code entry points that are used by callback functions, etc. Familiarity with C memory management, simple event based programming and resource management in a multi-threaded application is a baseline for working effectively with the code.
## Compiling DAWN
This section describes how to add tha currently published version of DAWN to a local OpenWrt build environment, so that you can add DAWN to locally built firmware images or the Image Builder target. It assumes you have some familiarity with building OpenWrt, so is more of an "aide memoir" than specific steps. In other words, just copying and pasting the below will not work!
Clone Openwrt
https://git.openwrt.org/openwrt/openwrt.git
Update Feeds
./scripts/feeds update -a
Install DAWN
./scripts/feeds install dawn
Add DAWN to the build (under `Network -> dawn`)
make menuconfig
Compile
make package/dawn/compile
## Creating a local DAWN development instance
This section describes how to configure the OpenWrt build environment to use an alternate source code version, so you can work on that code. Do the above Compiling Dawn steps first.
Enable local source code (under `Advanced Configuration -> Enable package source-tree override`)
make menuconfig
Now you need to clone DAWN, e.g. into your home directory
git clone https://github.com/berlin-open-wireless-lab/DAWN.git ~/DAWN
You have to add now a symlink. In the openwrt branch do something like
ln -s ~/DAWN/.git/ ~openwrt/feeds/packages/net/dawn/git-src
Now compile dawn
make package/dawn/{clean,compile}
You should then be able to copy the dawn binary executable file to your device to test your changes.
## DAWN Quality Assurance
### Runtime Messages
Helper macros and functions are provied to assist with appropriate management of messages. The general convention is to issue messages one of the following priorities:
- ERROR (0): A significant runtime failure, such as memory exhaustion or unexpected ability to write to a network socket.
- WARNING (0): An algorithmically unexpected event, such as no AP seeming to be the host for a client device.
- ALWAYS (0): An infrequent information message that a user or administrator will want to see, such as a device being kicked from one AP to another.
- INFO (1): Reasonably frequent messages that indicate normal operation, such as the arrival of hostapd messages. The log should still be "user friendly" at this level.
- TRACE (2): Messages that help indicate why a decision or code path was taken.
- DEBUG (3): Verbose tracing of code paths, etc.
The minimum logging level (as specified in /etc/config/dawn) at which the priority appears is indicated, eg (0).
### Memory handling
There are wrappers for the standard C memory management functions malloc(), free(), etc. These help ensure that memory allocation is managed correctly by building a list of resources that have been allocated but not released.
While DAWN is running sending a HUP signal to the process will generate a list of currently allocated blocks in the system log, visible with logread.
In a small network ony a few tens of blocks are needed. A longer list may suggest a memory leak, and inspection of the list to find multiple items allocated at the same line of code may indicate where it is arising.
### MUTEX Handling
DAWN has a set of data lists that are accessed by code which is triggered by multiple event types (timer, network message, ubus message, etc). Because of this there is a chance that data could become corrupted by competing blocks of code, leading to invalid memory access, process faults, etc. Access to these resources is therefore managed by POSIX Threads mutex objects.
These potential problems will not be seen on a platform that is highly non-preemptive, so to help track down mutex handling errors such as accessing a resource without an appropriate lock helper functions are available. This helps ensure that when the same code is run on platforms which use pre-emptive scheduling it is less likely to hit threading bugs.
dawn_mutex_require() can be used to indicate that a segment of code is accessing a resource that should be locked. Often the lock should be taken by a "higher up" block of code, and if it hasn't been a runtime warning will appear in the system log. Further messages in the logs from dawn_mutex_lock() and ..._unlock() can be used to help review threading issues, such as trying to take a lock twice, not at all, etc.
### Test Harness
In addition to the dawn binary another named test_storage is built by CMAKE. This can be used to excercise the core data storage and scoring algorithms to ensure that expected behaviour occurs. At the time of writing a number of *.script files exist that can be passed to test_storage, but these haven't necessrily been maintained as the code has evolved from when they were originally written.

125
INSTALL.md
View file

@ -1,62 +1,101 @@
## Installation # DAWN Installation and Configuration
This guide should allow you to get DAWN running, and check its basic behaviour.
### Compiling DAWN ## Setting up Routers
DAWN will typically run in a network where one AP is providing core networking services like DHCP and internet gateway, while other APs are being used to extend wifi network range. For example the "main" AP near the telecoms provider entry point, and one or more other AP on the other side of the house, in the garden, etc. Or a number of AP distributed about an office building.
Update Feeds The term "dumb AP" is typically used for the extending APs, meaning that they don't directly provide those DHCP type services. If adding APs for the first time as a part of the plan to make DAWN work then it's important to have them configured correctly, and you can find a good guide to that [here](https://gist.github.com/braian87b/bba9da3a7ac23c35b7f1eecafecdd47d).
./scripts/feeds update -a ## Installing DAWN
### Install a full version of WPAD
Use the local package manager to install a full version of wpad, for example on OpenWrt:
Install DAWN opkg update
opkg remove wpad-basic wpad-mini
opkg install wpad-openssl
./scripts/feeds install dawn ### Install DAWN
The published verson of DAWN should install easily:
Select dawn under opkg install dawn
make menuconfig ### Developers
If you want to install versions of DAWN that are not fully packaged yet or to work on a fork of the code yourself then see the [Developer Guide](DEVELOPER.md).
Compile ## Configuring DAWN
make package/dawn/compile Review the configuration guide to see what you might want to change [configuration guide](CONFIGURE.md). At a minimum:
## Compile Latest DAWN - Be sure to enable the DAWN functions that you want (at least "kicking")
Clone Openwrt ## Check That DAWN Is Running
By default DAWN won't send much to the system log, so it can be hard to see if it is working at all.
https://git.openwrt.org/openwrt/openwrt.git If you have an 802.11k/v enaled device then if you place it close to one AP until it connects, and then move it close to another you should see a message after a minute or so where DAWN is asking the device to move to the other AP:
Update feeds logread -f | grep dawn
<Message here that shows transfer>
./scripts/feeds update packages If you'd like to see more messages to help confirm DAWN is interacting with the relevant services then edit the config file to set the messaging level to '1'.
install dawn ## See What DAWN Is Seeing
Once it has been running for a few minutes you can query the running DAWN instance via UBUS to understand what view of the network it has constructed.
./scripts/feeds install dawn To get an overview of all connected Clients sorted by the SSID, then AP BSSID, then device MAC:
Now do root@OpenWrt:~# ubus call dawn get_network
{
"Free-Cookies": {
"00:27:19:XX:XX:XX": {
"78:02:F8:XX:XX:XX": {
"freq": 2452,
"ht": 1,
"vht": 0,
"collision_count": 4
}
},
"A4:2B:B0:XX:XX:XX": {
"48:27:EA:XX:XX:XX: {
"freq": 2412,
"ht": 1,
"vht": 0,
"collision_count": 4
},
}
},
"Free-Cookies_5G": {
}
}
make menuconfig To get the view of which AP each client can see you can use:
Select `Advanced Configuration -> Enable package source-tree override`. root@OpenWrt:~# ubus call dawn get_hearing_map
{
Further, select dawn under `Network -> dawn`. "Free-Cookies": {
"0E:5B:DB:XX:XX:XX": {
Now you need to clone DAWN, e.g. into your home directory "00:27:19:XX:XX:XX": {
"signal": -64,
git clone https://github.com/berlin-open-wireless-lab/DAWN.git ~/DAWN "freq": 2452,
"ht_support": true,
You have to add now a symlink. In the openwrt branch do something like "vht_support": false,
"channel_utilization": 12,
ln -s ~/DAWN/.git/ feeds/packages/net/dawn/git-src "num_sta": 1,
"ht": 1,
Now compile dawn "vht": 0,
"score": 10
make package/dawn/clean && make package/dawn/compile },
"A4:2B:B0:XX:XX:XX": {
### Configure Dawn "signal": -70,
"freq": 2412,
Edit settings under "ht_support": true,
"vht_support": false,
/etc/config/dawn "channel_utilization": 71,
"num_sta": 3,
Restart daemon "ht": 1,
/etc/init.d/dawn restart "vht": 0,
"score": 10
}
}
}
}

139
README.md
View file

@ -1,121 +1,36 @@
![DAWN PICTURE](https://image.ibb.co/nbmNfJ/dawn_bla.png) ![DAWN PICTURE](https://image.ibb.co/nbmNfJ/dawn_bla.png)
# DAWN # DAWN
Decentralized WiFi Controller DAWN is a decentralized controller for wi-fi clients (eg, laptops, phones) that aims to ensure that each client is connected to an access point (AP, aka "wifi router") that will give good network throughput. This reduces wastage of radio capacity due to weak / distant radio connections that cause transmission retry, degredation of speed, etc.
## Installation Decentralised means that DAWN is a peer-peer network of instances - there is no controlling "master" node. Every instance of DAWN will find its peers via uMDNS (aka Bonjour) network discovery. Further DAWN instances can therfore be added without explicit configuration of the whole network, reducing network maintenance overhead.
**You need full wpad installation and not wpad-basic**. ## Installation and Configuration
See [installation](INSTALL.md). Installing DAWN is quite simple. The TL;DR version for anyone not wanting to read the [installation guide](INSTALL.md) is:
- **Be sure to install a full wpad-\* version and not wpad-basic**
- Be sure to configure extender routers as "dumb AP"
Top tip from the [configuration guide](CONFIGURE.md):
- Be sure to enable the DAWN functions that you want (at least "kicking")
## How DAWN Works
Each DAWN instance gathers information about two types of client: those that are currently connected to the host AP, plus those querying whether to connect. It then shares that information with other DAWN instances. Each then has a view of how well any AP can "see" each client device, and that then allows DAWN to steer a client to a different AP when appropriate.
For example, if a device is currently connected to AP1 with a signal strength of -65dB it may be quite happy to stay there because many devices will not look to roam until the signal goes past -70dB (note the minus sign: -70dB is more negative / worse than -65dB). However, if DAWN on AP1 knows that the same device can see AP2 at a level of -55dB then DAWN can tell the device to switch to AP2, which will improve overall radio performance if applied to multiple devices across multiple AP.
DAWN can also evaluate other parameters that a device may not include in its roaming decisions, such as currently connected clients per AP, availability of speed enhancing capabilities, etc. However, it is ultimately for a client device to decide which AP it will connect to so it may ignore DAWN's proposal, especially if it is using a significantly different algorithm to DAWN.
DAWN works best with networks where AP and devices have 802.11k capailites for discovering the quality of radio signals, plus 802.11v for requesting devices to move to a different AP. If 802.11r is enabled for fast, seamless transfer of a device across APs then it enhances the overall user experience, but DAWN doesn't directly use it.
802.11k/r/v were developed to enable the type of functionality that DAWN provides, so older devices that do not have these capabilites are by definition harder to control. DAWN will try to steer "legacy" devices if configured to do so, but it can be a less than perfect user experience due to the time taken to create connections to the new AP.
## LuCI App ## LuCI App
There is an luci app called [luci-app-dawn](https://github.com/openwrt/luci/tree/master/applications/luci-app-dawn). There is an luci app called [luci-app-dawn](https://github.com/openwrt/luci/tree/master/applications/luci-app-dawn) that adds some DAWN information to the management interface of an OpenWrt device.
## Setting up Routers
You can find a good guide to configure your router is [here](https://gist.github.com/braian87b/bba9da3a7ac23c35b7f1eecafecdd47d).
I setup the OpenWRT Router as dumb APs.
## Configuration
|Option |Standard | Meaning |
|-------------------|---------|---------|
|ht_support | '10' |If AP and station support high throughput.|
|vht_support | '100' |If AP and station support very high throughput.|
|no_ht_support | '0' |If AP and station not supporting high throughput.|
|no_vht_support | '0' |If AP and station not supporting very high throughput.
|rssi | '10' |If RSSI is greater equal rssi_val.|
|low_rssi | '-500' |If RSSI is less than low_rssi_val.|
|freq | '100' |If connection is 5Ghz.|
|chan_util | '0' |If channel utilization is lower chan_util_val.|
|max_chan_util | '-500' |If channel utilization is greater max_chan_util_val.|
|rssi_val | '-60' |Threshold for an good RSSI.|
|low_rssi_val | '-80' |Threshold for an bad RSSI.|
|chan_util_val | '140' |Threshold for an good channel utilization.|
|max_chan_util_val | '170' |Threshold for a bad channel utilization.|
|min_probe_count | '2' |Minimum number of probe requests aftrer calculating if AP is best and sending a probe response.|
|bandwidth_threshold | '6' |Threshold for the receiving bit rate indicating if a client is in an active transmission.|
|use_station_count | '1' |Use station count as metric.|
|max_station_diff | '1' |Maximal station difference that is allowed.|
|eval_probe_req | '1' |Evaluate the incoming probe requests.|
|eval_auth_req | '1' |Evaluate the incomning authentication reqeuests.|
|eval_assoc_req | '1' |Evaluate the incoming association requests.|
|deny_auth_reason | '1' |Status code for denying authentications.|
|deny_assoc_reason | '17' |Status code for denying associations.|
|use_driver_recog | '1' |Allow drivers to connect after a certain time.|
| min_number_to_kick | '3' | How often a clients needs to be evaluated as bad before kicking. |
| chan_util_avg_period | '3' | Channel Utilization Averaging |
| set_hostapd_nr | '1' | Feed Hostapd With NR-Reports |
| op_class | '0' | 802.11k beacon request parameters |
| duration | '0' | 802.11k beacon request parameters |
| mode | '0' | 802.11k beacon request parameters |
| scan_channel | '0' | 802.11k beacon request parameters |
## ubus interface
To get an overview of all connected Clients sorted by the SSID.
root@OpenWrt:~# ubus call dawn get_network
{
"Free-Cookies": {
"00:27:19:XX:XX:XX": {
"78:02:F8:XX:XX:XX": {
"freq": 2452,
"ht": 1,
"vht": 0,
"collision_count": 4
}
},
"A4:2B:B0:XX:XX:XX": {
"48:27:EA:XX:XX:XX: {
"freq": 2412,
"ht": 1,
"vht": 0,
"collision_count": 4
},
}
},
"Free-Cookies_5G": {
}
}
To get the hearing map you can use:
root@OpenWrt:~# ubus call dawn get_hearing_map
{
"Free-Cookies": {
"0E:5B:DB:XX:XX:XX": {
"00:27:19:XX:XX:XX": {
"signal": -64,
"freq": 2452,
"ht_support": true,
"vht_support": false,
"channel_utilization": 12,
"num_sta": 1,
"ht": 1,
"vht": 0,
"score": 10
},
"A4:2B:B0:XX:XX:XX": {
"signal": -70,
"freq": 2412,
"ht_support": true,
"vht_support": false,
"channel_utilization": 71,
"num_sta": 3,
"ht": 1,
"vht": 0,
"score": 10
}
}
}
}
## OpenWrt in a Nutshell
![OpenWrtInANuthshell](https://raw.githubusercontent.com/PolynomialDivision/upload_stuff/master/dawn_pictures/openwrt_in_a_nutshell_dawn.png)
NB: As of early-2022 it hasn't had the developer attention it needs recently, so may not be working as well as you might like.
## Developers
If you want to use versions of DAWN that are not fully packaged yet or to work on a fork of the code yourself then see the [Developer Guide](DEVELOPER.md).