Friday, June 17, 2011

Crystalbuntu Instalation Guide - Part 2 - Preparing The Thumb-drive


NOTE! This site has MOVED!


Please visit www.quixventure.com instead! the info here is getting old and may no longer be accurate!!


WE HAVE MOVED! Ozymandyaz Tek is now QuixVenture.com



Part 2 - Preparing the Crystalbuntu USB Thumb-drive

The process to install Linux on an Apple TV is actually quite simple, but things get a bit more complicated when you also want to remove the hard drive from the Apple TV. This guide will include everything you need to do to get up and running with no hard drive. This guide will also include a number of optional configuration changes that may be very useful to those who need them such as adding a static IP address, DNS address and later some advanced XBMC settings.

Also, since I personally need to use component video, this guide will include the steps necessary to use either HDMI or Component video.

Software you will need:


Step 1 - Give Credit Where Credit is Due

Sam Nazarko has, on his own built and maintained the tool that makes this all possible. Go to stmlabs.com and send him a donation! Seriously... Do it now =)

What Sam’s tool does is really quite amazing. You can read a lot more about it on his blog, but the short version is this... First, you download a small tool that will automatically format and partition your thumb drive (formerly a daunting task for the Linux n00b.) Then the tool will image the USB drive with a custom Linux installation already pre-configured with XBMC and all the drivers needed to run the AppleTV with a CrystalHD card. But that's only half the story since Sam also maintains a server that allows the AppleTV to “phone home” (but only if you want it too!) at each boot and check for any updates to either the the Linux image, OS configuration, XBMC or even the CrystalHD driver. Updates have been steady so far and each one has brought improved performance and features.

Donation made? Good... Next, Go to XBMC.org and make a donation to the team there as well. These guys work very hard to make what amounts to the very best available media player and they ask nothing in return. XBMC is maintained as well as or better then most retail media players, but XBMC is totally free. The team maintains a superb support forum and the developers themselves are very active in both troubleshooting and building new improvements and features. They deserve a lot of credit and a little cash too!

So, in re-cap:
  1. Donate to Sam
  2. Donate to Team XBMC
  3. Move on =)
Step 2 - Install Sam’s CrystalHD for AppleTV Tool

