Added docs folder

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/advanced_config.rst

@@ -0,0 +1,227 @@
+======================
+Advanced Configuration
+======================
+
+During your node's *Basic Setup* you used the configuration display by clicking the **Setup** button and typing your username and password. The configuration area has several additional features which will be described in more detail below. Clicking **Node Status** exits configuration mode without saving any changes, returning you to the *Node Status* display.
+
+.. image:: _images/06-admin-header.png
+   :alt: Admin Navigation Controls
+   :align: center
+
+There are several control buttons below the configuration links section.
+
+**Help**
+   Opens a new window or tab to display the node help page.
+
+**Save Changes**
+  Click this button to save any configuration changes you have made. Saving changes will first do a basic validation of the new settings, saving them to flash memory if no errors are found. The new settings take effect in about 20 seconds and a reboot may or may not be required.
+
+**Reset Values**
+  Click this button to reload the currently saved settings from flash memory, effectively undoing any changes that were made.
+
+**Default Values**
+  Click this button to reset your node's basic settings to the default values. This action does not affect your existing node name.
+
+**Reboot**
+  Click this button to force your node to reboot.
+
+Basic Setup
+-----------
+
+You have already configured many of the basic settings, but there are several additional features that will be explained below.
+
+.. image:: _images/07-setup-options.png
+   :alt: Setup Options
+   :align: center
+
+Mesh RF Column
+^^^^^^^^^^^^^^
+
+*Mesh RF* is the node's *radio* interface. The AREDN |trade| firmware has been designed to simplify the process of configuring networking interfaces. Network values are automatically calculated based on the unique :abbr:`MAC (Media Access Control)` addresses of your node. Normally you will not need to change any of the network settings on this page, so keep these values unless you fully understand how the mesh works and why the defaults may not be suitable for your situation.
+
+The *Active Settings* can be adjusted and applied without saving changes or rebooting your node. However, they will return to their original values after a reboot unless you click *Save Changes*. A node may decrease its output power as it increases its data rate in order to maintain a linear spectrum. The *Distance* setting increases the packet retry timer to allow stations that are farther away more time to respond.
+
+LAN Column
+^^^^^^^^^^
+
+The LAN column contains the settings for the Local Area Network hosted by the AREDN |trade| node. There are several options under the *LAN Mode* dropdown.
+
+The default mode is ``5 Host Direct``. In this mode every host on the LAN has direct access to and from the mesh. This mode was created to reduce the amount of manual configuration needed to provide services to the mesh, since many services do not work well if they are hosted behind a :abbr:`NAT (Network Address Translation)` router. With *Direct* mode the LAN shares the same address space as the mesh at large. Port forwarding is not needed because NAT is not used, and there is no firewall between the LAN and the mesh.
+
+The mesh address space is automatically managed, so you cannot configure the LAN network settings in *Direct* mode. The only configurable option available in *Direct* mode is the size of the LAN subnet which can accommodate either 1, 5, or 13 LAN hosts. A one host subnet can be used for either a single server or a separate network router using its own NAT which is capable of more advanced routing functions than those available on a mesh node.
+
+It is important not to use a subnet larger than is necessary because the chance of an IP address conflict on the mesh increases with the size of the subnet. The LAN subnet parameters are automatically calculated and depend on the IP address of the *Mesh RF* interface. If a conflict does occur it can be fixed by changing the *Mesh RF* IP address.
+
+The other LAN Mode is ``NAT``, and in this mode the LAN is isolated from the mesh. All outgoing traffic has its source address modified to be the *Mesh RF* IP address of the node. This is the same way that most routers use an Internet connection, and all services provided by computers on the LAN can only be accessed through port forwarding rules. A single :abbr:`DMZ (DeMilitarized Zone)` server can be used to accept all incoming traffic that is not already handled by other rules or by the node itself.
+
+By default each node runs a :abbr:`DHCP (Dynamic Host Control Protocol)` server for its LAN nodes. The last octet of the start/end range for host IP addresses is shown in the LAN column. If you choose to disable the DHCP server, you must manually configure the host IP addresses to be within the LAN network range. There should be only one DHCP server on each subnet, so you may need to disable your node's DHCP server if there is already another device providing DHCP services on your LAN network.
+
+The *Disable Default Route* checkbox will tell the node not to advertise that it can be used as a default gateway. This means that computers on the LAN network will have no route to reach the Internet or other networks via the mesh node. If this checkbox is selected your hosts will not be able to access the Internet even if your node has Internet available on its WAN port. You may need to disable the default route if your node needs to be connected to two networks at once, such as being wired to the mesh and connected to a local served agency WiFi network.
+
+WAN Column
+^^^^^^^^^^
+
+The :abbr:`WAN (Wide Area Network)` interface on your node is typically used to connect it to the Internet or to another external network. By default the WAN interface is set to obtain an IP address via DHCP from your upstream network. The :abbr:`DNS (Domain Name System)` servers are set by default to use Google's DNS services and should not be changed under normal circumstances. Google's name resolution servers are configured properly to detect error conditions and report them correctly.
+
+If you are not going to use the WAN interface on your node, you can select *disabled* from the *Protocol* dropdown list. If you will be using your node as a *Tunnel Server*, you should assign the node a *Static* IP address on your WAN network. This will be explained in the *Tunnel Server* section below.
+
+When a node has Internet access from either the WAN or LAN interface, that access is available to the node itself and to any computers connected via the *LAN* port. Checking the *Mesh Gateway* box will also allow this node to route traffic from the *Mesh RF* interface to/from the Internet or other external network. By default the *Mesh Gateway* box is unchecked because it is not desirable to route Internet traffic over the radio interface. AREDN |trade| is an FCC Part 97 amateur radio network, so be sure that any traffic which will be sent over the radio complies with FCC Part 97 rules. If you want local wireless Internet access, consider using a standard FCC Part 15 compliant access point instead of the node's *Mesh Gateway* feature.
+
+Node VLANs
+^^^^^^^^^^
+
+Many of the devices used as AREDN |trade| nodes have only one Ethernet port, but more than one type of network traffic must share that single port. The AREDN |trade| firmware implements :abbr:`VLANs (Virtual Local Area Network)` in order to accomplish this. Different types of traffic are tagged to identify the network to which they belong.
+
+VLAN 1
+  Packets received by the node that are tagged for VLAN 1 will be identified as WAN traffic from the Internet or another external network.
+
+VLAN 2
+  Packets received by the node that are tagged for VLAN 2 will be identified as traffic from a :abbr:`DtD (Device to Device)` node directly connected via Ethernet cable.
+
+No VLAN tag
+  Packets received by the node that are untagged will be identified as LAN traffic from computers on the local area network.
+
+It is important to understand AREDN |trade| VLANs when configuring network smart switches for Internet access, tunneling, or DtD linking of nodes.
+
+Port Forwarding, DHCP, and Services
+-----------------------------------
+
+Click the **Port Forwarding, DHCP, and Services** link to navigate to these settings. This section provides a way for you to configure LAN network address reservations and service advertisements on your node. If your LAN network uses ``NAT`` mode, you may also need to define port forwarding rules.
+
+----------
+
+.. image:: _images/08-port-forward.png
+   :alt: Port Forwarding, DHCP, and Services
+   :align: center
+
+----------
+
+If your node is running its default DHCP server on the LAN network, it will automatically provide IP addresses to connected hosts. Look under the **Current DHCP Leases** heading to see the existing hosts and their assigned IP address.
+
+.. note:: The hostnames of computers connected to the mesh at large must be unique. Typically you should prefix your amateur radio callsign to the computer's hostname in order to have the best chance of it being unique on the mesh network.
+
+Since DHCP leases are dynamic and can change over time, there may be a reason why a host's assigned IP address should be made permanent. This is especially useful if that host will provide an application, program, or service through your node to the mesh network at large. You can permanently reserve that host's DHCP address by clicking the *Add* button to the right of the host in the *DHCP Leases* list. You will see that host now appears in the list under the **DHCP Address Reservations** heading above the list of leases.
+
+Advertised Services
+^^^^^^^^^^^^^^^^^^^
+
+Network services can run on LAN hosts or on your node itself. Just remember that AREDN |trade| nodes have a limited amount of system resources with which to run services, so it may be a good idea to run services on an external computer connected to the node's LAN network. In the example above you can see that an external host has been given a reserved DHCP address, and it is also running the *meshchat* program as a service that is advertised on the network through this node. Use the following steps to create an advertised service.
+
+Name
+  Enter a service name in the *Name* field.
+
+Link
+  Check this box if your want your advertised service to display an active link in the web browser. This allows mesh users to navigate to your service by clicking the link.
+
+Protocol
+  Enter the protocol to use in the field between *Link* and *URL*. Common protocols include ``http`` for website services and ``ftp`` for file transfer services. Other services may use other protocols.
+
+URL
+  From the dropdown list select the node or host on which this service is running.
+
+Port
+  Enter the network port on which the service is listening for user connections. There may be several applications provided through a single web server on a node or host using a single port, and in that case a valid application *Path* must be entered after the port number (as in the example above). In other cases the network port alone uniquely identifies the application or program that is listening for user connections to that service.
+
+Once you have entered the values for your advertised service, click *Add* to add the service to the **Advertised Services** list. You may also remove an existing advertised service by clicking the *Del* button to delete it from the list.
+
+Port Forwarding
+^^^^^^^^^^^^^^^
+
+If you are using ``NAT`` for your LAN mode, then *Port Forwarding* rules are the only way other devices have for connecting to your services. To create a port forwarding rule, select the network interface on which the traffic will enter your node. Select the protocol used by the incoming packets (TCP, UDP, or Both). Enter the port number that the external request is using to connect to your service. When your node receives traffic on the selected interface, protocol, and port, the request will be routed to the LAN IP address and port on which that host is listening for incoming service requests.
+
+See your node's **Help** file for additional insights on how this configuration section changes based on the LAN mode of your node.
+
+Tunnel Server
+-------------
+
+Click the **Tunnel Server** link to navigate to these settings. This section provides a way for you to configure your node with a special service that allows node-to-node connections across the Internet. Unless you have a specific need for this type of network connection, it is recommended that you do not install the *Tunnel Server* feature. This is because it will cause your node to dedicate limited system resources to running a service that may rarely or never be used. In order to increase the performance of your node you should conserve system resources so they will be available for normal node operations, which is especially important for nodes with limited memory and storage.
+
+Internet Connectivity Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to run your node as either a *Tunnel Server* or *Tunnel Client*, you will need to configure additional settings and equipment.
+
+Managed Switch Settings (both Client and Server networks)
+  Set your VLAN-capable network switch to appropriately tag traffic from the Internet with "VLAN 1" before sending it to your node. This allows your node to properly identify the traffic as coming from the Internet connection on its WAN interface. See the equipment manual for your managed switch to determine how to configure these settings. There are also AREDN |trade| `website posts <https://www.arednmesh.org/content/configuring-netgear-gs105e-switch-lanwan-ports>`_ which contain helpful information.
+
+  Your node should have Internet access after the smart switch is configured, and you can use the node's new Internet connection to install the *tunneling* software package. This package should be installed on both the tunnel server and the tunnel client nodes.
+
+WAN Interface IP (Tunnel Server *node* only)
+  Set a static IP address on your tunnel server node's WAN interface so your Internet-connected router/firewall has a consistent way to forward traffic to your node.
+
+Internet Firewall/Router Settings (Tunnel Server network only)
+  Set your network firewall or router to permit traffic from the Internet on port 5525, which is the default AREDN |trade| tunnel service port. Then configure a port forwarding rule on your firewall or router to send any traffic from the Internet on port 5525 to the static IP address of your node's WAN interface on the *node's* port 5525. See the equipment manual for your firewall or router to determine how to configure these settings.
+
+Tunnel Server Node Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following diagram shows an overview of tunnel services between two nodes.
+
+----------
+
+.. image:: _images/10-tunneling-diagram.png
+   :alt: Tunneling Diagram
+   :align: center
+
+----------
+
+The tunnel network address ranges are automatically calculated, and it is not necessary to change these settings unless there is a specific reason why the defaults will not work for your situation.
+
+Tunnel Server DNS Name
+  Enter the *Public IP Address* or the *Dynamic DNS URL* by which Internet-connected nodes can reach your network.
+
+Client Node Name
+  Enter the exact node name of the client node that will be allowed to connect to your node over the tunnel. Do not include the "local.mesh" suffix.
+
+Client Password
+  Enter a complex password that the client node will use to connect to your node over the tunnel. Use only uppercase and lowercase characters and numbers in your password.
+
+Once these settings are correct, click *Add* to add the new client to the list of authorized tunnel clients. On the right of each entry there is an envelope icon which will automatically open your computer's email program and copy the client settings into a new email which allows you to quickly and easily send credentials to the owners of the client nodes.
+
+To allow a client to connect to your tunnel server, select the **Enabled?** checkbox and click the **Save Changes** button. When a tunnel connection becomes active, the cloud icon at the right of each row will change to indicate that the tunnel is active.
+
+Tunnel Client
+-------------
+
+Click the **Tunnel Client** link to navigate to these settings. In this section you can configure your node to connect over the Internet to another node running as a *Tunnel Server*. You should already have your VLAN-capable network switch configured as explained in the *Tunnel Server* section above.
+
+Contact the amateur operator who controls the tunnel server and request client credentials by providing your specific node name. The tunnel server administrator will provide you with the public IP or :abbr:`DDNS (Dynamic Domain Name Service)` URL for the tunnel server, the password you are to use, and the network IP address for your client node. Enter these values into the appropriate fields on your node and click *Add* to create a client entry in the list.
+
+----------
+
+.. image:: _images/11-tunnel-client.png
+   :alt: Tunnel Client Settings
+   :align: center
+
+----------
+
+To allow your client to connect to the tunnel server, select the **Enabled?** checkbox and click the **Save Changes** button. When a tunnel connection becomes active, the cloud icon at the right of each row will change to indicate that the tunnel is active.
+
+Administration
+--------------
+
+Click the **Administration** link to navigate to these settings. There are four sections that provide a way for you to update the AREDN |trade| firmware, as well as to install or remove software packages on your node.
+
+.. image:: _images/09-admin-upgrade.png
+   :alt: Upgrade and Packages
+   :align: center
+
+.. note:: Files cannot be uploaded to a node while a tunnel server or client connection is enabled. Disable tunnel client or server connections before uploading firmware, packages, or ssh key files. The *Upload* buttons will be disabled until tunnels are disabled.
+
+**Firmware Update**
+  If you have a new firmware image that has already been downloaded to your computer, click the *Browse* button and select the firmware file to upload. Click *Upload* and the file will be uploaded and installed on the node.
+
+  If the node has Internet access (either from its WAN interface or from the mesh) you can use the *Download Firmware* option. Click *Refresh* to update the list of available images. Select the image to download, click *Download*, and wait for the firmware to download and be installed. When upgrading firmware, you can retain your existing configuration settings by selecting the *Keep Settings* checkbox.
+
+**Package Management**
+  Here you can install or remove software packages on the node. *Upload Package* allows you to install a package file from your computer. *Download Package* allows you do retrieve a package over the Internet from the AREDN |trade| website. Clicking *Refresh* will update the list of packages available for download, but try to avoid updating this list unless you absolutely require it. The package information database is stored locally and will use quite a bit of storage space. Under normal circumstances it is rare to require a package refresh.
+
+  The *Remove Package* list shows all packages currently installed on the node. Selecting a package and clicking *Remove* will uninstall the package. You will only be able to remove packages that you have added. All installed packages are shown, but the pre-installed packages cannot be deleted since they are necessary for proper operation of the node.
+
+**Authorized SSH Keys**
+  Uploading ssh keys allows computers to connect to a node via ssh without having to know the password. The ssh keys are generated on your computer using built-in utilities or the `PuTTY <https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html>`_ program's *Key Generator*. Once you have the key files on your computer, you can upload its *public* key to your AREDN |trade| node. If you want to remove an installed key, select it and click the *Remove* button.
+
+**Support Data**
+  There may be times when you want to view more detailed information about the configuration and operation of your node, or even forward this information to the AREDN |trade| forum in order to get help with a problem. Click *Download Support Data* to save a compressed archive file to your local computer.
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/aredn_overview.rst

