First, a thank you

The Rockbox port to the iPod has only been made possible by the hard work of the members of the ipodlinux project who have performed the difficult and time-consuming task of understanding a hardware platform with almost no available documentation. If it wasn't for the source code and documentation released by that project, Rockbox on the iPod would never have happened.

Introduction

Rockbox on the iPod is in a very early stage of development - so expect a few rough edges. It is functional on the iPod Color/Photo (those are the regular-sized iPods with color screens that are NOT capable of video playback), the "4G" grayscale iPod (the one with the clickwheel), the iPod Nano 1st gen (not the new ones with metal bodies), the iPod Video (5G) and the iPod Mini (1G and 2G).

IMPORTANT NOTE Rockbox only works with Windows format iPods (FAT32). In order to use a Mac format (HFS) iPod, you will need to convert it to FAT32. This can be done by using the iPod Updater on a Windows computer. After this conversion, you can continue to use your iPod on your Mac. Or if you dont have acces to a Windows computer, follow the "Convert an iPod from HFS to FAT32" steps.

HELP NEEDED If you have successfully performed the conversion of an iPod from HFS to FAT32 without using a Windows computer, please share your tips here.

Just managed it on my Nano 1st gen from OSX, and it was horrible ( but worth it ). My tips : -- AndrewWatson - 27 Jun 2006

• Before starting, make sure iTunes is not setup to launch on iPod insertion
• Follow steps 1a and 1b before going down to the reformatting stuff
• Use diskutil unmount /dev/diskNsN to unmount the partition where that is called for, rather than the finder eject or diskutil
• If your iPod locks up with a spinning activity icon ( in the top left corner ) when you try to mount it in disk mode, it may well be doing an fsck_msdos which takes forever. I waited 10 minutes before giving up, killing the fsck, and reformating the partiion using newfs_msdos -F32 -v iPod /dev/rdiskNsN

Rockbox will NOT read the iTunes Database. It is designed as a filestree based music player. You can have it display hidden files, and browse those files copied over by iTunes, but iTunes does rename the files to non-informative strings, so this may be cumbersome. Rockbox will not affect the database in any way, and these files will still be usable as normal via the retail OS.

There no easy installer for Rockbox yet (can you help develop one?) - you currently have to carefully follow the instructions on this page and perform each step manually using command-line utilities. You should be aware that if you use the Apple updater to upgrade your Apple firmware, you will need to repeat this process in order for Rockbox to boot again.

For questions about running Rockbox on your iPod, see the IpodFAQ.

Uninstallation and Upgrade instructions

To uninstall the Rockbox bootloader, you can type the following command to restore your iPod to its original state:

./diskdump -w /dev/diskN bootpartition.bin

where "N" is the disk number of your iPod (found using the instructions in Step 1b below) and "bootpartition.bin" is a file containing the original contents of your iPod's firmware/boot partition. This file is created in Step 1c below.

Installation instructions

Note: Instead of installing the rockbox bootloader as explained below, you might install the iPodLinux loader which offers a menu so you can choose between Apple and Rockbox software. And its installation instructions may be easier to follow than these following here, as they are much briefer.

Step 1 - Install the bootloader

In order to make your iPod load and execute the Rockbox firmware, you will need to install the Rockbox bootloader. Unless bugs are found, or significant new feature are added, you will only have to perform this step once. This is the hardest part of installing Rockbox and will hopefully be replaced by a GUI installation program in the future.

In the following instructions, I will assume that you have downloaded all the files to a folder on your Desktop called called "rockbox" - but you can use any folder you wish.

a) Download the required files

Create a new folder on your desktop called "rockbox" and download the following files into it:

• diskdump
• For iPod Color/Photo users - bootloader-color.bin, for iPod 4G (Grayscale) users - bootloader-4g.bin, for iPod Nano 1st gen users - bootloader-nano.bin, for iPod Video/5G users - bootloader-video.bin, for iPod Mini 1G users - bootloader-mini1g.bin, for iPod Mini 2G users - bootloader-mini2g.bin and for iPod 3G users - bootloader-3g.bin
• ipod_fw

Example: (Folder containing downloaded items)

The two executable programs are licensed under the GNU GPL - source code for diskdump is available in diskdump-0.1.zip and source code for ipod_fw is available in the Rockbox CVS.

