====== Building MESHdesk firmware using the LEDE Project ======

===== What is the LEDE Project? =====

> The LEDE project is founded as a spin-off of the OpenWrt project and shares many of the same goals. We are building an embedded Linux distribution that makes it easy for developers, system administrators or other Linux enthusiasts to build and customize software for embedded devices, especially wireless routers. The name LEDE stands for Linux Embedded Development Environment.

===== Why are you advocating LEDE Project instead of OpenWrt? =====

  * The LEDE project is endorsed by communities that share common interests to MESHdesk (eg Mesh networks)
  * The LEDE project is active and dynamic.

===== Preparing the environment =====
  * We assume you have a standard install of the Ubuntu 16.04 operating system.
  * You need to install certain required packages which the LEDE build environment needs to function correct.
<code bash>
sudo apt-get update
sudo apt-get install build-essential subversion git-core libncurses5-dev zlib1g-dev gawk flex quilt libssl-dev xsltproc libxml-parser-perl unzip mercurial
</code>

------------

===== Check out the code =====
  * We will use the **17.0.1 release** of LEDE which is the first stable release of the LEDE Project.

<WRAP center round tip 100%>
  * Please note that we use the **release 17.0.1** and not the **lede-17.01 branch**.
  * Refer to this URL for the different releases and branches: https://github.com/lede-project/source/
</WRAP>

<code bash>
cd ~
mkdir lede
cd lede
git clone https://git.lede-project.org/source.git
#To see the tags (releases)
git fetch --tags
git tag -l
#Checkout the 17.0.1 release
git checkout v17.01.0
</code>
  * This will create a folder called **source** where the build environment resides.

<WRAP center round tip 100%>
 <wrap em>Please refrain from using the current development branch or even the **lede-17.01** branch since something in that code breaks the Batman-adv mesh in the MESHdesk firmware making it useless.</wrap>
</WRAP>

------------

===== Installing the packages =====
  * Update the feeds:
<code bash>
./scripts/feeds update
</code>
   * Install the following MESHdesk specific packages:
<code bash>
./scripts/feeds install coova-chilli
./scripts/feeds install luasocket
./scripts/feeds install libuci-lua
./scripts/feeds install curl
./scripts/feeds install -a -p routing 
./scripts/feeds install iwinfo
./scripts/feeds install alfred
</code>

  * You might get some warnings when you install thse packages. 
    * They are non-critical except if you might want to include ssl support with CoovaChilli.
    * The other warning is if you might want to include GPS support with Alfred
<code bash>
Installing package 'coova-chilli' from packages
WARNING: No feed for package 'libmatrixssl' found, maybe it's already part of the standard packages?

Installing package 'alfred' from routing
WARNING: No feed for package 'libgps' found, maybe it's already part of the standard packages?
</code>

-----------------

===== Adding the MESHdesk package =====
  * MESHdesk is now very easy to add since it is simply an LEDE package which can be selected.
  * Check out the current development MESHdesk code from SVN
<code bash>
svn checkout svn://dvdwalt@svn.code.sf.net/p/radiusdesk/code/trunk/meshdesk/MESHdesk ./MESHdesk
</code>
  * Make a tar file of the code:
<code bash>
tar -czvf MESHdesk.tar.gz ./MESHdesk
</code>
  * Change directory to the LEDE **source** code:
<code bash>
cd ./source
</code>
  * Create a directory called **zzz-MESHdesk** with a sub directory called **files** under the **package** directory.
<code bash>
mkdir -p ./package/zzz-MESHdesk/files
</code>
  * Copy the MESHdesk.tar.gz file to the **./package/zzz-MESHdesk/files** directory.
<code bash>
cp [where ever you file is]/MESHdesk.tar.gz ./package/zzz-MESHdesk/files
</code>
  * Change directory to the ./package/zzz-MESHdesk/files directory and extract the file.
<code bash>
cd ./package/zzz-MESHdesk/files
tar -xzvf MESHdesk.tar.gz
</code>
  * Move the **Makefile** to be under the **zzz-MESHdesk** directory.
<code bash>
mv ./MESHdesk/Makefile ../
</code>
  * The MESHdesk code also include a **password** and **shadow** file with a user **root** and password **admin**.
  * To include that in the firmware you need to do the following:
    * Create a **files** directory under the **source** directory.
    * Create a directory structure similar to what you want on the firmware
    * Add the files in these directories
   * Change directory to the LEDE **source** code:
<code bash>
cd ./source
mkdir -p files/etc
cp ./package/zzz-MESHdesk/files/MESHdesk/files/common/passwd ./files/etc
cp ./package/zzz-MESHdesk/files/MESHdesk/files/common/shadow ./files/etc
</code>

<WRAP center round tip 90%>
  * Should you wish to get an existing build environment's MESHdesk package updated to the latest SVN:
<code bash>
cd ./source
cd ./package/zzz-MESHdesk/files/MESHdesk
svn update
#It will mention that it restored the Makefile
#Restored 'Makefile'
cd ../
mv ./MESHdesk/Makefile ../
</code>
</WRAP>


-----------------

