Skip to content

Instantly share code, notes, and snippets.

@itachi-re

itachi-re/imou-hx21-openwrt-installation.md

Last active August 25, 2026 15:10
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save itachi-re/15bc389175c8b0738f64f24db30c0325 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save itachi-re/15bc389175c8b0738f64f24db30c0325 to your computer and use it in GitHub Desktop.
Download ZIP
Complete guide to installing OpenWrt on the Imou HX21 (official 25.12.x native support) — no-soldering SSH access via config restore, NAND backup, bootloader flash, reset-button TFTP recovery, and sysupgrade. Includes both Windows and Linux/openSUSE commands.
Raw
imou-hx21-openwrt-installation.md

Installing OpenWrt on the Imou HX21 — Complete Guide

Verified against: official OpenWrt upstream commit 2462b36f0cb2 (mediatek: add support for Imou HX21, merged Nov 2025), the OpenWrt forum thread "Adding Support For Imou HX21," and a field-tested community walkthrough. Current stable branch shipping this device: OpenWrt 25.12.x (25.12.4 as of writing — always re-check the firmware selector for the latest).

0. Read this first

  • Hardware you're flashing: MediaTek MT7981B/MT7981BA (Filogic 820, dual A53), 256 MB DDR3 RAM, 128 MB SPI-NAND (Foresee F35SQA001G), MT7531AE switch, MT7976C Wi-Fi. This is the global Imou HX21 — hardware-identical to the Chinese Imou LC-HX3001, but region-locked on stock firmware.
  • This is a genuine brick-risk procedure. The bootloader (FIP) and preloader (BL2) live in the same NAND you're writing to. Back up every partition before touching anything, keep the router on wired ethernet + stable power throughout, and don't skip the backup step "because it'll probably be fine."
  • Two routes exist:
    1. Official OpenWrt, no soldering (recommended — this is the "easy way" and what this guide covers in depth). Uses a community SSH-enabling config restore instead of UART.
    2. UART/serial fallback — only needed if the no-solder SSH method doesn't work on your unit's firmware revision.
  • Do the whole thing over a direct ethernet cable, not Wi-Fi. No Wi-Fi bridge, no switch in between if you can help it.

1. What you need

Hardware

  • The HX21 router + its power adapter
  • A PC with an ethernet port (or USB-to-ethernet adapter)
  • An ethernet cable
  • (Only for the UART fallback): CH340/CP2102 USB-to-UART adapter + jumper wires, soldering iron

Software — Windows

Software — openSUSE Tumbleweed / any Linux

  • openssh (you already have this — ssh/scp cover PuTTY + WinSCP)
  • atftp for the TFTP server: 
    sudo zypper install atftp picocom
    (picocom only needed for the UART fallback)
  • NetworkManager (default on Tumbleweed) for setting a temporary static IP — nmcli

Firmware files — from the official firmware selector: 👉 https://firmware-selector.openwrt.org/?version=25.12.4&target=mediatek%2Ffilogic&id=imou_hx21