@@ -0,0 +1,25 @@
+==============
+AREDN Overview
+==============
+
+The AREDN |trade| acronym stands for "Amateur Radio Emergency Data Network" and it provides a way for *Amateur Radio* operators to create high-speed ad hoc *Data Networks* for use in *Emergency* and service-oriented communications.
+
+For many years amateur radio operators and their served agencies have relied on voice transmissions for emergency or event communications. A typical message-passing scenario involved conveying the message to a radio operator who would write or type it onto a standard ICS-213 form. The message would then be relayed by radio to another operator who would write or type it on another ICS-213 form at the receiving end. The form would typically be hand-delivered to the recipient who would read and sign the form. Any acknowledgement or reply would then be handled through the same process from the receiving end back to the originator.
+
+This tried-and-true scenario has worked well, and it continues to work for handling much emergency and event traffic. Today, however, digital transmission is more commonly used instead of traditional methods and procedures. The hardcopy ICS-213 form is giving way to the Winlink electronic form, with messages being passed using digital technologies such as AX.25 packet, HF Pactor, Fldigi, and others.
+
+.. sidebar:: Our Mission
+
+   The primary goal of the AREDN |trade| project is to empower licensed amateur radio operators to quickly and easily deploy high-speed data networks when and where they are needed.
+
+In today's high-tech society people have become accustomed to different ways of handling their communication needs. The preferred methods involve short messaging and keyboard-to-keyboard communication, along with audio-video communication using Voice Over IP (VoIP) and streaming technologies.
+
+The amateur radio community is able to meet these high-bandwidth digital communication requirements by using FCC Part 97 amateur radio frequency bands to send digital data between devices which are linked with each other to form a self-healing, fault-tolerant data network. Some have described this as an amateur radio version of the Internet. Although it is not intended for connecting people to **the Internet**, an AREDN |trade| mesh network will provide typical Internet or intranet-type applications to people who need to communicate across a wide area during an emergency or community event.
+
+An AREDN |trade| network is able to serve as the transport mechanism for the preferred applications people rely upon to communicate with each other in the normal course of their business and social interactions, including email, chat, phone service, document sharing, video conferencing, and many other useful programs. Depending on the characteristics of the AREDN |trade| implementation, this digital data network can operate at near-Internet speeds with many miles between network nodes.
+
+The primary goal of the AREDN |trade| project is to empower licensed amateur radio operators to quickly and easily deploy high-speed data networks when and where they might be needed, as a service both to the hobby and the community. This is especially important in cases when traditional "utility" services (electricity, phone lines, or Internet services) become unavailable. In those cases an off-grid amateur radio emergency data network may be a lifeline for communities impacted by a local disaster.
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/basic_setup.rst

