[[PageOutline]]
[=#mesh]
= Mesh Networking =

This page is a showcase exhibiting 802.11s Mesh Networking on Gateworks Single Board Computers.

[[Image(mesh01.png,600px)]]



This screenshot was generated using Zenmap to graphically represent a mesh network topology. A Nmap ping scan was ran on a Gateworks board with two peers connected via mesh, scan output was then exported to a desktop PC in .xml format.  

== What is Mesh Networking
A mesh network is a local network topology in which nodes connect dynamically without a hierarchy.  Data transfer will follow the most efficient path between clients.  This technology is applicable in many different industries, such as transportation, defense, and energy sectors.

There are many flavors of mesh software that have existed in the past, including OLSR and BATMAN, but the 802.11s format is what is recommended today. 

Reference:
 * [https://en.wikipedia.org/wiki/Mesh_networking Wikipedia]

== Getting started with Mesh == 
There are many variables in mesh networking, thus there's not an all purpose approach for how a mesh network should be configured.  It will require research to decide what hardware and software configuration will fit your needs closest.  

==== Single Board Computer
Gateworks manufactures ARM single board computers that act as a node in a mesh network. The single board computers have Mini-PCIe slots that allow for !WiFi Mini-PCIe cards.

Gateworks offers a few different families of SBCs, with each family having a specific CPU. The Newport Family features a 64-bit CPU with DDR4 RAM while the Ventana Family features a 32-bit ARM CPU with DDR3 RAM. Both families are excellent choices as platforms in a mesh network.  

 * [https://www.gateworks.com/products/ Gateworks Single Board Computers]

==== !WiFi Radios

The first thing to consider is what radio to use, not all radios support mesh and some that do will require specific kernel versions or firmware to accomplish this.  The best source of information will be the radio manufacturer — something to consider when selecting a radio is the level of support that will be available.  Linux kernel mailing lists should be used as a primary resource if you suspect there's an issue with the driver, kernel, or radio firmware.  WLE900VX is an excellent choice of radio and is available from the [https://shop.gateworks.com/ Gateworks store].  This radio has been tested to work with 4.14, 4.20, and 5.4 kernels.  A second radio which has been tested by Gateworks is the WPEQ-261ACNI(BT), this card is half length and includes bluetooth.  According to the manufacturer this card will only mesh in kernel versions 5.3 and newer, and only when using a custom built wpa_supplicant.  When creating a mesh network not all radios need to be the same model, we have tested creating a mesh network using a combination of these two radio models successfully. 

Recommended !WiFi Radio:
 * [https://shop.gateworks.com/index.php?route=product/product&product_id=196 Gateworks GW17032 - Compex WLE900VX 802.11AC Radio]

==== Operating System

Select a Board Support Package (BSP) that is appropriate for your application.  In our testing the Bionic Ubuntu root filesystem was used with both Newport and Ventana family boards.  OpenWRT and Buildroot are viable options as well.  Enabling the necessary kernel modules will be required, though you may find in Gateworks kernel defconfigs these options have already been added. In our testing the following kernel config options were enabled:

CONFIG_MAC80211_MESH=y

CONFIG_LIBERTAS_MESH=y

This can be verified in Linux userspace with the command:
{{{#!bash
zcat /proc/config.gz |grep mesh -i
}}}

During testing attach antennas or attenuators depending on the proximity of the radios.  Without a strong clean signal the network may behave unpredictably.  

== Configuring your Operating System / BSP 

Beyond the aforementioned steps providing anything more than general pointers would be impractical. There are many variables in how hardware can behave, what works in one case will cause a different configuration to fail.  The following guidance is intended for those using Ath10k radios.  

Some circumstances will require testing multiple firmware versions.  Ath10k firmware can be downloaded from this repository:

https://github.com/kvalo/ath10k-firmware

The version of the current firmware being used can be verified by checking dmesg. 
{{{#!bash
dmesg |grep ath -i 
}}}
Example:
{{{
[   16.699066] ath10k_pci 0000:07:00.0: firmware ver 10.2.4-1.0-00037 api 5 features no-p2p,raw-mode,mfp,allows-mesh-bcast crc32 a4a52adb
}}}

Depending on the firmware version you may be required to use a module parameter for rawmode.  In some situations using rawmode will cause the interface to not appear, it is best to test without this option enabled first.  When configuring the network you may receive a message informing you that it is required. 

To enable raw mode:  
{{{#!bash
setenv bootargs "${bootargs} ath10k_core.rawmode=1"
}}}
This option can also be enabled in the bootscript.  On Newport make changes to "newport.env".    

Check that your wireless interface is available:
{{{#!bash
ls /sys/class/net/
}}}

Check mesh point is an available network type: 
{{{#!bash
iw list |grep "mesh point"
}}}
If these two items are present proceed with bringing up the mesh interface.

=== Bringing up the mesh network interface using "iw" ===

Reference:
* https://wireless.wiki.kernel.org/en/users/drivers/ath10k/mesh

Create a mesh point interface “mesh0”.
{{{#!bash
iw phy phy0 interface add mesh0 type mp
}}}
Confirm the creation of the new interface.
{{{#!bash
iw mesh0 info
#if set correctly this command will return the following:
#Interface mesh0
#        type mesh point
}}}
Configure channel information, all radios on the network must be configured to use the same frequency.
{{{#!bash
iw dev mesh0 set freq 5745 80 5775
}}}

Optionally, the interface’s MAC address can be set.
{{{#!bash
ifconfig mesh0 hw ether 00:11:22:33:44:56
}}}

Assign a static IP and bring up the interface.
{{{#!bash
ifconfig mesh0 192.168.1.10
}}}

Join a network. “mesh-ath10k” is the mesh ID which can be maximum of 32 bytes long.
{{{#!bash
iw dev mesh0 mesh join mesh-ath10k
}}}

Verify link status, this command will not return anything unless there are minimum two peers on the network.  
{{{#!bash
iw mesh0 station dump
}}}

=== Bringing up the mesh network interface using "wpa_supplicant" ===

Some firmware will require compiling wpa_supplicant from source. 

Download the source code from this address:

http://www.linuxfromscratch.org/blfs/view/svn/basicnet/wpa_supplicant.html

Install required packages:
{{{#!bash
apt-get install libssl-dev dbus libdbus-1-dev libdbus-glib-1-2 libdbus-glib-1-dev libnl-3-dev libnl-genl-3-dev build-essential -y
}}}
Extract the .tar and create a .config:
{{{#!bash
tar -xvf wpa_supplicant-2.9.tar.gz
cd wpa_supplicant-2.9/wpa_supplicant/
cp defconfig .config
}}}

Use "vi" to edit the .config file, make sure CONFIG_MESH is not commented out and verify it is enabled:
{{{
CONFIG_MESH=y
}}}

Build wpa_supplicant:
{{{#!bash
make all & make install
}}}
* Optional - execute the command "which wpa_supplicant" to locate the file that is currently in your $PATH and replace it with the one you have freshly built. 
Verify that wpa_supplicant is the desired version:
{{{#!bash
wpa_supplicant -v 
}}}	
Create an /etc/wpa_supplicant.conf file with the following contents:
{{{ 
ctrl_interface=/var/run/wpa_supplicant
user_mpm=1
network={
	ssid="Mesh0"
	mode=5
	frequency=2442
	key_mgmt=NONE
}}}
Create a mesh point interface “mesh0”:
{{{#!bash
iw phy phy0 interface add mesh0 type mp
}}}
Optinally set the interface’s MAC address:
{{{#!bash
ifconfig mesh0 hw ether 00:11:22:33:44:56
}}}
Assign a static IP and bring up the interface.
{{{#!bash
ifconfig mesh0 192.168.1.10
}}}
Verify wpa_supplicant is not already running, if so kill the PID:
{{{#!bash
ps -ef |grep wpa 
kill -9 <PID>
}}}
Launch wpa_supplicant, run in the background.
{{{#!bash
wpa_supplicant -Dnl80211 -imesh0 -c /etc/wpa_supplicant.conf -B $
}}}
Check that two peers are connected:
{{{#!bash
iw mesh0 station dump
}}}
== Pre-built Software Image
Gateworks standard pre-built images do not normally include the options for mesh networking. 

For convenience, the software image .img.gz that was used for testing with a Newport SBC is linked below.    

[http://dev.gateworks.com/fae/mesh-newpor54.img.gz Newport Mesh Pre-Built .img.gz]

= B.A.T.M.A.N.

Better Approach To Mobile Adhoc Networking is a routing protocol which enables the user to create a decentralized layer 2 network.  For more information see the [https://www.open-mesh.org/projects/batman-adv/wiki official BATMAN wiki].  

This example is directed at Ubuntu users, though BATMAN can be used with OpenWRT and Buildroot as well.  

Before configuration make sure you have antennas or attenuators connected.  Then verify your wireless radio is capable of being used for mesh.  This can be checked using the command "iw list |grep mesh -i".

To begin, flash two boards with the image linked below:

http://dev.gateworks.com/newport/images/focal-newport.img.gz

Boot them and install batman-adv:

{{{#!bash
apt install batctl -y
}}}

Edit /etc/modules add the line below:
{{{
batman-adv
}}}
'sync' then power cycle the boards, once you're back to the command prompt issue the following commands:
{{{#!bash
ip link set up dev wlan0
iw dev wlan0 del
iw phy phy0 interface add wlan0 type mesh
ip link set up mtu 1532 dev wlan0
iw dev wlan0 mesh join my-mesh-network
batctl if add wlan0
# Optional, use "batctl if" to see if your interface is active.
ip link set up dev bat0
batctl n
}}}

With this is done on both boards "batctrl n" should display the MAC of the neighbor board:
{{{
root@focal-newport:~# batctl n
[B.A.T.M.A.N. adv 2019.4, MainIF/MAC: wlan0/04:f0:21:3e:59:55 (bat0/ae:23:a0:50:1c:27 BATMAN_IV)]
IF             Neighbor              last-seen
        wlan0  04:f0:21:3e:59:56    0.084s
}}}