Differences

This shows you the differences between two versions of the page.

--- network:firmware:meshdesk [2024/02/17 11:47] – created system
+++ network:firmware:meshdesk [2025/04/15 05:18] (current) – system
@@ Line 1: / Line 1: @@
 <nav type="pills" justified="false">
   * [[:user_manuals|Back to Documentation]]
-  * [[:radius:rad_kick|A]]
+  * [[:network:firmware:meshdesk|With MESHdesk packages]]
 </nav>
+----
+====== OpenWRT 24.10.x with MESHdesk packages ======
+<alert type="info">
+Follow these instructions to include the MESHdesk package on devices that can run OpenWRT version 24.10.x
+</alert>
+===== Minimum hardware requirements =====
+  * The minimum hardware requirements are:
+        * **16M Flash**
+        * **64M RAM**
+  * Although the system can potentially support hardware with fewer resources, support is no longer practical in 2024.
+  * The hardware does not need to be equipped with a radio.
+  * Hardware without radios can be managed with APdesk.
+  * Mediatek and Atheros / Qualcomm SOC devices are supported.
+  * Other target systems are also supported, but have not yet been thoroughly tested.
+  * If you are not sure if your hardware works, please visit the OpenWrt website and check it. The list of supported hardware is constantly expanding.
+  * Next, let us look at the steps you need to take to compile OpenWrt with the included MESHdesk package.
+<panel type="primary">
+===== Steps when adding new hardware =====
+==== Explanation of our modus operandi (MO) ====
+  * To introduce a new device we will:
+      - We create an initial firmware image for development that contains all the required packages and files, but with centralized management <wrap em>disabled</wrap>.
+      - Then we flash a device with this image and make the device-specific adjustments so that the device works as expected with central management.
+      - We can then use these optimized files to create a production image for the device that contains the device-specific files.
+  * This approach allows us to:
+        * Minimize the risk of bricking the device (a factory reset resets the device to a normal running OpenWrt)
+        * Allow fine tuning of the device without having to create and flash a new firmware image every time we make a change.
+------
+==== First development firmware ====
+These steps are performed <wrap em>ONLY ONCE</wrap> when you introduce new hardware.
+  - Build OpenWRT with the MESHdesk package (MESHdesk disabled).
+  - Flash your device.
+  - Prepare the **wan_network** file for this specific device.
+  - Prepare the **meshdesk** config file for this specific device.
+  - Prepare the **captive_config.json** file for this specific device.
+<alert type="info">
+To better structure the documentation, we have set up special pages describing these files, including their function and their adaptation to your specific device.
+</alert>
+<wrap em>This is a one-time process. Once you have customized the files, you can skip this step in the future and simply use the device-specific files if you need to create new firmware for the same hardware.</wrap>
+-------
+==== Production Firmware ====
+  - Create OpenWRT firmware with the MESHdesk package, which contains the device-specific files for
+     - wan_network
+     - captive_config.json
+     - meshdesk
+  - Flash your device with the production firmware.
+</panel>
+  * So without further ado, let us start with the first development firmware.
+  * We will take a Xiaomi 4A 100M access point as an example device.
+  * You can use the hardware of your choice and simply apply the same principles.
+===== Checkout the MESHdesk code =====
+  * Most of the packages you can include when building OpenWrt firmware are either part of the SDK or can be included via the package feeds, which are also part of the SDK.
+  * You can also include packages that are not part of the SDK or the feeds.
+  * The MESHdesk package is one such package.
+  * The MESHdesk package is hosted on Github as part of a git repository.
+  * This git repository also contains the other elements that we will use in the development of our firmware (the Luci application and some additional files)
+  * Check out the **openwrt-meshdesk** package from the Github repository.
+<code>
+#Do this in the working directory e.g. cd 24.10.1 (on the same level as the openwrt directory)
+git clone https://github.com/RADIUSdesk/openwrt-meshdesk.git openwrt-meshdesk
+</code>
+  * The repository consists of three main components. Each of them is located in its own folder.
+       - **MESHdesk** - This is the MESHdesk package that will be included in the SDK.
+       - **files** - This is the overwrite structure that contains files to be overwritten during the build process.
+       - **luci-app-meshdesk** - This is the Luci application that allows you to enable or disable centralized control of the device.
+===== Copying the three components =====
+  * The **MESHdesk** folder must be copied under the **package** folder (openwrt/package).
+<code bash>
+#cd to the working directory
+cp -R ./openwrt-meshdesk/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 copying the packages, enter 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 Luci application MESHdesk is listed as one of the available Luci applications.
+===== Select Packages To Include With Firmware =====
+<panel type="primary">
+{{:network:firmware:openwrt-cursors.png|}}
+</panel>
+  * The OpenWrt SDK has a cursors interface (similar to Midnight Commander for the old school readers 8-O)
+  * To start this cursors interface, you have to change from the working directory to the **openwrt** directory.
+  * Then issue the following:
+<code bash>
+#cd to the working directory
+cd openwrt
+make menuconfig
+</code>
+  * Here you select the hardware architecture of the device for which you want to create the firmware and its model.
+  * Also select the following packages when creating the firmware.
+  * When you select a package, you have the option of building it as a module (M) or including it completely (*).
+  * **Make sure you select the (*) option to fully include the package.**
+  * The package names in bold are required.
+  * The Mosquitto packages are for MQTT support.
+  * The Batman packages are for Mesh support.
+<panel type="primary" title="Package selection" no-body="true">
+^ Location      ^ Package       ^ Comment        ^
+| Base system    |**MESHdesk**    |     |
+| Base system    |sqm-scripts   | Used for bandwidth control on VLANs
+| Kernel Modules -> Netfilter Extensions  | kmod-nft-bridge | <wrap em>Include if you want to block or speed limit users</wrap> |
+| Kernel Modules -> Network Devices  | kmod-dummy | Include for internal VLAN (Dynamic RADIUS based VLANs on AP) |
+| Kernel Modules -> Network Support  | kmod-batman-adv | Keep the default options |
+| Languages -> Lua  |lua-mosquitto  |      |
+| Languages -> Lua  |**libiwinfo-lua**   |     |
+| Languages -> Lua       | **luasocket**  |     |
+| Libraries     | **libuci-lua**  |     |
+| Luci -> Collections     | **luci**  |    |
+| Luci -> Modules    | **luci-compat**   | Needs this modules for our package **VERY IMPORTANT** |
+| Luci -> Applications    | **luci-app-meshdesk**  | Luci App to enable and disable central management |
+| Luci -> Applications    | luci-app-sqm  | Used for bandwidth control on VLANs
+| Luci -> Themes   | **luci-theme-material**  | Modern theme that is easy to customize |
+| Luci ->  Libraries  | **luci-lib-httpclient**  |  |
+| Luci ->  Libraries  | **luci-lib-httpprotoutils**   |  |
+| Luci ->  Libraries  | **luci-lib-json**  |  |
+| Luci ->  Libraries  | **luci-lib-jsonc**  |  |
+| Network -> Captive Portals   | **coova-chilli**  | Select **OpenSSL** as **SSL Library**. Also select **Enable the JSON interface..** and **..Coova miniportal...** |
+| Network -> File Transfer   | **curl**   |     |
+| Network -> Firewall   | **iptables-nft**   | **Very important for backward compatibly of iptables**   |
+| Network -> Routing and Redirection  | **relayd** |      |
+| Network -> WirelessAPD | **wpad IEEE 802.1x Auth/Supplicant (built-in full)**   | Un-select wpad-basic also required for Hotspot 2.0 |
+| Network   | batctl-full  | Un-select batctl-default |
+|Network  | mosquitto-client-ssl  | Note the **CLIENT** package |
+|Network  | iw-full  | Required for Hotspot 2.0 |
+</panel>
+<panel type="primary" title="Advanced Package selection" no-body="true">
+^ Location      ^ Package       ^ Comment        ^
+| Kernel modules -> USB Support | kmod-usb-net-cdc-mbim  |    |
+| Kernel modules -> USB Support | kmod-usb-net-qmi-wwan  |     |
+| Kernel modules -> USB Support | kmod-usb-serial-option | optional - for AT commands |
+| Kernel modules -> USB Support | kmod-usb-serial-qualcomm  |   |
+| Kernel modules -> USB Support | kmod-usb-serial-sierrawireless  |   |
+| Kernel modules -> USB Support | kmod-usb-wdm  |   |
+| Network -> WWAN |uqmi  |    |
+| Utilities    |usb-modeswitch    |Used with LTE USB dongles  |
+| Utilities -> Terminal |minicom   |    |
+</panel>
+  * Once you have selected these packages, you can save the configuration and run **make** to create the firmware.
+  * The finished firmware can then be found in the **openwrt/bin/target/<architecture>** folder.
+  * In our case we will use //openwrt/bin/targets/ramips/mt76x8/openwrt-ramips-mt76x8-xiaomi_mi-router-4a-100m-squashfs-sysupgrade.bin//
+  * The firmware you have just created is then a standard OpenWrt and you can flash your hardware like a normal OpenWRT and then access it via **192.168.1.1**.
+        * Username and Password is **root** and **admin** for Luci and ssh.
+  * The next section covers the files you need to be attend to for the specific hardware tweaks.
+==== Note on Warnings  ====
+  * When you run the **make** command, you may see these warnings.
+  * They are harmless and can be ignored.
+<code bash>
+WARNING: Makefile 'package/utils/busybox/Makefile' has a dependency on 'libpam', which does not exist
+WARNING: Makefile 'package/utils/busybox/Makefile' has a dependency on 'libpam', which does not exist
+WARNING: Makefile 'package/utils/busybox/Makefile' has a build dependency on 'libpam', which does not exist
+WARNING: Makefile 'package/network/services/lldpd/Makefile' has a dependency on 'libnetsnmp', which does not exist
+WARNING: Makefile 'package/utils/policycoreutils/Makefile' has a dependency on 'libpam', which does not exist
+WARNING: Makefile 'package/utils/policycoreutils/Makefile' has a dependency on 'libpam', which does not exist
+WARNING: Makefile 'package/utils/policycoreutils/Makefile' has a build dependency on 'libpam', which does not exist
+make[2]: Entering directory '/home/system/Documents/fw_sdk/24.10.1/openwrt/scripts/config'
+make[2]: 'conf' is up to date.
+make[2]: Leaving directory '/home/system/Documents/fw_sdk/24.10.1/openwrt/scripts/config'
+make[1] world
+make[2] target/compile
+make[3] -C target/linux compile
+</code>
+===== Files to tweak =====
+Use ssh to gain access to the device to modify these files.
+<list-group>
+  * {{fa>file?fw}} [[:network:firmware:openwrt-wan-network|wan_network]]
+  * {{fa>file?fw}} [[:network:firmware:openwrt-meshdesk-file|meshdesk]]
+  * {{fa>file?fw}} [[:network:firmware:captive_portal-json|captive_portal.json]]
+</list-group>
+  * Once the customizations are complete, we can test everything.
+  * Log in to your device with Luci (http://192.168.1.1)
+  * The following image shows how to point the device to the controller via the GUI.
+<panel type="primary">
+{{:network:firmware:meshdesk_activate.png|}}
+</panel>
+  * Point the device at your controller and restart it.
+  * If all goes well, it will be displayed under New Arrivals - Hardware.
+  * If it is a new hardware type add it to the controller as described here: Hardware (Again Once Off)
+===== The Production Built =====
+  * If everything works as intended on the device, you can use these optimized 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 table to find the location for the optimized files in the SDK.
+<panel type="primary" title="Files" no-body="true">
+^On Device   ^On SDK    ^
+|/etc/MESHdesk/configs/wan_network  |openwrt/files/etc/MESHdesk/configs/  |
+|/etc/config/meshdesk  | openwrt/files/etc/config  |
+|/etc/MESHdesk/configs/captive_config.json  |openwrt/files/etc/MESHdesk/configs/  |
+|/etc/MESHdesk/reporting/report_to_server.lua  |openwrt/files/etc/MESHdesk/reporting  |
+</panel>
+  * This brings us to the end of the page that describes how to create MESHdesk firmware for specific hardware.