@@ -0,0 +1,63 @@
+==================
+Basic Radio Setup
+==================
+
+After you have installed the AREDN |trade| firmware, rebooted the device, and connected your computer to the LAN port on the :abbr:`PoE (Power over Ethernet)` you can navigate to the following URL: ``http://localnode:8080``. The initial status page will be displayed, instructing you to configure your node by clicking the **Setup** button.
+
+----------
+
+.. image:: _images/01-setup-nocall.png
+   :alt: Setup N0CALL
+   :align: center
+
+----------
+
+You will be prompted to enter the administrative login credentials. The default authentication credentials are:
+
+| Username: ``root``
+| Password: ``hsmm``
+
+The **Basic Setup** page will be displayed, as shown below.
+
+   .. image:: _images/02-basic-setup.png
+      :alt: Basic Setup
+      :align: center
+
+----------
+
+In order to get your new AREDN |trade| node on the air, you need to enter the following items.
+
+**Node Name**
+  Begin the node name with your callsign, followed by unique identifying information of your choice. Node names may contain up to 63 letters, numbers, and dashes, but cannot begin or end with a dash.  Underscores, spaces, or any other characters are not allowed. Node names are not case sensitive, but the case will be preserved on the node status display.
+  Amateur radio operators are required to identify all transmitting stations. The AREDN |trade| node name is beaconed automatically by the node every five minutes, so the node name must contain your callsign. Recommended names follow the (callsign)-(label) format, such as AD5BC-MOBILE or AD5BC-1. This is similar to the MYCALL setting you would give a packet :abbr:`TNC (Terminal Node Controller)`, but without the 0-15 character restriction.
+
+**Password**
+  Set a new administration password for the node. Enter it again in the *Retype Password* box to verify it is correct. The first time a node is configured it will require you to change the password. Be sure to remember or record the new password so you can use it for any future administrative tasks on the node.
+
+**Node Description**
+  This is not a required field, but it is a good place to describe the features or function of this device. Many operators use this field to list their contact information, the radio model and antenna specifications, or the tactical purpose for the node. There are no character restrictions in the field, but the maximum length allowed is 210 characters.
+
+**Mesh RF**
+  The *IP Address, Netmask, and SSID* fields are automatically calculated for you based on the unique :abbr:`MAC (Media Access Control)` address of your node. Do not change these settings. Everything under the **LAN** and **WAN** columns can be left unchanged for now.
+
+**Channel and Channel Width**
+  Nodes communicate only with other nodes that use the same channel and channel width. You can determine the correct settings by talking with other local node operators to find out which settings are required for joining their networks.
+
+**Active Settings**
+
+* Use the dropdown list to select the maximum output power for this device. Remember that amateur operators are required to use the minimum power necessary to make contact with other stations.
+
+* Use the slider to select the estimated maximum distance you estimate between your node and other neighboring nodes.
+
+* Some devices have max power levels that change depending on the channel or frequency being used, and in that case the max level may change when you save the settings. The output power will be capped at the max level supported by the hardware for that frequency.
+
+* Once these settings have been adjusted, click the **Apply** button.
+
+**Optional Settings**
+  In this section you can enter your node's latitude and longitude, as well as the grid square designator. Click the **Apply Location Settings** button after entering this information. You may also change the timezone for your node's system time.
+
+Once you have entered, applied, and verified that your node settings are correct, click the **Save Changes** button. Your node will record the new configuration settings and automatically reboot.
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/conf.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'AREDN Getting Started Guide'
+copyright = u'2018, AREDN'
+author = u'KC0EUW'
+
+# The short X.Y version
+version = u'3.18.9.0'
+# The full version, including alpha/beta/rc tags
+release = u'3.18.9.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+#html_theme = 'sphinxdoc'
+html_theme = 'nature'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'AREDN_Getting_Started_Guidedoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'AREDN_Getting_Started_Guide.tex', u'AREDN\\_Getting\\_Started\\_Guide',
+     u'AREDN', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'aredn_getting_started_guide', u'AREDN_Getting_Started_Guide',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'AREDN_Getting_Started_Guide', u'AREDN_Getting_Started_Guide',
+     author, 'AREDN_Getting_Started_Guide', 'A basic guide for getting started with AREDN.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------

