Update Methods - SuperKali/BananaWRT GitHub Wiki

๐Ÿ“ˆ 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.