Preparing and Formatting the SD Card
OpenELEC is designed to keep the OS separate from the user-writeable storage area. This requires two partitions on the SD card:
- Partition #1 mounts as /flash and is 128MB in size, is labelled as “System” and will be FAT32 formatted. It holds the SYSTEM and kernel.img files that the OpenELEC OS is uncompressed from at boot-time (approx. 80-90MB), and essential boot files including the bootloader.
- Partition #2 mounts as /storage and uses the remaining space on the SD card. It will be labelled as “Storage” and is EXT4 formatted. It should be a minimum of 512MB to store XBMC settings, database files, image caches, SSH keys and the swapfile (256MB), but in practice a larger 4GB or 8GB card is a more sensible size.
To prepare a bootable SD card your Linux build-system will need the “parted”, “e2fsprogs” and “dosfstools” packages installed and an SD-card reader device.
The following commands assume /dev/sdb is the SD card device. Partitioning will permanently erase the SD card so please double-check that a) you select the right /dev/device and do not accidentally erase your OS, and b) the card does not contain irreplaceable family pictures!
First we remove all existing partitions and create a new MBR partition scheme:
sudo parted -s /dev/sdb mklabel msdos
Next we create a 128MB FAT32 partition and mark it as bootable:
sudo parted -s /dev/sdb unit cyl mkpart primary fat32 -- 0 16
sudo parted -s /dev/sdb set 1 boot on
Then we add the second partition using all remaining space
sudo parted -s /dev/sdb unit cyl mkpart primary ext2 -- 16 -2
To make sure the above commands worked, we check the partition layout:
sudo parted -s /dev/sdb print all
It should look similar to the output below from an 8GB SD card. Please check the partition sizes and note the bootable flag on partition one:
[sraue@linux]$ sudo parted -s /dev/sdb print all
Model: Generic- Multi-Card (scsi)
Disk /dev/sdb: 7965MB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Number Start End Size Type File system Flags
1 1049kB 132MB 131MB primary boot, lba
2 132MB 7948MB 7816MB primary
Next we format the partitions and set filesystem labels. The first is VFAT (FAT32) formatted and is labelled “System” and the second is EXT4 formatted and labelled “Storage”:
sudo mkfs.vfat -n System /dev/sdb1
sudo mkfs.ext4 -L Storage /dev/sdb2
To ensure the kernel sees our new partition layout we force a reload of the partition table:
Installing OpenELEC to the SD Card
First change to the OpenELEC.tv folder where we built OpenELEC. In the example below this a folder within the root of my home folder:
Next we install the bootloader from the “bcm2835-driver” package. This is located in the project build folder. If you have downloaded pre-built files from elsewere the bootloader files can also be downloaded from here: https://github.com/raspberrypi/firmware/tree/master/boot. The *start.elf file controls how Raspberry Pi’s allocates RAM between OS and Video. The arm128_start.elf file allocates 128MB to each. The commands below assume the “System” partition has mounted as /media/System but some distros mount removable devices to other locations, e.g. /mnt/System.
sudo cp build.OpenELEC-RPi.arm-devel/bcm2835-driver-*/boot/arm128_start.elf /media/System/start.elf
sudo cp build.OpenELEC-RPi.arm-devel/bcm2835-driver-*/boot/bootcode.bin /media/System/
sudo cp build.OpenELEC-RPi.arm-devel/bcm2835-driver-*/boot/loader.bin /media/System/
Next we install kernel and system files from ~/OpenELEC.tv/target to the SD card. The kernel and system files have long names that identify the build kind, date and rNumber. They need to be renamed as we copy them. The system file must be renamed to SYSTEM (all uppercase) and the kernel file must be renamed to kernel.img (all lowercase, and not KERNEL).
sudo cp target/OpenELEC-RPi.arm-devel-20120424035956-r10695.system /media/System/SYSTEM
sudo cp target/OpenELEC-RPi.arm-devel-20120424035956-r10695.kernel /media/System/kernel.img
Next we create a “cmdline.txt” file that contains bootloader parameters:
sudo echo "dwc_otg.lpm_enable=0 root=/dev/ram0 rdinit=/init boot=/dev/mmcblk0p1 disk=/dev/mmcblk0p2 ssh quiet" > /media/System/cmdline.txt
To explain the boot parameters:
- root=/dev/ram0 tells the kernel to use a ramdisk as rootdevice, primary to extract the initramfs which is embedded in the kernel here.
- rdinit=/init tells the kernel the location of the init script to start initramfs.
- boot=/dev/mmcblk0p1 tells OpenELEC the partition which contains the kernel.img and SYSTEM file. It is also possible to use partition labels (boot=LABEL=System) or UUID (boot=UUID=<insert_your_uuid>) or to boot over the network (PXE)
- disk=/dev/mmcblk0p2 tells OpenELEC the “Storage” partition. It can also use partition labels (disk=LABEL=Storage) or UUID (disk=UUID=<insert_your_uuid>) or boot over the network (PXE)
- ssh tells the system to always start the embedded SSH server to enable remote console access. It is optional, but will be useful on a “development” system. The SSH username is “root” and the password is “openelec” i.e.
- debugging enables the optional debugging mode; /var/log/messages will be preserved over a reboot and will contain additional information, and a local console is available on CTRL+ALT+F3 for access to the system (CTRL+ALT+F1 switches back to XBMC).
(Note from dom: "Also, I don't think the "CTRL+ALT+F3" debugging console is available on R-Pi. It may be happening under the openGLES layer, but you can't see it.")
- quiet hides kernel messages from the screen during boot, this should be used unless you need to see kernel output for debugging.
- nosplash prevents the OpenELEC splash screen from loading, shaving a few ms from the boot process. The splash screen can be useful for debugging if you need to see some of the init script actions that are recorded via the splash during boot.
Let’s check that all the files we need are on the SD card. You should have:
[sraue@linux]$ ls -la /media/System
drwx------. 2 sraue sraue 16384 Apr 25 17:09 .
drwxr-xr-x. 4 root root 80 Apr 25 16:58 ..
-rw-r--r--. 1 sraue sraue 83316736 Apr 25 17:00 SYSTEM
-rw-r--r--. 1 sraue sraue 16528 Apr 25 16:59 bootcode.bin
-rw-r--r--. 1 sraue sraue 134 Apr 25 17:13 cmdline.txt
-rw-r--r--. 1 sraue sraue 8126852 Apr 25 17:00 kernel.img
-rw-r--r--. 1 sraue sraue 314691 Apr 25 17:00 loader.bin
-rw-r--r--. 1 sraue sraue 2025988 Apr 25 16:59 start.elf
If all files are present we can unmount the System and Storage partitions:
sudo umount /dev/sdb1
sudo umount /dev/sdb2
Now it’s safe to remove the SD card and insert it in the Raspberry PI’s card slot. The first time you power the system on and boot OpenELEC the boot will be slower as the OS creates SSH keys, the swapfile and the folder structures that XBMC needs. Future boots will be faster!
Reporting Issues and Fixes
The OpenELEC Raspberry Pi image has not been extensively tested so we know there will be bugs. It is important that you provide feedback on things that don’t work to the developers via the project issues tracker on github (link below). If you can provide technical insight into the problem with samples of log data and code snippets it dramatically reduces the research needed to figure out the root cause. If you create patches that address issues please fork the project and submit patches as a pull request, as this reduces the effort required to implement the fix and allows the OpenELEC developers to work faster and smarter.
- OpenELEC wiki: http://wiki.openelec.tv/index.php?title=Compile_from_source
- OpenELEC developer forum: http://openelec.tv/forum/20-development-discussion
- Sources on github: https://github.com/OpenELEC/OpenELEC.tv
- Issues (bug) tracker: https://github.com/OpenELEC/OpenELEC.tv/issues
- IRC chat support: http://openelec.tv/find-help/chat