Skip to content

Upgrading Router Firmware

This guide shows you how to upgrade the firmware on your GL.iNet router hubs.

Prerequisites

  • Latest version of wsctl installed
  • Physical or network access to router hubs
  • Site numbers for each router hub
  • Firmware files provided by Blackfire Technology

Process Overview

  1. Update wsctl to the latest version (if not already done)
  2. Flash routers with the latest firmware — Hubs from wsctl, Nodes from the router's UBOOT web interface
  3. Reconfigure each hub via the wsctl TUI's Configure Hub flow

Step-by-Step Guide

1. Update wsctl

Ensure you have the latest version of wsctl installed on your local machine

2. Flash Router Firmware

Control Hubs — from wsctl:

  1. Copy the Hub firmware file (.bin, .img or .trx) provided by Blackfire Technology into your deployment directory.
  2. Connect your laptop to the Hub so it's reachable at 10.34.0.1 (SSH, port 22).

  3. Launch wsctl, open Upgrade → Upgrade Control Hub, pick the firmware file, and confirm. wsctl uploads the image, verifies it with sysupgrade -T, and runs sysupgrade -n; the Hub reboots.

    The same flow is available as a command: wsctl hub upgrade --firmware ./firmware.bin (add --ip <address> if the Hub isn't at 10.34.0.1).

The upgrade wipes the Hub's configuration

sysupgrade -n does not keep settings, so the Hub comes back without its Site's WireGuard and LAN config. Step 3 puts it back.

Nodes — the TUI's Upgrade Node entry is not yet enabled, so for each GL.iNet Node:

  1. Access the router's UBOOT web interface
  2. Upload the latest respective firmware file provided by Blackfire Technology
  3. Initiate the upgrade and wait for the router to reboot

Firmware Compatibility

Only use firmware files provided or approved by Blackfire Technology. Using incompatible firmware may cause router malfunction.

3. Reconfigure Each Hub

From your local machine (in the deployment directory), launch the wsctl TUI, open Node Sites, select the Hub's existing Site, and press H (Configure Hub). wsctl connects to the Hub over SSH, checks its MAC address against the Site, applies the LAN and WireGuard configuration plus the device scanner, and reboots the Hub.

The command-line equivalent is wsctl hub configure <site>, where <site> is the site number (e.g. 0), name, or ID.

Router Upgrade Tips

  • Upgrade one router at a time
  • Schedule during maintenance windows
  • Keep firmware files organised
  • Document which sites have been upgraded
  • Test connectivity

Troubleshooting

Router Won't Boot After Firmware Flash

If the router fails to boot after flashing:

  1. Power cycle the router (unplug for 30 seconds, then plug back in)
  2. Wait 2-3 minutes for full boot
  3. Try accessing the web interface again
  4. If still unresponsive, contact Blackfire Technology support

Firmware Version Compatibility

Version Requirements

Always check the Waveshift release notes for firmware compatibility requirements. Some Waveshift server versions may require specific minimum firmware versions on router hubs.