Skip to content

Update Methods

Jump to bottom
SuperKali edited this page Apr 24, 2025 · 1 revision

📈 Update System Evolution

BananaWRT's update system has evolved over time:

🆕 Newer Versions (Current)

In recent BananaWRT releases (April 2025 and newer), the update functionality is integrated directly into the system through the banana-update command:

banana-update [fota|ota|packages] [--dry-run] [--reset]

📜 Older Versions

In older BananaWRT releases (before April 2025), updates were performed using the standalone script:

/bin/sh update-script.sh [fota|ota|packages] [--dry-run] [--reset]

🛠️ Available Update Methods

1. 📡 FOTA (Firmware Over The Air)

The FOTA method is the simplest approach, downloading and installing the latest firmware directly from GitHub.

# Newer versions
banana-update fota

# Older versions
/bin/sh update-script.sh fota

How it works:

  1. 🌐 The system connects to GitHub and fetches available releases
  2. 📋 You'll see a list of the latest releases (stable and nightly)
  3. 🔢 Select your preferred release by entering its number
  4. ⬇️ The script downloads all necessary firmware files
  5. 💿 Files are flashed to the appropriate partitions
  6. 🔄 A sysupgrade is performed to complete the installation
  7. 🔌 Your device reboots with the updated firmware

When to use FOTA:

  • 🌐 When you have a reliable internet connection
  • 🚀 When you want the simplest update experience
  • 🔍 When you want to see all available versions before choosing

2. 💾 OTA (On-The-Air)

The OTA method uses firmware files you've already downloaded to your device.

# Newer versions
banana-update ota

# Older versions
/bin/sh update-script.sh ota

Requirements for OTA:

  • ⬆️ Copy these four firmware files to your device's /tmp directory:
    • immortalwrt-{VERSION}-mediatek-filogic-bananapi_bpi-r3-mini-emmc-preloader.bin
    • immortalwrt-{VERSION}-mediatek-filogic-bananapi_bpi-r3-mini-emmc-bl31-uboot.fip
    • immortalwrt-{VERSION}-mediatek-filogic-bananapi_bpi-r3-mini-initramfs-recovery.itb
    • immortalwrt-{VERSION}-mediatek-filogic-bananapi_bpi-r3-mini-squashfs-sysupgrade.itb
  • ⌨️ You'll need to enter the firmware version when prompted

When to use OTA:

  • 📉 When you have limited or unreliable internet on your device
  • 🖥️ When you've already downloaded the firmware files on another computer
  • 🎯 When you want to install a specific version that might not be in the latest releases list

3. 📦 Packages Update

This method updates only the custom packages without changing the base firmware.

# Newer versions
banana-update packages

# Older versions
/bin/sh update-script.sh packages

How it works:

  1. 🔍 Checks the repository for package updates
  2. 📋 Displays a list of packages that can be updated
  3. ✅ Asks for confirmation before proceeding
  4. 📦 Updates selected packages without changing the system firmware

When to use Packages Update:

  • 📦 When you only want to update BananaWRT custom packages
  • 🛑 When a full firmware update isn't necessary
  • 🆕 When new package versions are available but the base system is stable

⚙️ Additional Options

🧪 Dry Run Mode

To simulate the update process without making actual changes:

# Newer versions
banana-update fota --dry-run

# Older versions
/bin/sh update-script.sh fota --dry-run

The --dry-run flag works with all update methods and shows what would happen without making actual changes.

🔄 Factory Reset

To perform a factory reset during update (doesn't preserve configuration):

# Newer versions
banana-update fota --reset

# Older versions
/bin/sh update-script.sh fota --reset

The --reset flag causes the update to not preserve your configuration, essentially performing a factory reset. This is useful if you're experiencing issues and want a clean start.

📋 Update Process Details

📝 What Gets Updated

A full firmware update (FOTA or OTA) updates:

  • 🥾 Bootloader (preloader and uboot)
  • 🚑 Recovery image
  • 🗂️ Root filesystem
  • 🧠 Kernel

A package update only updates:

  • 📦 Custom BananaWRT packages
  • ⚙️ Package configurations

💾 Configuration Preservation

By default, updates preserve your configuration settings including:

  • 🌐 Network configuration
  • 📡 Wi-Fi settings
  • 👤 User accounts
  • 📦 Installed packages
  • ⚙️ Custom configurations

When using the --reset flag, configuration is not preserved.

🔄 Package Auto-Restoration

BananaWRT includes a smart package auto-restoration system:

  • ♻️ After a firmware update, the system automatically reinstalls previously installed custom packages
  • 🔄 This ensures your functionality remains consistent after updates
  • 🍌 The system is built into the banana-utils package

🛠️ Troubleshooting Updates

⚠️ Common Update Issues

🔍 Unable to download firmware files

Solution:

  • 🌐 Check your internet connection
  • 📡 Try using a different network
  • 📥 Download the files manually and use the OTA method

💥 Error during flashing

Solution:

  • ⚡ Ensure device has adequate power during the update
  • 🔍 Check if all required files are present in /tmp
  • 🔄 Try the update again with a stable release

🚫 Device won't boot after update

Solution:

  • 🔌 Connect to serial console
  • ⏱️ Interrupt boot process and enter recovery mode
  • 💿 Flash firmware again using recovery mode

📦 Package update fails

Solution:

  • 🔄 Update the package lists: opkg update
  • 🔍 Check repository configuration
  • 🧪 Try updating individual packages manually

✅ Best Practices

  1. Always backup your configuration before updating:

    sysupgrade -b /tmp/backup-$(date +%F).tar.gz

  2. ⚡ Ensure stable power during updates to prevent interruptions

  3. 🛡️ Use stable releases for production environments, nightly builds for testing

  4. 💽 Keep disk space available in /tmp (at least 100MB) for firmware files

  5. 👀 Monitor the update process to catch any errors early

For additional help, visit the BananaWRT Discussions page.

Clone this wiki locally