[next] [prev] [prev-tail] [tail] [up]

2.  Installation

2.1 Overview
2.2 Prerequisites
2.3 Installing Rockbox
2.3.1 Automated Installation
2.3.2 Manual Installation
2.3.3 Enabling Speech Support (optional)
2.4 Running Rockbox
2.5 Updating Rockbox
2.6 Uninstalling Rockbox
2.6.1 Automatic Uninstallation
2.6.2 Manual Uninstallation

2.1.  Overview

There are two ways of installing Rockbox: automated and manual. While the manual way is older, more tested and proven to work correctly, the automated installation is based on a nice graphical application that does almost everything for you. It is still important that you have an overview of the installation process to be able to select the correct installation options.

There are three separate components, two of which need to be installed in order to run Rockbox:

The Ipod bootloader.
The Ipod bootloader is the program that tells your player how to load and start the original firmware. It is also responsible for any emergency, recovery, or disk modes on your player. This bootloader is stored in special flash memory in your Ipod and comes factory-installed. It is not necessary to modify this in order to install Rockbox.
The Rockbox bootloader.
The Rockbox bootloader is loaded from disk by the Ipod bootloader. It is responsible for loading the Rockbox firmware and for providing the dual boot function. It directly replaces the Ipod firmware in the player’s boot sequence.
The Rockbox firmware.
Similar to the Ipod firmware, most of the Rockbox code is contained in a “build” that resides on your player’s drive. This makes it easy to update Rockbox. The build consists of a directory called .rockbox which contains all of the Rockbox files, and is located in the root of your player’s drive.

Apart from the required parts there are some addons you might be interested in installing.

Fonts.
Rockbox can load custom fonts. The fonts are distributed as a separate package and thus need to be installed separately. They are not required to run Rockbox itself but a lot of themes require the fonts package to be installed.
Themes.
The view of Rockbox can be customized by themes. Depending on your taste you might want to install additional themes to change the look of Rockbox.

2.2.  Prerequisites

Before installing Rockbox you should make sure you meet the prerequisites. You may need some additional tools for installation. In most cases these will already be available on your computer, but if not, installing some additional software might be necessary.

USB connection.
To transfer Rockbox to your player you need to connect it to your computer. For manual installation/uninstallation, or should autodetection fail during automatic installation, you need to know where to access the player. On Windows this means you need to figure out the drive letter associated with the player. On Linux you need to know the mount point of your player.

Your player should enter disk mode automatically when connected to a computer via USB. If your computer does not recognise your player, you may need to enter the disk mode manually. Disconnect your player from the computer. Hard reset the player by pressing and holding the Menu and Select buttons simultaneously. As soon as the player resets, press and hold the Select and Play buttons simultaneously. Your player should enter disk mode and you can try reconnecting to the computer.

Note: Firewire detection is not supported in Rockbox at the moment. Please use USB only.

For manual installation and customization additional software is required.

ZIP utility.
Rockbox is distributed as a compressed archive using the .zip format. Your computer will normally already have a means of handling such archive files. Windows XP has built-in support for .zip files and presents them to you as directories unless you have installed a third party program that handles compressed files. For other operating systems this may vary. If the .zip file format is not recognised on your computer you can find a program to handle them at http://www.info-zip.org/ or http://sevenzip.sf.net/, both of which can be downloaded and used free of charge.
Text editor.
As you will see in the following chapters, Rockbox is highly configurable. In addition to saving configurations, Rockbox also allows you to create customised configuration files. If you would like to edit custom configuration files on your computer, you will need a text editor like Windows’ “Wordpad”.

Note: In addition to the requirements described above, Rockbox only works on Ipods formatted with the FAT32 filesystem (i.e. Ipods initialized by Itunes for Windows). It does not work with the HFS+ filesystem (i.e. Ipods initialized by Itunes for the Mac). More information and instructions for converting an Ipod to FAT32 can be found on the IpodConversionToFAT32 wiki page on the Rockbox website. Note that after conversion, you can still use a FAT32 Ipod on a Mac.

2.3.  Installing Rockbox

2.3.1.  Automated Installation

To automatically install Rockbox, download the official installer and housekeeping tool Rockbox Utility. It allows you to:

Prebuilt binaries for Windows, Linux and MacOS X are available at the RockboxUtility wiki page.

Warning: When first starting Rockbox Utility run “Autodetect”, found in the configuration dialog (File → Configure). Autodetection can detect most player types. If autodetection fails or is unable to detect the mountpoint, make sure to enter the correct values. The mountpoint indicates the location of the player in your filesystem. On Windows, this is the drive letter the player gets assigned, on other systems this is a path in the filesystem.

