Introduction: Raspberry Pi 2 Media Center: Kodi on XBian

Author: Timothy Wood
Date: April 2015


This guide walks through the construction and configuration of a home media center from parts to running system. After following these steps, you will have a running Kodi media server on a Raspberry Pi 2 in an Altoids tin case, ready for you to attach a thumb drive or hard drive with your media. These steps detail the method I used in my build with the hardware and software choices I made, but there are other options that you can choose. I included some notes about alternative choices in the steps where alternatives are available. Although the steps in this guide are specific, you should be able to adapt the general method for some of the alternative choices.

I chose to use the following components and software.

  • Raspberry Pi 2 Altoids tin case
  • Xbian 1.0 Release Candidate 2 operating system
  • Remote control input via IR receiver wired to GPIO

When I built my media center, I did most of my work with the Raspberry Pi 2 plugged into a desktop computer monitor and set of speakers. These steps could have been done while plugged into an HDMI capable television.

About This Project

Difficulty: Moderate

Total time: 5 hours (rough guess). 2 to 3 hours if you do not set up a remote control (Step 6).

This project requires prior experience with

  • Dremel to cut metal
  • Linux command line and configuration files (for Step 6 only)

List of steps

Step 1: Gather Parts

Step 2: (Optional) Work around “Xenon death flash” bug

Step 3: Make a case from an Altoids tin

Step 4: Download XBian onto a MicroSD card

Step 5: Install XBian on the Raspberry Pi 2

Step 6: (Optional) Install and configure infrared remote control capability

Step 7: Updates and next steps

The instructions in Step 6 enable the media center to accept commands from any remote control you have or purchase. I bought a remote control at a thrift store. If you have a television that supports HDMI CEC (Consumer Electronics Control), you do not need to perform Step 6. Instead, you can control the media center with your television's remote control without any additional configuration required.


Kodi – A free and open source media server and entertainment center. Formerly XBMC.

LIRC – Linux Infrared Remote Control. A software package that decodes digital infrared signals of most commercial remote controls. Included by default as part of XBian.

XBian – A GNU/Linux based operating system for the Raspberry Pi, Raspberry Pi 2, and other small computing devices that runs the Kodi software.

Step 1: Step 1: Gather Parts

Before beginning this project, be sure you have all the parts and tools needed.


  • Raspberry Pi 2 model B
  • Empty Altoids tin
  • MicroSD card (at least 2 GB)
  • AC to microUSB power adapter for the Raspberry Pi 2(output 5 volts, 1 to 2 amps)
  • Ethernet cable
  • HDMI cable
  • Television with HDMI input or computer monitor with HDMI input and speakers
  • Remote control
  • Three female to female jumper wires, about 20cm long
  • Vishay Semiconductor TSOP 38238 IR receiver


  • Duct tape or electrical tape
  • Mounting putty (optional)
  • Scissors or pocket knife
  • Permanent marker
  • Dremel with metal cutting bit
  • Metal file
  • Computer which supports MicroSD cards and has SSH client software (Step 6 only)
  • USB keyboard USB mouse (optional)
  • Hot glue (optional)


Instead of using the Raspberry Pi 2, you can build a media center using an earlier version of Raspberry Pi. Prior to this project, I completed a similar one using a Raspberry Pi model B rev. 2. The advantage of the Raspberry Pi 2 is that it has a faster processor and more memory, which should make the media center load and respond faster.

In addition to XBian, there are several other operating systems to run Kodi on the Raspberry Pi. See Step 4 for a list of other current software distributions.

Step 2: Step 2: (Optional) Work Around “Xenon Death Flash” Bug

The Raspberry Pi 2 has a peculiar bug which causes it to power down when exposed to intense flashes of light of certain wavelengths, such as those of laser pointers and xenon flash bulbs. Although this will not damage the Pi, a running system could experience data corruption. This only occurs under particular conditions, so if you do not expect to take flash photos of the board with a traditional xenon flash bulb, you do not have to do anything about the bug. The easiest workaround is to cover the affected part, device U16, with opaque tape or glue. For more information, see

Parts and tools

  • Raspberry Pi 2
  • Electrical tape, duct tape, or mounting putty
  • Scissors or pocket knife


  1. Identify device U16 on the Raspberry Pi 2 board. It has a shiny surface, and it is located between the HDMI port and the Raspberry Pi logo.
  2. Cut a small piece of tape and place it over device U16, or cover it completely with a small blob of putty. The tape or putty should completely cover both the top and sides of device U16.

