====== OpenWRT 17.01.x with MESHdesk packages ======
<WRAP center round info 90%>
Follow these instructions to build the MESHdesk firmware on devices capable of running OpenWRT version 17.01.x
</WRAP>

===== Minimum Hardware Requirements =====
  * The minimum hardware requirements are:
        * **8M Flash**
        * **64M RAM**
  * Although the system can potentially support hardware with less resources, supporting them in 2021 is not practical any more.
  * The hardware does not need a radio on it. 
  * Hardware without radios can be managed using **APdesk**.
  * Mediatek and Atheros / Qualcomm SOC devices are supported.
  * Other target systems are also supported but have not been thoroughly tested to date.
  * If you are not sure if your hardware will work please visit the OpenWRT website and check. They have an ever growing list of supported hardware.
  * Next we will look at the steps you need to take to get MESHdesk working with it.

===== Steps In Adding New Hardware =====
==== The Very First Time (Draft) ====
These steps you have to do **ONCE ONLY**
  - Build OpenWRT with MESHdesk firmware (MESHdesk disabled).
  - Flash your device.
  - Prepare the **wan_network** file for specific device.
  - Prepare **meshdesk** config file for specific device.
  - Prepare **captive_config.json** file for specific device.

==== Afterwards (Final) ====
  - Build OpenWRT with MESHdesk firmware containing the device specific files for
        - **wan_network**
        - **captive_config.json**
        - **meshdesk**
  - Flash your device with the final built of firmware.

  * So without further ado, lets get going with the first draft built.
  * In this page we will take an **Open Mesh OM2P (first version)**  Access Point as a sample unit.
  * You can use the hardware of your choice and simply apply the same principles.
  * Make sure you followed [[md:openwrt-meshdesk-prep|these]] instructions to prepare the environment.

===== Fetching the MESHdesk package =====
  * Check out the OpenWRT-MESHdesk package from the SourceForge repository.
<code bash>
#Do this in the working directory e.g. cd 17.01.7
git clone git://git.code.sf.net/p/radiusdesk/openwrt-meshdesk openwrt-meshdesk
</code>
  * The package has three main components. Each one is located in a unique folder.
  - **zzz-MESHdesk** - This is the MESHdesk package which will be build by the SDK.
  - **files** - This is the override structure containing files to override during the build process.
  - **luci-app-meshdesk** - This is the Luci application used to enable central control.

=====  Copying the three components =====
  * The **zzz-MESHdesk** folder needs to be copied under the **package** folder (openwrt/package).
<code bash>
#cd to the working directory
cp -R ./openwrt-meshdesk/zzz-MESHdesk ./openwrt/package 
</code>
  *  The **files** folder needs to sit directly under the **openwrt** folder (root level).
<code bash>
#cd to the working directory
cp -R ./openwrt-meshdesk/files ./openwrt 
</code>
  * The **luci-app-meshdesk** folder needs to be copied under the **feeds/luci/applications** folder.
<code bash>
#cd to the working directory
cp -R ./openwrt-meshdesk/luci-app-meshdesk ./openwrt/feeds/luci/applications
</code>
===== Updating the available packages  =====
  * Since we added a Luci application, we need to tell the SDK about it.
  * After you copied the packages across issue the following command:
<code bash>
#cd to the working directory
cd ./openwrt
scripts/feeds update -i
#Install the package to make it visible 
scripts/feeds install luci-app-meshdesk
</code>
  * The result is that the MESHdesk Luci application will be listed as one of the available Luci applications.

<WRAP center round important 100%>
  * These instructions are for the **17.01.x** branch.
  * Each branch has a unique set of small tweaks in its instructions.
  * If you are using a different branch **please refer to that branch's page**
</WRAP>

===== Select Packages To Include With Firmware =====
  * Select the following packages when building the firmware.
  * Package names in bold are required.
  * The Mosquitto packages are for MQTT support.
  * The Batman packages are for mesh support.