docs/downloading_firmware.rst

@@ -0,0 +1,17 @@
+==========================
+Downloading AREDN Firmware
+==========================
+
+Once you have selected and obtained a device, the next step is to choose the matching AREDN |trade| firmware image for that specific device. The `AREDN download page <http://downloads.arednmesh.org/firmware/ubnt/html/stable.html>`_ displays the most current firmware releases for every supported device.
+
+Locate your device model/version in the left column. Most manufacturers print the hardware version on the product package label. In some cases, though, you may need to start the device using the manufacturer's pre-installed firmware and navigate to the system information page to determine the hardware version.
+
+There are two types of firmware images: one for the first-time replacement of the manufacturer's firmware, and the other for subsequent upgrades of the already running AREDN |trade| image.
+
+* If you are loading AREDN |trade| firmware on a device for the first time you will typically choose the firmware from the middle column, because your device is still running the manufacturer's firmware and not the AREDN |trade| :abbr:`UI (User Interface, usually displayed in a web browser)`.
+* If you are already running AREDN |trade| firmware on the device then you will choose the firmware release from the righthand column, and you will use the AREDN |trade| web interface to perform a firmware upgrade.
+
+Once you have selected the correct firmware image for your device, click the link to download the image file to your local computer. Make a note of the download location on your computer, since you will need to use that image to install the AREDN |trade| firmware on your device.
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/index.rst