Note: Rockbox Utility currently lacks some guiding messages. Please have a look at the manual installation instructions if you are stuck during installation.

2.3.2.  Manual Installation

Choosing a Rockbox version

There are three different types of firmware binaries available from the Rockbox website: Release version, current build and daily build. You need to decide which one you want to install and get the appropriate version for your player.

Release.
The release version is the latest stable release, free of known critical bugs. The current stable release of Rockbox is available at http://www.rockbox.org/download/.
Current Build.
The current build is built at each source code change to the Rockbox SVN repository and represents the current state of Rockbox development. This means that the build could contain bugs but most of the time is safe to use. You can download the current build from http://build.rockbox.org/.
Archived Build.
In addition to the release version and the current build, there is also an archive of daily builds available for download. These are built once a day from the latest source code in the SVN repository. You can download archived builds from http://www.rockbox.org/daily.shtml.

Warning: Because current builds and daily builds are development versions which change frequently, they may behave differently than described in this manual, or they may introduce new (and maybe annoying) bugs. If you do not want to get undefined behaviour from your player, you should stick to the current stable release if there is one for your player. If you want to help with project development, you can try development builds and help by reporting bugs. Just be aware that these are development builds that are highly functional but not perfect!

Installing the firmware

  1. Download your chosen version of Rockbox from the links in the previous section.
  2. Connect your player to the computer via USB or Firewire as described in the manual that came with your player.
  3. Take the .zip file that you downloaded and use the “Extract all” command of your unzip program to extract the files onto your player.

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

Note: If the contents of the .zip file are extracted correctly, you will have a directory called .rockbox, which contains all the files needed by Rockbox, in the main directory of your player’s drive. If you receive a “-1” error when you start Rockbox, you have not extracted the contents of the .zip file to the proper location.

Installing the fonts package

Rockbox has a fonts package that is available at http://www.rockbox.org/daily.shtml or from the extras link in the menu on the Rockbox website. The fonts package rarely changes and is therefore not included in the firmware .zip file. When installing Rockbox for the first time, you should install the fonts package.

  1. Download the fonts package from the link above.
  2. Take the file that you downloaded above, and use the “Extract all” command of your unzip program to extract the files in the .zip file onto your player. As with the firmware installation, the entire contents of the fonts .zip 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 fonts! The .zip already contains the correct internal structure.

Installing the bootloader

In order to make your player load and execute the Rockbox firmware you have just installed, you will need to install the Rockbox bootloader. Unless bugs are found in the bootloader code, or significant new feature are added, you will only have to perform this step once.

Bootloader installation from Windows

  1. Make sure you are logged into your computer as Administrator, or a user with Administrator privileges and connect your player. If you have configured iTunes to open automatically when your player is attached (the default behaviour), then wait for it to open and then quit it. You also need to ensure the “Enable use as disk” option is enabled for your player in iTunes.
  2. Download ipodpatcher.exe from http://download.rockbox.org/bootloader/ipod/ipodpatcher/win32/ipodpatcher.exe and run it.
  3. If all has gone well, you should see some information displayed about your player and a message asking you if you wish to install the Rockbox bootloader. Press i followed by ENTER, and ipodpatcher will now install the bootloader. After a short time you should see the message “[INFO] Bootloader installed successfully.” Press ENTER again to exit ipodpatcher.

  4. Note: If ipodpatcher fails to install the bootloader for you, please be certain that you do indeed have a supported iPod model. If you do, run ipodpatcher once more and try again. If you don’t, then do not attempt to install again.

  5. Make sure that you have correctly extracted a build of Rockbox so that you have a /.rockbox, which contains all the files needed by Rockbox in the root of your player’s drive and that you have also installed the fonts package – see section 2.3.2 for more information.
  6. Disconnect your player in the usual way. The bootloader is now installed.

