adding a few bits to the install guide

Author: sneakers-the-rat

docs/guide.configuration.rst

@@ -0,0 +1,3 @@
+just unlinked stubs for future configuration page.
+
+You probably want to set the agent name (e.g.: "Pilot 1").

docs/guide.installation.rst

@@ -48,43 +48,56 @@ Now install the system packages that are required by Autopilot. You can do this
         libhdf5-dev \
         libzmq-dev \
         libffi-dev
-        
-        
-Next, install `virtualenv`, which allows us to create an installation environment for Autopilot.::
-
-    pip3 install virtualenv
-
-You can read more about virtualenv on `their docs <https://virtualenv.pypa.io/en/latest/>`_. For now, let's create a virtual environment for Autopilot, and name it "autopilot". By convention, these virtual environments are stored in the directory `~/.venv`.::
-
-    mkdir ~/.venv
-    virtualenv ~/.venv/autopilot
 
 
 On the Terminal device
 ----------------------
 
 On the computer that will run the Terminal, you also need to install virtualenv and create a virtualenv for Autopilot, but you don't need to install all the system dependencies (the line beginning with "sudo apt install"). 
 
-Note that Python version 3.7 is required on both the Terminal and the Pilot. We have mostly tested Autopilot with virtualenv, but so far it appears that "conda" can be used instead of "virtualenv" on the Terminal if that's easier for you. So something like this should work::
+Creating a Virtual Environment
+------------------------------
+
+We recommend using autopilot within a virtual environment -- we primarily develop with `virtualenv` but `conda` also appears to work.
+
+First, install `virtualenv` (see the `virtualenv docs <https://virtualenv.pypa.io/en/latest/>`_)::
+
+    pip3 install virtualenv
+
+Then, create a venv. By convention, these virtual environments are stored in the directory `~/.venv`, but they can
+be located anywhere.
+
+**With `virtualenv`**::
+
+    mkdir ~/.venv
+    python3 -m virtualenv ~/.venv/autopilot
+    source ~/
+
+**With conda**::
 
     conda create --name autopilot python=3.7
-    conda activate autopilot
 
+.. note::
+    Python version 3.7 is required on both the Terminal and the Pilot due to dependencies on the Spinnaker API for high-speed
+    cameras. In the future we will move to `aravis <https://github.com/SintefManufacturing/python-aravis>`_ to avoid this.
 
-Installing Autopilot
-====================
-Now we're ready to install Autopilot on both the Pilot and Terminal devices. Follow the same instructions on both the Pi and the computer.
+The virtual environment must be "activated" now and any time you work with autopilot
+(:mod:`.setup_autopilot` will detect which venv it is run from and source it in the launch script).
 
-First, make sure the "autopilot" virtual environment is active.::
+**With `virtualenv`**::
 
-    source ~/.venv/autopilot/bin activate
+    source ~/.venv/autopilot
 
-(Or if you are using conda instead)::
+**With conda**::
 
     conda activate autopilot
 
-Either way, you should see that the command prompt begins with the string "(autopilot)". If you want to exit the virtual environment at any time, just type `deactivate`, but make sure the environment is activated whenever you're installing software or running Autopilot.
+Either way, you should see that the command prompt begins with the string "(autopilot)".
+If you want to exit the virtual environment at any time, just type `deactivate`.
 
+Installing Autopilot
+====================
+Now we're ready to install Autopilot on both the Pilot and Terminal devices. Follow the same instructions on both the Pi and the computer.
 
 Method 1: Installation with pip
 -------------------------------
@@ -93,24 +106,16 @@ If you're just taking a look at Autopilot, the easiest way to get started is to
 
     pip3 install auto-pi-lot
 
-.. note::
-
-    I'm just figuring out python packaging and this is a pretty complicated one to package! Please `submit issues <https://github.com/wehr-lab/autopilot/issues>`_
-    if the pip install isn't working!
-
 Method 2: Installation from source
 ----------------------------------
 
 If you want to start writing your own experiments and tinkering with Autopilot,
 we strongly recommend forking `the repository <https://github.com/wehr-lab/autopilot/>`_
 and developing directly in the library so your gorgeous insights can be integrated later.
 
-In this example, we'll keep the source code in a directory called `~/dev`. You might want to keep other source code there too. (Don't forget to make sure that your virtual env "autopilot" is activated before running the install step!)
+Clone the repository and install an "editable" version with `-e`, this makes it so python uses the source code in your
+cloned repository, rather than from the system/venv libraries.::
 
