Merge pull request #2 from kc0euw/master

Added Network Design Guide

Getting_Started_Guide/index.rst

@@ -1,19 +0,0 @@
-===========================
-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

How to Use GitHub for AREDN.md

@@ -0,0 +1,58 @@
+# How to Use GitHub
+## Contributing to the AREDN Project
+
+
+### Create Your GitHub Account
+
+To contribute to the AREDN project you first must create your own GitHub account. This is free and easy to do by following these steps:
+
+1. Open your web browser and navigate to the GitHub URL `https://github.com`.
+2. Click the `Sign Up` button and enter a username, email, and password. We suggest using your callsign as the username.
+3. On the GitHub website, click the `Sign In` button and enter your username or email, followed by your github password.
+4. You can enter "aredn" into the search bar to find all repositories related to AREDN, or if you want to contribute directly to the AREDN firmware you can type this URL into your web browser: `https://github.com/aredn/aredn_ar71xx`.
+
+### Understanding GitHub Workflow
+
+The process of contributing and tracking changes to AREDN is circular. Code is maintained in the AREDN Master repository on GitHub. To contribute a potential code update, you must first FORK the AREDN master repository to your own GitHub account. You then CLONE your copy of the code from your GitHub repository to your own local computer. Make and test any changes you want to contribute using your local computer's copy of the code.
+
+When you are satisfied with your changes, COMMIT them to your local computer's repository, then PUSH those local changes to your copy of the code on your own GitHub account. Finally, create a PULL REQUEST, which tells the AREDN development team that you would like your changes to be reviewed for inclusion in the AREDN Master repository.
+
+![GitHub Workflow](_images/GitHub-workflow.png)
+
+#### One-time Repository Setup:
+
+1. Login to your own GitHub account and navigate in your browser to `https://github.com/aredn/aredn_ar71xx`
+2. Click the `Fork` button on the upper right side of the page.  You now have a copy of the AREDN source code on your own GitHub account.
+3. Go to your local computer and copy your fork of the AREDN source code: `git clone https://github.com/myCall/aredn_ar71xx`
+4. `cd aredn_ar71xx`  This directory contains your local copy of the AREDN source code. The following commands will be executed while you are in this directory or its subdirectories.
+5. `git remote add aredn https://github.com/aredn/aredn_ar71xx`  
+
+Now your local environment knows about both the master code repository and your forked copy on your GitHub account.
+
+#### Ongoing Development Cycle:
+
+1. Update your local environment with the latest code changes from the rest of the community, which will include any changes you had previously submitted.   *Caution:*  never make code changes directly on the `develop` branch.  This will result in inconsistencies between the main repository and your repository, requiring a force-remove of any changes you have made.
+	1. `git checkout develop`
+	2. `git pull aredn develop`
+2. Create a git code branch to fix a bug or implement a new feature:
+	1. `git checkout -b my-wiz-bang-feature-name`
+3. Make your changes and test them.
+4. When ready to submit changes, check to see whether they still work with code others have recently submitted. In GitHub terminology, “pull” down the latest changes and “rebase” or move your code on top of the latest. In this process you might find conflicts with someone else’s code, making further merge edits necessary.
+	1. `git stash` to stash the changes still in process.
+	2. `git checkout develop`
+	3. `git pull aredn develop`
+	4. `git checkout my-wiz-bang-feature-name`
+	5. `git rebase develop` to move your branch and changes on top of the latest code others have submitted.
+	6. `git stash pop` to reapply your stashed changes
+	7. Resolve any conflicts that need to be merged if warned in the step above.
+	8. Final build and validation that your changes work on top of the latest changes from all of the AREDN contributors.
+5. `Commit` your changes to your local repository, then `Push` the changes to your own GitHub repository.
+	1. `git commit`
+	2. `git push origin my-wiz-bang-feature-name`
+6. Create a `Pull Request` (PR) to the AREDN master repository by browsing to `github.com/myCall/aredn_ar71xx`, then select the my-wiz-bang-feature-name branch. Click the `New Pull Request` button to generate your Pull Request. Others can now review your code, test it, and give feedback. If feedback is given and you need to make changes, go back to step 3.
+7. Once your changes have been accepted into the AREDN master repository, delete your branch:
+	1. On your local repository: `git branch -D my-wiz-bang-feature-name`
+	2. On your forked copy of your GitHub repository: `git push origin --delete my-wiz-bang-feature-name`
+
+You can continue contributing new features by beginning the development cycle again, starting with step 1 on the Ongoing Development Cycle.
+

README.md

@@ -1,2 +1,21 @@
-# aredn-doc
-This is a project to create AREDN documentation so it can be made available on ReadTheDocs.
+# AREDN Documentation
+This repository is for creating documentation for the AREDN project so it can be made available on ReadTheDocs.
+
+## Contributing:
+If you are interested in contributing to the rapidly growing set of AREDN related information, you can easily do so on GitHub. This works the same way as if you were contributing code to the project.
+
+AREDN documentation is written using the reStructuredText markup language. Text is saved in "rst" files.
+
+After you setup your GitHub account, you should:
+
+1. FORK the AREDN documentation repository to your GitHub account.
+2. Then, to send updates or additions, checkout your repository from github.com/your-account/documentation, commit local changes you have made (additions or corrections to the AREDN docs), push to origin (your repository).
+3. Create a pull request.
+
+The AREDN team will then review your request just as it does for code changes. Once your documentation contributions are committed to the AREDN GitHub repository, a webhook updates and builds the latest docs for viewing and exporting on ReadTheDocs.org
+
+## Viewing the Docs:
+To view the AREDN documentation in a web browser, navigate to ReadTheDocs.org and search for the AREDN Documentation.
+
+## Exporting to PDF:
+While viewing the AREDN documentation in your web browser, you will see the Topics list in the left panel. At the bottom of the panel is a drawer labeled "ReadTheDocs" showing the version you are viewing. Click the label bar to open it. From the drawer you can export the documentation set as a single PDF or Epub file. This is handy if you want to take a PDF copy of the guidebook with you into the field where you do not have Internet access.

arednGettingStarted/advanced_config.rst

@@ -223,5 +223,15 @@ Click the **Administration** link to navigate to these settings. There are four
 **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.
 
+Node Reset Button
+-----------------
+
+The reset button on an AREDN |trade| node has two built-in functions based on the length of time the button is pressed.
+
+With the node powered on and fully booted:
+
+* Hold for 5 seconds to reset the password and DHCP server
+* Hold for 15 seconds to return the node to “just-flashed” condition
+
 .. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
    :ltrim:

arednGettingStarted/selecting_devices.rst

@@ -17,7 +17,7 @@ One of the best sources of detailed device information is a manufacturer's datas
 
 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.
+.. note:: See the **AREDN Network Design Guide** for more information about constructing robust mesh networks.
 
 
 .. |trade|  unicode:: U+02122 .. TRADE MARK SIGN

arednNetworkDesign/channel_planning.rst

