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, orgpioset. - Display: Check resolution with
fbsetorxrandr. - UART/I2C/SPI: Use
dmesgto 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:
- Use serial or local console to access the board.
- Boot from a backup SD card or mount the original SD card on another Linux system.
- Replace script.bin with the backup:
sudo cp /boot/script.bin.backup /boot/script.bin. - Review the .fex changes you made. Look for syntax errors, wrong port names (PA vs PB), or conflicting pin assignments.
- Test changes incrementally (one section at a time) to isolate the problem.
bin2fex or fex2bin fails with syntax error
- Symptoms:
fex2binreports parse errors or invalid values. - Steps:
- Check for typos in section names (e.g.,
[gpio_para]vs[gpio_pra]). - Verify port names match SoC naming (PA, PB, PC, PD, etc.). Do not use invalid port letters.
- Check integer values are in valid ranges. GPIO function codes are typically 0-7.
- Remove any duplicate entries (same pin defined twice).
- Use a known-good .fex as reference. Decompile a working script.bin and compare structure.
- Check for typos in section names (e.g.,
GPIO pin does not work as expected
- Symptoms: Pin state does not change; conflicts with UART/I2C/SPI.
- Steps:
- Check if the pin is assigned to another function in a different FEX section (UART, I2C, SPI).
- Verify the pin function code. 0 = input, 1 = output. Other values assign the pin to hardware interfaces.
- Confirm pull-up/pull-down settings match your circuit requirements.
- Use
dmesg | grep gpioto check for kernel messages about GPIO conflicts. - 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:
- Check
[disp_init]section. Verifyscreen0_output_typematches your display (3 = HDMI, 4 = LCD). - Try different
screen0_output_modevalues (consult mode table for your board). Common values: 4 = 720p, 5 = 1080p. - If using an LCD panel, verify timing parameters (pixel clock, horizontal/vertical sync) match the panel datasheet.
- Revert to known-good display settings and test with a different display/cable.
- Check kernel logs for display driver errors:
dmesg | grep disp.
- Check
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