- ::
-
-    mkdir ~/dev
-    cd ~/dev
     git clone https://github.com/wehr-lab/autopilot.git
     cd autopilot
     pip3 install -e .
@@ -119,14 +124,14 @@ In this example, we'll keep the source code in a directory called `~/dev`. You m
 
     Depending on your permissions, eg. if you are not installing to a virtual environment, you may get a permissions error and need to install with the ``--user`` flag
 
-Configuration
-==============
-
 .. note::
 
-    If you didn't install the system dependencies on the Pilot device yet (by running the long line beginning with "sudo apt install" in the first section of this document), you can do so now with ::
+    Development work is done on the ``dev`` branch, which may have additional features/bugfixes but is much less stable!
+    To use it just ``git checkout dev`` from your repository directory.
+
 
-        python3 -m autopilot.setup.run_script env_pilot
+Configuration
+==============
 
 After installation, set Autopilot up! Autopilot comes with a "guided installation" process where you can select the actions you want and they will be run for you. The setup routine will:
 
@@ -136,29 +141,40 @@ After installation, set Autopilot up! Autopilot comes with a "guided installatio
 * create a user directory (default ``~/autopilot``) to store prefs, logs, data, etc.
 * create a launch script
 
-This must be run in a sufficiently large terminal window (80x43 is not enough). Otherwise, you'll get an error, in which case simply increase the size of the window.
-
 To start the guided process, run the following line. ::
 
     python3 -m autopilot.setup.setup_autopilot
 
 Select agent
 -------------
-Each runtime of Autopilot is called an "Agent", each of which performs different roles within a system, and thus have different requirements. If you're running the setup script on the Pi, select "Pilot". If you're running the setup script on a desktop computer, select "Terminal". If you're configuring multiple Pis, then select "Child" on the child Pis. Then hit "OK". You can navigate this interface with the arrow keys, tab key, and enter key.
+Each runtime of Autopilot is called an "Agent", each of which performs different roles within a system, and thus have different requirements.
+If you're running the setup script on the Pi, select "Pilot". If you're running the setup script on a desktop computer, select "Terminal".
+If you're configuring multiple Pis, then select "Child" on the child Pis. Then hit "OK".
 
+You can navigate this interface with the arrow keys, tab key, and enter key.
 
 .. image:: _images/setup_agent_selection.png
     :alt: Select an autopilot agent
     :width: 100%
 
 Select scripts
 ---------------
-Now you will see a menu of potential scripts that can be run. Select the scripts you want to run, and then hit "OK". Note that even the simplest task ("free water") requires pigpio, so you may want to include that one. You can see the commands that will be run in each of these scripts in :func:`.setup_autopilot.run_script` and :func:`.setup_autopilot.list_scripts`.
+Now you will see a menu of potential scripts that can be run.
+Select the scripts you want to run, and then hit "OK". Note that even the simplest task ("free water") requires pigpio,
+so you may want to include that one. You can see the commands that will be run in each of these scripts with :func:`.setup_autopilot.run_script` and :func:`.setup_autopilot.list_scripts`.
+
 
 .. image:: _images/setup_scripts.png
     :alt: Select scripts to setup environment
     :width: 100%
 
