Initial entry

README.md

@@ -1,2 +1,114 @@
 # autoAP
-Simple Automatic AP for Raspberry Pi if no connected WiFi
+Simplified Automatic Access Point for Raspberry Pi if no connected WiFi
+
+## Overview
+
+autoAP provides a simple mechanism for turning a Raspberry Pi into an Access Point if the Pi is unable to connect to it's defined WiFi network. autoAP is simple to install and super-lightweight, requiring only one additional process.
+
+autoAP is not intended to replace hostapd. If your use case needs a full-function Access Point, you want hostapd. A typical use case for autoAP would be for a Pi that you're taking outside of your known WiFi networks, and want to connect to it from another device in order to configure it, use it for demonstration purposes, etc.
+
+autoAP was initially created by [jake](https://raspberrypi.stackexchange.com/users/92303/jake) and posted in the article [Automatically Create Hotspot if no Network is Available](https://raspberrypi.stackexchange.com/questions/100195/automatically-create-hotspot-if-no-network-is-available). There are other tools, such as [wifi-connect](https://github.com/balena-io/wifi-connect). My take is that wifi-connect is a more heavyweight solution with correspondingly more features.
+
+autoAP, on the other hand, is super-lightweight, and can install on Raspbian Full or Raspbian Lite without requiring any additional software to be installed.
+
+## Requirements
+
+autoAP has minimal system requirements, but they are important:
+
+* autoAP has been tested only on Raspbian Buster. It *should* run on Stretch, but that remains to be verified.
+* autoAP requires use of systemd-networkd for network configuration. A provided script (rpi-networkconfig) simplifies the switch.
+
+## Installation
+
+Download install-autoAP and autoAP.sh to /usr/local/bin on your Pi, and run install-autoAP:
+
+Download/install directions:
+https://github.com/gitbls/autoAP/raw/master/autoAP.sh
+
+* `sudo curl -L https://github.com/gitbls/autoAP/raw/master/autoAP.sh -o /usr/local/bin/autoAP.sh`
+* `sudo curl -L https://github.com/gitbls/autoAP/raw/master/install-autoAP -o /usr/local/bin/install-autoAP`
+* `sudo curl -L https://github.com/gitbls/autoAP/raw/master/rpi-networkconfig -o /usr/local/bin/rpi-networkconfig`
+* `sudo chmod 755 /usr/local/bin/autoAP.sh /usr/local/bin/install-autoAP`
+* `sudo /usr/local/bin/install-autoAP`
+
+install-autoAP will configure your system for autoAP. The detailed steps are described here for your convenience and reference.
+
+* Prompt for the SSID and password for Access Point mode
+* Try to get your current WiFi configuration from /etc/wpa_supplicant/wpa_supplicant.conf if it is available. If it is not available, install-autoAP will prompt for the following information:
+    * WiFi Country
+    * Your WiFi SSID
+    * Your WiFi Password
+* If /etc/wpa_supplicant/wpa_supplicant.conf exists, it will be renamed to /etc/wpa_supplicant/wpa_supplicant.conf-orig, to avoid confusion
+* Write the file /etc/wpa_supplicant/wpa_supplicant-wlan0.conf with the gathered information, defining both your WiFi network and the Access Point mode SSID and Password
+* install-autoAP will create:
+    * /etc/systemd/system/11-wlan0.network and 12-wlan0AP.network. These are the network configuration files used by systemd-networkd for your wireless network.
+    * /etc/systemd/system/wpa-[email protected], which is the service definition for the process that monitors the WiFi status and switches from Access Point mode to Client mode (and back) as appropriate.
+    * /etc/systemd/system/wpa-autoap-restore.service, which calls /usr/local/bin/autoAP.sh to ensure that the systemd network configuration is correct.
+    * /usr/local/bin/autoap-local.sh, which is a skeleton file that you can modify to call your scripts or programs that are interested in WiFi mode changes. For instance, if you want to start a program when the Pi enters Access Point mode (and stop when it enters Client mode), you would add the appropriate start and stop commands in the fairly obvious places
+    * /usr/local/bin/autoAP.conf, which has the autoAP monitor configuration information. The parameters are:
+        * **enablewait** (defaults to 2 minutes): This is the amount of time that autoAP will wait before it tries to connect to your WiFi again after Access Point mode is started. You might want this to be longer if you want the Access Point to remain active for a long period of time or shorter if you only need it briefly.
+        * **disconnectwait** (defaults to 20 seconds): This is the amount of time that autoAP will wait after the last client disconnects from the Access Point before it tries to reconnect to your WiFi. You might want this to be longer if you expect to disconnect and reconnect frequently over longer time spans.
+        * **debug** (defaults to 1 [off]): If debug is set to 0 [on], autoAP will log some additional information to the system log for troubleshooting.
+
+As a last step, install-autoAP will remind you to switch to networkd-systemd if it is not currently running on the Pi.
+
+`/usr/local/bin/rpi-networkconfig` will make the appropriate network software configuration changes to enable your selected network "machinery". rpi-networkconfig can switch between dhcpcd, systemd-networkd, and NetworkManager, although configuration files are only created for systemd-networkd. rpi-networkconfig will not overwrite the configuration written by install-autoAP. rpi-networkconfig will create /etc/systemd/system/10-eth0.network for your Ethernet device, and it will be set for DHCP operation. 
+
+In sommary, the network configuration files for systemd-networkd are (all in /etc/systemd/network):
+
+* **10-eth0.network** - Defines the network for the Ethernet device
+* **11-wlan0.network**- Defines the network for the WiFi device in normal mode
+* **12-wlan0AP.network** - Defines the network for the WiFi device in Access Point mode
+
+And the systemd services installed are (all in /etc/systemd/system):
+
+* **[email protected]** - The main service for autoAP
+* **wpa-autop-restore.service** - Restores the network configuration, if needed, when the system is restarted
+
+If you made it this far, it's time to reboot!
+
+## Operation
+
+### Usage
+If you are planning to use autoAP, make sure that wpa-autoap@wlan0 service is enabled. If you aren't planning to use autoAP, you can (but don't need to, as it's very lightweight) disable wpa-autoap@wlan0 and the network will behave normally. 
+
+To enable: 
+
+* `sudo systemctl enable wpa-autoap@wlan0`
+
+To disable:
+
+* `sudo systemctl disable wpa-autoap@wlan0`
+
+
+### Detailed Operational Description
+
+The system startup will proceed normally. The wpa-autoap@wlan0 service is bound to the service wpa_supplicant@wlan0, so systemd will start it automatically if it's enabled. wpa_supplicant@wlan0 is running the same old wpa_supplicant, so it will process WiFi connects, disconnects, etc, just as before. 
+
+If wpa_supplicant times out trying to connect to your WiFi (for instance, if the Pi is not at home or your router/access point is down), it will then look at the next defined network (the autoap Access Point network), which changes the wpa_supplicant mode to AP. A message is sent to wpa-autoap (via wpa_cli), which calls /usr/local/bin/autoAP.sh with the network name and the event AP-ENABLED. autoAP will reconfigure the network to Access Point mode, restart systemd-networkd, and call /usr/local/bin/autoap-local.sh to do any additional desired processing.
+
+When the last client disconnects from the Access Point, autoAP will wait disconnectwait time units before reverting to WiFi scanning mode, looking for your WiFi network. And, if your WiFi network is not found, it will restart Access Point mode.
+
+Similarly, when the Access Point is started, it will wait enablewait time units before reverting to WiFi scanning mode.
+
+## Troubleshooting
+
+If things are not working for you, the first step in tracking things down is to examine the system journal (journalctl) for error information. You can also enable debugging, which will output additional status information to the system journal. You enable debugging by sudo editing /usr/local/bin/autoAP.conf and changing debug=1 to debug=0. The debug logging will start the next time wpa_supplicant notices a wireless transition or the autoAP reconfigure timer expires.
+
+## Known Issues
+
+* If wpa-autoap@wlan0 is enabled at system startup, it may fail to start the first or second time due to an apparent startup race condition between it and wpa_supplicant@wlan0. It's completely harmless since the service automatically restarts on failure, but for those of you who look through logs, you may see this.
+* ???
+
+## Futures
+
+In no particular order, things I'm thinking about for autoAP:
+
+* Lightweight web page for additional configuration while in Access Point mode
+* Improved wpa_supplicant network profile support. Currently only a single WiFi network configuration (e.g., your Home network) is supported by the installer, in addition to the Access Point. You can, however, add additional WiFi network configurations to /etc/wpa_supplicant/wpa_supplicant-wlan0.conf after installing autoAP.
+* Integration with dhcpcd and/or Network Manager
+* Your suggestions?
+
+## Final Thoughts
+
+This is the first release. It has been well-tested by me, but has not been exposed to the variety of devices, different usage models, and users in the world. If you run into any problems, please post them on this GitHub, and I'll work with you to resolve them.