Bootloader installation from Mac OS X

  1. Attach your player to your Mac and wait for its icon to appear in Finder. If you have configured iTunes to open automatically when your player is attached (the default behaviour), then wait for it to open and then quit it. You also need to ensure the “Enable use as disk” option is enabled for your player in iTunes.
  2. Download and open ipodpatcher.dmg from http://download.rockbox.org/bootloader/ipod/ipodpatcher/macosx/ipodpatcher.dmg and then double-click on the ipodpatcher icon inside. You can also drag the ipodpatcher icon to a location on your hard drive and launch it from the Terminal.
  3. If all has gone well, you should see some information displayed about your player and a message asking you if you wish to install the Rockbox bootloader. Press i followed by ENTER, and ipodpatcher will now install the bootloader. After a short time you should see the message “[INFO] Bootloader installed successfully.” Press ENTER again to exit ipodpatcher and then quit the Terminal application.

  4. Note: If ipodpatcher fails to install the bootloader for you, please be certain that you do indeed have a supported iPod model. If you do, run ipodpatcher once more and try again. If you don’t, then do not attempt to install again.

  5. Your player will now automatically reconnect itself to your Mac. Wait for it to connect, and then eject and unplug it in the normal way.

    Note: You should unplug your ipod immediately after ejecting it to prevent Rockbox immediately rebooting your player into disk mode when it detects that your player is attached to a computer.

  6. Make sure that you have correctly extracted a build of Rockbox so that you have a /.rockbox, which contains all the files needed by Rockbox in the root of your player’s drive and that you have also installed the fonts package – see section 2.3.2 for more information.

Bootloader installation from Linux

  1. Download ipodpatcher from http://download.rockbox.org/bootloader/ipod/ipodpatcher/linux32x86/ipodpatcher (32-bit x86 binary) or http://download.rockbox.org/bootloader/ipod/ipodpatcher/linux64amd64/ipodpatcher (64-bit amd64 binary). You can save this anywhere you wish, but the next steps will assume you have saved it in your home directory.
  2. Attach your player to your computer.
  3. Open up a terminal window and type the following commands:

      cd $HOME
      chmod +x ipodpatcher
      ./ipodpatcher

    Warning: You may need to be the root user in order for ipodpatcher to have sufficient permission to perform raw disk access to your player.

  4. If all has gone well, you should see some information displayed about your player and a message asking you if you wish to install the Rockbox bootloader. Press i followed by ENTER, and ipodpatcher will now install the bootloader. After a short time you should see the message “[INFO] Bootloader installed successfully.” Press ENTER again to exit ipodpatcher.
  5. Make sure that you have correctly extracted a build of Rockbox so that you have a /.rockbox, which contains all the files needed by Rockbox in the root of your player’s drive and that you have also installed the fonts package – see section 2.3.2 for more information.
  6. Disconnect your player in the usual way. The bootloader is now installed.

2.3.3.  Enabling Speech Support (optional)

If you wish to use speech support you will also need a voice file, English ones are available from http://www.rockbox.org/daily.shtml. Download the “voice” package for your player and unzip it directly to the root of your player. You should now find an english.voice in the /.rockbox/langs directory on your player. Voice menus are enabled by default and will come into effect after a reboot. See section 8.8 for details on voice settings.

2.4.  Running Rockbox

Remove your player from the computer’s USB port. Hard resetting the Ipod by holding Menu+Play for a couple of seconds until the player resets. Now Rockbox should load. When you see the Rockbox splash screen, Rockbox is loaded and ready for use.

Note: If you have loaded music onto your player using Itunes, you will not be able to see your music properly in the File Browser. This is because Itunes changes your files’ names and hides them in directories in the Ipod_Control directory. Files placed on your player using Itunes can be viewed by initializing and using Rockbox’s database. See section 4.2 for more information.

2.5.  Updating Rockbox

Updating Rockbox is easy even if you do not use the Rockbox Utility. Download a Rockbox build. (The latest release of the Rockbox software will always be available from http://www.rockbox.org/download/). Unzip the build to the root directory of your player like you did in the installation stage. If your unzip program asks you whether to overwrite files, choose the “Yes to all” option. The new build will be installed over your current build.

Note: If you use Rockbox Utility be aware that it cannot detect manually installed components.

2.6.  Uninstalling Rockbox

Note: The Rockbox bootloader allows you to choose between Rockbox and the original firmware. (See section 3.1.3 for more information.)

2.6.1.  Automatic Uninstallation

You can uninstall Rockbox automatically by using Rockbox Utility. If you installed Rockbox manually you can still use Rockbox Utility for uninstallation but will not be able to do this selectively.

2.6.2.  Manual Uninstallation

To uninstall Rockbox and go back to using just the original Ipod software, connect the player to your computer and follow the instructions to install the bootloader but, when prompted by ipodpatcher, enter u for uninstall instead of i for install.

If you wish to clean up your disk, you may also wish to delete the .rockbox directory and its contents. Turn the Ipod off. Turn the player back on and the original Ipod software will load.

[next] [prev] [prev-tail] [front] [up]