+.. note::
+
+    Autopilot uses a slightly modified version of pigpio (https://github.com/sneakers-the-rat/pigpio) that allows it to
+    get absolute timestamps (rather than system ticks) from gpio callbacks, increases the max number of scripts, etc. so
+    if you have a different version of pigpio installed you will need to remove it and replace it with this one (you can
+    do so with ``python -m autopilot.setup.run_script pigpiod``
+
 Configure Agent
 ----------------
 Each agent has a set of systemwide preferences stored in ``<AUTOPILOT_DIR>/prefs.json`` and accessible from :mod:`autopilot.prefs`.
@@ -167,8 +183,6 @@ Each agent has a set of systemwide preferences stored in ``<AUTOPILOT_DIR>/prefs
     :alt: Set systemwide prefs
     :width: 100%
 
-You probably want to set the agent name (e.g.: "Pilot 1").
-
 Configure Hardware
 -------------------
 
@@ -180,12 +194,27 @@ Press ``ctrl+x`` to add Hardware, and fill in the relevant parameters (most are
     :alt: Configure Hardware
     :width: 100%
 
-After completing this step, the file `prefs.json` will be created if necessary and populated with the information you just provided. If it already exists, it will modified with the new information while preserving the previous preferences. 
+After completing this step, the file `prefs.json` will be created if necessary and populated with the information you just provided.
+If it already exists, it will modified with the new information while preserving the previous preferences.
 
-You can also manually edit the prefs.json file if you prefer. `A template version for the Pilot is available <https://groups.google.com/g/autopilot-users/c/_MqzLDDq3CE>`_ that defines the ports, LEDs, and solenoids that are necessary for the "free water" task, which may be a useful way to get started.
+You can also manually edit the prefs.json file if you prefer.
+`A template version for the Pilot is available <https://groups.google.com/g/autopilot-users/c/_MqzLDDq3CE>`_
+that defines the ports, LEDs, and solenoids that are necessary for the "free water" task, which may be a useful way to get started.
 
 Networking
 ==========
+
+.. note::
+
+    Networking is a point of major future development, particularly how agents discover one another and how ports are assigned.
+    Getting networking to work is still a bit cumbersome, but you can track progress or contribute to improving networking
+    at `issue #48 <https://github.com/wehr-lab/autopilot/issues/48>`_
+
+IP Addresses
+------------
+
+Pilots connect to a terminal whose IP address is specified as ``TERMINALIP`` in ``prefs.json``
+
 The Pilot and Terminal devices must be on the same network and capable of reaching one another. You must first figure out the IP address of each device with this command::
 
     ipconfig
@@ -200,32 +229,42 @@ And on the Pilot, run::
 
     ping 192.168.1.42
 
-If that doesn't work, something's up with your router or building network.
+If that doesn't work, there is something preventing the computers from communicating from one another, typically this is the
+case if the computers are on university/etc. internet that makes it difficult for devices to connect to one another. We
+recommend networking agents together using a local router or switch (though some have reported being able to
+`use their smartphone's hotspot in a pinch <https://groups.google.com/g/autopilot-users/c/JvWIPpYY0TI/m/fzSBET8PAAAJ>`_ ).
 
-You also need to make sure that a port is open on the Terminal device to receive messages from the Pilot. By default, this is port 5560. If you don't have a firewall, your ports are already open. But your version of Ubuntu may have a firewall ("ufw") running. If so, you can open this port on the Terminal by running the following::
+Ports
+-----
 
-    sudo ufw allow from 192.168.1.200 to any port 5560
+Agents use two prefs to configure their ports
+
+* ``MSGPORT`` is the port that the agent receives messages on
+* ``PUSHPORT`` is the port of the 'upstream' agent that it connects to.
 
-Make sure that the Pilot knows where the Terminal is by editing the line TERMINALIP in prefs.json on the Pilot to 192.168.1.42 (or whatever the IP address of your Terminal is).
+So, if connecting a Pilot to a Terminal, the ``PUSHPORT`` of the Pilot should match the ``MSGPORT`` of the Terminal.
 
-Similarly, tell the Terminal to expect information on port 5560. Do this by editing prefs.json on the Terminal and setting MSGPORT to 5560. Note that MSGPORT/PUSHPORT should be swapped between Terminal and Pilot devices.
+Ports need to be "open," but the central operation of a firewall is to "close" them. To open a port if, for example,
+you are using ``ufw`` on ubuntu (replacing with whatever port you're trying to open to whatever ip address)::
 
+    sudo ufw allow from 192.168.1.200 to any port 5560
 
 Testing the Installation
 ========================
 
-To test whether this all worked, try to start Autopilot. (Don't forget to activate your virtual environment first!) 
-
-Run this on the Pilot::
+A launch script should have been created by :mod:`~autopilot.setup.setup_autopilot` at ``<AUTOPILOT_DIR>/launch_autopilot.sh`` --
+this is the primary entrypoint to autopilot, as it allows certain system-level commands to precede launch (eg.
+activating virtual environments, enlarging shared memory, killing conflicting processes, launching an x server, etc.).
 
-    python3 -m autopilot.core.pilot -f ~/autopilot/prefs.json
+To launch autopilot::
 
-Alternatively, there is a launch script for the Pilot that includes some other magic, like activating the virtual environment and killing some troublesome daemons.::
+    ~/autopilot/launch_autopilot.sh
 
-    bash ~/autopilot/launch_autopilot.sh
+.. note::
 
-And run this on the Terminal::
+    Selecting the script ``alias`` in :mod:`~autopilot.setup.setup_autopilot` allows you to call the launch script by just typing ``autopilot``
 
-    python -m autopilot.core.terminal -f ~/autopilot/prefs.json
+The actual launch call to autopilot resembles::
 
-Now everything is installed and you are ready to move on to "Training a Subject", the next step in the documentation!
+    python3 -m autopilot.core.<AGENT_NAME> -f ~/autopilot/prefs.json
+