Run OpenWrt on Banana Pi BPI-R4 and BPI-R4 Pro 8X (MT7988A, Wi-Fi 7) with an optional UniFi Protect + UniFi Network Application stack — a cost-effective alternative to the Ubiquiti UNVR + Cloud Gateway combo.
Complete install system that runs entirely on GitHub — no Linux machine needed.
Tested hardware: Banana Pi R4 rev 1.0 (4GB) · Banana Pi R4 rev 1.1 (8GB) · Banana Pi R4 Pro 8X · UniFi G5 Flex camera · UniFi U7-LR WiFi 7 AP
- Board variants
- DIP switch reference
- Part A — BPI-R4: Install
- Part B — BPI-R4: UniFi stack
- Part C — BPI-R4 Pro 8X: Install
- Part D — BPI-R4 Pro 8X: UniFi stack
- Part E — Fork and customize
- Architecture
- NVMe partition layout
- Hardware notes
- Known behaviors
| # | Variant | RAM | WiFi | Notes |
|---|---|---|---|---|
| 1 | 4GB standard | 4 GB | ✅ | Standard board |
| 2 | 4GB wired | 4 GB | ❌ | No WiFi, lower footprint |
| 3 | 4GB PoE | 4 GB | ✅ | BPI-R4 with 2.5GE PoE port |
| 4 | 4GB PoE wired | 4 GB | ❌ | PoE, no WiFi |
| 5 | 8GB standard | 8 GB | ✅ | 8 GB RAM board |
| 6 | 8GB wired | 8 GB | ❌ | 8 GB RAM, no WiFi |
| 7 | 8GB PoE | 8 GB | ✅ | 8 GB RAM, PoE |
| 8 | 8GB PoE wired | 8 GB | ❌ | 8 GB RAM, PoE, no WiFi |
| 9 | 8GB wired UniFi | 8 GB | ❌ | Pre-configured for UniFi Network + Protect |
| 10 | 8GB PoE wired UniFi | 8 GB | ❌ | PoE, pre-configured for UniFi |
⚠️ UniFi variants (9, 10) require 8 GB RAM. Running UniFi Network + Protect on 4 GB causes memory exhaustion.
| Variant | RAM | WiFi | Notes |
|---|---|---|---|
| Pro 8X WiFi | 8 GB | ✅ | BPI-R4 Pro 8X with WiFi 7 |
| Pro 8X wired | 8 GB | ❌ | BPI-R4 Pro 8X, no WiFi |
| Boot medium | A | B |
|---|---|---|
| SD card | 1 | 1 |
| NAND | 0 | 1 |
| eMMC | 1 | 0 |
NVMe boot is controlled by U-Boot environment, not DIP switch. After running
install-nvme.sh, the device boots from NVMe automatically — DIP stays at NAND (A=0, B=1) and is never changed again.
NAND and eMMC are fully functional permanent options. NVMe is recommended for larger storage needs — required for the UniFi stack.
The SD card is a full, self-contained OpenWrt system. It boots on its own and
ships the /root/install-dir/ installer scripts. From there you write a small
"lean" installer to NAND, and the NAND system is what installs eMMC and NVMe.
Why go through NAND? eMMC and the SD card share the same MMC controller, so eMMC cannot be written while you are booted from SD. Installing eMMC (and, for a consistent flow, NVMe) is therefore always done from the NAND system.
-
Go to Releases and pick the release for your RAM variant, then download its SD image:
RAM Release SD image 4 GB release-4gb-standardopenwrt-mediatek-filogic-bananapi_bpi-r4-sdcard.img.gz8 GB release-8gb-standardopenwrt-mediatek-filogic-bananapi_bpi-r4-8gb-sdcard.img.gzPoE boards use the
release-*-poetags and the matching…-poe-…-sdcard.img.gzimage. -
Flash it to a microSD card using Balena Etcher.
-
Insert the SD card, set DIP A=1, B=1 (SD boot) and power on.
-
Connect via SSH:
ssh root@192.168.1.1(no password).
Run from the SD card:
/root/install-dir/install-nand.sh
Select your RAM variant (4 GB or 8 GB), then choose the file source — download
from GitHub (default) or a local file in /tmp (development/testing).
After the script finishes:
- Power off.
- Set DIP A=0, B=1 (NAND boot) and power on.
- Connect via SSH:
ssh root@192.168.1.1.
You are now on the NAND system, which is used to install eMMC and NVMe below.
Run this from the NAND system (DIP A=0, B=1).
⚠️ If you want both NVMe and eMMC: Runinstall-emmc.shbeforeinstall-nvme.sh. After NVMe installation the device always boots from NVMe.
Make sure a WAN cable is connected, then run:
/root/install-dir/install-nvme.sh
Select your board variant from the menu. The script checks NVMe health, downloads images (~150 MB), writes OpenWrt to NVMe and reboots automatically.
Updating — to update OpenWrt on NVMe, boot into NAND (DIP A=0, B=1) and run
install-nvme.shagain. Data on p3 is never touched.
Must be run from the NAND system (DIP A=0, B=1). eMMC shares its controller with the SD card, so it cannot be written from the SD system.
/root/install-dir/install-emmc.sh
After installation set DIP A=1, B=0 (eMMC boot) and power on.
- BPI-R4 8 GB RAM (rev 1.2+ recommended)
- NVMe SSD, minimum 500 GB (1 TB recommended for Continuous Recording)
- UniFi camera (G5 Flex tested) · UniFi AP (U7-LR WiFi 7 tested)
- A Ubiquiti account (optional — required only for Remote Access)
| Service | Address |
|---|---|
| UniFi Protect | https://192.168.1.1 |
| UniFi Network Application | https://192.168.1.2:8443 |
| LuCI | http://192.168.1.1:8081 |
Follow Steps 1–2 above, then run:
/root/install-dir/install-nvme.sh
Select variant 9 (8GB wired UniFi) or 10 (8GB PoE wired UniFi).
⚠️ Run from SSH terminal only — not from LuCI terminal (ttyd). The script modifies the firewall and a ttyd session will be interrupted.
cd /mnt/nvme0n1p3
sh unifi-setup.sh
⚠️ When prompted, disconnect the WAN cable before pressing Enter.
- Open
https://192.168.1.1. - Accept the SSL warning (self-signed certificate).
- Other Configuration Options → Local Network → Set Up Console Offline.
- Enter a console name, set a password, click Finish.
Immediately disable auto-updates: Settings → Control Plane → Updates.
Reconnect the WAN cable, then:
cd /mnt/nvme0n1p3
sh unifi-network-setup.sh
- Open
https://192.168.1.2:8443. - Complete the setup wizard.
- Settings → System — disable auto-updates.
- Connect the camera to a LAN port and power it on.
- Hardware reset (hold reset button until LED changes).
- Protect dashboard → Devices — camera appears for adoption.
After factory reset the AP auto-discovers the Network Application via DNS (unifi → 192.168.1.2). It appears as "Pending adoption" within a minute.
If auto-discovery fails (older firmware):
ssh ubnt@<AP_IP> "/usr/bin/syswrapper.sh set-inform http://192.168.1.2:8080/inform"
<AP_IP> visible in LuCI (http://192.168.1.1:8081) → Network → DHCP Leases. Default credentials: ubnt / ubnt
BPI-R4 Pro 8X uses a different SoC configuration, NAND layout, and device trees than the standard BPI-R4. Pro 8X images are not compatible with standard BPI-R4 and vice versa.
- BPI-R4 Pro 8X board
- NVMe SSD in slot CN14 (M-key), minimum 512 GB — tested with Patriot P300 512 GB. CN15 and CN18 are B-key slots for LTE modems, not NVMe.
- microSD card (temporary, for install only)
- For WAN and LAN connectivity: SFP or SFP copper modules are recommended
- Go to Releases and download the SD card image from release-pro-8x-wired or release-pro-8x-standard:
openwrt-mediatek-filogic-bananapi_bpi-r4-pro-8x-sdcard.img.gz - Flash to a microSD card using Balena Etcher.
- Insert SD card, set DIP A=1, B=1 (SD boot) and power on.
- Connect via SSH:
ssh root@192.168.1.1(no password).
Connect the WAN cable, then run:
/root/install-dir/install-nand.sh
After the script finishes:
- Power off.
- Set DIP A=0, B=1 (NAND boot) and power on.
- Connect via SSH:
ssh root@192.168.1.1.
⚠️ Run this beforeinstall-nvme.sh. After NVMe installation the device always boots from NVMe.
/root/install-dir/install-emmc.sh
Select 1 (Pro 8X WiFi) or 2 (Pro 8X wired).
After installation set DIP A=1, B=0 (eMMC boot) to use eMMC, or keep DIP at A=0, B=1 and continue with NVMe install.
From the NAND system, connect the WAN cable and run:
/root/install-dir/install-nvme.sh
Select 1 (Pro 8X WiFi) or 2 (Pro 8X wired).
The script checks NVMe health, downloads images (~150 MB), writes OpenWrt to NVMe and reboots automatically.
After reboot the router boots from NVMe. DIP stays at A=0, B=1 permanently — this is correct.
boot-nand # switch to NAND on next reboot
boot-nvme # switch back to NVMe on next reboot
Pro 8X wired is ideal for running the UniFi stack — 8 GB RAM, NVMe storage, and no onboard WiFi interference.
- BPI-R4 Pro 8X (wired variant recommended)
- NVMe SSD in slot CN14, minimum 512 GB (1 TB recommended for Continuous Recording)
- UniFi camera (G5 Flex tested) · UniFi AP (U7-LR WiFi 7 tested)
- A Ubiquiti account (optional — required only for Remote Access)
| Service | Address |
|---|---|
| UniFi Protect | https://192.168.1.1 |
| UniFi Network Application | https://192.168.1.1:8443 |
| LuCI | http://192.168.1.1:8080 |
Follow Part C Steps 1–2, then run:
/root/install-dir/install-nvme-unifi.sh
Select 1 (Pro 8X WiFi) or 2 (Pro 8X wired).
⚠️ Run from SSH terminal only — not from LuCI terminal (ttyd). The script modifies the firewall and a ttyd session will be interrupted.
sh /mnt/nvme0n1p3/unifi-setup.sh
When asked to download or use a local file — select [1] Download. The script downloads the Docker image (~660 MB) and loads it automatically.
⚠️ When prompted, disconnect the WAN cable before pressing Enter.
- Open
https://192.168.1.1. - Accept the SSL warning (self-signed certificate).
- Other Configuration Options → Local Network → Set Up Console Offline.
- Enter a console name, set a password, click Finish.
Immediately disable auto-updates: Settings → General → Auto Update.
Reconnect the WAN cable, then:
sh /mnt/nvme0n1p3/unifi-network-setup.sh
- Open
https://192.168.1.1:8443. - Complete the setup wizard.
- Settings → System — disable auto-updates.
Same procedure as Part B — see Adding a camera and Adopting an Access Point.
Fork this repository to build your own customized release.
- Fork on GitHub. Do not rename the fork — it must stay named
bpi-r4-deploy. - Go to Settings → Actions → General → set Workflow permissions to Read and write.
- Go to Actions → Build BPI-R4 Pro 8X → Run workflow, select Pro-8X-wifi or Pro-8X-wired.
- After ~2 hours, releases appear in your fork.
To install from your fork, edit GH_USER at the top of the install scripts.
| Component | Role |
|---|---|
| BPI-R4 / Pro 8X | Routing, firewall, Docker runtime, NVMe storage |
| UniFi Protect | Camera management (dciancu Docker image) |
| UniFi Network Application | WiFi management (linuxserver Docker image) |
| UniFi AP | Professional WiFi (U7-LR WiFi 7 tested) |
| Partition | Size | Purpose |
|---|---|---|
| p1 | 256 MB | Boot (kernel) |
| p2 | 512 MB | Root filesystem |
| p3 | remainder | Data / Docker / UniFi storage |
| Issue | Details |
|---|---|
| NVMe + SFP conflict | Some NVMe disks pull down the I2C bus, disabling SFP ports |
| Affected disks | Chinese OEM NVMe drives (e.g. generic 128 GB) |
| Not affected | Samsung EVO series |
| Fixed in | Rev 1.2+ |
For new builds, BPI-R4 8 GB RAM rev 1.2+ is recommended.
After a cold boot or reboot, allow approximately 4–5 minutes for the router to become fully operational.
Approximate timeline:
- ~1 min — router reachable via SSH/LuCI
- ~3 min — UniFi Protect available
- ~8–10 min — UniFi Network Application fully initialized
When WAN goes down and comes back up, the installed hotplug handler (99-docker-nft) restores Docker nftables rules automatically — no reboot needed.
On the very first boot into the NAND system, U-Boot may print messages like:
UBI: Bad EC magic in block XXXX
This is normal — U-Boot is initializing the NAND flash. The messages disappear on subsequent boots.
If a build fails with a disk-related error, re-run the workflow — runners with sufficient space are usually available shortly.
This project is not affiliated with Ubiquiti Inc. in any way.
🍌 TEAM WOZIWRT+CLAUDE