Merge pull request #1582 from rubo77/readthedocs

docs: cherry-pick from master of all relevant changes for 2018.1.x

docs/features/autoupdater.rst

@@ -8,10 +8,10 @@ Building Images
 
 By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
 during development), but it can be enabled by setting the variable GLUON_BRANCH when building
-to override the default branch set in the set in the site configuration.
+to override the default branch set in the site configuration.
 
 A manifest file for the updater can be generated with `make manifest`. A signing script (using
-``ecdsautils``) can by found in the `contrib` directory. When creating the manifest, the
+``ecdsautils``) can be found in the `contrib` directory. When creating the manifest, the
 ``PRIORITY`` value may be defined by setting ``GLUON_PRIORITY`` on the command line or in ``site.mk``.
 
 ``GLUON_PRIORITY`` defines the maximum number of days that may pass between releasing an update and installation
@@ -35,9 +35,9 @@ A fully automated nightly build could use the following commands:
 ::
 
     git pull
-    (cd site && git pull)
+    (git -C site pull)
     make update
-    make clean
+    make clean GLUON_TARGET=ar71xx-generic
     NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
     make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ar71xx-generic GLUON_BRANCH=experimental
     make manifest GLUON_BRANCH=$GLUON_BRANCH GLUON_RELEASE=$GLUON_RELEASE

docs/features/multidomain.rst

@@ -214,20 +214,21 @@ domain.conf only variables
 
    -  wifi*.ap.ssid
 
-- Some values should be only set in legacy domains and not in new domains.
+-  Some values should be only set in legacy domains and not in new domains.
+
    -  mesh.vxlan
 
-       -  By default, this value is `true`. It should be only set to `false`
-          for one legacy domain, since vxlan prevents accidental wired
-          merges of domains. For old domains this value is still available
-          to keep compatibility between all nodes in one domain.
+      -  By default, this value is `true`. It should be only set to `false`
+         for one legacy domain, since vxlan prevents accidental wired
+         merges of domains. For old domains this value is still available
+         to keep compatibility between all nodes in one domain.
 
    -  next_node.mac
 
-       -  For new domains, the default value should be used, since there is
-          no need for a special mac (or domain specific mac). For old domains
-          this value is still available to keep compatibility between all
-          nodes in one domain.
+      -  For new domains, the default value should be used, since there is
+         no need for a special mac (or domain specific mac). For old domains
+         this value is still available to keep compatibility between all
+         nodes in one domain.
 
 Example config
 --------------

docs/user/site.rst

@@ -118,8 +118,15 @@ wifi24 \: optional
     Additionally it is possible to configure the ``supported_rates`` and ``basic_rate``
     of each radio. Both are optional, by default hostapd/driver dictate the rates.
     If ``supported_rates`` is set, ``basic_rate`` is required, because ``basic_rate``
-    has to be a subset of ``supported_rates``.
-    The example below disables 802.11b rates.
+    has to be a subset of ``supported_rates``. Possible values are: 
+
+    - 6000, 9000, 12000, 18000, 24000, 36000, 48000, 54000 (OFDM)
+    - 1000, 5500, 11000 (legacy 802.11b, DSSS)
+
+    The example below disables legacy 802.11b rates (DSSS) for performance reasons.  
+    For backwards compatibility in 802.11, this setting only effects 802.11a/b/g rates. 
+    I.e in 802.11n 6 MBit/s is announced  all time. In 802.11ac the field is used to 
+    derive the length of a packet.
 
     ``ap`` requires a single parameter, a string, named ``ssid`` which sets the
     interface's ESSID. This is the WiFi the clients connect to.
@@ -211,15 +218,31 @@ mesh
     In addition, options specific to the batman-adv routing protocol can be set
     in the *batman_adv* section:
 
-    The optional value *gw_sel_class* sets the gateway selection class. The
-    default is class 20, which is based on the link quality (TQ) only; class 1
-    is calculated from both the TQ and the announced bandwidth.
+    The optional value *routing_algo* allows to set up ``BATMAN_V`` based meshes. 
+    If unset, the routing algorithm will default to ``BATMAN_IV``.
+
+    The optional value *gw_sel_class* sets the gateway selection class, the
+    default is ``20`` for B.A.T.M.A.N. IV and ``5000`` kbit/s for B.A.T.M.A.N. V.
+
+    - **B.A.T.M.A.N. IV:** with the value ``20`` the gateway is selected based
+      on the link quality (TQ) only; with class ``1`` it is calculated from
+      both, the TQ and the announced bandwidth.
+    - **B.A.T.M.A.N. V:** with the value ``1500`` the gateway is selected if the
+      throughput is at least 1500 kbit/s faster than the throughput of the
+      currently selected gateway. 
+
+    For details on determining the threshhold, when to switch to a new gateway,
+    see `batctl manpage`_, section "gw_mode".
+    
+    .. _batctl manpage: https://www.open-mesh.org/projects/batman-adv/wiki/Gateways
+
     ::
 
       mesh = {
         vxlan = true,
         filter_membership_reports = false,
         batman_adv = {
+          routing_algo = 'BATMAN_IV',
           gw_sel_class = 1,
         },
       }