@@ -0,0 +1,19 @@
+===========================
+AREDN Getting Started Guide
+===========================
+
+**Version 3.18.9.0**
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Topics
+
+   aredn_overview
+   selecting_devices
+   downloading_firmware
+   installing_firmware
+   basic_setup
+   node_status
+   mesh_status
+   advanced_config
+   more-info.rst

docs/installing_firmware.rst

@@ -0,0 +1,24 @@
+=========================
+Installing AREDN Firmware
+=========================
+
+The steps for installing device firmware are documented on the AREDN |trade| website in the `Current Software <https://www.arednmesh.org/content/current-software>`_ section. Under the **Software** menu, select **Download** to reach the *Current Software* page.
+
+There are two cases for installing AREDN |trade| firmware:
+
+#. If you already have an existing version of AREDN |trade| running on your device, then you can navigate to **Setup** -> **Administration** -> **Firmware Update** to install your new firmware. This process will be explained in more detail in the **Advanced Administration** section of this guide.
+
+#. If you are installing AREDN |trade| firmware on a device for the first time, each hardware platform may require a unique procedure.
+
+   + **Ubiquiti** devices can typically upload a new firmware image using :abbr:`TFTP (Trivial File Transfer Protocol)`. The up-to-date procedures for accomplishing this task are shown on the `TFTP Firmware Installation <https://www.arednmesh.org/content/tftp-firmware-installation>`_ page of the AREDN |trade| website.
+
+   + **TP-LINK** devices use the manufacturer's pre-installed PharOS interface to upload and apply new firmware images. Navigate to the *Setup* section to select and upload new firmware. Check the TP-LINK documentation for your device if you have questions about using their built-in interface.
+
+   + **Mikrotik** devices can be updated using a specific process that is documented on the `Instructions for Mikrotik Devices <https://www.arednmesh.org/content/installation-instructions-mikrotik-devices>`_ page on the AREDN |trade| website. A new "easy install" process for Mikrotik devices is in development and will be described when it becomes available.
+
+Once your device is running AREDN |trade| firmware, you can display its web interface by connecting your computer to the LAN port on the :abbr:`PoE (Power over Ethernet)` and navigating to the following URL: ``http://localnode:8080``
+
+By default AREDN |trade| devices run the :abbr:`DHCP (Dynamic Host Control Protocol)` service on their LAN interface, so your computer will receive an IP address from the node as soon as it is connected with an Ethernet cable. Ensure that your computer is set to obtain its IP address via :abbr:`DHCP (Dynamic Host Control Protocol)`.
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/mesh_status.rst

