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.
- Go to Releases and find any release — all releases contain the same SD rescue image
bpi-r4-rescue-sdcard.img.gz. - Download
bpi-r4-rescue-sdcard.img.gz. - 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).
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.
⚠️ 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–240 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.
/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