@@ -667,41 +690,5 @@ modules
 site-repos in the wild
 ^^^^^^^^^^^^^^^^^^^^^^
 
-This is a non-exhaustive list of site-repos from various communities:
-
-* `site-ffa <https://github.com/tecff/site-ffa>`_ (Altdorf, Landshut & Umgebung)
-* `site-ffac <https://github.com/ffac/site>`_ (Regio Aachen)
-* `site-ffbs <https://github.com/ffbs/site-ffbs>`_ (Braunschweig)
-* `site-ffhb <https://github.com/FreifunkBremen/gluon-site-ffhb>`_ (Bremen)
-* `site-ffda <https://git.darmstadt.ccc.de/ffda/site>`_ (Darmstadt)
-* `site-ff3l <https://github.com/ff3l/site-ff3l>`_ (Dreiländereck)
-* `site-ffeh <https://github.com/freifunk-ehingen/site-ffeh>`_ (Ehingen)
-* `site-fffl <https://github.com/freifunk-flensburg/site-fffl>`_ (Flensburg)
-* `site-ffgoe <https://github.com/freifunk-goettingen/site-ffgoe>`_ (Göttingen)
-* `site-ffgt-rhw <https://github.com/ffgtso/site-ffgt-rhw>`_ (Guetersloh)
-* `site-ffhh <https://github.com/freifunkhamburg/site-ffhh>`_ (Hamburg)
-* `site-ffho <https://git.ffho.net/freifunkhochstift/ffho-site>`_ (Hochstift)
-* `site-ffhgw <https://github.com/lorenzo-greifswald/site-ffhgw>`_ (Greifswald)
-* `site-ffka <https://github.com/ffka/site-ffka>`_ (Karlsruhe)
-* `site-ffki <https://git.freifunk.in-kiel.de/ffki-site/>`_ (Kiel)
-* `site-fflz <https://github.com/freifunk-lausitz/site-fflz>`_ (Lausitz)
-* `site-ffl <https://github.com/freifunk-leipzig/freifunk-gluon-leipzig>`_ (Leipzig)
-* `site-ffhl <https://github.com/freifunk-luebeck/site-ffhl>`_ (Lübeck)
-* `site-fflg <https://github.com/kartenkarsten/site-fflg>`_ (Lüneburg)
-* `site-ffmd <https://github.com/FreifunkMD/site-ffmd>`_ (Magdeburg)
-* `site-ffmwu <https://github.com/freifunk-mwu/sites-ffmwu>`_ (Mainz, Wiesbaden & Umgebung)
-* `site-ffmyk <https://github.com/FreifunkMYK/site-ffmyk>`_ (Mayen-Koblenz)
-* `site-ffmo <https://github.com/ffruhr/site-ffmo>`_ (Moers)
-* `site-ffmg <https://github.com/ffruhr/site-ffmg>`_ (Mönchengladbach)
-* `site-ffm <https://github.com/freifunkMUC/site-ffm>`_ (München)
-* `site-ffhmue <https://github.com/Freifunk-Muenden/site-conf>`_ (Münden)
-* `site-ffms <https://github.com/FreiFunkMuenster/site-ffms>`_ (Münsterland)
-* `site-neuss <https://github.com/ffne/site-neuss>`_ (Neuss)
-* `site-ffniers <https://github.com/ffruhr/site-ffniers>`_ (Niersufer)
-* `site-ffndh <https://github.com/freifunk-nordheide/ffnordheide/tree/ffnh-lede/ffndh-site>`_ (Nordheide)
-* `site-ffnw <https://git.nordwest.freifunk.net/ffnw-firmware/siteconf/tree/master>`_ (Nordwest)
-* `site-ffrgb <https://github.com/ffrgb/site-ffrgb>`_ (Regensburg)
-* `site-ffrn <https://github.com/Freifunk-Rhein-Neckar/site-ffrn>`_ (Rhein-Neckar)
-* `site-ffruhr <https://github.com/ffruhr?utf8=✓&query=site>`_ (Ruhrgebiet, Multi-Communities)
-* `site-ffs <https://github.com/freifunk-stuttgart/site-ffs>`_ (Stuttgart)
-* `site-fftr <https://github.com/freifunktrier/site-fftr>`_ (Trier)
+A non-exhaustive list of site-repos from various communities can be found on the
+wiki: https://github.com/freifunk-gluon/gluon/wiki/Site-Configurations