===== Tweaking MESHdesk package =====
==== MediaTek or Atheros ====

  * We now support both MediaTek and Atheros based devices.
  * This enables MESHdesk firmware to run on a whole lot of additional devices.
  * The MediaTek devices are typically cheaper when compared to the Atheros based devices.
  * We even got the MediaTek devices to mesh on 802.11AC!

  * When you compile for MediaTek, replace the **dhcp_network_one_eth** with **dhcp_network_one_eth_mediatek** and the **frmwr_network_one_eth** with **frmwr_network_one_eth_mediatek**.
  * When you compile for Atheros, replace the **dhcp_network_one_eth** with **dhcp_network_one_eth_atheros** and the **frmwr_network_one_eth** with **frmwr_network_one_eth_atheros**.

<code bash>

#Compiling MediaTek
cd ./source
cp ./package/zzz-MESHdesk/files/MESHdesk/configs/dhcp_network_one_eth_mediatek ./package/zzz-MESHdesk/files/MESHdesk/configs/dhcp_network_one_eth
cp ./package/zzz-MESHdesk/files/MESHdesk/configs/frmwr_network_one_eth_mediatek ./package/zzz-MESHdesk/files/MESHdesk/configs/frmwr_network_one_eth

#Compiling Atheros
cd ./source
cp ./package/zzz-MESHdesk/files/MESHdesk/configs/dhcp_network_one_eth_atheros ./package/zzz-MESHdesk/files/MESHdesk/configs/dhcp_network_one_eth
cp ./package/zzz-MESHdesk/files/MESHdesk/configs/frmwr_network_one_eth_atheros ./package/zzz-MESHdesk/files/MESHdesk/configs/frmwr_network_one_eth

</code>

<WRAP center round alert 90%>
  * Pleas take care to do the steps above or else you could render your firmware **useless** if it is using the wrong file!
</WRAP>


==== HTTP or HTTPS ====
  * We also support both **HTTPS** and **HTTP** when the device fetch and report its settings to the back-end.
  * To use HTTPS instead of the default **HTTP** edit the meshdesk config file
<code bash>
 vi ./package/zzz-MESHdesk/files/MESHdesk/meshdesk
</code>
  *  Change the protocol to **https**.
<code bash>
config internet 'internet1'
        option dns 'rd01.wificity.asia'
        option url 'cake2/rd_cake/nodes/get_config_for_node.json'
        option status_url 'cake2/rd_cake/mesh_reports/submit_report.json'
        option actions_url 'cake2/rd_cake/node_actions/get_actions_for.json'
        option ap_url 'cake2/rd_cake/aps/get_config_for_ap.json'
        option ap_status_url 'cake2/rd_cake/ap_reports/submit_report.json'
        option ap_actions_url 'cake2/rd_cake/ap_actions/get_actions_for.json'
        option protocol 'https'
        option ip '192.168.99.1'
</code>

==== Identity interface ====
  * The following step is only required on some TP Link devices. Notably those who has Gigabit Ethernet ports.
  * On these devices the LAN is connected to **eth1** instead of the usual **eth0**.
  * We know of the **TP-Link WR1043ND** and also the **Archer** models that have this issue.
<code bash>
 vi ./package/zzz-MESHdesk/files/MESHdesk/meshdesk
</code>
  * Edit the following and change:
<code bash>
option id_if 'eth0'
</code>
  * To
<code bash>
option id_if 'eth1'
</code>

==== Default mode ====
  * The MESHdesk firmware currently supports three modes. 
  * They are:
    * **off** -> The MESHdesk package is not active
    * **mesh** -> The device will contact the **MESHdesk** applet and are managed as a mesh node.
    * **ap** -> The device will contact the **APdesk** applet and are managed as a member of one of the AP Profiles.
<code bash>
 vi ./package/zzz-MESHdesk/files/MESHdesk/meshdesk
</code>
    * These are specified as an option under the **settings** section.
<code bash>
option gw_auto_reboot_time '600'
option mode 'mesh'
option id_if 'eth0'
</code>

==== Preset for a certain model and server ====
  * Should you wish to already have the firmware setup when you flash it (As needed for Over The Air OTA upgrades) check the following additional items.
  * Specify the server it is pointing to
<code bash>
 vi ./package/zzz-MESHdesk/files/MESHdesk/meshdesk
</code>
  * Under **internet1** the value of **ip**
  * Under **settings** the value of **hardware** should specify the correct value of the model you use. Available options are in the same file.
  * Then you need to specify a system config file to define the LED we will use to indicate the mesh traffic
<code bash>
 vi ./files/etc/config/system
</code>
  * Use this as a reference.
<code bash>
config system
        option ttylogin '0'
        option log_size '64'
        option urandom_seed '0'
        option timezone 'SAST-2'
        option hostname '505'

config timeserver 'ntp'
        option enabled '1'
        option enable_server '0'
        list server '0.lede.pool.ntp.org'
        list server '1.lede.pool.ntp.org'
        list server '2.lede.pool.ntp.org'
        list server '3.lede.pool.ntp.org'

config led 'wifi_led'
        option name 'wifi'
        option trigger 'netdev'
        option dev 'bat0'
        option mode 'link tx rx'
        option sysfs 'zbt-wa05:blue:air'