Video How To (Getting and using Sam's tool:)





Got to Sam’s site (http://www.stmlabs.com/projects/crystalhd-for-appletv/) and get the tool from the bottom of the page. Unzip the file and run the executable program “partitioner.exe.”

The tool will give you two options, USB Drive or Hard Drive. For this install we want to use the default USB option. The hard drive option will cause the USB drive to install the image onto the internal drive of the AppleTV... Since we are going to remove the hard drive, we will use the USB option and have the tool build us a self contained bootable thumb-drive.

In the center of the application select your USB drive from the list. If you do not see it, it must not be installed or formatted properly. Windows will need to see the drive before Sam’s tool can use it. Find your thumb-drive, check the box, make sure you are connected to the Internet and click GO.



The tool will now format the USB drive, download a 550MB image from Sam’s site and write the image to the drive. This will take some time... While you wait... Go rip apart the Apple TV as described in Part 3!

Step 3 - Use Knoppix Live CD/USB to Edit Files on the Thumb-Drive

At this point you should already have a fully functional and bootable AppleTV USB Key and at you can just plug it in and boot the AppleTV so long as you have not yet removed the hard drive. However the point of this guide is to remove the drive... We will need to edit a couple files in the thumb-drive since the device name will have changed.

Video How To (Making the Knoppix Thumb Drive)



Some background on why all this is necessary

When a hard drive is installed in the AppleTV it is given the device name /dev/sda (with partitions defined as /dev/sda1, /dev/sda2, etc...) and an attached USB drive is named /dev/sdb. But, with no hard drive installed, the USB drive takes the /dev/sda name. Since Sam's tool is designed to boot from the USB drive and not interfere with what is on  the hard disk, a number of configuration files explicitly call the full path "/dev/sdb#" and as a result we will need to change those to /dev/sda#."

The AppleTV hardware requires that there be a number of separate partitions on its boot device and it must be partitioned in the GPT format. Unfortunately only certain tools can read that format and make the data available to us without first booting into the Apple TV.

To access the files locked inside the thumb-drive we will use the Knoppix Live image from (yet another...)  USB thumb-drive. I use YUMI to create the drive since I am lazy and this small app does all the work! The GParted live CD (or USB) will work also, but Knoppix will allow you to edit the files more easily using either nano or Leafpad. Also, since Knoppix is a more robust distro you can use the pre-loaded web browser to cut and past the commands directly from this guide (assuming Knoppix can find your network hardware.) Both live images will allow us to boot a computer into a Linux environment that can then mount each of the partitions on the USB drive so we can edit the necessary files. In addition, since we will have access to the root file system, we can set an IP address and modify the xorg.conf to enable component video.

Video How To (Using Knoppix to edit files:)
This video will cover all the steps listed below involving the use of Linux to modify files on the thumb-drive. The whole process can be completed in less then ten minutes.





3.1 Boot to Knoppix

Build the Knoppix bootable USB thumb-drive using the Universal USB Installer from pendrivelinux.com. Run the app, Select Knoppix, download the Knoppix ISO from the their website (use the check box in the Installer app to automatically find the ISO) and  build the drive. Once you have it, plug the USB drive into a computer and boot to it. Soon after, you should have a desktop running Knoppix.

In this guide I will be using the Knoppix Live image and will be booting from a thumb-drive as opposed to the CD. I will also be editing files in Leafpad since is is easier to use then nano or VI, but you may use any text editor you prefer. Booting from a USB drive will cause my internal hard drive to be mapped as /dev/sda, the bootable Knoppix thumb-drive to be /dev/sdb and finally the AppleTV thumb-drive (when plugged in) to become /dev/sdc. If I were to use a live CD there would be one less device and the AppleTV thumb-drive would be /dev/sdb. This is all confusing I know, and to a windows user it’s down right mind numbing. But don't worry, just try and boot with a USB thumb drive in a computer with only a single hard drive and then all the device names should match my examples! But if you must use a CD, remember that everywhere I use "/dev/sdc" you will likely needs to replace it with "/dev/sdb."

3.2 - Plug in the newly created Apple TV thumb-drive and use GParted to mount the partitions

Plug in the AppleTV thumb-drive after the Knoppix live desktop is visible, then click on the "Terminal" icon in bottom tool bar. This will open a terminal window and allow us to run GParted.



Enter:
Sudo gparted

This will launch GParted in a window. Close the terminal window one it is open since it will display information from GParted while that app is open.

Now, we need to verify what device the AppleTV USB has been mapped to, so making sure your AppleTV USB drive is plugged in, and find “GParted” in the app title menu. Select “Refresh Devices” and then look for the AppleTV thumb-drive in the drop down on the right hand side of the app. Select the AppleTV drive (based on its size) and then check to see what device name it has. The device name is important because we need to know what partitions to mount.

For me, the AppleTV drive is /dev/sdc. To make sure you have selected the correct drive, look for these four partitions on the thumb-drive:
  1. /dev/sdc1 - hfs+
  2. /dev/sdc2 - linux swap
  3. /dev/sdc3 - ext3
  4. /dev/sdc4 - unallocated


We will need to mount both the hfs+ and ext3 partitions and modify files inside them.

In GParted, simply right click on each partition (The fist one called hfs+ and the third one called ext3) and select the menu option "mount to" and the default mount point. This will mount the file system of the partition in the folder "/media" within Knoppix. The full mount path will be /media/sd?# where "?" is the letter of the device and "#" is the number of the partition... So in my case, /dev/sdc1 is mounted to /media/sdc1 and /dev/sdc3 is mounted to /media/sdc3.




3.2.1 - Modify the com.apple.boot.plist file in the hfs+ recovery partition

Open a new terminal window by clicking on the “terminal” icon on the Knoppix desktop. This will open a terminal window. Run the following commands:
Note: This step assumes that the mount point for the two partitions was /media/sdc1 and /media/sdc3. If your device names were different, replace what I have below with your device names.

cd /media/sdc1
sudo leafpad com.apple.boot.plist





Now from within the text editor, use the arrow keys to locate the line of text that reads as follows:

<string>root=/dev/sdb3 ro vesa video=vesafb<string>

Change the /dev/sdb3 to /dev/sda3

<string>root=/dev/sda3 ro vesa video=vesafb<string>





The HFS+ "recovery" partition is used by the AppleTV kind of like a BIOS in a traditional PC. By modifying the com.apple.boot.plist file we are telling the AppleTV to continue its boot process from the third partition on the first drive. Since Crystalbuntu expected there to be a hard drive at /dev/sda it was designed to boot from /dev/sdb and we are changing that for our purposes. Note, no matter what drive name was mapped in Knoppix, the file on the thumb drive must use /dev/sda1.

Finally, save the file from the title menu and close Leafpad.

We are done with the first partition.


3.2.2 Modify the fstab file on the ext3 partition

Next, we need to modify the /etc/fstab file within the third partition. This is actually the root file system that will be used by Linux on the AppleTV.

To edit the file, run the following commands in the terminal window used before, or open a new one:
Note: This step assumes that the mount point for the two partitions was /media/sdc1 and /media/sdc3. If your device names were different, replace what I have below with your device names.

cd  /media/sdc3
sudo leafpad etc/fstab

In the text editor, locate any instance of the text /dev/sdb# (such as /dev/sdb3 or /dev/sdb2) and replace the /sdb with /sda, i.e. /dev/sdb2 will become /dev/sda2 and /dev/sdb3 will become /dev/sda3.

Here is what is will look like before you edit:

# /etc/fstab: static file system information.
#
# <file system> <mount point> <type> <options> <dump> <pass>
proc /proc proc defaults 0 0
# /dev/sdb3
/dev/sdb3 / ext3 noatime,errors=remount-ro 0 $
# /dev/sdb2
/dev/sdb2 none swap sw 0 0

here is what it needs to look like (edits are red):


# /etc/fstab: static file system information.
#
# <file system> <mount point> <type> <options> <dump> <pass>
proc /proc proc defaults 0 0
# /dev/sda3
/dev/sda3 / ext3 noatime,errors=remount-ro 0 $
# /dev/sda2
/dev/sda2 none swap sw 0 0

Again, save the file from the title menu and close Leafpad.

3.2.3 Modify the /etc/network/interfaces to set an IP address

In my network I want my AppleTV to have a static IP address, and to do that I need to set an IP in the /etc/network/interfaces file as well as setup DNS in the /etc/resolv.conf file. If you want your AppleTV to use DHCP, ignore this step. Also, DNS is critical! At each boot Crystalbuntu looks for updates, and on the first boot this mandatory to retrieve the XBMC application and CrystalHD drivers. If you set an IP here without also setting up DNS, Crystalbuntu will not work.

Type the following command to open the file in nano:

cd /media/sdc3
sudo leafpad etc/network/interfaces

The file will look like this:

# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto eth0
iface eth0 inet dhcp



And you need to look more like this (edits in bold:)
(NOTE: replace the addresses below with what you want for your network)

# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto eth0
   iface eth0 inet static
   address 192.168.1.101
   netmask 255.255.255.1
   network 192.168.1.0
   broadcast 192.168.1.255
   gateway 192.168.1.1



 Save the file and close the window.

Next, we will need to add DNS information to the /etc/resolv.conf file.

cd /media/sdc3
sudo leafpad etc/resolv.conf

The file will be empty, so add these lines (Edit the first line to match your local router or DNS, the second line is a free DNS server and is optional.)

nameserver 192.168.1.1
nameserver 208.67.220.220


Save the file and close the window.

3.2.4 - Edit the xorg.conf file to enable 720p (or 1080p) over Component video

If you use HDMI, forget about this section... But if you need component video output (or composite), you need to edit the xorg.conf file. Most guides tell you to do this, but not how... Well... It's very easy and this is what I did. Also, I cut and paste right out of this guide, its must easier that way and that is happening in the screenshot.

Run the commands:

cd /media/sdc3
sudo leafpad etc/X11/xorg.conf



This will open the xorg.conf file in Leafpad. Once open, navigate with the mouse or arrow keys to the end of the file and look for the section that starts with:

Section "Screen"

You will need to add the following four lines under the Monitor “monitor0” section.

Option "UseDisplayDevice" "TV"
Option "TVOutFormat" "COMPONENT"
Option "TVStandard" "HD720p"
Option "TVOverScan" "0.80"

And then, under the SubSection "Display" line, add one more line:

Modes "1920x1080" "1280x720" "1024x768" "720x480" "800x600" "640x480"

The result should look like this (edits in bold:)

Section "Screen"
  Identifier "Screen0"
    Device "Device0"
    Monitor "Monitor0"
    Option "UseDisplayDevice" "TV"
    Option "TVOutFormat" "COMPONENT"
    Option "TVStandard" "HD720p"
    Option "TVOverScan" "0.80"
    DefaultDepth 24
    Option "NoLogo" "True"
  SubSection "Display"
    Modes "1920x1080" "1280x720" "1024x768" "720x480" "800x600" "640x480"
    Depth 24
  EndSubSection
EndSection


Hit save in Leafpad and close the window.

NOTE - If you need Composite video, you may try the following... But DO NOT DO THIS unless you NEED Composite.

For composite output, Connect a cable from the green (luma) component output on the AppleTV to the yellow composite input on the TV. The xorg.conf need the following settings for "Section Screen"Section "Screen" instead of those posted above.
Identifier "Screen0"
 Device "Device0"
  Monitor "Monitor0"
  DefaultDepth 24
  Option "DPI" "100x100"
  Option "UseEvents" "1"
  Option "AddARGBVisuals" "1"
  Option "AddARGBGLXVisuals" "1"
  Option "UseDisplayDevice" "TV"
  Option "UseEDID" "FALSE"
  Option "TVOutFormat" "COMPOSITE"
  Option "TVStandard" "NTSC-M"
  Option "TVOverScan" "0.80
  Option "NoLogo" "True"
  Option "Coolbits" "1"
SubSection "Display"
 Depth 24
 Modes "720x480" "640x480"
EndSubSection
EndSection

Remove:

Section "Extensions"
Option "Composite" "Disable"
EndSection



3.3 - Closing out of Knoppix

That's it! We are all done with Knoppix and shutdown the computer now and plug the AppleTV USB key into the AppleTV!

Now - If you have not already done so, rip apart the hardware in Part 3 - Modifying the Apple TV Hardware

NOTE: As of the July 2011 update there is one more step required after the first boot is complete! Sam added support for the hard drive to spin down when the system is idle, but there is a small bug that causes the ATV to not run XBMC if no hard drive is present. Please see the blog post about "Fixing the July Update"
Posted by