RPi building and installing OpenELEC

=OpenELEC=

On Monday, 23 April 2012 OpenELEC released the first compilable git version for Raspberry Pi.

OpenELEC is an embedded operating system built specifically to run XBMC, the open source entertainment media hub. The idea behind OpenELEC is to allow people to use their Home Theatre PC (HTPC) like any other device you might have attached to your TV, like a DVD player or Sky box. Instead of having to manage a full operating system, configure it and install the packages required to turn it into a hybrid media center, OpenELEC is designed to be simple to install, manage and use, making it more like running a set-top box than a full-blown computer.


 * OpenELEC Mainsite
 * In February 2012, OpenELEC.tv announced their ARM port for Raspberry Pi
 * OpenELEC forum thread
 * RaspberryPi forum thread

=Build Instructions=

Cross Compiling and Build Systems
The heart of the OpenELEC project is our software build system. It supports a software building technique called cross-compiling; the process of creating executable code that runs on one hardware platform from something other than that platform. Cross compiling is a crucial function for the OpenELEC project for the following reasons:


 * It allows us to build 32bit and 64bit packages and OpenELEC images. It does not matter whether the build-host itself is 32bit or 64bit.
 * It allows us to build OpenELEC for a range of different CPU architectures like x86, ARM and PowerPC. This tutorial will help you cross compile an ARM compatible OpenELEC image from an x86 compatible build-host.
 * There is no dependency on the particular versions of compiler, libc and Linux kernel headers installed on the build-host. We cross-compile our own versions to ensure we always produce consistent and properly built software packages.
 * It allows you to run any Linux distribution as your build system. No matter what your personal preference the resulting OpenELEC image will always be the same.
 * It allows us to use the full power of the build-host. Like most ARM devices the Raspberry Pi does not have super fast CPU’s or lots of memory and it uses low-cost but slow USB and flash-card memory for storage; making it unsuitable for native building of large and complex software. Other Linux distributions targetting Raspberry Pi plan to use emulator tools like QEMU that were designed to test and run small software projects to build a full Operating System and it scares us to think how slow and error prone this will be. Even a highly optimised “minimalist” OS like OpenELEC involves the creation of ~500,000 small files during compilation so it’s simple common sense to cross compile and leverage the significantly better resources of a fast local build-host.

How to get the OpenELEC sources?
To build OpenELEC you will need a Linux system like Fedora, Ubuntu, ARCH Linux or SuSE Linux to use as your build-system. To “check out” OpenELEC's sources you must have the git software package installed. OpenELEC is hosted on github so the command to run is: git clone git://github.com/OpenELEC/OpenELEC.tv.git

After doing this you will have an "OpenELEC.tv" folder. Change to this folder with: cd OpenELEC.tv

OpenELEC is project based and each pre-built OpenELEC image has its own project folder. If you navigate to "projects/RPi" you will find the "options" file which defines the core packages and drivers used in the RPi project and the Linux kernel configuration. Another folder to look at is the "packages/" folder-tree which contains the build-scripts, patches, configs and meta (info) file for each software package included within OpenELEC.

Building OpenELEC
To create an OpenELEC image for Raspberry Pi we need to tell the build-system the project and architecture to build for. The Raspberry Pi project uses the "arm" architecture so the “make” command to start the build process with is: PROJECT=RPi ARCH=arm make

That’s all that’s needed! ..but make sure you type the command EXACTLY as shown here as the make command is case-sensitive.

The first thing the build-system does is check for the essential software packages it needs to function. If any are missing it “should” automatically download and install them for you. It may not work automatically on every Linux distro, but if it cannot install them automatically it will print a list of missing package-names on screen so you can install them manually.

For example on Ubuntu you can manually install the needed software with sudo apt-get install g++ nasm flex bison gawk gperf autoconf automake m4 cvs libtool byacc texinfo gettext zlib1g-dev libncurses5-dev git-core build-essential xsltproc libexpat1-dev

on Ubuntu 12.04 you need to install additionally sudo apt-get install autopoint

to configure Perl in Ubuntu sudo perl -e shell -MCPAN install XML::Parser exit

The speed of the build process depends on the hardware you’re running. On “current” hardware with multi-core CPUs and several GB of RAM it can be as quick as 2.5 hours. If you are using older hardware it could run to 10-12 hours. The first time you build will always be slower as the build-system needs to download and cache the sources for each package we use. Future builds will run faster as the sources have been cached and only a small number of new or changed packages will need to be fetched.

=Install instructions=

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: sudo partprobe

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: cd ~/OpenELEC.tv

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:

ssh root@192.168.2.1 (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.")
 * 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=) 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=) 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).
 * 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. This 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 total 91626 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. 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.

=Useful links:=
 * 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