For those who need to develop products based on the OpenWrt platform, the target audience can be divided into two categories:

• Pure software development based on x86 hardware. For example, the recently popular fnOS is a system deeply customized based on Linux, which only requires running a virtual machine to develop and debug software.

• Product development for network devices, such as home wireless routers, gateways, enterprise-grade APs, etc. These devices often do not use x86 hardware and need to be cross-compiled to run on target hardware.

This article will introduce the OpenWrt environment setup for both development methods. You can choose the appropriate solution based on your learning goals and the actual situation of your testing environment.

Running OpenWrt in a Virtual Machine

There is a tutorial on the OpenWrt official website titled OpenWrt on VirtualBox HowTo, which explains how to run OpenWrt in a virtual machine. The address is:

https://openwrt.org/docs/guide-user/virtualization/virtualbox-vm

Of course, you first need to install a virtual machine. Here we also use VirtualBox as the testing software. If you need to use other virtual machine software, you can refer to:

https://openwrt.org/docs/guide-user/virtualization/start

Step 1: Install VirtualBox

First, go to the official website to download the latest VirtualBox installation package and install it according to the prompts. There are no special instructions, so this part will be skipped.

Step 2: Download OpenWrt Image

The OpenWrt official website has compiled various versions of system images that we can directly download and use. We only need to download the corresponding OpenWrt x86 architecture 64-bit system version, which includes two types of file:

1. squashfs-combined.img.gz: This disk image uses the traditional OpenWrt partition layout, containing a read-only squashfs formatted root filesystem and a read-write data partition that can be used to save configurations and install software packages.

2. ext4-combined.img.gz: This disk image uses a readable and writable ext4 filesystem partition to save all data (including the root filesystem), without a read-only squashfs root filesystem. The advantage of this approach is that it expands the available partition space, but functions that rely on a read-only squashfs root filesystem, such as failsafe and factory recovery, cannot be used.

Both do not affect everyone learning and application development, but to learn the purest OpenWrt, it is recommended to use squashfs-combined.img.gz this image.

So where to download this image? You can go to the official website link:

https://downloads.openwrt.org/releases/

For the directory structure of the image, please refer to the link below:

https://openwrt.org/docs/guide-user/installation/openwrt_x86

You can choose the appropriate version according to your needs. Here I directly choose the latest version 23.05.5:

Select the link highlighted in the image above, which will download a file named openwrt-23.05.5-x86-64-generic-squashfs-combined.img.gz to your local computer.

Note: When choosing versions, it is recommended to check the release notes for each release version, where you can see the new features added in the version, software version upgrades, and more importantly, whether you can accept the defects mentioned in the known issues.

Step 3: Convert the Image to VDI Format

We will extract the downloaded image to get a file named openwrt-23.05.5-x86-64-generic-squashfs-combined.img, which cannot be used directly and needs to be converted to .vdi format. You can refer to this article:

https://www.cnblogs.com/jackadam/p/10175943.html

Here is the command I executed:

c:\Program Files\Oracle\VirtualBox>VBoxManage.exe convertfromraw --format VDI e:\openwrt-23.05.5-x86-64-generic-squashfs-combined.img e:\openwrt.vdiConverting from raw image file="e:\openwrt-23.05.5-x86-64-generic-squashfs-combined.img" to file="e:\openwrt.vdi"...Creating dynamic image with size 126353408 bytes (121MB)...

Thus, a file openwrt.vdi will be generated locally, and you can expand its disk size according to your needs. I choose to expand it to 128MB:

c:\Program Files\Oracle\VirtualBox>VBoxManage.exe modifymedium e:\openwrt.vdi --resize 1280%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

Step 4: Create a Virtual Machine

Next, we need to open VirtualBox and start creating a brand new virtual machine. First, open the virtual machine software, directly use the Ctrl+N shortcut key to create a new virtual machine, and fill in the virtual machine information in the following format:

It is important not to select a virtual CD-ROM here. Then select hardware configuration:

For us, 512MB of memory and a dual-core CPU are already a very high configuration. In the next step, select the virtual hard disk configuration:

Select “Use an existing virtual hard disk file” here, and you will use the openwrt.vdi file you just created. Finally, click the “Finish” button at the bottom right, and the virtual machine will be created.

Step 5: Run the Virtual Machine

Select the virtual machine we just created on the following page and click the “Start” button at the top, as shown below:

The device will boot quickly, but it is a command line interface, and the running effect is as follows:

At this point, the OpenWrt running environment built on the VirtualBox virtual machine is complete. You can develop and debug your business software in this environment as needed.

Running OpenWrt on Network Device Hardware

In my daily work, I mainly run OpenWrt on actual network device hardware. Of course, this method not only increases hardware costs but also requires a broader technical knowledge base, making it slightly more difficult to get started. However, I still recommend that everyone have a hardware device for testing.

Step 1: How to Choose Hardware Devices?

If you are new to this industry, I recommend preparing a piece of hardware that can be used for learning and testing. As for how to choose, I provide the following suggestions:

• For chip solution manufacturers, it is recommended to choose MTK, as they are easy to find. MTK has an astonishing market share in the retail and SMB markets, so there are many hardware models available for you to choose from, and the prices on second-hand markets are also very low;

• Choose mature or currently mainstream hardware, and do not choose the latest hardware. The latest hardware is difficult to find information on. If you are already working in the related industry and can obtain the public board and SDK provided by the chip manufacturer, it is an exception. Among chip solutions, choosing wireless router products based on MT7621A has the best cost performance; choosing AX3000 products based on the MT7981B solution is currently mainstream, and you will likely use them in future work; the MT7987 series products are MTK’s latest Wi-Fi 7 platform, which is very cutting-edge, and if you have the opportunity to get them, you can take the lead.

• When selecting devices, try to choose products that can be accessed directly through serial port or ssh/telnet tools. This will reduce the difficulty of switching to your compiled firmware. For example, the H3C Magic series can directly access the background, and Xiaomi products can switch to versions that allow access to the background through online flashing firmware (they can also be upgraded directly via u-boot). TP-LINK products are not suitable for complete beginners (they do not have open backgrounds, and most Flash capacity is relatively small).

• For complete novices, it is best to choose products with 16MB capacity Nor Flash. Even if the flashing process “bricks” the device, you can spend a small amount of money to buy a cheap programmer to revive it. If it is Nand Flash, adapting to the underlying hardware drivers and various complex file systems is difficult, and the cost of buying a programmer is also high. Most Wi-Fi 5 products based on MT7621 are Nor Flash, and you can search for disassembly information online before choosing to find the corresponding Flash information.

If you are an in-service developer in the related industry, I believe you will have no shortage of devices, and you must have a prototype and public boards provided by chip manufacturers based on your preferences or current work content.

Due to space limitations, I will not introduce specific flashing methods for models here. If there is a demand, you can message me privately.

Step 2: Flashing the Device

This step varies by device, and the goal is to switch the device to a version that can upgrade to the official OpenWrt firmware. Some manufacturers’ devices use u-boot by default and do not block serial port access, so you can directly upgrade to the OpenWrt official firmware version via serial port. However, some manufacturers cannot upgrade via serial port but can enable ssh through special means, allowing you to replace u-boot and firmware by logging into the device’s background remotely, which is relatively complex and carries a risk of failure. Finally, the ultimate solution is to buy a programmer, directly take down the Flash on the board, and burn the version that supports the OpenWrt official firmware, which requires a certain level of hands-on ability.

Devices with open backgrounds are easier to operate, and there are many cheap products on the market currently. I will not make recommendations here; you can search for them on Baidu:

The answers provided by Baidu are also incomplete. Xiaomi and H3C Magic are the two brands I have tested and found to be feasible. TP-LINK, which I have disassembled a few times, has blocked serial port access and is confirmed to be unworkable; others should make judgments based on their resources.

I will next use a board with MT7621AT+MT7905DAN+MT7975DN, which uses a combination of 16MB NOR FLASH and 256MB DDR memory. This is the first generation of AX1800 Wi-Fi 6 chip solution launched by MTK, which is relatively easy to find on the market and can serve as a reference for everyone.

Step 3: Setting Up the Compilation Environment

I personally recommend using Ubuntu 18.04 LTS as your compilation development environment. Although there are newer compilation environments available, many of the newer system versions are not friendly to us. On one hand, you may encounter problems that need to be solved by yourself, and it is difficult to find relevant information online; on the other hand, both Qualcomm and MediaTek’s SDK recommend using Ubuntu 18.04 as the compilation server. If you use a higher system version, it is likely that the SDK compilation will fail, especially since Qualcomm requires using Python 2.7, and higher versions have many compatibility issues.

Similarly, we will still use the VirtualBox virtual machine to install the Ubuntu 18.04 LTS system as the compilation server. The virtual machine installation part is very simple, and there are many tutorials online, so I will not introduce it here. The system installation image I used is:

ubuntu-18.04.6-desktop-amd64.iso

After the system installation is complete, please first update the software packages of the system and install some basic software for compiling OpenWrt. This is not fixed and relates to the specific version of OpenWrt being compiled. Generally, it includes:

sudo apt install git subversion build-essential gawk vim bison libncurses5-dev

In the first compilation, you will encounter compilation errors and need to install software based on the error prompts.

Then you need to download the OpenWrt system source code, which can be directly downloaded from GitHub:

https://github.com/openwrt/openwrt

On this website, select the appropriate Tag version according to your needs. I currently choose version 23.05.4. Although the latest is 23.05.5, there are still some issues that have not been fixed, so I did not choose the latest version, and the differences between the two are not significant.

Finally, click the Code button and choose to download the source code in .zip format. The downloaded source code package is not large, only 14.6MB, which may overturn your expectations. A single Linux kernel source package should be hundreds of megabytes, yet its initial form is so small. This might be the charm of building OpenWrt based on buildroot.

Before starting the compilation, if you are interested, I recommend checking the changelog:https://openwrt.org/releases/23.05/notes-23.05.4

Then copy the source package to your virtual machine working directory and execute the following commands:

unzip openwrt-23.05.4.zipcd openwrt-23.05.4./scripts/feeds update -a./scripts/feeds install -a

This will download the software sources according to the feeds.conf.default configuration file in the root directory and finally install them to the specified directory of the system. At this point, the directory structure of the system source code is basically completed.

Next, configure the relevant information of the target hardware by executing the make menuconfig command in the openwrt-23.05.4 root directory, which will pop up a configuration menu as follows:

The options in the red box are required to uniquely identify a single board hardware.MT7621 has two sets of public board configurations, corresponding device tree files are:

• mt7621_mediatek_ap-mt7621a-v60.dts: Corresponds to the 16MB Nor Flash configuration.

• mt7621_mediatek_mt7621-eval-board.dts: Corresponds to the Nand Flash configuration.

Since my test hardware is 16MB Nor Flash, I choose the MT7621A-V60 EVB board as shown above.

At this point, do not rush to compile, as you still need to modify the device tree by modifying openwrt-23.05.4/target/linux/ramips/dts/mt7621_mediatek_ap-mt7621a-v60.dts, adding the chosen node content:

#include "mt7621.dtsi"]/ {  compatible = "mediatek,ap-mt7621a-v60", "mediatek,mt7621-soc";  model = "Mediatek AP-MT7621A-V60 EVB";    chosen {    bootargs = "console=ttyS0,115200 root=/dev/mtdblock5";  };};

This is to prevent some u-boot startup parameters from not carrying the storage location of the rootfs filesystem, which leads to startup failure. The specific settings depend on your partition scheme, as my partition is as follows:

Then, execute the following commands to start the compilation:

make defconfigmake V=s -j8

After the compilation is complete, you can find the corresponding upgrade package at the following path:

Step 4: Version Upgrade and Testing

I will upgrade through the device’s serial port, which requires installing a tftp server software on the PC and placing the upgrade package in the working directory of the tftp server. I recommend using tftpd64, and the running interface is as follows:

After powering on the device, the serial port will print as follows:

Select “2. Upgrade firmware”, and then follow the prompts to enter the device’s IP address and the address of the PC’s tftp server, and finally enter the file name of the upgrade package to be downloaded:

After the upgrade is complete, the device will automatically restart and begin booting the OpenWrt system. Wait for the device to complete the startup, and you will see the following information:

Final Summary

Setting up a development environment is a very tedious but also full of surprises. Many people may encounter all sorts of issues even when following the steps above, which is very normal. However, do not be discouraged; promptly check online for solutions to problems. The more you do this, the more proficient you will become.Many professionals in this industry may never build such a development environment from scratch in their lifetime, as large companies have dedicated IT departments to handle it. So once you succeed, congratulations, you are already ahead of many of your peers~