134 lines
4.3 KiB
ReStructuredText
134 lines
4.3 KiB
ReStructuredText
gluon-hoodselector
|
||
==================
|
||
|
||
This package provides an automated way to continuously select the correct
|
||
domain based on the geolocation of a node. The purpose of Hoodselector is to
|
||
automatically detect in which domain the node is located based on its
|
||
geolocation settings. Therefore domains are required to have bounding boxes,
|
||
defined as polygons or rectangles. Based on this information Hoodselector will
|
||
select a domain from the list of known domains and migrate towards it without
|
||
requiring a reboot. This package therefore provides a scalable and
|
||
decentralized approach to automatic domain selection.
|
||
|
||
Background information
|
||
----------------------
|
||
|
||
The main problem of the Nordwest Freifunk community was the quickly rising
|
||
number of nodes in the network. This indirectly affected the stability of the
|
||
network, because the noise inside the network, e.g. management traffic from
|
||
the batman-adv protocol, was rising, too. Inside the community there were some
|
||
ideas like building separate firmwares for each region. This solution would
|
||
cause issues with splitting regions again and nodes scattered among regions
|
||
which belong to a different region. Therefore we decided to develop a
|
||
dynamic and decentralized management of regions called domains.
|
||
The Hoodselector's task is to choose the "right" domains in an intelligent way
|
||
and to hold the network together and accessible.
|
||
|
||
A domain is defined by geostationary fixed shapes by using longitude & latitude
|
||
in combination with the domain configuration system. Below you can see a visual
|
||
example of a regional domain:
|
||
|
||
.. figure:: ./gluon-hoodselector-domainmap.jpeg
|
||
:alt: Regional domains visualized as shapes defined by latitude & longitude
|
||
|
||
© OpenStreetMap contributors
|
||
|
||
Behaviour
|
||
------------------
|
||
|
||
The following is an abstract state diagram which gives an overview
|
||
of the process:
|
||
|
||
.. image:: ./gluon-hoodselector.svg
|
||
|
||
The sequence of this diagram reflects the priority of its running modes.
|
||
Each mode will be explained separately below.
|
||
|
||
geolocation mode
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
This mode will only be entered when a node has location coordinates set.
|
||
Nodes with a position will set their domain based on it.
|
||
The node will skip to the next mode when the node (a) has no position or
|
||
(b) its position is not within any of the defined bounding boxes.
|
||
|
||
default domain mode
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
This mode will be entered if no other mode before fits.
|
||
It provides a fallback to the default domain.
|
||
|
||
Domain shapes
|
||
-------------
|
||
|
||
There are two types of domains: the unique default one without a defined shape
|
||
and others which contain shapes.
|
||
|
||
* **default domain**
|
||
|
||
The default domain doesn’t hold any shapes and represents the inverted area of
|
||
all other shapes held by other domains with geo coordinates. It will only be
|
||
entered if a node could not be matched to a geo domain. A suggested approach is
|
||
to define the "old" network as default domain and gradually migrate nodes from
|
||
there to geo domains.
|
||
|
||
* **geo domains**
|
||
|
||
A geo domain contains shapes, which are described by three dimensional arrays
|
||
and represents the geographical size of the domain. There are two possible
|
||
definitions of these shapes. The first one is using rectangles so that only
|
||
two coordinates per box are needed to define it (see below for an
|
||
example). The second one uses polygons which can have multiple edges.
|
||
Each domain can hold multiple shapes.
|
||
|
||
.. image:: ./gluon-hoodselector-rectangle-example.svg
|
||
|
||
site.conf
|
||
---------
|
||
|
||
The designer of the shapes must always ensure that no overlapping polygons
|
||
between domains will be created or else the order in the domain list will
|
||
become relevant. If for example domain A and B overlap, Hoodselector
|
||
would, for that overlapping area, only ever reach domain A, but never domain B.
|
||
Here is an example of a rectangular definition of a shape:
|
||
Example::
|
||
|
||
hoodselector = {
|
||
shapes = {
|
||
{
|
||
{
|
||
lat = 53.128,
|
||
lon = 8.187
|
||
},
|
||
{
|
||
lat = 53.163,
|
||
lon = 8.216
|
||
},
|
||
},
|
||
},
|
||
},
|
||
|
||
Here is an example of a shape defined by a triangle:
|
||
Example::
|
||
|
||
hoodselector = {
|
||
shapes = {
|
||
{
|
||
{
|
||
lat = 53.128,
|
||
lon = 8.187
|
||
},
|
||
{
|
||
lat = 53.163,
|
||
lon = 8.216
|
||
},
|
||
{
|
||
lat = 53.196,
|
||
lon = 8.194
|
||
},
|
||
},
|
||
},
|
||
},
|
||
|
||
This package is incompatible with :doc:`gluon-config-mode-domain-select`.
|