(If that exact version URL is stale by the time you read this, just go to https://firmware-selector.openwrt.org/, type "Imou HX21" and pick the latest stable release — do not use the LC-HX3001 profile, use the native imou_hx21 one.)

You need 4 files total. The firmware selector's main download gives you the sysupgrade image; the bootloader artifacts (preloader/FIP) and the initramfs recovery image are usually listed under the same device page as additional/other downloads. Grab:

openwrt-25.12.x-mediatek-filogic-imou_hx21-preloader.bin
openwrt-25.12.x-mediatek-filogic-imou_hx21-bl31-uboot.fip
openwrt-25.12.x-mediatek-filogic-imou_hx21-initramfs-recovery.itb
openwrt-25.12.x-mediatek-filogic-imou_hx21-squashfs-sysupgrade.itb

⚠️ Important: the bootloader has these exact filenames hardcoded for TFTP lookups (no version string). You'll rename the files before serving them — covered in Step 4.

2. Step 1 — Get SSH access on stock firmware (no soldering)

The global HX21's stock (Imou) firmware ships with SSH disabled but Dropbear present. A community member (byjahidul) built a modified backup-config file that re-enables SSH when restored through the stock web UI — no UART needed for most units.

  1. Connect your PC directly to a LAN port on the HX21 with an ethernet cable. Power the router on.
  2. Get an IP from it (DHCP client, or set your PC static in 192.168.10.0/24 if it doesn't hand one out) and browse to the stock web UI — typically http://192.168.10.1. Default credentials are usually admin / admin on first boot; if you've already set up the router via the Imou app, use whatever password you set.
  3. Download the SSH-enabling config file: 👉 https://github.com/byjahidul/Imou-HX21 (file: HX21-ssh.bin)
  4. In the web UI: System → Backup/Restore → Restore Configuration, upload HX21-ssh.bin.
  5. The router reboots. After it comes back:
    • Web UI password becomes 12345678
    • SSH is open at root@192.168.10.1 with no password (just press Enter)
ssh root@192.168.10.1

If this doesn't work on your firmware revision: fall back to UART. Open the case, solder GND/RX/TX to the UART pads (no VCC needed), connect at 115200 baud with picocom -b 115200 /dev/ttyUSB0, power on, hit Enter quickly to get a prompt, then:

dropbear -p 22
passwd

and SSH in as above.

3. Step 2 — Back up everything

Once you have a root shell, do not skip this.

cat /proc/mtd

Note the mtd numbers for BL2, u-boot-env, Factory, FIP, and the big UBI/rootfs partition (device+numbering can vary slightly by firmware batch — match against the label column, not just the example numbers below).

Small partitions (safe to dump to /tmp, which is RAM-backed):

dd if=/dev/mtd1 of=/tmp/BL2_backup.bin bs=1M count=1
dd if=/dev/mtd2 of=/tmp/u-bootenv_backup.bin bs=512K count=1
dd if=/dev/mtd3 of=/tmp/factory_backup.bin bs=2M count=1
dd if=/dev/mtd4 of=/tmp/FIP_backup.bin bs=2M count=1

Pull them to your machine over SCP (this replaces WinSCP entirely on Linux):

mkdir -p ~/hx21-backup && cd ~/hx21-backup
scp root@192.168.10.1:/tmp/BL2_backup.bin .
scp root@192.168.10.1:/tmp/u-bootenv_backup.bin .
scp root@192.168.10.1:/tmp/factory_backup.bin .
scp root@192.168.10.1:/tmp/FIP_backup.bin .

The big UBI/rootfs partition (~115 MB) — too large for the 256 MB-RAM device's /tmp to hold comfortably alongside a running system. On Linux you can stream it straight over SSH without ever touching the device's storage, which is cleaner than the chunked Windows workaround:

ssh root@192.168.10.1 "cat /dev/mtd5" > ubi_backup.bin

(replace mtd5 with whatever your cat /proc/mtd showed as the UBI partition)

Verify integrity:

ssh root@192.168.10.1 "dd if=/dev/mtd5 bs=1M count=115 2>/dev/null | md5sum"
md5sum ubi_backup.bin

Both hashes must match. If they don't, redo the backup before proceeding — do not flash anything until this is clean.

4. Step 3 — Flash the new bootloader (FIP)

Upload the FIP file to the router's /tmp:

scp openwrt-25.12.x-mediatek-filogic-imou_hx21-bl31-uboot.fip root@192.168.10.1:/tmp/

On the router (over SSH):

mtd write /tmp/openwrt-25.12.x-mediatek-filogic-imou_hx21-bl31-uboot.fip FIP
sync

This installs the OpenWrt bootloader over the stock one. From this point on, power-cycling gives you an OpenWrt-style u-boot with a proper recovery menu and a reset-button TFTP recovery mode — which is the mechanism that lets the rest of this go without ever touching UART.

5. Step 4 — TFTP-recover into OpenWrt

Set up your PC:

  • Static IP 192.168.1.254/24, no gateway needed, directly wired to the router's LAN port.

    Linux/openSUSE (temporary, replace eth0 with your interface):

    sudo ip addr flush dev eth0
sudo ip addr add 192.168.1.254/24 dev eth0
sudo ip link set eth0 up

    Or persist it with NetworkManager:

    nmcli con add type ethernet ifname eth0 con-name hx21-flash ip4 192.168.1.254/24
nmcli con up hx21-flash

Rename and serve the recovery files. The bootloader looks for hardcoded filenames (no version string), so:

mkdir -p ~/tftpboot && cd ~/tftpboot
cp /path/to/openwrt-25.12.x-mediatek-filogic-imou_hx21-preloader.bin \
   openwrt-mediatek-filogic-imou_hx21-preloader.bin
cp /path/to/openwrt-25.12.x-mediatek-filogic-imou_hx21-initramfs-recovery.itb \
   openwrt-mediatek-filogic-imou_hx21-initramfs-recovery.itb

Start the TFTP server:

sudo atftpd --daemon --port 69 ~/tftpboot

(Windows equivalent: point Tftpd64's "Current Directory" at a folder with those same two renamed files, server interface = 192.168.1.254.)

Now trigger recovery on the router:

  1. Power off the HX21.
  2. Hold the Reset button down.
  3. Power it back on while still holding Reset, and keep holding for ~10–15 seconds.
  4. The bootloader's boot_first logic detects the held reset button and automatically requests the preloader over TFTP, writes it, then requests and boots the initramfs recovery image straight into RAM.
  5. Watch your atftpd logs (or Tftpd64's log viewer) — you should see two file transfers happen a few seconds apart.
  6. After a minute or two, the router should be reachable at http://192.168.1.1 and via SSH — this is a temporary, RAM-only OpenWrt, not yet persistent.
ssh root@192.168.1.1
passwd   # set a root password now, you'll want it later

If nothing happens on reset+power, your unit may need the UART bootmenu approach instead: connect serial, power on, and in the custom OpenWrt bootmenu manually select "Load BL2 preloader via TFTP and then write to NAND", then "Boot system via TFTP." This is only needed as a fallback — the reset-button method above is the documented no-solder path.

6. Step 5 — Install the permanent firmware

With the temporary recovery system booted and reachable at 192.168.1.1:

scp openwrt-25.12.x-mediatek-filogic-imou_hx21-squashfs-sysupgrade.itb root@192.168.1.1:/tmp/
ssh root@192.168.1.1
sysupgrade /tmp/openwrt-25.12.x-mediatek-filogic-imou_hx21-squashfs-sysupgrade.itb

The router reboots and this time it's persistent — permanent OpenWrt on NAND. Give it a couple of minutes.

7. Step 6 — First boot & (optional) preloader update

Back on ethernet, browse to http://192.168.1.1 for LuCI, or SSH in the same way. Set a real root password immediately (passwd) if you haven't already, and configure Wi-Fi under Network → Wireless (it ships disabled by default on a fresh flash).

Optional — update the BL2 preloader too, so the router is fully off stock bootloader components. This step is marked in red in the upstream instructions because a failed BL2 write has no fallback recovery — only do it once you've confirmed the router boots and works normally on the new firmware, and only if you actually need it (most people don't):

opkg update
opkg install kmod-mtd-rw
insmod mtd-rw i_want_a_brick=1
mtd write /tmp/openwrt-mediatek-filogic-imou_hx21-preloader.bin bl2

(upload the preloader.bin to /tmp via scp first, same as before)

8. Quick troubleshooting notes

  • WAN LED stuck "on" when disconnected — a cosmetic bug reported by another user on this exact device; harmless.
  • No internet through WAN after flashing, everything else fine — almost always a subnet collision: if your upstream modem/router is also 192.168.1.0/24, OpenWrt's default LAN clashes with it. Change OpenWrt's LAN IP (Network → Interfaces → LAN) to something like 192.168.23.1/24, apply, then reconnect your PC after it gets a new DHCP lease. On 25.12+, LuCI wants the address written as a single ip/prefix value (e.g. 192.168.23.1/24), not separate IP + netmask fields.
  • Always re-check the firmware selector link at flash time — release numbers move (25.12.0 → 25.12.4 already), and the exact filenames only make sense for the version you actually download.

Sources

  • OpenWrt upstream commit: mediatek: add support for Imou HX21 (Jahidul Islam, merged Nov 2025, PR openwrt/openwrt#20753)
  • OpenWrt Forum: "Adding Support For Imou HX21" (forum.openwrt.org/t/adding-support-for-imou-hx21/242973)
  • OpenWrt Forum: "ISP + openwrt router configuration" (forum.openwrt.org/t/isp-openwrt-router-configuration/251178) — confirms 25.12.x stable support and firmware selector URL
  • github.com/byjahidul/Imou-HX21 — SSH-enabling config file
  • Community walkthrough: "Install ImmortalWrt on Imou HX21 Router" by Faisal Faruque Rafat (Medium) — backup/TFTP/sysupgrade mechanics
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment