Building and Installing OpenELEC for Raspberry Pi

From OpenELEC
Jump to: navigation, search

Ambox content.png

This page is incomplete and may require expansion or cleanup. Please help to improve the article, or discuss the issue on the talk page.


Contents

OpenELEC

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.

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

If you plan on updating your current system, your build command would be: 

 PROJECT=RPi ARCH=arm make release

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 zip

on Ubuntu 12.04 you need to install additionally 

 sudo apt-get install autopoint xfonts-utils

to configure Perl in Ubuntu 

 sudo apt-get install libxml-parser-perl


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.

Update instructions

In target/ folder rename *.kernel and *.system to KERNEL and SYSTEM 

 mv target/OpenELEC-RPi.arm-devel-*.kernel /target/KERNEL
 mv target/OpenELEC-RPi.arm-devel-*.system /target/SYSTEM

Next step is to create checksums: 

 md5sum -t target/SYSTEM > target/SYSTEM.md5
 md5sum -t target/KERNEL > target/KERNEL.md5

Next and final step is to put these files inside the update/ folder on your current rpi system and reboot. For more information on how to update go here.

Updating and rebuilding OpenELEC

To update current branch, in root folder type: 

 git pull

This will retrieve the latest changes to the source. Once you're finished you can start a new build: 

 PROJECT=RPi ARCH=arm make

or 

 PROJECT=RPi ARCH=arm make release

if the build fails you could try and remove compiled data and cache. On a sidenote: You might want to try make clean first as removing cache will delete all downloaded sources thus the build process will be longer. 

 make clean
 rm -rf ~/.ccache-openelec

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!

Also we assume at this stage that the SD card is not mounted. To unmount issue 

 sudo umount /dev/sdb

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, make sure that both partitions are mounted. Your distro will likely auto mount them if you reinsert your card; or issue the following 

 sudo mount /dev/sdb1 /media/System
 sudo mount /dev/sdb2 /media/Storage

Next we install the bootloader from the “bcm2835-bootloader” 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-bootloader-*/arm128_start.elf /media/System/start.elf
 sudo cp build.OpenELEC-RPi.arm-devel/bcm2835-bootloader-*/bootcode.bin /media/System/
 sudo cp build.OpenELEC-RPi.arm-devel/bcm2835-bootloader-*/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-*.system /media/System/SYSTEM
 sudo cp target/OpenELEC-RPi.arm-devel-*.kernel /media/System/kernel.img

Next we create a “cmdline.txt” file that contains bootloader parameters: 

 echo "boot=/dev/mmcblk0p1 disk=/dev/mmcblk0p2 ssh quiet" | sudo tee /media/System/cmdline.txt

To explain the boot parameters:

  • 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. 
 ssh root@192.168.2.1
  • debugging enables the optional debugging mode; /var/log/messages will be preserved over a reboot and will contain additional information
  • 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!

Booting your Raspberry Pi

Connect your RPi to your display, connect the ethernet cable and power it on. You should see the OpenELEC splash screen, and after a few minutes the Confluence menu of XBMC.

If you do not have a USB input device to control XBMC you can enable the XBMC webserver and download the XBMC Remote App for iOS or Android.

To enable the XBMC webserver, ssh (password below) to your RPi and edit ~/.xbmc/userdata/guisettings.xml. Browse through the file and you will see the options to turn on the webserver and set a username and password. Once done, restart the Raspberry Pi and set the remote app to the current IP address of the unit. You are good to go!

The default username password for openELEC is: 

   username: root
   password: openelec

Tuning OpenELEC on your Raspberry Pi

OpenELEC and XBMC offer some options to tune the system if you experience lags or slowdowns in certain situations. Some of these options are non-default because they are not well tested or carry a higher risk of bugs during operation of the system.

Enable dirty region redraw in XBMC

By default XBMC always redraws the whole screen when there are some changes in the UI (e.g. highlighting a button). When redraw of dirty regions is enabled for the XBMC interface (supported since XBMC v11 Eden) it tries to limit the redrawing to only those parts of the UI which really have changed. This can improve the improve the performance of the XBMC interface and remedy some lags. It has no influence on video playback though. (see dirty regions documentation in XBMC wiki)

To enable redraw of dirty regions create the file ~/.xbmc/userdata/advancedsettings.xml and add following settings to the file: 

   <?xml version="1.0" encoding="UTF-8"?>
   <advancedsettings>
     <gui>
       <algorithmdirtyregions>1</algorithmdirtyregions>
       <nofliptimeout>1000</nofliptimeout>
     </gui>
   </advancedsettings>

Please note that in recent dev builds (as at 18th August 2012), the dirty region on some displays can be the only visible segment of the screen, blanking the remainder rather than retaining as intended.

Minimize dynamic UI content and changes

Fetching and animating dynamic content in the XBMC UI required also some CPU power. Disabling those features can also help to minimize lags or slowdowns in the XBMC UI.

  • Turn off RSS feeds in the Skin settings
  • Turn off weather information in the Skin settings
  • Choose a skin with as few dynamic animations as possible. The more stuff "moves" on the screen the more CPU power is required.

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:

Retrieved from "http://wiki.openelec.tv/index.php?title=Building_and_Installing_OpenELEC_for_Raspberry_Pi&oldid=1187"
Personal tools
Namespaces
Variants
Actions
Donate
Navigation
Wiki help
Toolbox