^ Package      ^ Location       ^ Comment        ^
| **zzz-MESHdesk**    | Base system  |     |
| kmod-batman-adv | Kernel Modules -> Network Support | Keep the default options |
| lua-mosquitto  | Languages -> Lua |      |
| **libiwinfo-lua**      | Languages -> Lua  |     |
| **luasocket**      | Languages -> Lua  |     |
| **libuci-lua**     | Libraries |     |
| **luci**           | Luci -> Collections |    |
| **luci-app-meshdesk**    | Luci -> Applications | Luci App to enable and disable central management |
| **luci-theme-material**   | Luci -> Themes | Modern theme that is easy to customize |
| **luci-lib-httpclient**  | Luci ->  Libraries |  |
| **luci-lib-json**  | Luci ->  Libraries |  |
| **luci-lib-jsonc**  | Luci ->  Libraries |  |
| coova-chilli   | Network -> Captive Portals | Select **OpenSSL** as **SSL Library** //Do not include to save space eg on **OM2P**// |
| **curl**  | Network -> File Transfer |     |
| **relayd**  | Network -> Routing and Redirection |      |
| batctl  | Network  |  |
| mosquitto-client-ssl | Network | Note the **CLIENT** package |
| wpad IEEE 802.1x Auth/Supplicant (built-in full) | Network  | //Use default wpad-mini to save space eg on **OM2P**//|

  * After you selected these packages you can save the configuration and issue **make** to build the firmware.
  * The firmware you just built will be standard OpenWRT in effect and you can flash your hardware as with normal OpenWRT then access it on **192.168.1.1**.
        * Username and Password is **root** and **admin** for Luci and ssh.
  * The next section will cover the files you have to attend to for the specific hardware tweaks.

<WRAP center round info 90%>
Although the  **OM2P** has 16M FLASH there is a 7M fail-safe partition which complicates things a bit.
To keep things small I //included// the mesh parts (Batman) but //excluded// **coova-chilli** and the full version of **wpad** in the firmware I created
</WRAP>


===== Initial File Preparation =====
  * Use ssh to gain access to the device in order to tweak these files.
==== wan_network ====
  * Refer to the default **/etc/config/network** file.
<file bash network>
config interface 'loopback'
	option ifname 'lo'
	option proto 'static'
	option ipaddr '127.0.0.1'
	option netmask '255.0.0.0'

config globals 'globals'
	option ula_prefix 'fd15:97e0:cb63::/48'

config interface 'lan'
	option type 'bridge'
	option ifname 'eth0'
	option proto 'static'
	option ipaddr '192.168.1.1'
	option netmask '255.255.255.0'
	option ip6assign '60'

config interface 'wan'
	option ifname 'eth1'
	option proto 'dhcp'

config interface 'wan6'
	option ifname 'eth1'
	option proto 'dhcpv6'

</file>
  * With this setup we have the POE port as LAN (The port next to the Power Jack).
  * We also have the WAN sitting next to the antenna.
  * This is **not ideal** for us since we want to feed power onto the WAN port.
  * Next look at the **/etc/MESHdesk/configs/wan_network** file that is derived from it.
<file bash wan_network>
config interface 'loopback'
    option proto 'static'
    option ipaddr '127.0.0.1'
    option netmask '255.0.0.0'
    option ifname 'lo'

config interface 'lan'
    option ifname 'eth0'
    option type 'bridge'
    option proto 'dhcp'

config interface 'client_0'
    option proto 'dhcp'

config interface 'client_1'
    option proto 'dhcp'

</file>
  * Note there are no **switch** sections. Please refer to the other Wiki pages on the convention to use if the //network// file has **switch** sections.
  * **client_0** and **client_1** interface sections can always be kept as is.
  * **lan** interface section is in actuality the **WAN** port. (This is due to the historical nature of the project and also that we support hardware with a single Ethernet port)
  * Since we wanted the port with POE (eth0) as WAN we actually kept the membership of the **lan** interface as is (remember it is actually the **WAN** port)
  * Next we will look at the ///etc/config/meshdesk// file and tweak it to work with our environment and our hardware.

<WRAP center round tip 90%>
  * There is a growing list of existing sample **wan_network** files under the ///openwrt/package/zzz-MESHdesk/files/MESHdesk/configs// folder.
  * They have a convention of **network_<firmware_id>** e.g. network_xiaomi_4a_100
  * Simply copy that file over //openwrt/package/zzz-MESHdesk/files/MESHdesk/configs/wan_network//
  * Those files will have a matching existing hardware section in the //openwrt/package/zzz-MESHdesk/files/MESHdesk/meshdesk// file 
