release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Search | Go
Wiki > Main > JztoolInstall

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. If your player is listed as in development, then you will need to manually compile a bootloader. Instructions on how to do this are beyond the scope of this guide.

Player Version Download link
FiiO M3K bf3e67204c-20220402 bootloader.m3k
Shanling Q1 bf3e67204c-20220402 bootloader.q1
AIGO Eros Q 98f7623-20220401 bootloader.erosq

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.

  1. Make sure your player is fully powered off.
  2. Connect a USB cable to your player -- but don't plug it into your computer yet.
  3. 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.
  4. 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.

Screenshot of the Rockbox recovery menu

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.

Note: The menu navigation buttons are described on screen at the bottom of the bootloader menu.

The .bin file can be used to restore the bootloader. It's recommended to copy the .bin file off your SD card once the installation is finished, and keep it somewhere safe. When you want to restore the backup, copy it to the root of your SD card and select Restore from the Bootloader menu. The name of the .bin file varies depending on your player, shown in the table below.

Player Backup file name
FiiO M3K fiiom3k-boot.bin
Shanling Q1 shanlingq1-boot.bin
AIGO Eros Q erosqnative-boot.bin

Be careful not to take a backup again after installing, as this will overwrite your first backup!

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

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.

Screenshot of the Zadig window

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.

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, this can be safely ignored.

You should now be able to reboot your player and boot Rockbox.
r7 - 18 May 2022 - 17:56:17 - AidanMacDonald

Copyright © by the contributing authors.