markdown style formatting, adding content to configure

docs/about.md

@@ -1,10 +1,6 @@
-## About the Project
+# About the Project
 
-[Pwnagotchi](https://twitter.com/pwnagotchi) is an "AI" that learns from the WiFi environment and instruments 
+[Pwnagotchi](https://twitter.com/pwnagotchi) is an "AI" that learns from the WiFi environment and instruments [bettercap](https://www.bettercap.org/) in order to maximize the WPA key material that's being captured either passively or by performing deauthentication and association attakcs. This material is collected as pcap files containing any form  of handshake supported by [hashcat](https://hashcat.net/hashcat/), including [PMKIDs](https://www.evilsocket.net/2019/02/13/Pwning-WiFi-networks-with-bettercap-and-the-PMKID-client-less-attack/), full and half WPA handshakes.
-[bettercap](https://www.bettercap.org/) in order to maximize the WPA key material that's being captured either passively
- or by performing deauthentication and association attakcs. This material is collected as pcap files containing any form 
- of handshake supported by [hashcat](https://hashcat.net/hashcat/), including [PMKIDs](https://www.evilsocket.net/2019/02/13/Pwning-WiFi-networks-with-bettercap-and-the-PMKID-client-less-attack/), 
-full and half WPA handshakes.
 
 ![handshake](https://i.imgur.com/pdA4vCZ.png)
 
@@ -20,4 +16,4 @@ If instead you just want to use your own parameters and save battery and CPU cyc
 
 ## License
 
-`pwnagotchi` is made with ♥  by [@evilsocket](https://twitter.com/evilsocket) and the [amazing dev team](https://github.com/evilsocket/pwnagotchi/graphs/contributors). It's released under the GPL3 license.
+`pwnagotchi` is made with ♥  by [@evilsocket](https://twitter.com/evilsocket) and the [amazing dev team](https://github.com/evilsocket/pwnagotchi/graphs/contributors). It's released under the GPL3 license.

docs/configure.md

@@ -1,7 +1,6 @@
-### Connecting to your Pwnagotchi
+# Connecting to your Pwnagotchi
 
-Once you wrote the image file on the SD card, there're a few steps you'll have to follow in order to configure your unit properly, first, start with connecting the USB cable to the 
+Once you wrote the image file on the SD card, there're a few steps you'll have to follow in order to configure your unit properly, first, start with connecting the USB cable to the data port of the Raspberry Pi and the RPi to your computer. After a few seconds the board will boot and you will see a new Ethernet interface on your host computer.
-data port of the Raspberry Pi and the RPi to your computer. After a few seconds the board will boot and you will see a new Ethernet interface on your host computer.
 
 You'll need to configure it with a static IP address:
 
@@ -26,26 +25,32 @@ Moreover, it is recommended that you copy your SSH public key among the unit's a
 ssh-copy-id -i ~/.ssh/id_rsa.pub pi@10.0.0.2
 ```
 
-### Configuration
+## Configuration
 
-You can now set a new name for your unit by [changing the hostname](https://geek-university.com/raspberry-pi/change-raspberry-pis-hostname/). Create the `/root/custom.yml` file (either via SSH or by direclty editing the SD card contents from a computer) that will override 
+You can now set a new name for your unit by [changing the hostname](https://geek-university.com/raspberry-pi/change-raspberry-pis-hostname/). Create the `/root/custom.yml` file (either via SSH or by direclty editing the SD card contents from a computer) that will override the [default configuration](https://github.com/evilsocket/pwnagotchi/blob/master/sdcard/rootfs/root/pwnagotchi/config.yml) with your custom values.
-the [default configuration](https://github.com/evilsocket/pwnagotchi/blob/master/sdcard/rootfs/root/pwnagotchi/config.yml) with your custom values.
+
+## Language Selection
 
 For instance, you can change `main.lang` to one of the supported languages:
 
-* **english** (default)
+- **english** (default)
-* german
+- german
-* dutch
+- dutch
-* greek
+- greek
-* macedonian
+- macedonian
-* italian
+- italian
-* french
+- french
 
-The set the type of display you want to use via `ui.display.type` (if your display does not work after changing this setting, you might need to complete remove power from the Raspberry and make a clean boot).
+## Display Selection
+
+Set the type of display you want to use via `ui.display.type` (if your display does not work after changing this setting, you might need to completely remove power from the Raspberry and make a clean boot).
 
 You can configure the refresh interval of the display via `ui.fps`, we advise to use a slow refresh to not shorten the lifetime of your display. The default value is 0, which will only refresh when changes are made to the screen.
 
-### Host Connection Share
+## Host Connection Share
 
-If you connect to the unit via `usb0` (thus using the data port), you might want to use the `scripts/linux_connection_share.sh` or 
+If you connect to the unit via `usb0` (thus using the data port), you might want to use the `scripts/linux_connection_share.sh` or `scripts/macos_connection_share.sh` script to bring the interface up on your end and share internet connectivity from another interface, so you can update the unit and generally download things from the internet on it. Note this script takes as inputs the two interfaces and shouldn't be run without arguments.
- `scripts/macos_connection_share.sh` script to bring the interface up on your end and share internet connectivity from another interface, so you can update the unit and generally download things from the internet on it.
+
+## Troubleshooting
+
+If your network connection keeps flapping on your device connecting to your pwnagotchi, check if `usb0` (or equivalent) device is being controlled by NetworkManager. You can check this via `nmcli dev status`.

docs/dev.md

@@ -1,4 +1,4 @@
-## Software
+# Software
 
 - Raspbian + [nexmon patches](https://re4son-kernel.com/re4son-pi-kernel/) for monitor mode, or any Linux with a monitor mode enabled interface (if you tune config.yml).
 
@@ -21,6 +21,7 @@ usage: ./scripts/create_sibling.sh [OPTIONS]
     -d           # Only run dependencies checks
     -h           # Show this help
 ```
+
 ## Adding a Language
 
 If you want to add a language use the `language.sh` script. If you want to add for example the language **italian** you would type:

docs/faq.md

@@ -10,4 +10,4 @@ Because Python sucks and TF is huge.
 
 ## Why ...?
 
-Because!
+Because!

docs/index.md

@@ -16,4 +16,4 @@
 
 ## License
 
-`pwnagotchi` is made with ♥  by [@evilsocket](https://twitter.com/evilsocket) and the [amazing dev team](https://github.com/evilsocket/pwnagotchi/graphs/contributors). It's released under the GPL3 license.
+`pwnagotchi` is made with ♥  by [@evilsocket](https://twitter.com/evilsocket) and the [amazing dev team](https://github.com/evilsocket/pwnagotchi/graphs/contributors). It's released under the GPL3 license.

docs/install.md

@@ -1,7 +1,6 @@
 # Installation
 
-The project has been developed to run on a Raspberry Pi 0 W configured as an [USB Ethernet gadget](https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/ethernet-gadget) device in order to connect to it via USB. 
+The project has been developed to run on a Raspberry Pi 0 W configured as an [USB Ethernet gadget](https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/ethernet-gadget) device in order to connect to it via USB. However, given the proper configuration tweaks, any GNU/Linux computer with a WiFi interface that supports monitor mode could be used.
-However, given the proper configuration tweaks, any GNU/Linux computer with a WiFi interface that supports monitor mode could be used.
 
 ## Required Hardware
 
@@ -34,9 +33,7 @@ Color displays have a much slower refresh rate, in some cases it can take up to
 
 The easiest way to create a new Pwnagotchi is downloading the latest stable image from [our release page](https://github.com/evilsocket/pwnagotchi/releases) and write it to your SD card. You will need to use an image writing tool to install the image you have downloaded on your SD card.
 
-[balenaEtcher](https://www.balena.io/etcher/) is a graphical SD card writing tool that works on Mac OS, Linux and Windows, 
+[balenaEtcher](https://www.balena.io/etcher/) is a graphical SD card writing tool that works on Mac OS, Linux and Windows, and is the easiest option for most users. balenaEtcher also supports writing images directly from the zip file, without any unzipping required. To write your image with balenaEtcher:
-and is the easiest option for most users. balenaEtcher also supports writing images directly from the zip file, 
-without any unzipping required. To write your image with balenaEtcher:
 
 - Download the latest [Pwnagotchi .img file](https://github.com/evilsocket/pwnagotchi/releases).
 - Download [balenaEtcher](https://www.balena.io/etcher/) and install it.
@@ -45,4 +42,4 @@ without any unzipping required. To write your image with balenaEtcher:
 - Select the SD card you wish to write your image to.
 - Review your selections and click 'Flash!' to begin writing data to the SD card.
 
-Your SD card is now ready for the first boot!
+Your SD card is now ready for the first boot!

docs/plugins.md

@@ -1,8 +1,7 @@
 # Plugins
 
 Pwnagotchi has a simple plugins system that you can use to customize your unit and its behaviour. You can place your plugins anywhere
-as python files and then edit the `config.yml` file (`main.plugins` value) to point to their containing folder. Check the [plugins folder](https://github.com/evilsocket/pwnagotchi/tree/master/sdcard/rootfs/root/pwnagotchi/scripts/pwnagotchi/plugins/default/) for a list of default
+as python files and then edit the `config.yml` file (`main.plugins` value) to point to their containing folder. Check the [plugins folder](https://github.com/evilsocket/pwnagotchi/tree/master/sdcard/rootfs/root/pwnagotchi/scripts/pwnagotchi/plugins/default/) for a list of default plugins and all the callbacks that you can define for your own customizations.
-plugins and all the callbacks that you can define for your own customizations.
 
 Here's as an example the GPS plugin:
 

docs/usage.md

@@ -1,4 +1,6 @@
-### User Interface
+# Usage
+
+## User Interface
 
 The UI is available either via display if installed, or via http://pwnagotchi.local:8080/ if you connect to the unit via `usb0` and set a static address on the network interface (change `pwnagotchi` with the hostname of your unit).
 
@@ -10,7 +12,7 @@ The UI is available either via display if installed, or via http://pwnagotchi.lo
 * **PWND**: Number of handshakes captured in this session and number of unique networks we own at least one handshake of, from the beginning.
 * **AUTO**: This indicates that the algorithm is running with AI disabled (or still loading), it disappears once the AI dependencies have been bootrapped and the neural network loaded.
 
-### Training the AI
+## Training the AI
 
 At its core Pwnagotchi is a very simple creature: we could summarize its main algorithm as:
 
@@ -27,7 +29,7 @@ while True:
         for client in ap.clients:
             # deauthenticate the client to get its half or full handshake
             deauthenticate(client)
-    
+
     wait_for_loot()
 ```
 
@@ -73,14 +75,11 @@ personality:
     sad_num_epochs: 25
 ```
 
-There is no optimal set of parameters for every situation: when the unit is moving (during a walk for instance) smaller timeouts and RSSI thresholds might be preferred
+There is no optimal set of parameters for every situation: when the unit is moving (during a walk for instance) smaller timeouts and RSSI thresholds might be preferred in order to quickly remove routers that are not in range anymore, while when stationary in high density areas (like an office) other parameters might be better. The role of the AI is to observe what's going on at the WiFi level, and adjust those parameters in order to maximize the cumulative reward of that loop / epoch.
-in order to quickly remove routers that are not in range anymore, while when stationary in high density areas (like an office) other parameters might be better. 
-The role of the AI is to observe what's going on at the WiFi level, and adjust those parameters in order to maximize the cumulative reward of that loop / epoch.
 
-#### Reward Function
+## Reward Function
 
-After each iteration of the main loop (an `epoch`), the reward, a score that represents how well the parameters performed, is computed as 
+After each iteration of the main loop (an `epoch`), the reward, a score that represents how well the parameters performed, is computed as (an excerpt from `pwnagotchi/ai/reward.py`):
-(an excerpt from `pwnagotchi/ai/reward.py`):
 
 ```python
 # state contains the information of the last epoch
@@ -107,15 +106,13 @@ reward = h + a + c + b + i + m
 
 By maximizing this reward value, the AI learns over time to find the set of parameters that better perform with the current environmental conditions.
 
+## BetterCAP's Web UI
 
-### BetterCAP's Web UI
+Moreover, given that the unit is running bettercap with API and Web UI, you'll be able to use the unit as a WiFi penetration testing portable station by accessing `http://pwnagotchi.local/`.
-
-Moreover, given that the unit is running bettercap with API and Web UI, you'll be able to use the unit as a WiFi penetration testing portable station
-by accessing `http://pwnagotchi.local/`.
 
 ![webui](https://raw.githubusercontent.com/bettercap/media/master/ui-events.png)
 
-### Update your Pwnagotchi
+## Update your Pwnagotchi
 
 You can use the `scripts/update_pwnagotchi.sh` script to update to the most recent version of pwnagotchi.
 
@@ -132,7 +129,7 @@ usage: ./update_pwnagitchi.sh [OPTIONS]
 
 ```
 
-### Backup your Pwnagotchi
+## Backup your Pwnagotchi
 
 You can use the `scripts/backup.sh` script to backup the important files of your unit.
 
@@ -140,12 +137,10 @@ You can use the `scripts/backup.sh` script to backup the important files of your
 usage: ./scripts/backup.sh HOSTNAME backup.zip
 ```
 
-### Random Info
+## Random Info
-
-- **On a rpi0w, it'll take approximately 30 minutes to load the AI**.
-- `/var/log/pwnagotchi.log` is your friend.
-- if connected to a laptop via usb data port, with internet connectivity shared, magic things will happen.
-- checkout the `ui.video` section of the `config.yml` - if you don't want to use a display, you can connect to it with the browser and a cable.
-- If you get `[FAILED] Failed to start Remount Root and Kernel File Systems.` while booting pwnagotchi, make sure
-the `PARTUUID`s for `rootfs` and `boot` partitions are the same in `/etc/fstab`. Use `sudo blkid` to find those values when you are using `create_sibling.sh`.
 
+* **On a rpi0w, it'll take approximately 30 minutes to load the AI**.
+* `/var/log/pwnagotchi.log` is your friend.
+* if connected to a laptop via usb data port, with internet connectivity shared, magic things will happen.
+* checkout the `ui.video` section of the `config.yml` - if you don't want to use a display, you can connect to it with the browser and a cable.
+* If you get `[FAILED] Failed to start Remount Root and Kernel File Systems.` while booting pwnagotchi, make sure the `PARTUUID`s for `rootfs` and `boot` partitions are the same in `/etc/fstab`. Use `sudo blkid` to find those values when you are using `create_sibling.sh`.