You will perform the following steps from the Mac OS X Terminal. Start a Terminal and type cd Desktop/rockbox to navigate into the rockbox folder you created in the previous step.

Before you can continue, you need to ensure that Mac OS knows that the ipod_fw and diskdump files you downloaded are executable programs. To do this, type the following command:

chmod +x ipod_fw diskdump

b) Find your iPod

Now attach your iPod to your Mac (using either USB or Firewire) and wait for iTunes to open. When iTunes opens, close it down.

In your Terminal window, type the command mount and press enter. This will list all the disks (and other devices) that are "mounted" on your computer. The last drive in the list should be your iPod. For example:

/dev/disk1s2 on /Volumes/DAVE_S IPOD 1 (local, nodev, nosuid)

In order to install the ipod bootloader, you need to "unmount" this disk using the following command:

diskutil unmount /dev/disk1s2

Replacing "/dev/disk1s2" with the device name Mac OS has assigned to your ipod. This may take a few seconds, after which Mac OS will say "Volume /dev/disk1s2 unmounted".

"/dev/disk1s2" refers to the second partition on /dev/disk1 - remember the disk number for the next step.

c) Read the existing firmware partition from your iPod

Type the following command, replacing /dev/disk1 with the disk device (NOT including the "s2" at the end) assigned to your ipod that you found in the previous step:

./diskdump -r /dev/disk1 bootpartition.bin

This should create a file (approximately 40MB for the iPod 4G and Color/Photo and 80MB for the Nano 1st gen) containing a copy of the "firmware partition" on your iPod.

IMPORTANT NOTE: You should keep a safe backup of this bootpartition.bin file for use if you ever wish to either upgrade the Rockbox bootloader or uninstall Rockbox from your iPod.

d) Extract the Apple firmware from your firmware partition image.

Type the following command to extract Apple's firmware from the bootpartition.bin image file:

./ipod_fw -o apple_os.bin -e 0 bootpartition.bin

This should create a file approximately 5MB in size called apple_os.bin containing the Apple firmware for your iPod.

d2) (iPod Video/5G and Nano 1G users only) Extract the extra firmware from your firmware partition image.

The iPod Video/5G and Nano 1G have extra firmware. This needs to be extracted as follows:

./ipod_fw -o apple_sw_5g_rcsc.bin -e 1 bootpartition.bin

NOTE: You must give it the exact name "apple_sw_5g_rcsc.bin"

e) Create the new Rockbox-enabled image file containing the Rockbox Bootloader

iPod 4G (grayscale) users should type the following command to create the file rockboot.bin:

./ipod_fw -g 4g -o rockboot.bin -i apple_os.bin bootloader-4g.bin

iPod Color/Photo users should type the following command to create the file rockboot.bin:

./ipod_fw -g color -o rockboot.bin -i apple_os.bin bootloader-color.bin

iPod Nano 1st gen users should type the following:

./ipod_fw -g video -o rockboot.bin -i apple_os.bin bootloader-nano.bin

iPod Video users should type the following:

./ipod_fw -g video -o rockboot.bin -i apple_os.bin bootloader-video.bin

iPod Mini 1G users should type the following:

./ipod_fw -g mini -o rockboot.bin -i apple_os.bin bootloader-mini1g.bin

and iPod Mini 2G users should type the following:

./ipod_fw -g mini -o rockboot.bin -i apple_os.bin bootloader-mini2g.bin

f) Install the bootloader!

Type the following to write your new Rockbox-enabled firmware to your iPod, replacing /dev/disk1 by the disk device assigned to your iPod.

./diskdump -w /dev/disk1 rockboot.bin

This command will complete quite quickly, but if you look at your iPod, you will see that the disk icon is still spinning in the corner. DO NOT disconnect your ipod yet.

After the disk icon has finished spinning (this may take one to two minutes), your iPod will be mounted on your Mac again. Now eject it in the normal way (e.g. from Finder).

g) Testing

You can now disconnect your ipod from your PC in the normal way. This should cause your iPod to reboot.

You should now see a light blue screen with some tiny writing - this is the Rockbox bootloader. Because you haven't yet installed Rockbox itself, the bootloader will fail to start Rockbox and should then default to start the original Apple firmware. If this happens, then all has gone well.

Step 2 - Install Rockbox

a) Download rockbox.zip for your iPod

