Installing the Rockbox bootloader with jztool
These instructions describe how to install the Rockbox bootloader for the following players based on the
IngenicX1000 SoC.
Rockbox generally works well on these players, but you should check your player's wiki page for any port-specific caveats.
NOTE: The AIGO Eros Q/K, AGPTek H3, HiFi Walker H2, or Surfans F20 all share the same hardware. If you have a player in this family, you should follow the Eros Q instructions regardless of your player's branding.
Overview
Installing the Rockbox bootloader on your player is a two-step process.
The first step is connecting your player to your computer in USB boot mode and loading the Rockbox bootloader. This will not modify your player; the bootloader runs solely in RAM. The bootloader displays a recovery menu which is used perform the remainder of the installation.
The second step is backing up your existing bootloader and flashing the Rockbox bootloader to your device. This is done by selecting the relevant options in the bootloader's recovery menu.
Flashing the Rockbox bootloader will replace the original firmware's bootloader, which is why you should take a backup of the original bootloader. The backup will allow you to restore your device to a factory state, should you wish to.
If for some reason your player becomes unbootable (aka. "soft bricked"), you can unbrick it loading up the Rockbox bootloader over USB, and re-installing the bootloader or restoring an earlier bootloader backup. Since USB boot mode is a built-in feature of the CPU, this will work even if your player firmware is completely corrupted or wiped.
Using the web-based installer
The web-based installer at
https://amachronic.github.io/jztooljs/ runs from your browser and is probably the most user friendly installation method, especially if you are not comfortable with the command line -- simply follow the instructions on the page to install the bootloader on your player. The web installer does not install a Rockbox build, so you will still have to download one from the
daily builds page and unzip it to your SD card.
The web installer is recommended if you are on Windows because it does not require installing additional drivers, unlike the command line
jztool method, and it also supports more platforms -- any platform with a WebUSB-capable browser like Chrome/Chromium or Edge should work.
Please note that the web installer is new and is therefore not as well tested as the traditional
jztool method. If you run into any problems or have suggestions for improvements, the best places to go are the Rockbox forums or IRC channel, or you can open a
Github issue.
Using jztool
The
jztool command-line utility is used to perform the installation and should work on any desktop OS.
Windows users will need administrator access in order to install a USB driver for
jztool. The driver itself is a Microsoft driver that's shipped with Windows, however.
Linux users will need root access in order to access to the player in USB boot mode.
Step 1: Download the needed files
You'll need to download the latest bootloader for your player from the table below.
You will also need to download
jztool for your platform. Prebuilt binaries are provided for Windows, Mac, and Linux. Users of other OSs must compile
jztool from source (found under
utils/jztool in the Rockbox repository).
Although not strictly necessary for the bootloader installation, you'll eventually need to install a Rockbox build to your SD card. You can do this alongside the bootloader installation when you prepare the SD card, or you can choose to do this after the installation. Visit the
daily builds page to download a build for your player.
NOTE: To reduce confusion, the Eros Q builds on the daily builds page are for the hosted version of Rockbox and will not work with the native version. Builds for the native version are kept at
https://build.rockbox.org/data/rockbox-erosqnative.zip, and are updated with every commit.
Windows users will also need to download Zadig, a tool that simplifies the installation of USB drivers for
libusb based applications. Download links and further information can be found on Zadig's homepage,
https://zadig.akeo.ie/.
Step 2: Prepare the SD card
You will need a microSD card with a FAT32/FAT16 filesystem for use with Rockbox. In particular, exFAT is not supported. If you are using Windows, you may need to use a 3rd-party tool such as
Guiformat to format your card, because Windows doesn't allow drives larger than 32 GiB to be formatted as FAT32. Your player's original firmware may also be able to format your SD card.
Once the card is properly formatted, copy the bootloader you downloaded (eg.
bootloader.m3k) to the root of the SD card.
If you have already downloaded a Rockbox build, you can extract it to the SD card now to install it. Take the
rockbox.zip file that you downloaded and use the âExtract allâ command of your unzip program to extract the files onto your player.
Important: The entire contents of the
.zip file should be extracted directly to the root of your playerâs drive. Do not try to create a separate directory on your player for the Rockbox files! The
.zip file already contains the internal structure that Rockbox needs. If the contents of the
.zip file are extracted correctly, you will see a directory called
.rockbox on the root directory of your SD card. (You may need to show hidden files to see the folder on some operating systems.)
When you are finished copying all the required files, safely eject the card and insert it into your player's SD card slot.
Step 3: Connect your player
Connect your player in USB boot mode to begin the installation. USB boot mode allows firmware to be loaded to the player over USB, and is activated by holding down a button while powering on the player.
| Player |
USB boot button |
| FiiO M3K |
Volume Down |
| Shanling Q1 |
Play (center button) |
| AIGO Eros Q |
Menu |
The recommended way of connecting your player is given below.
- Make sure your player is fully powered off.
- Connect a USB cable to your player -- but don't plug it into your computer yet.
- Hold the USB boot button while plugging the other end of the cable into your computer. It is not necessary to press the power button.
- Release the USB boot button.
Windows users now need to install a
libusb driver before proceeding with the rest of the installation. Unless you've previously installed the driver on your computer, head down to the
"Installing the USB driver" section for instructions and return here when done.
Step 4: Load the bootloader
With your player connected in USB boot mode, you are ready to load the Rockbox bootloader. Open a command prompt or terminal in the folder containing
jztool, and copy the bootloader file you downloaded in step 1 to this folder.
Copying the bootloader file is optional, but if it is located in a different directory you'll need to amend the
jztool command below with the full path to the file.
Use the tables below to find the appropriate command to load the bootloader.
Windows
| Player |
Command |
| FiiO M3K |
.\jztool.exe -v fiiom3k load bootloader.m3k |
| Shanling Q1 |
.\jztool.exe -v shanlingq1 load bootloader.q1 |
| AIGO Eros Q |
.\jztool.exe -v erosq load bootloader.erosq |
You do not need administrator access for this command. Running as a normal user is enough.
Mac / Linux
| Player |
Command |
| FiiO M3K |
./jztool -v fiiom3k load bootloader.m3k |
| Shanling Q1 |
./jztool -v shanlingq1 load bootloader.q1 |
| AIGO Eros Q |
./jztool -v erosq load bootloader.erosq |
Both Linux and Mac users may need to do
chmod +x jztool in order to execute
jztool, and Mac users will probably need to go into System Preferences --> Security & Privacy in order to tell MacOS that it's okay to execute
jztool.
Linux users will need permissions to access the USB device, either by running
jztool as root with
sudo or
su -c or by changing permissions on the USB device node.
To change the permissions temporarily, which lasts until the device is unplugged, find the bus and device number of your USB device with
lsusb:
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 003: ID 05c8:03ac Cheng Uei Precision Industry Co., Ltd (Foxlink) HP TrueVision HD Camera
Bus 001 Device 002: ID 8087:0a2a Intel Corp. Bluetooth wireless interface
Bus 001 Device 005: ID a108:1000 Ingenic Semiconductor Co.,Ltd X1000
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
In the above example, the player shows up as
a108:1000 Ingenic Semiconductor Co,Ltd X1000. It is device
005 on bus
001, so its device node would be
/dev/bus/usb/001/005. As root, change the ownership of the device node with
chown, replacing
MYUSER with your username, and
BUS /
DEV with the bus and device numbers from
lsusb:
# chown MYUSER /dev/bus/usb/BUS/DEV
Step 5: Complete the install
If the bootloader was loaded successfully, you will see the Rockbox recovery menu on your player's screen.
Reminder: Make sure your SD card has been prepared with a FAT32 filesystem and you have copied the bootloader (the same one you loaded with
jztool) to the root of the SD card, and insert the SD card to your player.
First, you should take a backup of your existing bootloader especially if this is your first time installing the Rockbox bootloader on this player. Use the buttons on your player to select
Backup under the
Bootloader menu. This will take a backup of your current bootloader and save it to a
.bin file on your SD card. This file should be kept somewhere safe. If you later decide you want to remove Rockbox you will need it to restore the original bootloader. Be careful not to take a backup again after installing, as this will overwrite your first backup!
Note: On the Eros Q, bootloader backups are tied to the original firmware version that is currently installed on your player. See the "known issues" section below.
When you're ready to flash the Rockbox bootloader, select
Install or update from the
Bootloader menu. If it displays a
Success! message, then you have completed the installation! Otherwise, check the
troubleshooting section below for tips.
Step 6: Start Rockbox
Now that the bootloader is installed, you can start Rockbox by selecting
Rockbox from the
Boot Select section of the menu, or simply by rebooting your player.
If you receive a message
Error loading Rockbox: File not found then your Rockbox installation is probably incomplete. Scroll down to the troubleshooting section for instructions on installing a build on your SD card.
Installing a USB driver for jztool (Windows)
If you're doing the installation from a Windows computer and you have not used
jztool on the computer before, you will need to install a backend driver for
libusb using
Zadig to allow
jztool to access your player in USB boot mode. Further information on Zadig can be found on its homepage.
Zadig allows you to choose from multiple backend drivers for
libusb. Though
jztool works with any backend driver, the one recommended by the
libusb project is
WinUSB, a Microsoft driver shipped with most recent versions of Windows. Some users have reported that
WinUSB does not work, in which case the
libusbK backend can be used as an alternative. It may be necessary to try other backends in case both
WinUSB and
libusbK do not work.
Whichever driver you use, it is only installed for the device you select in Zadig and will not affect other USB devices on your system.
To install the driver, make sure your player is connected in USB boot mode and open Zadig.
Use the drop down menu to select your device. The device name will be displayed as 'X' followed by a hollow square (for some reason, this is how the device name is displayed on Windows). It is important to check the USB IDs are correct -- make sure the ID is
A108 1000, which is the same for all players using the X1000
SoC.
WARNING: Clicking
Install will replace the driver of the selected device with a
libusb driver! Zadig will even let you replace your keyboard or mouse driver, which will render them unusable until you re-install the proper drivers, so be sure you have got the correct device!
When you have selected your player and the driver you want to install, click
Install to start the installation. It can take a few minutes, so be patient and don't unplug your device. Once the driver installation completes, you can continue installing Rockbox on your player.
Removing Rockbox
If you'd like to remove Rockbox, use the
Restore option in the Rockbox bootloader menu. This will restore the original bootloader and erase all traces of Rockbox from your player's internal flash memory. The bootloader backup file must be copied to the root of your SD card. Download the backup file for your player below, or alternatively, you can use your own backup created during installation.
Note: There is no Eros Q backup available to download yet. More work is needed to determine if different backup files are needed for different player models and firmware versions, in the meantime please be sure to make your own backups and keep them somewhere safe.
Known issues
Bootloader backups on the Eros Q may not restore your device to a usable state if you have updated the original firmware (OF) after taking the backup.
To avoid issues, do not update the OF while the Rockbox bootloader is installed. If you want to change your OF version, remove the Rockbox bootloader first by restoring your bootloader backup, and
then update the original firmware. After the update, you can reinstall Rockbox and take a new backup (and make sure to delete your old one, which is now useless).
Troubleshooting
If you run into any problems during the installation it's best to ask on the usual support channels - the forum, IRC, or mailing lists - for help. That said, the most common issues are usually simple mistakes you can correct yourself:
- Skipping one of the steps in the instructions
- Not copying files to the right location
- Opening the command line in the wrong location
- Not formatting the SD card properly
It could save you (and others!) time if you make sure you haven't forgotten anything before asking for help.
Wrong partition table
If you are having difficulty getting Rockbox to recognize your SD card despite it having a valid FAT32 filesystem then it is possible it is formatted with a GPT partition table. Rockbox only supports an MBR partition table.
Error loading Rockbox: File not found
This message is displayed by the bootloader if it cannot locate the Rockbox firmware on your SD card. This usually means your installation is missing or incomplete. To install a build on your SD card follow these steps:
- Download a build for your player from the dev builds page.
- Connect your SD card to your computer either with a card reader or with the "USB Mode" option in the bootloader.
- Extract the .zip file you downloaded to the SD card.
If the .zip was extracted successfully you should see a
.rockbox folder on the root of your SD card.
If you are using
multiboot, double check your redirect files. If you don't know what multiboot is, you can ignore this.
You should now be able to reboot your player and boot Rockbox.
Copyright © by the contributing authors.