@@ -0,0 +1,97 @@
+================
+Channel Planning
+================
+
+The previous section identified the different channels in each frequency band which are available for AREDN |trade| networking. Devices on each side of a radio link must use the same frequency band, channel, and channel width. Beyond that requirement, however, you have quite a bit of freedom to select the radio channels that will ensure the highest signal quality for your network.
+
+In a basic AREDN |trade| *meshnet* with individual nodes spread across a limited geographical area, all of the nodes may use the same frequency, channel, and channel width. This allows them to establish a network and route data to any of the sites as needed. However, as more nodes join the network or when several nodes are :abbr:`collocated (sharing the same physical site)`, it is possible for them to interfere with each other. In order for an AREDN |trade| network to scale up in size and complexity, channel planning becomes increasingly important.
+
+Some amount of data traffic is required for :abbr:`OLSR (Optimized Link State Routing protocol)` to maintain and operate the mesh network. Having a growing number of nodes on the same channel will increase the amount of :abbr:`OLSR (Optimized Link State Routing protocol)` handshaking, which can lead to more latency for data traffic across the network. Any application, program, or service that is sensitive to latency (especially voice or video services) may experience difficulty or even become unusable.
+
+Another case is when there is one poor quality link over which all traffic must be routed. The handshaking and data retransmissions may cause all the other links to wait. The entire network can be impacted by one low quality path which becomes a single bottleneck. If at all possible you should increase the signal quality of that vital link, or establish a better link as an alternate path.
+
+Channel Contention
+------------------
+
+In any wireless network there will be nodes which are not within radio range of each other. In the example below, **A** can hear **B** but cannot hear **C**. Since **A** and **C** are hidden from each other, they may try to transmit on the same channel at the same time without knowing it. Collision detection mechanisms will not help because the nodes have no way to communicate except through node **B**, so collision avoidance mechanisms must be used instead.
+
+.. image:: _images/hidden-node.png
+   :alt: Hidden Node Problem
+   :align: center
+
+AREDN |trade| firmware follows `IEEE 802.11a/b/g/n standards <https://en.wikipedia.org/wiki/IEEE_802.11n-2009>`_ and uses `Carrier Sense Multiple Access / Collision Avoidance (CSMA/CA) <https://en.wikipedia.org/wiki/Carrier-sense_multiple_access>`_ for determining whether a channel is busy.  Optionally AREDN |trade| firmware also employs `Request to Send / Clear to Send (RTS/CTS) messages <https://en.wikipedia.org/wiki/IEEE_802.11_RTS/CTS>`_ to negotiate the use of a channel. Decreased network throughput is one side effect of this, because several nodes may be negotiating or waiting to use the channel.
+
+For `hidden nodes <https://en.wikipedia.org/wiki/Hidden_node_problem>`_, two approaches may help to minimize this issue. You may be able to make the hidden nodes visible to each other, for example by increasing their signal strength. The alternative is to isolate the nodes completely by placing them onto different bands or channels. Since nodes using directional antennas are nearly invisible to others not positioned in the antenna's beam, directional antennas should be used with care when sharing a channel. It may be more appropriate to create a separate link between the sites and to put the radios on a different band or channel.
+
+Route Flapping
+--------------
+
+This is another issue that can lead to performance problems on a network. You may have parallel paths between two *Remote Nodes*, and these paths have similar :abbr:`ETX (Expected Transmit metric)` values which indicates that the cost of using either route is comparable. These two paths may appear to be functioning well most of the time.
+
+However, when a bandwidth-intensive application such as video conferencing begins sending traffic across one of the paths, you may notice that link getting bogged down and the :abbr:`ETX (Expected Transmit metric)` will drop below that of the other path. At this point :abbr:`OLSR (Optimized Link State Routing protocol)` switches to the alternate path which now has a lower cost. The video stream then bogs down its new path, which lowers the :abbr:`ETX (Expected Transmit metric)`, and :abbr:`OLSR (Optimized Link State Routing protocol)` switches back to the original link whose :abbr:`ETX (Expected Transmit metric)` is better again. This situation may continue indefinitely, with neither path being able to deliver the traffic adequately.
+
+This issue can happen on multi-hop links with similar :abbr:`ETX (Expected Transmit metric)` which seem to work fine until they are loaded with traffic. Then packet loss begins to occur, connections time out, and neither path is reliable during that cycle. One solution might be to improve the multi-hop link cost by increasing the signal quality of the links along one of the paths. Conversely, you could also turn down the power on the alternate path to increase its cost. If bandwidth-intensive traffic must be passed between two remote endpoints, the best approach would be to design a more robust path between those two endpoints to meet that need.
+
+Collocated Nodes
+----------------
+
+.. image:: _images/collocated-nodes.png
+   :alt: Collocated Nodes
+   :align: right
+
+At some sites there may be several devices mounted on the same building or structure. The photo on the right shows many nodes collocated on a single tower. Network problems can occur if these nodes share an RF band and channel. For example, when two sector antennas are collocated and share the same channel, the network throughput for that site will be reduced by half or more. If you have collocated nodes then it makes sense to allow the devices to pass traffic over their Ethernet interface rather than forcing them to use their radio channel.
+
+Device to Device (DtD) Linking
+++++++++++++++++++++++++++++++
+
+In its most basic configuration for two collocated nodes, an Ethernet cable is connected between the PoE *LAN* port of each device. :abbr:`OLSR (Optimized Link State Routing protocol)` will assign a very low "link cost" (0.1) to the DtD connection and automatically route traffic between the nodes over Ethernet rather than causing the RF channel to become busy.
+
+One added benefit of DtD linking is that you can link nodes which are operating on different bands and channels. Nodes that are using *Channel Separation* to avoid interfering with each other can still pass data at high speeds through their DtD link and be members of a single network. At a tower site like the one shown here, you could link 2.4 GHz, 3.4 GHz, and 5.8 GHz nodes to the same *meshnet*. In fact, at a busy site like this it is best practice to use DtD linking, because otherwise RF channel contention could make the network unusable.
+
+Ideally you should configure your collocated nodes to use different bands and channels, then set up DtD links between the nodes to ensure that traffic is routed efficiently without generating RF contention or delays. :abbr:`OLSR (Optimized Link State Routing protocol)` will always choose the DtD path first when passing traffic between linked nodes. Each AREDN |trade| node recognizes incoming packets tagged with :abbr:`VLAN (Virtual Local Area Network)` 2 as DtD traffic.
+
+.. image:: _images/dtd-linking.png
+   :alt: DtD Linking
+   :align: center
+
+In the simple example above, the smart switch will share all traffic across all ports and every node will receive it on its DtD link. If this is not what is desired, you can configure additional VLANs on the switch to isolate port traffic so that only the nodes which should receive specific traffic will see it. For example, you may have a video surveillance system (5) or a :abbr:`VoIP (Voice over IP)` phone system (6) and traffic from those devices should only be passed to a specific set of links as shown in the diagram below.
+
+.. image:: _images/vlan-isolation.png
+   :alt: Traffic Isolation with VLANs
+   :align: center
+
+Antenna Polarization
+++++++++++++++++++++
+
+Most of the latest AREDN |trade| devices use dual polarity antennas and :abbr:`MIMO (Multiple Input - Multiple Output)` features in the radios that  exploit multipath propagation. However, if you are using single polarity antennas with "single chain" radios, another way to achieve signal separation for collocated devices is to orient the site's antennas so that one is vertically polarized and the other is horizontally polarized. This can result in a signal separation of up to 20 dB. Vertical polarization is usually preferred because it tends to be less susceptible to reflections and rain fade, but horizontal polarization still provides adequate signal with clear line of sight. Note that the antennas on both sides of a radio link must be oriented the same way.
+
+Aligning Link Nodes
+-------------------
+
+The AREDN |trade| web interface provides information that is helpful when aligning two nodes that are being installed to form a link. On the **Node Status** page, click the **Charts** button to view the *Realtime Signal to Noise* graph. Slowly turn and tilt your antenna, pausing to view the signal metrics. Once you see the best signal, as shown below, you can lock your antenna into position. Depending on the implementation, a Signal to Noise Ratio of 15 dB is adequate to pass data at speeds in the range of 5 to 20 :abbr:`Mbps (Megabits per second)`.
+
+.. image:: _images/align-nodes.png
+   :alt: Aligning Nodes
+   :align: center
+
+Channel Planning Tips
+---------------------
+
+.. sidebar:: Avoid Network Scalability Issues
+
+   If there are two towers or cell coverage areas within range of each other, configure them with different channels to avoid poor performance.
+
+You may experience poor network performance if there are too many nodes using the same band and channel. Here is a simple example to illustrate the issue: a three-hop path from QTH1 to Tower1 to Tower2 to QTH2. If all links are using the same channel, then only one link at half-duplex can send data at a time. This instantly cuts the throughput by one-third or more and increases latency with protocol overhead. To improve performance you can configure each link to use a different channel, allowing simultaneous transmissions. In the first case with channel sharing, it might be possible to have one HD video stream and one VoIP call with frequent dropouts. In the second case using different link channels, you could have three HD video streams and several VoIP calls simultaneously with few dropouts.
+
+Based on the purpose for your network, try to create reliable paths to the locations where data is needed. Use channel separation and DtD linking of collocated nodes to avoid RF channel contention. The 3.4 GHz and 5.8 GHz bands provide the most unshared channels for use in AREDN |trade| networks.
+
+* If you need broad local coverage for a high profile area you can install sector antennas on a tower site: for example, three panels with 120 degree beam width each. DtD link the sectors at the tower site, and use different channels for each sector in order to avoid channel contention issues.
+
+* Consider putting each local *meshnet* on its own channel to minimize the interaction between coverage areas, similar to how cellular network "cells" are planned and deployed.
+
+* If you are installing long distance point to point links to connect mesh islands, be sure to use a separate band or channel for the backbone link. This type of link has a single purpose: to carry as much data as quickly as possible from one end to the other. Eliminate any type of channel contention so that these links can focus on throughput without distractions.
+
+* Remember that a multi-hop path through the network must have good signal quality on each leg of the journey. You cannot expect adequate performance through a series of poor quality links. For example, if you traverse three links having :abbr:`LQ (Link Quality)` metrics of 65%, 45%, and 58%, your aggregate :abbr:`LQ (Link Quality)` will be 17% which is unusable. The aggregate :abbr:`LQ (Link Quality)` should be at least 50% to have a usable path.
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

arednNetworkDesign/frequency_bands.rst

@@ -0,0 +1,86 @@
+==============================
+Radio Spectrum Characteristics
+==============================
+
+AREDN |trade| networks operate in the microwave radio spectrum, and licensed amateur radio operators have unique access to many of these frequencies. For bands in which amateur operators share the spectrum, there is an increased chance for RF interference which may make certain frequencies unusable for AREDN |trade| data networking. All of the 33 cm band is shared with other FCC authorized users. All of the upper channels on the 13 cm band are shared with standard FCC Part 15 :abbr:`WiFi (IEEE 802.11x)` and FCC Part 18 :abbr:`ISM (Industrial, Scientific, Medical)` users, as are all of the lower channels on the 5 cm band. The only frequency range which amateur operators do not currently share with non-licensed users is the 9 cm band, in which the US military may occasionally operate radio location units. The following table lists each amateur radio band, frequency range, usable channel width, and the number of shared/unshared channels that are available for AREDN |trade| networking.
+
+=======  =================  ==============  ================    =================
+Band     Frequency Range    Usable Width    Shared Channels     Unshared Channels
+=======  =================  ==============  ================    =================
+33 cm    902-928   MHz      25 MHz          5                   *none*
+13 cm    2390-2450 MHz      45 MHz          7                   2
+9  cm    3300-3500 MHz      120 MHz         *none*              24
+5  cm    5650-5925 MHz      260 MHz         45                  7
+=======  =================  ==============  ================    =================
+
+The table above shows that the 9 cm band has the most available bandwidth in its unshared channels, while the 5 cm band has the next largest amount of available bandwidth in unshared channels. The choice of a frequency band for AREDN |trade| networking depends on several different factors, but you can "mix and match" bands in your network design as long as both sides of a radio link use the same band, channel, and channel width. The advantages and disadvantages of each frequency range are explained in the sections below.
+
+900 MHz Characteristics
+-----------------------
+
+**Disadvantages**
+  The entire 33 cm band is shared between several FCC authorized radio services. The disadvantage of using this band for AREDN |trade| networking is that in all but the most remote areas the RF noise floor may be very high, which reduces the :abbr:`SNR (Signal to Noise Ratio)` and results in packet loss, retransmission delays, and lower usable link quality.
+
+  Another disadvantage is that the required antenna system and support structures may be larger and heavier than those of higher frequency systems, and the equipment can be more expensive than devices that operate in the 2.4 and 5.8 GHz bands. Also the entire band is quite narrow (25 MHz) which means that only one, two, or five radio channels can exist in this shared frequency range, depending on the channel width that is selected.
+
+.. image:: _images/900mhz.png
+   :alt: 900 MHz Band
+   :align: center
+
+**Advantages**
+  The advantage of this frequency band is that its longer wavelength makes it better suited for penetrating some types of obstructions and foliage which would normally block signals at higher frequencies. Its :abbr:`NLOS (Non Line of Sight)` propagation characteristics may be exactly what is needed in order to establish an RF link between two difficult locations.
+
+2.4 GHz Characteristics
+-----------------------
+
+**Disadvantages**
+  The upper channels of the 13 cm band are shared with several other FCC authorized services. Depending on local RF conditions it may not be possible to use these shared channels because of the high noise floor which reduces :abbr:`SNR (Signal to Noise Ratio)` and decreases signal quality. This leaves licensed amateur operators only two unshared channels with a possible bandwidth of 10 MHz each.
+
+  One concern with all of the higher frequency bands is that there must be clear line of sight between the nodes on each side of the link. This means that not only do the nodes need to have an unobstructed direct path, but the Fresnel Zone between the nodes must also be clear. The diameter of the Fresnel Zone depends on the frequency and the distance between nodes. For example, on a link in the 13 cm band with 10 miles between nodes, the first Fresnel Zone radius will be 72 feet. If less than 20% of the Fresnel Zone is obstructed there is little signal loss, but any blockage beyond 40% will cause significant signal loss and could make the path unusable. In the 13 cm band the 60% no blockage radius is approximately 43 feet, which is often higher than most *Intermediate* or *Last Mile* nodes have been installed. Careful consideration must be given to node height and the terrain between nodes in order to minimize obstructions.
+
+.. image:: _images/2.4ghz.png
+   :alt: 2.4 GHz Band
+   :align: center
+
+**Advantages**
+  Within the available frequency range you have the option of selecting channel widths of either 5, 10, or 20 MHz, but only the 5 and 10 MHz widths should be used on the unshared channels. A larger channel width will provide higher data rates. However, one effect of reducing the channel width is to increase the :abbr:`SNR (Signal to Noise Ratio)` to improve signal quality. For example, changing from a 20 MHz to a 5 MHz channel width will result in a 6 dB signal gain and could make the difference between a marginal link and a usable one.
+
+  One advantage for the 13 cm band is that radio equipment and antenna systems are more readily available and less costly due to higher consumer demand. There is a wide variety of equipment from several manufacturers which supports the AREDN |trade| firmware and operates in this band. Radio and antenna systems for this band are often smaller in size and less difficult to install. With clear line of sight and well-tuned antennas, 2.4 GHz signals can propagate across very long distances.
+
+3.4 GHz Characteristics
+-----------------------
+
+**Disadvantages**
+  As mentioned above, there must be clear line of sight and the Fresnel Zone between nodes also must be clear. For a link in the 9 cm band with 10 miles between nodes the first Fresnel Zone radius will be 62 feet, which is less than the 13 cm band discussed above. However, the 60% no blockage radius is still about 37 feet. Consider node :abbr:`AGL (height Above Ground Level)` and terrain in order to minimize obstructions.
+
+  Equipment for the 9 cm band is less readily available and is typically more expensive due to less consumer demand. Care must be taken when selecting radios so as not to confuse them with the more common :abbr:`WiMAX (IEEE 802.16)` devices which are designed for the 3.65 GHz range.
+
+.. image:: _images/3.4ghz.png
+   :alt: 3.4 GHz Band
+   :align: center
+
+**Advantages**
+  The main advantage for using the 9 cm band is that it has more available bandwidth for use in unshared channels than any other band. You can select channel widths of 5, 10, or 20 MHz, with larger channel widths providing higher data rates. Remember that reducing the channel width will increase the :abbr:`SNR (Signal to Noise Ratio)` to improve signal quality if that is an issue for a particular link. Equipment in the 9 cm band is well-suited for *Backbone Links* since there is little possibility for interference from other devices sharing these frequencies at tower sites. With clear line of sight and well-tuned antennas, 3.4 GHz signals can propagate across very long distances.
+
+5.8 GHz Characteristics
+-----------------------
+
+**Disadvantages**
+  As mentioned previously, there must be clear line of sight and the Fresnel Zone between nodes also must be unobstructed. For a link in the 5 cm band with 10 miles between nodes the first Fresnel Zone radius will be 46 feet, which is much less than the frequency bands discussed above. However, the 60% no blockage radius in the 5 cm band is still about 28 feet. Be sure to account for node :abbr:`AGL (height Above Ground Level)` and terrain in order to achieve clear line of sight between nodes.
+
+.. image:: _images/5.8ghz.png
+   :alt: 5.8 GHz Band
+   :align: center
+
+**Advantages**
+  One advantage for using the 5 cm band is that it contains 52 channels, 7 of which are available exclusively for amateur radio operators. You can choose channel widths of 5, 10, or 20 MHz, with larger channel widths providing higher data rates. Remember that reducing the channel width will increase the :abbr:`SNR (Signal to Noise Ratio)` to improve signal quality if that is an issue for a problem link.
+
+  The radio equipment and antenna systems for this band are readily available and are less expensive due to greater consumer demand. There is a wide variety of equipment from several manufacturers which supports the AREDN |trade| firmware and operates across the 52 available channels. Radio and antenna systems for this band are often smaller in size and less difficult to install. Devices in the 5 cm band are also well-suited for *Backbone Links* since there is little chance for RF interference from other radios sharing these frequencies at high profile sites. With clear line of sight and well-tuned antennas, 5.8 GHz signals can propagate across very long distances.
+
+----------
+
+Different frequency ranges are available to connect the mesh nodes that are required in order to fulfill the purposes for your network. As you plan the frequencies to be deployed at specific locations, it may be helpful to use a *spectrum analyzer* for identifying ranges that are already in use. The ultimate goal is to have a reliable data network that accomplishes its purpose for providing services to the intended destinations and users.
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

arednNetworkDesign/network_modeling.rst

@@ -0,0 +1,69 @@
+================
+Network Modeling
+================
+
+As you design your AREDN |trade| network it is often helpful to estimate ahead of time whether a node or link might accomplish your goals for the network. One way to get this information is to use computer modeling programs that predict the performance of RF devices. There are many types of computerized tools that you can use, ranging from relatively expensive commercial software to freely available open source programs. You should select and become familiar with the tool that best fits your aptitude, experience, and budget.
+
+In this section two free tools will be used to illustrate how to determine your network's available paths and overall coverage. Keep in mind that a computer modeling tool only provides a prediction and does not guarantee that two sites will be able to communicate when actually deployed.
+
+Creating a Path Profile
+-----------------------
+
+Path profiles are very helpful for determining whether a link between two nodes will have clear line of sight and acceptable signal levels. In order to create a path profile you will need to have the following information for both of your node endpoints:
+
+* Latitude and Longitude
+* Antenna :abbr:`AGL (height Above Ground Level)`
+* Frequency
+* Transmit Power
+* Line Loss
+* Antenna Gain
+* Receiver Sensitivity
+
+Most computer modeling software will be able to estimate the link characteristics given this information.
+
+Ubiquiti AirLink Tool
++++++++++++++++++++++
+
+If you are using Ubiquiti radios there is a free modeling tool available on the Ubiquiti website (http://link.ubnt.com). This tool will ask you to locate your node endpoints by clicking on a map display. It allows you to select the radio frequency and model from a dropdown list, as well as having you specify the antenna heights, antenna gain, and transmit power. With this information it will calculate and display the coverage area and the link quality.
+
+The path profile is color coded to indicate whether the link quality is adequate. It displays the link distance, line of sight, as well as the Fresnel Zone and 60% clearance area. It also estimates the signal levels at each endpoint and the predicted throughput for the link. An example *AirLink* path profile is shown below.
+
+----
+
+.. image:: _images/airlink-path.png
+   :alt: Ubiquiti AirLink Modeling
+   :align: center
+
+----
+
+VE2DBE's Radio Mobile Tool
+++++++++++++++++++++++++++
+
+Whether or not you are using Ubiquiti devices, you can create detailed path profiles using VE2DBE's *Radio Mobile* software. This program is available for download, but it is very easy to use the web-based version: http://www.ve2dbe.com/rmonline.html
+
+With *Radio Mobile* you must first create a *Site* for each of your endpoints. Then you can select the endpoints from your *Site* dropdown to generate a path profile between any of the listed locations. Once you enter the radio and antenna information in the link display, *Radio Mobile* will create your path profile. There are several metrics displayed here which may not be available in the Ubiquiti tool, including free space path loss, obstruction loss, forest loss, urban loss, and fade margin. This additional information may help you determine why a path is not working, and it may assist you with choosing alternate sites for node locations. Typically a fade margin of 15 dB or greater is adequate for a usable link. An example *Radio Mobile* path profile is shown below.
+
+----
+
+.. image:: _images/radioMobile-path.png
+   :alt: Radio Mobile Path Profile
+   :align: center
+
+----
+
+Determining Node or Network Coverage
+------------------------------------
+
+In many cases it would be helpful to know ahead of time what area could potentially be covered with the signal generated by a particular node. Creating a coverage plot will show the predicted coverage on any of several types of base map.
+
+An example *Radio Mobile* coverage plot is shown below. After entering the site, radio, and antenna characteristics the software produces a color coded map that predicts the areas of best, marginal, or no signal. One useful feature of *Radio Mobile* allows you to overlay several site coverage plots onto a single map so you can see the extent of coverage provided by multiple nodes in your network. Coverage maps such as these can show you the areas of adequate signal, as well as the "holes" which you may need to fill if you require more comprehensive coverage.
+
+.. image:: _images/radioMobile-coverage.png
+   :alt: Radio Mobile Coverage Plot
+   :align: center
+
+
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

arednNetworkDesign/network_topology.rst

@@ -0,0 +1,35 @@
+==================
+Network Topologies
+==================
+
+Every AREDN |trade| node is capable of automatically joining an AREDN |trade| mesh network which is operating with the same SSID, channel, and bandwidth. A *Mesh* topology consists of independent nodes which each explore their surroundings by broadcasting their identity and listening for their neighbors' responses. Once nodes identify others within radio range, they share this information so that each node has a picture of the network topology. Periodic updates adjust the routes based on changes in signal quality or loss of a link, allowing the network to adapt to changing conditions. Since there are usually several possible routes between nodes, and since network disruptions typically effect only part of the network, a *Mesh* topology can be self-healing.
+
+.. image:: _images/01-mesh-topology.png
+   :alt: Mesh Topology
+   :align: center
+
+This automatic ability to form a mesh network is built into the AREDN |trade| firmware on each node. Every node within radio range of other nodes will be able to participate in the network to extend its reach, provide route redundancy, or host services needed on the network at large. This basic *meshnet* may serve its purpose perfectly for a short-term network deployment in support of a local event, or even for more permanent communication between nodes which are always within radio range.
+
+Types of Links
+--------------
+
+A variety of factors could isolate groups of mesh nodes from each other. For example, distance, terrain, structures, or foliage may prevent some of the nodes from communicating via RF. For long-term or permanent deployments there may be a need for special types of network links that connect what are called mesh "islands." A *link* consists of both sides of a radio path, including the two devices that communicate back and forth across that path.
+
+.. image:: _images/02-link-types.png
+   :alt: Other Topologies
+   :align: center
+
+**Backbone Links**
+  As the name implies, these links form the backbone or superhighway along which large amounts of data can travel for long distances at relatively high speed. Typically backbone or "backhaul" links are permanent installations on mountain peaks, tall buildings, or high towers. They are usually point-to-point links with large high-gain antenna systems running on reliable power sources. In some cases these links are designed with redundant radios which help ensure path protection. Backbone links can operate over distances between 10 to 30+ miles.
+
+**Intermediate Links**
+  Intermediate links bridge the gaps between endpoint nodes. Their primary purpose is to pass network data, but there may be cases where they also serve as mesh access nodes for users. Sometimes these links are call "mid-mile", "distribution", or "relay" nodes. They are usually installed on medium-height towers or buildings in order to achieve high signal quality with good line of sight to other intermediate nodes. Depending on conditions, intermediate links may operate over distances between 3 to 10+ miles.
+
+**Endpoint Links**
+  Endpoint links are used to connect destination nodes to the mesh network. Sometimes these links are call "last mile", "tactical", or "terminal" nodes. Usually these nodes serve either as the originator or the final destination for network traffic. Depending on local conditions, endpoint links typically operate over distances of 3 miles or less.
+
+Different types of radio links may be needed to connect all of the mesh nodes that are required in order to fulfill the purposes for your network. The ultimate goal is to have a reliable data network that accomplishes its purpose for providing services to the intended destinations and users.
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

arednNetworkDesign/networking_overview.rst

@@ -0,0 +1,32 @@
+===================
+Networking Overview
+===================
+
+This **AREDN Network Design Guide** will discuss some of the useful principles for creating robust data networks as a service both to the amateur radio hobby and the community at large. An AREDN |trade| network is able to serve as the transport mechanism for the 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 implementation, this digital data network can operate at near-Internet speeds with many miles between network nodes.
+
+There are a variety of ways to interconnect AREDN |trade| nodes, but the most important question that should be answered is *"What is the purpose for this particular network?"* The specific requirements of your situation will drive the design of your data network. For example, consider the following issues.
+
+**Temporary or Permanent**
+  Is your network being deployed as a short-term communication mechanism, possibly to meet the needs of a day-long event or a training exercise? If so, then several amateur radio operators with portable nodes can quickly establish an *ad hoc* network with a specific set of services to meet the communication needs for that situation. Those nodes and computers can probably operate from portable batteries, without any external power dependencies for such a limited-time deployment.
+
+  Is your network intended as a long-term or permanent infrastructure to serve the on-going communication needs of a local area or region? If so, then a more sophisticated network topology must be designed and constructed to meet those long-term requirements. More robust or ruggedized radio equipment may be necessary, and more reliable AC power or off-grid renewable energy resources will be required to ensure consistent operations.
+
+**Geography and Terrain**
+  Where is data communication needed? Are there specific locations where network nodes are required? What level of :abbr:`RF (Radio Frequency)` coverage will be needed in order to reach those locations? The places that the network must reach will determine the number and position of AREDN |trade| nodes.
+
+  What are the geographical characteristics of the area across which your data network will operate? Different types of terrain may require specific types of network connections in order to adequately cover the region over which data communications are needed. More demanding terrain may require a larger number of intermediate nodes or possibly larger higher-gain antenna systems and mounting structures.
+
+**Expansion and Growth**
+  Will your network need to expand or adapt to changing conditions over time? Mesh networks are ideally suited for *ad hoc* growth and least cost routing based on the availability of nodes. As more devices are added to the network, however, the topology becomes more complicated and data traffic may be routed through multiple "hops" in order to reach its intended destination. This could result in increased latency on the network, with some network segments becoming almost unusable if application response time thresholds cannot met.
+
+**Applications and Throughput**
+  What network programs, applications, or services should be provided in order to fulfill the purpose for this network? Each application will generate a certain amount of data traffic, and some programs or services are more data-intensive than others. The network needs to be designed to adequately pass the traffic for the required applications.
+
+  How many simultaneous users will be generating network traffic at different times? As the number of users increases, the amount of data traversing the network will also increase. In addition, with an increasing number of nodes on the network there will be a corresponding increase in the amount of :abbr:`OLSR (Optimized Link State Routing protocol)` traffic that is necessary to maintain the mesh network. An AREDN |trade| network should be designed to handle the expected workload.
+
+With these issues in mind, it is always best to keep your network as simple as possible and to include only those services which are required. Be sure to design your network so that it accomplishes its mission and suits its intended purpose.
+
+
+
+.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
+   :ltrim:

conf.py

@@ -19,7 +19,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = u'AREDN Getting Started Guide'
+project = u'AREDN Documentation'
 copyright = u'2018, AREDN'
 author = u'KC0EUW'
 
@@ -105,7 +105,7 @@ html_static_path = ['_static']
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'AREDN_Getting_Started_Guidedoc'
+htmlhelp_basename = 'AREDN_Documentation'
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -132,7 +132,7 @@ latex_elements = {
 # (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',
+    (master_doc, 'AREDN_Documentation.tex', u'AREDN Documentation',
      u'AREDN', 'manual'),
 ]
 
@@ -142,7 +142,7 @@ latex_documents = [
 # 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',
+    (master_doc, 'aredn_documentation', u'AREDN Documentation',
      [author], 1)
 ]
 
@@ -153,8 +153,8 @@ man_pages = [
 # (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.',
+    (master_doc, 'AREDN_Documentation', u'AREDN Documentation',
+     author, 'AREDN_Documentation', 'A guide for AREDN software.',
      'Miscellaneous'),
 ]
 

index.rst

@@ -0,0 +1,34 @@
+===================
+AREDN Documentation
+===================
+
+:Version: 3.18.9.0
+
+**Contents:**
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started Guide
+
+   arednGettingStarted/aredn_overview
+   arednGettingStarted/selecting_devices
+   arednGettingStarted/downloading_firmware
+   arednGettingStarted/installing_firmware
+   arednGettingStarted/basic_setup
+   arednGettingStarted/node_status
+   arednGettingStarted/mesh_status
+   arednGettingStarted/advanced_config
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Network Design Guide
+
+  arednNetworkDesign/networking_overview
+  arednNetworkDesign/network_topology
+  arednNetworkDesign/frequency_bands
+  arednNetworkDesign/channel_planning
+  arednNetworkDesign/network_modeling
+  more_info
+
+
+:Reviewers: KC0EUW, K5DLQ, AE6XE, K6AH, WU2S