Rockbox is in constant development - new versions of Rockbox are automatically compiled every time a source file is changed in the Rockbox CVS source code repository.

Download the current build (updated on every source change). You MUST ensure that you download the correct version of Rockbox for your iPod.

b) Unzip rockbox.zip to your iPod

The rockbox.zip you have downloaded contains the Rockbox firmware itself (a file called rockbox.ipod) plus a support directory containing configuration files, plugins, audio codecs, fonts and themes. This directory is called .rockbox (note the period at the start of the name) and it is hidden, meaning you won't see it in when looking at the extracted folder from Mac OS Finder.

Next, extract the archive, e.g. by double clicking on it in the Finder. You will get a new folder named "rockbox" (or "rockbox-ipodvideo-20060529" or something similar). This folder will contain both the rockbox.ipod file and the invisible .rockbox folder.

Now you need to copy these folder contents to the iPod disk's top-level (root) folder. Since you can't copy invisible items using the Finder (unless you've tweaked hidden settings to make invisible items appear), you will need to use the Terminal to copy the item to the iPod:

Open Terminal.app (in /Applications/Utilities) and type "cp -R " (note the blank at the end), then drag the rockbox folder's icon into the Terminal window so that its path name appears behind what you just typed. Then drag the iPod icon from the desktop into the Terminal window as well. Now the line should look similar to this:

YourMac:~ yourname$ cp -R /Users/yourname/Desktop/rockbox/ /Volumes/IPOD/

Press Return in the Terminal window and wait a few seconds. After that, a new line like this should appear in the Terminal window, which shows that the copy operation has finished:

YourMac:~ yourname$

Verify that you now see a "rockbox.ipod" file on your iPod disk.

That concludes the installation of the basic rockbox files.

If you later want to install a new version, simply perform these operations again. No need to erase the old installation, usually.

Step 3 - Enjoy Rockbox

Now eject your iPod and disconnect it from your Mac. If you had just installed the bootloader, the iPod will reboot automatically. Otherwise, reset the iPod by pressing the appropriate keys.

You should be greeted by the Rockbox file browser. To play music, simply navigate to the file and select it. Pressing MENU will access the Rockbox menu.

For more information, see the IpodFAQ and IpodStatus pages.

Convert an iPod from HFS to FAT32 (Optional method, but FAT32 is required)

If you have a Mac formatted iPod, and don't have access to a Windows computer, perform these steps to convert your iPod to FAT32:

a) Download the required files, find your iPod and unmount it

Before you proceed you must download the required files, as described in Step 1 a) and 1 b). In addition you need to find the device name Mac OS X has assigned your iPod and unmount the disk. To unmount your disk, open Disk Utility (located in Applications/Utilities). Then select your iPod and click 'Unmount'.

b) Download the partition table file that match your iPod (dumped from Windows formatted iPod's).

To recreate the partition table of a Windows formatted iPod you need to download the partition table file that exactly matches your iPod model. You should save this file in the same folder as files you downloaded in step 1 a).

c) Apply the correct partition table

Run the below command to write the partition table to your iPod:

dd if=mbr-xxxx.bin of=/dev/diskN

Replace mbr-xxxx.bin with the name of the MBR file you downloaded in step b).

NOTE you must replace "diskN" with the correct name of the disk device assigned to your iPod - disk1, disk2 etc. Using an incorrect device name in this command may result in the partition table for another hard disk in your system being changed. Which is very bad news.

d) Format the main partition with FAT32 file system

This can be done in 'Disk Utility'. Select the iPod partition disk on the left side, click the Erase tab, select 'MS-DOS File System' and at last click the 'Erase' button. Or use the 'newfs_msdos' application:

newfs_msdos -F32 -v iPod /dev/rdiskNs2

e) Follow to the Installation instructions from Step 1 c)

Follow the Installation instructions from Step 1 c) to the end

Further information about using Rockbox

Some useful tips are available in the IpodTips page. See also the IpodFAQ and IpodStatus pages.

Recovering from a crash

If Rockbox ever crashes and stops responding, then you can always force it to reboot as follows:

• Reboot your iPod by holding the MENU (top) and SELECT (middle) buttons for around 5 seconds.

Your iPod also has an emergency "disk mode" which gives you access to your iPod even if all the software installed on the disk is corrupt:

• Whilst the iPod is rebooting, hold SELECT and PLAY together to enter disk mode.