Banana Pi FEX Configuration

Summary

FEX (sometimes called script.bin configuration) is a legacy hardware configuration system used by older Allwinner kernels (3.4.x series). It defines GPIO pin assignments, peripheral settings, display timing, and other hardware parameters for Banana Pi and Banana Pro boards. Modern kernels (4.x+) use device tree instead.

This page covers when FEX is still relevant, how to safely edit FEX configurations, convert between FEX binary and text formats, and troubleshoot common issues. If your system uses device tree (check for .dtb files in /boot), you do not need FEX configuration.

Who this is for

Users running legacy 3.4.x kernel images on Banana Pi/Pro, people porting old tutorials that reference script.bin, and anyone troubleshooting GPIO or display issues on FEX-based systems.

What you'll do

• Determine if your system uses FEX or device tree configuration.
• Back up existing FEX configuration before making changes.
• Convert script.bin (binary) to .fex (text) for editing.
• Edit .fex file to change GPIO, display, or peripheral settings.
• Convert back to script.bin and test with recovery access available.
• Troubleshoot boot failures caused by FEX misconfigurations.

FEX vs device tree

When FEX is used

FEX is only relevant for legacy Allwinner 3.4.x kernel images (typically based on older Android/Allwinner SDK releases). These images store hardware configuration in /boot/script.bin.

Check if your system uses FEX:

uname -r          # If kernel version is 3.4.x, likely uses FEX
ls /boot/*.bin    # Look for script.bin
ls /boot/*.fex    # Look for .fex source files (if present)

When device tree is used

Modern kernels (4.x, 5.x, 6.x) use device tree blobs (.dtb files) stored in /boot. Device tree is the standard Linux hardware description format and is not compatible with FEX.

ls /boot/*.dtb    # Look for device tree blobs

If you see .dtb files, do not use FEX tools. Modify the device tree source (.dts) instead, recompile to .dtb, and update boot configuration.

Safe process for FEX changes

1. Back up existing configuration

Before any changes, back up the entire /boot partition:

sudo cp -a /boot /boot.backup.$(date +%F)
# Or back up just script.bin:
sudo cp /boot/script.bin /boot/script.bin.backup

Store the backup on a different storage device (USB stick, another SD card, or copy to your workstation).

2. Convert script.bin to .fex (text format)

Use the bin2fex tool (part of sunxi-tools package) to convert binary to text:

# Install sunxi-tools (if not already installed)
sudo apt install sunxi-tools

# Decompile script.bin to text format
sudo bin2fex /boot/script.bin /tmp/script.fex

The resulting .fex file is a text configuration file you can edit with a text editor.

3. Edit .fex file

Open the .fex file and make changes carefully. Common edits include:

• GPIO pin configuration: Change pin assignments, pull-up/pull-down settings.
• Display timing: Adjust resolution, refresh rate, timing parameters for LCD panels.
• UART/SPI/I2C settings: Enable or disable interfaces, change pin mappings.
• MAC address: Set Ethernet MAC address (some images randomize this on boot).

nano /tmp/script.fex
# or
vi /tmp/script.fex

Important: Change only one setting at a time. Syntax errors or wrong values can prevent boot.

4. Convert .fex back to script.bin

Use fex2bin to compile the edited .fex back to binary format:

sudo fex2bin /tmp/script.fex /boot/script.bin.new

Do not overwrite the original script.bin yet. Test the new file first.

5. Test with recovery access available

Rename the old script.bin and use the new one:

sudo mv /boot/script.bin /boot/script.bin.old
sudo mv /boot/script.bin.new /boot/script.bin
sync

Ensure you have serial console or local console access (HDMI + keyboard) in case the board does not boot. Reboot:

sudo reboot

If boot fails, use serial/local console to replace script.bin with the backup:

sudo cp /boot/script.bin.old /boot/script.bin
sudo reboot

6. Verify changes took effect

After successful boot, verify your changes:

• GPIO: Test pin state with gpioinfo, gpioget, or gpioset.
• Display: Check resolution with fbset or xrandr.
• UART/I2C/SPI: Use dmesg to verify interfaces are detected: dmesg | grep -E "uart|i2c|spi".

If verification passes, you can delete the .old and .backup files. If not, revert and investigate.

Common FEX sections

[gpio_para] section

Defines GPIO pin assignments, naming, and pull settings. Example:

[gpio_para]
gpio_used = 1
gpio_num = 10
gpio_pin_1 = port:PA10<1><default><default><default>
gpio_pin_2 = port:PA11<1><default><default><default>

Format: port:PAXX<function><pull><drive><data>. Function 0 = input, 1 = output. Pull: 0 = none, 1 = pull-up, 2 = pull-down.

[disp_init] section

Controls display output (HDMI, LCD, VGA). Example:

[disp_init]
disp_init_enable = 1
disp_mode = 0
screen0_output_type = 3  ; 3 = HDMI
screen0_output_mode = 5  ; Mode 5 typically = 1080p60

Changing screen0_output_mode affects resolution. Values are mode-specific; consult Allwinner documentation.

[uart_para] sections

Enables UART interfaces. Example:

[uart_para0]
uart_used = 1
uart_port = 0
uart_type = 2

Set uart_used = 0 to disable. Useful if GPIO pins conflict with UART.

Troubleshooting

Board does not boot after FEX change

• Symptoms: No display output, kernel panic, stuck at boot.
• Steps:
  1. Use serial or local console to access the board.
  2. Boot from a backup SD card or mount the original SD card on another Linux system.
  3. Replace script.bin with the backup: sudo cp /boot/script.bin.backup /boot/script.bin.
  4. Review the .fex changes you made. Look for syntax errors, wrong port names (PA vs PB), or conflicting pin assignments.
  5. Test changes incrementally (one section at a time) to isolate the problem.

bin2fex or fex2bin fails with syntax error

• Symptoms: fex2bin reports parse errors or invalid values.
• Steps:
  1. Check for typos in section names (e.g., [gpio_para] vs [gpio_pra]).
  2. Verify port names match SoC naming (PA, PB, PC, PD, etc.). Do not use invalid port letters.
  3. Check integer values are in valid ranges. GPIO function codes are typically 0-7.
  4. Remove any duplicate entries (same pin defined twice).
  5. Use a known-good .fex as reference. Decompile a working script.bin and compare structure.

GPIO pin does not work as expected

• Symptoms: Pin state does not change; conflicts with UART/I2C/SPI.
• Steps:
  1. Check if the pin is assigned to another function in a different FEX section (UART, I2C, SPI).
  2. Verify the pin function code. 0 = input, 1 = output. Other values assign the pin to hardware interfaces.
  3. Confirm pull-up/pull-down settings match your circuit requirements.
  4. Use dmesg | grep gpio to check for kernel messages about GPIO conflicts.
  5. Test with a different GPIO pin to rule out hardware damage.

Display shows wrong resolution or no output

• Symptoms: Blank screen, wrong resolution, display timing errors.
• Steps:
  1. Check [disp_init] section. Verify screen0_output_type matches your display (3 = HDMI, 4 = LCD).
  2. Try different screen0_output_mode values (consult mode table for your board). Common values: 4 = 720p, 5 = 1080p.
  3. If using an LCD panel, verify timing parameters (pixel clock, horizontal/vertical sync) match the panel datasheet.
  4. Revert to known-good display settings and test with a different display/cable.
  5. Check kernel logs for display driver errors: dmesg | grep disp.

FAQ

Should I use FEX or device tree for a new project?

Use device tree. FEX is legacy (3.4.x kernels only) and not supported by modern kernels. If your image uses device tree (.dtb files), do not attempt to use FEX tools.

Can I convert FEX configuration to device tree?

No direct conversion tool exists. You must manually create a device tree source (.dts) file with equivalent settings. This requires understanding device tree syntax. Consider upgrading to a modern kernel image instead.

Where can I find FEX examples for my board?

Check the sunxi-boards GitHub repository for reference .fex files. Search for your board model (Banana Pi, Banana Pro). Not all configurations are optimal; use as a starting point only.

What happens if I delete script.bin?

The board will not boot (on FEX-based systems). U-Boot loads script.bin to configure hardware before starting the kernel. Always keep a backup and test changes with recovery access available.

Can I use the same script.bin on different boards?

No. FEX configuration is board-specific. Using Banana Pi script.bin on Banana Pro (or vice versa) will cause boot failures or missing hardware (WiFi, SATA). Always use the correct configuration for your board.

How do I know which GPIO pins are safe to use?

Check your board's pinout diagram and the .fex file. Pins already assigned to UART, I2C, SPI, or other functions should not be repurposed unless you disable those interfaces. Start with pins explicitly labeled as GPIO-only.

What tools do I need to edit FEX files?

Install sunxi-tools package: sudo apt install sunxi-tools. This provides bin2fex and fex2bin utilities. Edit .fex files with any text editor (nano, vi, gedit).

Can I edit script.bin on Windows?

Not directly. You need Linux tools (bin2fex, fex2bin). Use a Linux VM, WSL (Windows Subsystem for Linux), or boot a Linux live USB to edit FEX files. Alternatively, mount the SD card on a Linux system.

Where can I learn more about Allwinner FEX format?

Check the linux-sunxi wiki FEX guide and linux-sunxi community resources. These contain detailed documentation on FEX syntax, pin naming, and hardware configuration.

Concrete example (back up config)

sudo cp -a /boot /boot.backup.$(date +%F)

Related pages

• Building U-Boot, script.bin and Linux kernel
• Wiki Main Page
• WiringPi and GPIO notes
• linux-sunxi FEX guide (external)

Author: LeMaker Documentation Team
Last updated: 2026-01-11