@@ -0,0 +1,60 @@
+===================
+Mesh Status Display
+===================
+
+The **Mesh Status** page lists mesh nodes, link quality information, and the advertised services on the mesh network.
+
+----------
+
+.. image:: _images/05-mesh-status.png
+   :alt: Mesh Status
+   :align: center
+
+----------
+
+Below the node name bar there are several controls.
+
+**Refresh**
+  This button refreshes the **Mesh Status** display with current information.
+
+**Auto**
+  This button sets the display to automatically refresh the node information every 10 seconds. To end auto-refresh mode, click **Stop** or **Quit**. **Stop** returns to the static *Mesh Status* display. **Quit** takes you back to the *Node Status* display, and clicking *Mesh Status* again from there will return you to auto-refresh mode on the *Mesh Status* display.
+
+**Quit**
+  This button returns you to the *Node Status* display.
+
+----------
+
+There are four sections on the **Mesh Status** display.
+
+**Local Hosts**
+  This shows your mesh node along with any connected hosts and the advertised services available on your node and hosts. Typically you may click the service name to open a new browser tab containing the features of that service. This will be true for any available services in the *Current Neighbors* or *Remote Nodes* sections.
+
+**Current Neighbors**
+  This shows a list of *Neighbor Nodes* that are directly connected with your node (1 hop). These nodes may be connected via :abbr:`RF (Radio Frequency)`, :abbr:`DtD (Device to Device)` link using an Ethernet cable, or a tunnel over an Internet connection. There are several link quality statistics displayed for each connected node.
+
+  - ``LQ`` or Link Quality is your node's view of the percent of :abbr:`OLSR (Optimized Link State Routing protocol)` packets received from the neighbor node. These packets exchange mesh routing and advertised services information, and they include a sequence number that is used to identify missing packets which is a measure of the quality of the link.
+
+  - ``NLQ`` or Neighbor Link Quality is the neighbor node's view of the percent of :abbr:`OLSR (Optimized Link State Routing protocol)` packets received from your node. This measures the quality of the link from the neighbor's side.
+
+  - ``TxMbps`` or Transmit Megabits per Second is a calculated estimate of the data rate achieved across the link with the neighbor node. This column may show zero if the data being transmitted between these nodes is not sufficient for the metric to be calculated.
+
+  - ``Services`` is the column where any available services on the neighbor node will be displayed. You may click on the service link to navigate to the webpage for that service on the neighbor node.
+
+  In addition to the neighbor node name, there may be a text abbreviation in parentheses that tells how the neighbor node is connected.
+
+  - ``(dtd)`` indicates a *Device to Device* connection using an Ethernet cable between the nodes. The neighbor may be listed twice if both an :abbr:`RF (Radio Frequency)` and :abbr:`DtD (Device to Device)` path exist.
+
+  - ``(tun)`` indicates the path to the neighbor node is over an Internet tunnel. ``(tun*?)`` next to a mesh node in the *Remote Nodes* column indicates the node has tunnel links over the Internet to connect mesh islands together. ``?`` is a number indicating the number of tunnel connections on that node.
+
+  - ``(wan)`` indicates the node has been configured as a *Mesh Gateway*. Typically this is a gateway to the Internet, but it may also be to another isolated network.
+
+**Remote Nodes**
+  This section lists other nodes on the network that are two or more hops away. Advertised services on nodes and their attached hosts are also listed. Remote Nodes are sorted by their ``ETX`` or *Expected Transmission* metric. :abbr:`ETX (Expected TX metric)` is a calculated estimate of the number of :abbr:`OLSR (Optimized Link State Routing protocol)` packets that must be sent in order to receive a round trip acknowledgement, and it is often referred to as "link cost". When sending data the :abbr:`OLSR (Optimized Link State Routing)` protocol selects the least cost route based on the lowest :abbr:`ETX (Expected TX metric)` path in the direction of the final destination.
+
+**Previous Nodes**
+  This section lists any nodes which were recently connected to your node but are not currently connected. It shows the node name or IP address, as well as how long it has been since a node was actively connected to your node.
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/more-info.rst

@@ -0,0 +1,11 @@
+======================
+Additional Information
+======================
+
+Additional information about the AREDN |trade| project can be found at the links below or by entering the keyword "AREDN" in online search engines and popular video sites.
+
+* `AREDN homepage <https://www.arednmesh.org/>`_
+* `AREDN forums <https://www.arednmesh.org/forum>`_
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/node_status.rst

@@ -0,0 +1,79 @@
+===================
+Node Status Display
+===================
+
+Once you have completed the initial setup on your AREDN |trade| node, you can connect your computer to the LAN port on the :abbr:`PoE (Power over Ethernet)` and navigate to the following URL: ``http://localnode:8080``. You will be redirected to the **Node Status** page as shown below.
+
+----------
+
+.. image:: _images/03-node-status.png
+   :alt: Node Status
+   :align: center
+
+----------
+
+Below the node name bar there are several controls.
+
+**Help**
+   Opens a new window or tab to display the node help page.
+
+**Refresh**
+   Updates the Node Status page with current data.
+
+**Mesh Status**
+   Opens the **Mesh Status** page showing the neighbor nodes and remote nodes visible on the mesh network, as well as what services are being provided by those nodes.
+
+**WiFi Scan**
+   Displays a list of other 802.11 signals that your node can see. The 802.11 signals may include Access Points, neighbor nodes, and other mesh networks (foreign ad-hoc networks), but only if they are using the same bandwidth settings as your node. When multiple ad-hoc networks are visible (with different SSIDs or channels), the *network* is displayed but not the individual nodes. There is also an automatic scan mode, but running a wifi scan continuously is not recommended because this will degrade mesh performance. A wifi scan transmits queries on all channels to discover other devices.
+
+**Setup**
+   Navigates to the **Setup** pages for your node. You will need to supply a username and password to access those pages. The username is always ``root``, while the password is the one you set during initial node setup. If the node has not yet been configured, the password is ``hsmm``.
+
+**Select Theme**
+   AREDN |trade| firmware has several built-in display themes. The default ``aredn`` theme has a gray background with black and red text. The ``black_on_white`` theme is often chosen because it provides the best screen contrast on a computer exposed to direct sunlight. ``red_on_black`` is much better suited for nighttime use since it helps preserve night vision.
+
+Node Settings Summary
+---------------------
+
+The area under the display controls shows both configuration and network status information. The left column contains the IP address details for the network interfaces on this node, as well as the SSID, channel, and bandwidth settings.
+
+The right column contains the Signal Strength readings and other attributes of your node. The **Signal/Noise/Ratio** shows the strongest neighbor radio signal strength (in :abbr:`dBm (decibels relative to one milliwatt)`) from all connected stations, and it is available only when the node is connected by :abbr:`RF (Radio Frequency)` to a mesh network.
+
+Below the Signal Strength readings are the node's **Firmware Version** and network type. The **System Time** is displayed, as well as the **Uptime**, or time since the last reboot. Nodes have no internal battery or realtime clock, so the time is reset every time the node is booted. If an Internet connection becomes available, the internal :abbr:`NTP (Network Time Protocol)` client will connect with a time server to sync the node's time.
+
+The **Load Average** is the average number of processes that have been running on the node for the last 1, 5, and 15 minutes. **Free Space** tells you how much space is available on local storage devices. Flash is the internal non-volatile storage where the operating system, configuration files, and software packages are kept. /tmp is a filesystem in memory that stores the node's current status and various temporary files. **Memory** is the amount of :abbr:`RAM (Random Access Memory)` available for running processes on the node.
+
+The :abbr:`OLSR (Optimized Link State Routing protocol)` **Entries** show the total number of entries in the routing table, as well as the number of nodes currently connected to the mesh network.
+
+Signal Charts
+-------------
+
+There is a **Charts** button next to the node's **Signal Stength** display, and clicking this button takes you to **Signal Charts**. This page shows :abbr:`RF (Radio Frequency)` signal information in both a realtime and an archived view. The default view shows the average signal of all connected stations in realtime.
+
+.. image:: _images/04-node-charts.png
+   :alt: Node Charts
+   :align: center
+
+At the top of the charts display there are several control buttons.
+
+**Archive**
+  This button shows the charts for any archived signal data on this node.
+
+**Realtime**
+  This button shows the charts for current signal data as seen from this node.
+
+**Quit**
+  This button exits the charts view and takes you back to the *Node Status* page.
+
+Below these controls you can choose to view the signal strength statistics for individual nodes that are directly connected to your node. Choose the neighbor node from the **Selected Device** dropdown list. Changing the selected device will automatically reload the chart to show that node's information.
+
+Hovering over data points within a chart will show additional information for each data point, including Time, Signal, Noise, :abbr:`SNR (Signal to Noise Ratio)`, TX Rate, TX :abbr:`MCS (Modulation Coding Scheme)`, RX Rate, and RX :abbr:`MCS (Modulation Coding Scheme)`. If no traffic is being routed to the neighbor, the Rate and MCS values may be zero until data is available. An MCS value of zero may indicate non-802.11n encoding schemes (ie. 802.11a/b/g).
+
+The small icon with three vertical dots in the upper right corner of the chart allows you to download a snapshot of the chart to a graphic file on your local computer (jpeg or png).
+
+Data shown in the **Archive** charts is not stored in permanent memory on the node. The node will store approximately two days of archived data, and all data is cleared when a node is rebooted.
+
+If you click and drag your mouse across a region of the chart, the display will zoom into that selected area. This allows you to view data points for a specific time range of your choice. While zoomed, two additional icons will appear in the upper right of the chart. The **Pan** icon allows you to scroll and pan the zoomed portion of the chart. The **Reset** icon returns the chart to its normal display mode.
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