</WRAP>
==== meshdesk ====
=== Tweaks For Our Hardware ===
  * MESHdesk use the LEDs of the device it is installed on to signal about the environment
        * It signals during startup about the method it uses to try and fetch its settings at that moment.
        * If the device is used in a mesh network it will signal how many neighboring nodes it sees after startup.
        * There is also another LED used to indicate if the device has proper contact with the controller. (The LED can be either ON or OFF in such a case)
        * Finally on mesh networks we can also specify a LED that will indicate mesh traffic flowing through a node.
        * Again lets look at the **OM2P** as a sample.
<code bash>
#change directory to where the LEDs are
cd /sys/class/leds/
ls 
#These are the LEDs available
ath9k-phy0        om2p:blue:lan     om2p:blue:power   om2p:blue:wan     om2p:green:wifi   om2p:red:wifi     om2p:yellow:wifi
#turn it off
echo "0" > om2p\:blue\:lan/brightness
#turn it on
echo "1" > om2p\:blue\:lan/brightness
#Go through all of them and confirm which is which on the device
</code>
  * This device has an interesting LED. It is the **tricolor wifi** LED.
  * In our case we can use the **om2p:yellow:wifi** of the tricolor to light up if the comms to the controller is broken.
  * We can also use the **om2p:green:wifi** of the tricolor to light up if the comms to the controller is OK.
  * We can use the **om2p:blue:wan LED** to signal during startup and neighbor counts.
  * We can use **om2p:blue:lan** for the mesh traffic indicator. 
  * With this info we can create a hardware section in ///etc/config/meshdesk//
<code bash>
config hardware 'om2p'                                                        
        option morse_led '/sys/class/leds/om2p:blue:wan/brightness'      
        option internet_led '/sys/class/leds/om2p:yellow:wifi/brightness'
        option wifi_led 'om2p:blue:lan'
</code>
  * This have to match the value for hardware under the **settings** section
<code bash>
config settings 'settings'
	option hardware 'om2p'
	option id_if 'eth0'
	option lan_up_file '/tmp/lan_up'
</code>
<WRAP center round info 90%>
Don't make the name of the hardware section more than 14characters. Longer names break things during deployment.
</WRAP>

  * Later we will also use the value of **om2p** to define the hardware on the controller.
  * The final tweak for the hardware in the config file is the interface that must be used as the **id_if**.
        * It will typically be **eth0**.
  * Since we want the **yellow LED** to be off when the comms to the controller is fine we need to check what the current setup is
  * With this device we also want to light up the green LED when the comms is fine.
<code bash>
vi /etc/MESHdesk/reporting/report_to_server.lua 
#Look for this section
    if(ok_flag)then                                 
        internetLED('0'); -- NOTE Here we can swap thme around eg make it 0 to turn off a red LED when the internet is OK
        checkForContollerReboot('1');                   
    else                                                                             
        internetLED('1');                                                        
        checkForContollerReboot('0');                  
    end
    
#Also modify the internetLED function to look like this:
function internetLED(state)            
    local hardware  = x.get('meshdesk', 'settings', 'hardware');
    local led       = x.get('meshdesk', hardware, 'internet_led');
    if(state == '0')then                                                 
         os.execute('echo 1 > /sys/class/leds/om2p\:green\:wifi/brightness' );
    end                                             
    if(state == '1')then                                   
         os.execute('echo 0 > /sys/class/leds/om2p\:green\:wifi/brightness' );
    end                            
    os.execute('echo '..state..' > ' .. led );                   
end

</code>

  * To activate the mesh traffic indicator LED you need to edit the ///etc/config/system// file's wifi_led section
  * See this snippet as reference.
<file bash>

config led 'wifi_led'
	option name 'wifi'
	option trigger 'netdev'
	option dev 'bat0'
	option mode 'link tx rx'
	option sysfs 'om2p:blue:lan'
</file>

  *  The following table lists some of the important items with comments 

^ Item        ^ Typical value           ^ Comment    ^
| settings -> hardware | om2p | Must match a hw definition in the file itself  |
| settings -> id_if  | eth0 | eg eth0, eth1 or wan - NOT eth0.1 (for those boards its just eth0)  |
| settings -> skip_radio_0  | 0 | set to 1 when radio0 is a 5G radio and you don't want to use it for config SSID  |

=== Tweaks For Our Environment ===
  *  The following table lists some of the important items with comments 

^ Item        ^ Typical value           ^ Comment    ^
| internet1 -> disabled    | 1  | change it to 0 in order for the device to be centrally controlled   |
| internet1 -> dns    | cloud.radiusdesk.com  | Supply Dummy Value If Not Using DNS System |
| internet1 -> protocol | https | Can be http or https |
| internet1 -> ip | 176.31.15.210 | Fallback when FQDN does not resolve on FQDN not used |

  * We are nearly done. The last stop is to edit the **captive_config.json** file to fit our specific hardware.


==== captive_portal.json ====
  * Edit the file ///etc/MESHdesk/configs/captive_config.json//.
  * This file is a JSON structure that the device uses as a reference to configure itself with a special captive portal when it is not yet managed by the controller.
  * There are only two items that might need to be tweaked
        * The radio number for the 2.4G band.
        * The **ifname** for the **lan** interface (We use the WAN port in out implementation)
  * With the **OM2P** radio0 is the 2.4G radio so no need to tweak that item. (If the hardware has radio1 as the 2.4G band simply look for all the references to **radio0** and make them radio1)
  * See this snippet of a device which has radio1 using the 2.4G band
<code javascript>
"wireless": [
            {
                "wifi-device": "radio1",
                "options": {
                    "channel": 1,
                    "disabled": 0,
                    "hwmode": "11g",
                    "htmode": "HT20"
                }
            },  
            {
                "wifi-iface": "two",
                "options": {
                    "device": "radio1",
                    "ifname": "two0",
                    "mode": "ap",
                    "network": "ex_two",
                    "encryption": "none",
                    "ssid": "_Replace_",
                    "key": "",
                    "hidden": false,
                    "isolate": false,
                    "auth_server": "",
                    "auth_secret": ""
                }
            },
            {
                "wifi-iface": "web_by_w",
                "options": {
                    "device": "radio1",
                    "mode": "sta",
                    "network": "web_by_w",
                    "encryption": "psk2",
                    "key": "radiusdesk",
                    "ssid": "meshdesk_config",
                    "disabled": "1"
                }
            }
        ],
</code>
  * With the **OM2P** the **ifname** we use is **eth0** for the **lan** interface definition.
<code javascript>
{
    "interface": "lan",
    "options": {
        "ifname": "eth0",
        "type": "bridge",
        "proto": "static",
        "ipaddr": "10.50.50.50",
        "netmask": "255.255.255.0"
    }
},
</code>
  * Once the tweaks are completed we can test everything out. 
  * The following link shows how to point the device to the controller using the GUI.
  * [[2021:xiaomi_md|OpenWrt Access Points Running MESHdesk Firmware]]
  * Point the device to your controller and reboot it.
  * If all goes well it will show up in **Unknown Nodes**
  * If it is a new hardware type add it to the controller as described here: [[2021:rd_full_hardware|Hardwares]] (Again Once Off)
  * [[md:xiaomi-attach|Attach A Device To Demo1 Mesh]]

===== The Final Built =====
  * If everything on the device work as intended you can use those tweaked files to build a final version of the firmware for the specific hardware.
  * Copy the files to a temporary folder on the machine where you are building the firmware.
  * Use the following as a lookup for the location inside the SDK where the tweaked files need to go.

^On Device   ^On SDK    ^
|/etc/MESHdesk/configs/wan_network  |openwrt/package/zzz-MESHdesk/files/MESHdesk/configs/  |
|/etc/config/meshdesk  | openwrt/package/zzz-MESHdesk/files/MESHdesk/  |
|/etc/MESHdesk/configs/captive_config.json  |openwrt/package/zzz-MESHdesk/files/MESHdesk/configs/  |
|/etc/MESHdesk/reporting/report_to_server.lua  |openwrt/package/zzz-MESHdesk/files/MESHdesk/reporting  |

  * This brings us to the end of the page on how to build MESHdesk firmware for specific hardware.