Note that I have not tested my Raspberry Pi with this tape as pictured because I do not expect anyone to take photos with traditional cameras while the media center is running. It may actually take a larger piece of tape to cover the device properly.

Step 3: Step 3: Make a Case From an Altoids Tin


Instead of using an Altoids tin case, you can purchase or 3D print a plastic case, or not use any case at all. Using a case will protect the Raspberry Pi. The Pi must always rest on a surface that is non-conductive to prevent damage from a short-circuit.

Parts and tools

  • Empty Altoids tin
  • Permanent marker
  • Dremel with metal cutting tip
  • Duct tape


  1. Clean the Altoids tin.
  2. Carefully hold the Raspberry Pi 2 board up to the case to see where openings need to be made. Hold the board and the case so the audio, HDMI, and MicroUSB ports will be on the side of the tin with the hinges.
  3. With the permanent marker, mark the areas of the tin to be cut away. The following areas must be removed (identified as if the side with the hinges is away from you).
    1. The whole left side and a thin edge from both the base and the lid, starting just ahead of the middle of the curved corners. This will provide an opening for the left two corners of the board, the Ethernet port, and the USB ports.
    2. A small strip of metal across the lower part of the right side, and a corresponding portion of the base. The opening should begin just before the beginnings of the curved corners of the tin. This will accommodate the right two corners of the board and the microSD card once it is inserted.
    3. A rectangular section from the back side of the tin around the audio port.
    4. A rectangular section from the back side of the tin around the HDMI port.
    5. A small rectangular section from the back side that extends the strip taken from the right side (corners and microSD strip) far enough to provide an opening for the microUSB connector.
  4. Double check that all the marked areas will fit the board in one position by carefully holding it up to the Altoids tin again and inspecting the marked areas.
  5. Using a Dremel, carefully cut out the marked sections of the tin, then remove any metal shavings and file the edges (they will be sharp).
  6. Carefully fit the Raspberry Pi into the case to verify that it fits correctly. Insert the side with the HDMI port into the case first, then gently press the rest of the board into place. Repeat the cutting and filing until the board fits easily but stays secure.
  7. Remove the Raspberry Pi, then wrap the base of the case with duct tape for insulation.

Step 4: Step 4: Download XBian Onto a MicroSD Card

XBian is a lightweight but complete Debian GNU/Linux distribution designed to run Kodi media center software. It is designed to provide lots of utilities and customizations and make “bleeding edge” features available, while still while still running fast. At the time of writing, it is in release candidate stage of development.

OSMC (Open Source Media Center. Successor to the now end-of-life Raspbmc which supports Raspberry Pi 2 hardware. A very simple Linux system with the minimum of software required to run Kodi. Also in release candidate stage at time of writing.) OpenELEC (Open Embedded Linux Entertainment Center. A minimal Linux system with only software required to run Kodi, designed to run fast. Latest stable release supports the Raspberry Pi 2.) Raspbmc (Now end-of-life. A complete Linux distribution designed to run Kodi and provide useful features.)

Parts and tools

  • Computer which supports MicroSD cards
  • MicroSD card


  1. Download the XBian installer from . There is a version for Windows, Mac OSX, and Linux.
  2. Extract the archive and run the installer. On Linux systems, the XBian installer requires the libQt5widgets library to be installed. If you receive the error, “error while loading shared libraries: cannot open shared object file: No such file or directory” the necessary package is not installed on your computer. On Fedora, install in a terminal with sudo yum install qt5-qtbase-gui .
  3. On page one of the installer, select “Raspberry Pi 2.” On page two, select “XBian Stable rpi2” and select your microSD card device.
  4. Click install. Confirm that it is OK to erase the microSD card. The installer will ask to download Xbian. Approve, then wait for the process to finish.
  5. When the process is complete, close the installer by clicking the X in the title bar.

Step 5: Step 5: Install XBian on the Raspberry Pi 2

Parts and tools

  • Raspberry Pi 2
  • MicroSD card with XBian downloaded
  • AC to MicroUSB power adapter
  • Ethernet cable
  • HDMI cable
  • Television with HDMI input or computer monitor with HDMI input and speakers
  • USB keyboard
  • USB mouse (optional)


  1. Plug the Raspberry Pi into a television or computer monitor, and attach the keyboard and mouse. Plug in the Ethernet cable and attach the Raspberry Pi to a working internet connection.
  2. Plug in the AC to MicroUSB power adapter.
  3. XBian will not take long to boot up. Once it does, follow the steps in the XBian Wizard to set it up. Use the keyboard and mouse to interact with the Raspberry Pi.
    1. Click Next. Click Manage network and verify the selected setting is correct.
    2. Click Next. Enter your MPEG-2 or VC-1 codec licenses if you purchased them. Otherwise, move on.
    3. Click Next. There is no need to restore anything from backup. Click Next.
    4. Click Manage update. Choose your preference for installing updates. Close the window and click Next.
    5. On the screen for installing additional packages, just click Next to complete the process.
  4. Enable audio output through the analog audio jack if needed.
    1. From the main menu, select System, then Settings, then System, then Audio output.
    2. Set Audio output device to “HDMI and Analogue”
  5. Turn off the Kodi news ticker at the bottom of the screen if desired.
    1. From the main menu, select System, then Settings, then Appearance, then Skin.
    2. Disable the option, “Show RSS news feeds.”

Step 6: Step 6: (Optional) Install and Configure Infrared Remote Control Capability

This is the most complicated step. In this step, you will attach an IR receiver to the Raspberry Pi and configure LIRC and Kodi to accept commands from a remote control.
If your television supports HDMI CEC (Consumer Electronics Control), you can interact with your media center using your television remote control and skip this entire step. If your television supports HDMI CEC, but you wish to use a separate remote control for this media center anyway, follow these instructions.

Important. The Raspberry Pi 2 GPIO pins are not 5 volt tolerant even though the IR receiver is. Do not use the 5 volt power pins in this step or you will burn out the GPIO pin. Use the 3.3 volt power supply pin to power the IR receiver connected to the Raspberry Pi.

Parts and tools

  • Computer with SSH client
  • Duct tape, electrical tape, or hot glue
  • Remote control
  • Three female to female jumper wires, about 20cm long
  • Vishay Semiconductor TSOP 38238 IR receiver
  • USB keyboard or mouse



  1. Make sure the Raspberry Pi is unplugged from its power supply.
  2. Choose three jumper wires to attach the IR receiver to the Raspberry Pi. I used green for data, black for ground, and red for supply voltage. Use to identify the pins of the IR receiver. Attach the jumper wires to the pins of the receiver.
  3. Optional. Secure the jumper wires together at the base of the IR receiver by wrapping them with tape.
  4. Review to identify pins in the Raspberry Pi 2 GPIO header. Carefully attach Attach the OUT wire (green in my photo) to pin number 12 on the Pi, which is GPIO 18. Attach the GND wire (black in my photo) to pin number 14, which is GND. Attach the supply voltage wire (red in my photo) to pin number 01, which is 3.3v DC power.
  5. Attach the IR receiver to the underside of the lid with tape or glue. I always keep the lid of the case open while the Raspberry Pi is running to allow heat to escape, and I have not tested the Pi in this case with the lid closed. If you wish to run your media server with the lid closed, you can attach the IR receiver to the front of the case and run the wires out of the case past the USB ports.
  6. Attach the display, keyboard or mouse, network cable, and power to the Raspberry Pi and wait for XBian to boot up.


Run the Linux commands for this step (shown in bold) as root. Switch to a root prompt with sudo -i or by prefacing every command with sudo

  1. Navigate to System, System info, Summary and note the IP address.
  2. On your computer, open your SSH client and connect to the IP address. The username is xbian and the password is raspberry
  3. Press Alt+E or Esc to exit the xbian-config menu.
  4. Optional: install vim or nano. apt-get install vim
  5. Retrieve a list of commands that Kodi recognizes from the remote keymap file. cat /usr/local/share/kodi/system/keymaps/remote.xml Copy and paste the contents of the section somewhere you can refer to it later.
  6. Copy the output of the command irrecord --list-namespace and paste it somewhere you can refer to it later.
  7. Make a list of key names from the irrecord namespace that match necessary (not all) Kodi commands. You will train the Raspberry Pi to recognize these buttons on your remote control. The key names I used are as follows, but this may not be a comprehensive list suitable for all Kodi features.
    1. KEY_0 (the numbers 0 through 9 on the remote)
    2. KEY_1
    3. KEY_2
    4. KEY_3
    5. KEY_4
    6. KEY_5
    7. KEY_6
    8. KEY_7
    9. KEY_8
    10. KEY_9
    11. KEY_BACK
    14. KEY_DOWN (down navigation buttons)
    16. KEY_HOME (will return you to Kodi's main menu)
    17. KEY_INFO
    18. KEY_LEFT (left navigation button)
    19. KEY_MENU (returns to the previously used Kodi menu)
    20. KEY_MUTE
    21. KEY_NEXT (next chapter)
    22. KEY_PAUSE
    23. KEY_PLAY (whether you use separate play and pause buttons or a combined playpause depends on your remote)
    25. KEY_POWER
    26. KEY_PREVIOUS (previous chapter)
    27. KEY_REWIND
    28. KEY_RIGHT (right navigation button)
    29. KEY_SELECT (selection button in the center of navigation arrows on most remotes)
    30. KEY_STOP KEY_UP (up navigation button)
  8. Edit the file /etc/modules so the LIRC kernel module is loaded at startup. Add a line to the file that says (without quotes) “lirc_rpi”
  9. Stop the LIRC service. service lirc stop
  10. Create the configuration file for your remote control. irrecord /home/xbian/remote.conf Follow the instructions on the screen. When prompted for a key to program, enter the name of one of the keys you listed in instruction 7 above, then press the corresponding key on your remote as instructed. Repeat until you have programmed all the keys you need, and press Enter to end the program.
  11. Open the file, remote.conf you just created. Find the line “name /home/xbian/remote.conf” and replace “/home/xbian/remote.conf” with a simple, easy to remember name for your remote control.
  12. Create a backup of the system's lircd.conf file. mv /etc/lirc/lircd.conf /etc/lirc/lircd.conf.original Copy the new file, remote.conf, you just made to /etc/lirc as the new lircd.conf file. cp /home/xbian/remote.conf /etc/lirc/lircd.conf
  13. Create a new Kodi LIRCmap file. Save it as /home/xbian/.kodi/userdata/Lircmap.xml (See for more information about the Lircmap file)
    1. Copy and paste the contents of my Lircmap.xml file below or the contents of the format from section 1.1
    2. Delete lines for unused commands
    3. Insert entries copied from the section of remote.conf you copied in instruction 11 above.
    4. Replace the text between the tags with the appropriate KEY_ name
    5. Replace the device name (remote device="") with the name you gave your remote in lircd.conf in instruction 11 above.
  14. Reboot the Pi and test that the remote control is working. I encountered the following two issues with my remote control and found solutions online.
    1. If it takes two button presses on the remote to get Kodi to respond, repeat this procedure, but in instruction 16, force recording in raw mode with irrecord –force /home/xbian/remote.conf Then run the command irrecord -a /home/xbian/remote.conf
    2. If you press a button on the remote and Kodi acts like it was pressed twice, there is a setting that needs to be changed. Edit /etc/lirc/hardware/lirc_rpi.conf and comment out the line that contains LIRCD_ARGS="-u"


The contents of my Lircmap.xml file have been included as an image at the beginning of Step 6 instead of pasted here because attempts to interpret the XML code instead of displaying the text.

Step 7: Step 7: Updates and Next Steps


Update the software installed on the Raspberry Pi 2 to obtain fixes for bugs, patches for security holes, and new features. To update, boot up XBian, then go to System, Settings, XBian, Update. Due to a bug in the version of XBian I downloaded, the entries in the XBian menu did not appear, but after installing updates, this issue was resolved. Update is the fourth from the top. Once you select Update, select Check for updates. The update process for the first time takes about half an hour on a good internet connection.

Add media

You can add music and video files you own to your media center by loading them on your MicroSD card (if it is large enough), placing them on a USB thumb drive, or by placing them on a USB hard drive. For a list of file formats supported by Kodi, see . Playing MPEG-2 (a common format which is also used for DVDs) or VC-1 video (used for some Blu-ray discs) on the Raspberry Pi 2 requires purchased licenses. See for details.

In order to use a USB hard drive with the Raspberry Pi, it must have a separate power source. This is because hard drives require a lot of extra power for their motors, and the Raspberry Pi cannot supply it. Either user a hard drive that includes its own AC power adapter, or use the drive with a powered USB hub. A powered USB hub has an AC power supply of its own in addition to the USB cable that connects it to a computer (in this case, the Raspberry Pi). Plug the USB cable of the external hard drive into the powered USB hub, then plug the USB cable of the powered hub into the Raspberry Pi.

Pi/e Day Contest

Participated in the
Pi/e Day Contest