</code>


  * Now the tweaks are completed we can select the packages to include.

-------------------

===== Selecting the packages =====
  * Enter the following command in the directory which you checked the code out:
<code bash>
make menuconfig
</code>
  * This will open a cursors interface which allows you to specify certain selections to include with the firmware build.
  * Along with this you also need to select the architecture and or board combination of the firmware you are planning to build. 
  * It seems the package selection get lost if you switch between architectures.
  * Make sure that when you build for another architecture the packages are still selected.
  * Some packages are actually optional, depending on how you user **MESHdesk** and **APdesk**. We recommend though that you include all of the packages in the list where possible. The optional packages which can be left out are the the following:
    * **Coova Chilli** - Not having this package will remove the captive portal functionality.
    * **OpenVPN** - Not having this package will remove the ability to set up OpenVPN tunnel exit points.
    * **wpad** - By using the default **wpad-mini** you will not have WPA2 Enterprise security available on the SSIDs.
  * Select the following packages as build-in when preparing the firmware:

<WRAP center round info 90%>
//We recommend that you include all of the packages in the list where possible.// 8-)
</WRAP>


^ Package      ^ Detail       ^ 
| **Languages -> lua**    | Embedded lightweight scripting language |
| **Languages -> luasocket** | We neet this library for precision timing |
| **libraries -> libuci-lua** | Interface library for lua scripting language to UCI system |
| **Kernel modules -> Network support -> batman-adv** | used for the mesh |
| **Network -> alfred** | used to communicate over the mesh  |
| **Network -> batctl** | User space configuration tool  |
| Network -> Captive Portals -> coova-chilli | Captive portal for the breakout points |
| **Network -> File Transfer -> Curl** | A Client side URL Transfer utility |
| Network -> VPN -> OpenVPN PolarsSSL | OpenVPN package for OpenVPN brige exit point - You can also use OpenVPN OpenSSL |
| Network -> wpad | use this instead of **wpad-mini** to allow WPA Enterprise suport |
| **Utilities -> iwinfo** | Handy utility to get Wifi info instead of iw |
| **Base system -> zzz-MESHdesk** | The package we checked out and added manually from SVN |

==== Support for 3G/4G dongles ====
<WRAP center round important 90%>
  * We are once again taking the lead with new features. 
  * Lets see <wrap em>when and if</wrap> the commercial guys will follow with 3G/4G support since it requires additional hardware.
</WRAP>

  * If you want to add support for 3G/4G dongles as an alternative to Ethernet based Internet be sure to include the following packages.

^ Package      ^ Detail       ^ 
| **Utilities -> comgt**    | Used to create chat scripts to connect to mobile network |
| **Kernel modules -> USB support -> kmod-usb-serial** | Required for USB data transfer |
| **Kernel modules -> USB support -> kmod-usb-serial-option** | Required for USB data transfer |
| **Kernel modules -> USB support -> kmod-usb-serial-wwan** | Required for USB data transfer |
| **Kernel modules -> USB support -> kmod-usb2** | Required for USB support in device |
| **Utilities -> usb-modeswitch** | Required to switch the mode of the USB stick from storage to modem  |



==== Atheros based 802.11AC ====

  * If you build firmware for hardware that includes the **ATH10K** driver, be sure to also include the binary blob firmware package.
  * The following table can be uses as a reference

^ Hardware      ^ Firmware Package       ^ 
| Yuncore XD3200    | ath10k-firmware-qca988x |


==== Support for WiFi Client Internet connection ====
<WRAP center round important 90%>
  * We are once again taking the lead with new features. 
  * This might take the others a bit quicker to catch up with us since it does not require additional hardware.
</WRAP>

  * If you want to add support for WiFi Client Internet connection as an alternative to Ethernet based Internet be sure to include the following package.

^ Package      ^ Detail       ^ 
| **Network -> Routing and Redirection -> relayd**    | Used to bridge the WiFi Station interface with the LAN |

----------------

===== Removing unused packages =====
  * Some devices that we flash the MESHdesk firmware on have limited space on the flash chip. These devices typically have only 4M flash.
  * We then need to remove as much of the packages we do not need in order for our firmware to fit on the chip.

^ Package      ^ Detail       ^ 
| Network -> odhcp6c    | No need for DHCP client v6 |
| Network -> odhcpd | No need for DHCP server v6 |
| Network -> ppp | No need for PPP |
| Kernel modules -> Network Support -> kmod-ppp | No need for PPP |
| Network → wpad | Use **wpad-mini** instead (This forfeit WPA Enterprise suport) |

<WRAP center round important 80%>
The only way we could manage to fit everything on a 4M device was to replace **wpad** again with **wpad-mini** (This on Chaos Calmer)
</WRAP>


----------------


===== Building the firmware =====
  * You should now be able to build the firmware using the following command inside the build directory
<code bash>
make V=99
</code>
  * The build process can take long especially if you have a slow machine with a slow Internet connection so put at least 12 hours aside for this.

----------

===== What next? =====
  * After the firmware has been build you can now flash it onto the device. Please see the specific pages related to the specific hardware.