docs/selecting_devices.rst

@@ -0,0 +1,24 @@
+========================
+Selecting Radio Hardware
+========================
+
+The amateur radio community has recognized the benefits of using inexpensive commercial :abbr:`WISP (Wireless Internet Service Provider)` radios to create AREDN |trade| networks. Each of these devices come with the vendor's firmware pre-installed, but by following a few simple steps this firmware can be replaced with an AREDN |trade| firmware image. Several open source software features have been adapted and enhanced to create the AREDN |trade| firmware, including :abbr:`OpenWRT (Open Wireless Router)` and :abbr:`OLSR (Optimized Link State Routing protocol)`. The AREDN |trade| team builds specific firmware images tailored to each type or version of radio, and the current list of supported devices is found on the AREDN |trade| website in the `Supported Platform Matrix <https://www.arednmesh.org/content/supported-platform-matrix/>`_.
+
+When selecting a device for your AREDN |trade| hardware there are several things to consider in your decision.
+
+* Radios should be purchased for the specific frequency band on which they will operate. Currently AREDN |trade| supports devices which operate in the 900 MHz, 2.4 GHz, 3.4 GHz, and 5.8 GHz bands.
+* Many devices come with an integrated dual-polarity :abbr:`MIMO (Multiple Input-Multiple Output)` antenna which helps to mitigate multipath propagation issues.
+* Radios can be purchased separately from the antenna, so it is possible to have more than one antenna option for a radio in order to optimize AREDN |trade| nodes for varying deployment conditions.
+* Costs of devices range from $50 to several hundred dollars for a complete node, so there are many options even for the budget-conscious operator.
+* Some older or lower cost devices have a limited amount of onboard memory, but firmware images continue grow in size and functionality. Consider purchasing a device with more memory over one with less memory.
+* Check the maximum power output of the device, since some devices have lower power capabilities.
+
+One of the best sources of detailed device information is a manufacturer's datasheet, usually available for download from the manufacturer's website. Currently AREDN |trade| supports over fifty device models from the following manufacturers: Mikrotik, TP-LINK, and Ubiquiti Networks.
+
+If you are just getting started with AREDN |trade| you can easily begin with one of the low-cost devices that comes with an integrated antenna and a :abbr:`PoE (Power over Ethernet)` unit. If you are expanding your AREDN |trade| network with more sophisticated equipment, you may choose a standalone radio attached to any of several kinds of high-gain antennas.
+
+.. note:: See the **AREDN Design Guide** for more information about constructing robust mesh networks.
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim: