Development Environment and Notes

Erik Kim

The preliminary requirements for building OpenWrt from source code include, but are not limited to:

  1. a GNU/Linux environment,
  2. approximately 16 GB of free space in order to generate a flashable firmware image,
  3. a minimum of 2 GB of RAM. 

The build system is a set of patches, files, and Makefiles which automate the process of building a cross-compilation toolchain. For each package you are building, you usually need a separate Makefile. For more information, visit Building Packages.

I initially tried building images using a VM with Ubuntu. However, due to unfamiliarity with the ecosystem and realizing the need for dependency locking, I decided to use NixOS to locally build and test parts of our package. Hence, more testing should be conducted on the Ubuntu platform in the future to ensure stability and full compatibility.

A major component of our project is the Ruby state machine. Hopefully for our purposes and convenience, we won’t be using a shell script to install it manually onto routers, although in certain scenarios we might end up having to provide users with prewritten scripts to troubleshoot bugs or other issues, should they arise. Instead, we will use an init script to automate the verification and update process at boot-time. This will allow us to 1) compile the Ruby state machine and its dependencies as a single package rather than scattered blocks of code, 2) should any developer want to modify parts of the stock image to suit their particular hardware needs, provide them with our “core” package, which will remain for the most part functional in various environments, and 3) identify both our short-term and long-term design goals more easily. 

The biggest obstacle I faced during the process was that the version of Ruby provided by OpenWRT as part of their limited selection of supported packages proved to be problematic for the following reasons: 

  1. It was not entirely stable – I ended up running into multiple dependency and conflict related errors;
  2. I could not find an option to install additional Gems, meaning I ended up editing the package files to manually include our dependencies and downgrade Ruby;
  3. we probably don’t need the full standard library – there has to be a way to strip it down further as the package is currently quite big as it is.

Building from Source: A Step-by-Step Guide

  1. Read Build System Setup, ensure you have the required packages. Then, scroll down to your distribution-specific instructions. Read each line carefully before executing it in the terminal. If you are using NixOS, use the following flake.nix file:

(link to be added)

  1. See Table of Hardware, make sure that your router is supported by OpenWRT.
  2. run git clone https://git.openwrt.org/openwrt/openwrt.git.
  3. Go to Build System Usage, run git switch openwrt-23.05 instead of git checkout v23.05.0
  4. Run make menuconfig, go to languages then Ruby, make sure you enable (<*>) compilation for the following modules:
  • socket,
  • logger,
  • set,
  • json,
  • date,
  • ruby-gems,
  • ipaddr,
  • fileutils.
  1. Do NOT run make -j$(nproc) defconfig download clean world yet.  

     4.   Download the Ruby state machine Makefile.  

  1. Put it in (source directory)/package/custom/wifiproject
  2. To test if it works correctly, cd to the source directory, run the following on the command line:
    1. make tools/install V=sc
    2. make toolchain/install V=sc
    3. make package/wifiproject/compile V=sc
  3. If any of the commands results in an error, record it and how you can reproduce the error. 

note: in the future, our program will probably require Ruby as a dependency; Ruby packages require host tools which make things a little trickier. However, currently we should not have any dependencies. As such, make sure you successfully ran i) and ii) if somehow dependencies give you trouble.   

    5. Download the Hostapd Makefile. 

    6. Now, run make menuconfig again, you should be able to see an option to select and include the Wificlient package. Enable it. 

Troubleshooting Guide and Precautions

While building an image, or even a package, you will inevitably run into a whole host of errors. In this section, you will find very general advice you can follow whenever there is an unexpected issue. 

Cleanup

  • A general rule to keep in mind is that you are supposed to run make clean before each full build. This is also equivalent to running rm -rf bin build_dir tmp; as such, it suffices to simply run rm -rf build_dir/package_build_directory after each failed package build attempt. 
  • In the event of a lib-*.c-related dependency issue, it is recommended that you run make targetclean instead to delete all cross-compile tools installed. This is true of most cases involving python3 check errors as well. For more information, see “Ubuntu.”  
  • If you need a factory reset for any reason, run make distclean.

Git

  • Always keep an external and an internal Git repository to save your progress. As trivial as this rule sounds, it is of paramount importance, especially taking into account the unfortunate fact that I myself was at fault for doing this and as a result lost a massive amount of progress when I accidentally mass deleted a bunch of directories. In a similar vein, always record your progress fully and concisely so that it is possible for anyone to reproduce the steps needed.

Ubuntu

  • Although Build System Setup is undoubtedly an invaluable resource, keep in mind that using a post-22.04 Ubuntu release is known to trigger Python-related errors. This is due to the absence of a python3-distutils module. To solve this, you should run:

Web Portal

  • Currently, the instructions on the github page do not work, how do we resolve this?

– 

Hostapd.sh

  • /lib/netifd/hostapd.sh 
  • hostapd_set_bss_options() {

–  This function prepares the Hostapd configuration settings for a specific physical interface (PHY).

– Reads various configuration options from the system’s configuration files (most likely UCI in OpenWrt) using the config_get function to retrieve encryption settings, key information, SSID and other wireless settings.

– Based on the encryption type, it configures the appropriate security settings.

– It builds a set of configuration lines by appending them to the variable $var.

– The hostapd.conf path for each interface is built based on the PHY device (radio hardware), typically stored in /var/run/hostapd-<phy>.

– var/run/wpa_supplicant and var/run/hostapd

How to Write an Initialization Script:

  • Useful Link
  • To start the hostapd process at boot time, we need to write an initialization script, which is pretty straightforward. 
  • Mkdir /run
  • Gem install httparty

Useful Links and Resources

  • To modify Hostapd for use with our program, we need access to its source code: link.
  • Another useful resource is the Hostapd Makefile which details the steps Openwrt employs to fetch data and files from the server.
  • This might also be of interest to us: Link.

Install OpenWRT on TP Link Archer A7 v5 step by step
1. Set your PC lan-card settings to Automatic or set: ip4:192.168.0.22/mask:255.255.255.0/gateway:192.168.0.1
2. Connect the lan cable in PC to router LAN-1 port
3. Open a browser and open the TP-Link default address http://192.168.0.1
If you are reading error 403 (or some certificate error) in browser: move your lan cable from WAN port to LAN-1 port
You will be asked to create a password on first opening. Set a new password and login.
4. You should see the router access page. Select: Advanced/System-Tools/Firmware-Upgrade
5. Select: Manual-Upgrade/Browse: Select the file downloaded from “Firmware OpenWrt Install” section openwrt-21.02.3-ath79-generic-tplink_archer-a7-v5-squashfs-factory.bin
6. Wait until firmware flashing is done. Do not interrupt the process – risk of bricking the router!
7. After flashing is done you will see “page not found”. This is normal.
8. Restart router and open in browser the OpenWRT default address: http://192.168.1.1 (manual LAN-card settings: ip4:192.168.1.122/mask:255.255.255.0/gateway:192.168.1.1 )
9. You should see the OpenWRT access page!

To enable TFTP, run the following: 

sudo chmod -R 777 /private/tftpboot

chmod 777 /private/tftpboot/ArcherC7v5_tp_recovery.bin

sudo launchctl load -F /System/Library/LaunchDaemons/tftp.plist

Hostapd Control Interface

Project: Split Machine into Two Parts

#!/usr/bin/ruby

require “fileutils”

require “logger”

# Logger for the base script

$logger = Logger.new(“/tmp/pifi_bootstrap.log”, 10, 10 * 1024 * 1024)

# Remember to create a folder to store updates.

# Directory for pulling updates

MAIN_CODE_DIR = “/opt/pifi”

MAIN_SCRIPT = “#{MAIN_CODE_DIR}/pifi_controller.rb”

# Git repository URL for the main code

GIT_REPO_URL = “https://github.com/[insert_here]”

def check_connectivity

  system(“ping -c 

def ensure_main_code

  # Clone or pull the latest main code

  if !Dir.exist?(MAIN_CODE_DIR)

    $logger.info(“Cloning repository…”)

    system(“git clone #{GIT_REPO_URL} #{MAIN_CODE_DIR}”)

  else

    $logger.info(“Pulling latest code…”)

    Dir.chdir(MAIN_CODE_DIR) do

      system(“git reset –hard”) # Ensure no local changes

      system(“git pull”)

    end

  end

end

def execute_main_code

  if File.exist?(MAIN_SCRIPT)

    $logger.info(“Executing main code…”)

    exec(“ruby #{MAIN_SCRIPT}”)

  else

    $logger.error(“Main script not found at #{MAIN_SCRIPT}”)

    exit(1)

  end

end

# Main bootstrap logic

begin

  $logger.info(“Starting process…”)

  ensure_main_code

  execute_main_code

rescue => e

  $logger.error(“Failed: #{e.message}”)

  $logger.error(e.backtrace.join(“\n”))

  exit(1)

end

Scroll to Top