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



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.

Player Version Download link Notes
FiiO M3K b4e7c60c6d-221029 bootloader.m3k  
Shanling Q1 b4e7c60c6d-221029 bootloader.q1  
AIGO Eros Q b4e7c60c6d-221029 bootloader.erosq Supports all model and firmware variants

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. For Eros Q users, note that you must choose the "Native" version.

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. 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.

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.

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.

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

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.

r13 - 28 May 2024 - 02:43:33 - DanaConrad

Copyright © by the contributing authors.