Difference between revisions of "Beginners Guide for 1.x"

From AwkwardTV
Jump to: navigation, search
m (Notes: link cleanup)
Line 294: Line 294:
5. It marks items viewed / unviewed - most handy when you want to know what episode you last watched.
5. It marks items viewed / unviewed - most handy when you want to know what episode you last watched.
6. It does appear to be in active development. See [http://wiki.awkwardtv.org/wiki/Sapphire#Sapphire_Beta_4_Preview here] and [http://appletv.nanopi.net/21/sapphire-beta-4-preview-10b4/ here].
6. It does appear to be in active development. See [[Sapphire#Sapphire_Beta_4_Preview |here]] and [http://appletv.nanopi.net/21/sapphire-beta-4-preview-10b4/ here].
7. Bar its custom icons (which you can replace, if you want), everything it does looks like it belongs on the Apple TV.
7. Bar its custom icons (which you can replace, if you want), everything it does looks like it belongs on the Apple TV.

Revision as of 17:02, 7 November 2007

Beginners Guide

First off let's be clear. Everyone's still learning what they're doing here and whilst I have done this procedure several times without incident, that's with my own setup. You follow this at your own risk and as with anything unauthorized and unsupported, there's a chance you might end up with a permanently broken (also known as "bricked", for obvious reasons) Apple TV. What you do here is entirely at your own risk.

--Simplicity 14:08, 5 November 2007 (CET)

Now that that's out the way, let's get started. There's a wealth of good information on the site, so I thought this might be a good place to bring everything together into a simple "how-to beginners guide", making a few assumptions as to a basic list of things everyone would like their Apple TV to be able to do. So, this page will be dedicated to very simple instructions on how to achieve the following:-

1. Unlock the Apple TV so it can be "seen" on your network.

2. Have the Apple TV use an external drive USB drive to sync and store your iTunes content seamlessly

3. Be able to copy other video formats not supported by iTunes to the Apple TV and play them using the on screen menus

4. Stop the Apple TV updating itself so you lose any of these functions

5. Remove any unwanted menu options left from the above process to make things all tidy.

Further, the goal of this guide is to achieve the above in easy to understand steps, so we must meet the following criteria:-

1. Explain each part of the process, so you know what it is you are doing

2. Never need to open the Apple TV and fiddle with its internals.

3. Keep it simple!

By the end, you should not only have an far more useful Apple TV, but also have an understanding of how it works, so that the rest of this site isn't quite as daunting.

Also, although this guide is quite long, you should not be put off. I have just been as detailed as I can be. It doesn't take more than an hour or so to get through all this - well, assuming it goes well, of course!

What you need before you start

1. An Intel Mac

2. An external USB Hard Drive - I suggest about 500Gb (at time of writing, these seem to be best price/size ratio).

3. A USB Thumb Drive - 128Mb will do.

We'll also need a couple of downloads, but I will point you to these during the process.

I'm not going to cover how to do this on a PowerPC Mac or Windows. If someone would like to write a separate guide to do this, based on this one, that's fine, but I would rather not mix the procedures, as it creates confusion.

If you're not sure if your Mac is running Intel, then just click the Apple logo in the top left corner of your screen and choose the menu option About This Mac. It will tell you what processor you are running. If it begins with "Intel", regardless what it ends with, you're good. If it says anywhere "PowerPC", you cannot use this procedure.

What you will do in this process

(And why you need the above)

You might already know that when on a network, Apple computers, be they laptops or desktops, simply "appear" in your Finder. However, the Apple TV does not. It only appears in iTunes. This is because the Apple TV has most of its network systems turned off, making it pretty hard to modify to do anything other than that which Apple intended - that is, sync iTunes content. There is an "in" for us, however. The Apple TV will read the contents of a USB Drive attached to it when it thinks it is doing a specific type reboot. What we are going to do is use this back door if you will, to install a small menu option on the Apple TV that will allow us to do three things:-

1. Enable SSH. This is a network option which will then allow us to use OS X's Terminal program log into the Apple TV and make some changes. Don't fear this, it's actually pretty simple.

2. Enable AFP. This will make your Apple TV appear on your network like any other Mac, allowing us to modify files, make folders, etc.

3. Intall other menu options, which in turn allows us to achieve a couple of other niceties, too, like playing films in .avi format.

Don't fear the Terminal

As beginner as this guide is, we are going to use something that looks frightening. The Terminal. Don't worry, things will end well. ;-)

Most of the time, you control your Mac using the mouse to drag and drop files, set program options, etc. The Terminal is a way of doing this using text. For every action you can do with a file, like copy from one location to another, there's a way of doing this with the Terminal. The Terminal also provides a few more options that we'll need. You should not fear the Terminal and most of the time, you're going to just be doing copy and paste actions. You can copy the commands from this page and paste them straight into the Terminal. I will explain each command, so that if it needs any changes specific to your system, you can make them easily.

Step One: Preparation's what you need

We need the Apple TV to be in its virgin state. This means, no content and running the software it shipped with. A few months back, Apple updated the Apple TV software to include a few extra functions, like YouTube. Originally, this was not on the Apple TV as an option. This update to the controlling software (known as "Firmware") was version 1.1, known as the YouTube update. We need Apple TV to be running firmware 1.0. So, you need to go to your Apple TV, Settings then Reset Settings then choose Factory Restore. Yes, you are going to wipe your Apple TV clean, but unless you've been hacking previously, there's no need to worry, because all your content is in iTunes and will be synced back again when we're done.

So, your Apple TV will reboot and restore itself to it's virgin state with firmware 1.0. Go through the process of setting up your network and registering it with iTunes again, just like when you bought it, but turn off syncing of any content. In iTunes, select the Apple TV and go through Music, Pictures, Video, etc and select the option to not sync any content under each. Then press Apply. We'll turn this all back on later.

Important Note

I do not know if Apple are now shipping Apple TVs with 1.1 firmware out the box. If you follow the Factory Restore process and still see the YouTube option, then you can't restore your Apple TV to 1.0 firmware using the above process. Perhaps someone else can help with a guide on how to do this.

If you see the YouTube option after factory restore, stop here. The rest isn't going to work.

Step Two: Making the USB Stick

Please remember: all this must be done on an Intel Mac and your Apple TV must be using Firmware 1.0. If you can see the 'YouTube' option, it's not. Turn back now!


The USB Stick we're going to use is commonly referred to a Patchstick. Fortunately for us, the hard work here has been done, so there's very little we need to do to complete what would otherwise be a pretty complicated step. What you're about to do:-

1. Download 2 files. One is the instructions and semi-automated program for making a Patchstick. The other is from Apple and is firmware 1.1 for the Apple TV. We don't need the whole thing, but the Patchstick will need a couple of files from it. This is a bit of a Catch 22 situation - we need files off the Apple TV, but can't get to the Apple TV without the files off it, so we're going to have to use the firmware from Apple.

2. Use the Terminal to enter one line that will run a series of commands

3. These commands will gather files you downloaded and files off your Intel Mac (see note below)

4. They will place them on the USB Stick in such a way that it will do what we need it to when plugged into the Apple TV.


Step 3 is why you must use an Intel Mac. The Apple TV runs on an Intel Processor. If you try and use files from an older PowerPC Mac, you'll 'brick' your Apple TV. If you're not sure if your Mac is running Intel, then just click the Apple logo in the top left corner of your screen and choose the menu option About This Mac. It will tell you what processor you are running. If it begins with "Intel", regardless what it ends with, you're good. If it says anywhere "PowerPC", you cannot use this procedure.

Making the Patchstick

So, let's go.

Download the 1.1 firmware from Apple, using this link. The Patchstick needs some files off the Apple TV, but, of course, since we cannot get into the Apple TV (yet!), we can't get the files. So, we're using this download from Apple. This download is a complete disk image which is used to update your Apple TV from 1.0 to 1.1 firmware. Whilst it contains several changes from the original firmware on the Apple TV, it still has one or two files we need in lieu of being able to get them off the Apple TV itself.

When the download is finished, open the file and you will find it creates a new drive for you called OSBoot. That's all we need to do with this.

Download this file Patchstick.zip. When it has finished, double click on it, and you will see a new folder on your desktop (or your downloads stack, if you're running Leopard). In here, we have the files that are going to go onto your Patchstick.

Round about now is the perfect time to plug in that USB Stick into your Mac. You will find it useful to make a note of the name of the USB Drive and if it is something that is very similar to another drive, rename it. I'm going to assume you rename the USB drive "Patchstick". You can rename the drive by selecting it in the Finder, CTRL-clicking on it and selecting the "Rename" option.

Now, open a Finder window, go to Applications and find the Utilities directory. Locate the Terminal utility and double click to run it. What we're about to do is run a file from the Patchstick download called a script. This is nothing more than a series of commands entered into the Terminal that perform various tasks. We also need to make sure that when you ruin the script you do so with the right privileges. You will no doubt have noticed that sometimes when performing tasks, like changing certain preferences, Mac OS X will ask for your password. The Terminal is no different in this respect and by prefixing any command you run with the word "sudo", you will have the Terminal ask for your password and run with administrator privileges.

You have the Terminal application open on screen. Open the Finder and locate where your Patchstick downloaded to. In Tiger, it will probably be on the desktop, so just double click on the folder on the desktop. In Leopard, it's probably in your user folder, under "Downloads". Regardless, locate the folder, open it and look for the file named createPatchstick. Click it once and drag it into the Terminal window and let go. You will see something a bit like this:-


This is how mine looks. Your username will change from "Peter" (probably!) and it might say Desktop rather than Downloads, depending on which version of OS X you are using, but nonetheless, the last part, "/createPatchstick" will be the same. This is all that matters for now.

The Terminal is a bit like the Finder, in so much as you are always in a directory. When you start the Terminal, you are in your home directory. We need to change to the Patchstick download directory, so change the above to read as follows by adding cd (change directory) and removing /createPatchstick from the end, as that's a file not a directory we can change to.

    cd /Users/peter/Downloads/Patchstick

This is how the Terminal sees directories or folders: separated by forward slashes.

Now we are ready to run the script. We need to do this with administrator privileges so the command must be prefixed by "sudo". We must also tell the Terminal that the file is a script to run, and we do this by adding "./" in front of the file name. So, type this into the Terminal:-

    sudo ./createPatchstick

You will be asked for your password. Enter it and press return. It is normal that you cannot see what you are typing and the cursor does not move.

The script will tell you a few things and then list your disks in what at first appears to be quite a frightening way. It's not, don't worry. Nothing has been changed at this stage. It is however, imperative that you get this next part right as in theory, you could wipe your whole hard drive with a tiny typo. So, read very carefully and double-check everything.

The list of drives will look something like this:-

    Listing available disks:
       #:                       TYPE NAME                    SIZE       IDENTIFIER
       0:     Apple_partition_scheme                        *76.3 Gi    disk0
       1:        Apple_partition_map                         31.5 Ki    disk0s1
       2:                  Apple_HFS boot                    76.2 Gi    disk0s3
       #:                       TYPE NAME                    SIZE       IDENTIFIER
       0:     Apple_partition_scheme                        *149.1 Gi   disk1
       1:        Apple_partition_map                         31.5 Ki    disk1s1
       2:                  Apple_HFS Patchstick              148.9 Gi   disk1s3
       #:                       TYPE NAME                    SIZE       IDENTIFIER
       0:     Apple_partition_scheme                        *232.9 Gi   disk2
       1:        Apple_partition_map                         31.5 Ki    disk2s1
       2:             Apple_Driver43                         64.0 Ki    disk2s2
       3:           Apple_Driver_ATA                         64.0 Ki    disk2s3
       4:             Apple_FWDriver                         112.0 Ki   disk2s4
       5:                  Apple_HFS music                   232.9 Gi   disk2s6

It depends how many drives you have (I have more, but have removed them from the list for simplicity's sake). What you are looking for is the information about the drive named Patchstick. Now you can see why we renamed the drive in the step above. In the example above, we're interested in this section:-

       #:                       TYPE NAME                    SIZE       IDENTIFIER
       0:     Apple_partition_scheme                        *149.1 Gi   disk1
       1:        Apple_partition_map                         31.5 Ki    disk1s1
       2:                  Apple_HFS Patchstick              148.9 Gi   disk1s3

As you can see, it is the part that describes the USB disk we named "Patchstick". What's most important is the /dev/disk1 part as our script wants this information so it knows which drive to turn into a Patchstick. Note that the name of the drive comes under the /dev/disk1 part, not before it. This would be a bad time to mix these up, since we're about to erase the drive and replace its contents.

Because your drive setup will certainly be different from mine, your USB Stick is most likely to have different dev/disk reference. So there is no confusion, I will use a capital N to refer to the number. You replace the N with the disk number for your Patchstick.

Make a note of the /dev/diskN reference and return to the Terminal. Press the up arrow key and the laast command executed will appear. Do not press enter yet. The last command was:-

    sudo ./createPatchstick

Change this to add the dev/diskN for your Patchstick:-

    sudo ./createPatchstick /dev/diskN

Double check this is right, then double check again. And again. Be 100% certain you have the right dev/diskN reference. You really do not want to get this wrong. When you are sure, press enter.

The script now runs. It will get data off your Mac and from its download folder and put in on your USB drive. You will be asked many times for your password. Enter it and press enter. When prompted for the location of the System/Library/Extensions folder, just press Enter, as you are running an Intel Mac and the folder is in the location the script expects it to be.

After entering your password many times, the script will tell you that your disk is unmounted and ready to patch your Apple TV. Holy hacking apples, Batman, we really are getting somewhere!

What might have gone wrong

Hopefully, the above went smoothly without error. If you ran into problems, double check you diskN reference was right, that you executed the cd command correctly and that you typed you typed your password correctly. Other than this, you're going to need to ask for help in the forums.

In the Finder, eject your Patchstick if not already ejected by the script and remove it from the computer. Time to move to the Apple TV.

Patching the Apple TV

This doesn't require much effort, other than holding your breath and crossing your fingers. If you had any errors when creating your Patchstick, you shouldn't proceed. I'm also going to assume the following is true:-

1. You have done a factory reset.

2. There is no content on your Apple TV (preferred, but not essential)

3. You are running 1.0 firmware. Essential. If you can see "YouTube" as a menu option, you're running 1.1 firmware and you need to do a factory reset. If you already have and you still have the YouTube option, your Apple TV shipped with 1.1 firmware and this process cannot help you.

Assuming all the above is OK, we move on.

Turn on the Apple TV and make sure you have easy access to the USB slot on the back. Plug in the Patchstick and then use the remote to do a reset by holding down the Menu and Minus (-) keys for 6 seconds. When the Apple TV restarts it will start reading off the USB Stick, and lots of text will appear on screen. If this doesn't happen, try a second reboot. If it still doesn't work, you can't proceed.

The Patchstick will only take a few seconds to do it's thing before starting a 30 second countdown. Almost always here you'll end up with the Apple TV saying something about a Kernel Panic. Don't Panic (imagine some large friendly letters). Just pull out the Patchstick before the Apple TV restarts and if needs be, pull the power cord, wait 10 seconds, then plug it back in. All being well (!), the Apple TV reboot and you have a new menu option called "Awkward TV", if it's worked.

Select the Awkward TV Menu option and use the menus to enable SSH and AFP. Note that the former can take quite a while. Just be patient. When you're done, pop back to your Intel Mac.

Enable External USB Storage

We're going to run another script now that will make the Apple TV use external storage on the USB port for all it's files. This is where that 500Gb hard drive will be used. We'll need to format it before we can use it though. Let's go.

Back to your Intel Mac, plug in the external USB hard drive. Go to the Applications Folder, find the Utilities Folder and open the Disk Utility. From the list of drives on the left side, select the disk you have just plugged in. Under Erase, select the Format option and use the format type "Mac OS Extended (Journaled)".

I think this is slightly different under Tiger. Perhaps someone can delete this line and add Tiger information here.

Wait for the drive to format and whilst you are, take the opportunity to download the next script we need, which is this External USB Drive Patch.

Once again we need to run a script, just like before. So, open the Terminal again and your downloaded file in the Finder and drag and drop the install-atvrhd.sh file so the Terminal shows something like:-


Change this by adding cd at the start and removing /install-atvrhd.sh from the end:-

    cd /Users/peter/Downloads/AppleTVHacks_USB_Patch

... and press enter.

Before proceeding, wait until your hard drive has finished formatting. When it has, take the hard drive to the Apple TV and ready it to be plugged in (Mains adaptor, perhaps?). Do not plug it in to the Apple TV yet! Whilst youa re at the Apple TV, grab the remote, go to the settings the network menu and make a note of the IP Address, which will be 4 numbers separated by dots. Pop back to your Intel Mac and at this stage, if your house is like mine, think about all the exercise you're getting by running up and down the stairs!

Back on the Intel Mac and in the Terminal, pick up where you left off and run the following command:

   sudo ./install-atvrhd.sh

And press enter. Here we go with another script.If you have followed all instructions, then you do have everything you need to complete this script. So, when asked "Are you ready to install" type "yes" and press enter.

You will then be asked the IP address of the Apple TV, so type that in as you noted it down before and press enter.

When asked "Do you have a copy of the kernel on this computer?" type "no" and press enter.

The script will then start to do its thing, creating files and sending them to your (newly visible-over-the-network Apple TV). You'll be asked for a password many times and this time do not enter your own password, but respond with "frontrow". You are being asked for the Apple TV's password, so that's what you need to give.

When asked "Where are the kernel extensions" just press enter, as they are exactly where the script would expect them to be.

Finally, the script will tell you "Finally, I need to restart your Apple TV [...]" and when you enter the password the last time, you need to go to your Apple TV and wait for it to reboot. When the flying images of the Apple TV's startup animation start to play, plug in and switch on the external drive. The Apple TV will copy all its media content (and remember, we turned all syncing off earlier, so there shouldn't be any, so it won't take too long) to the external drive and then reboot.

When it does, you can come back to the Intel Mac, open iTunes and click on the Apple TV. My goodness, you should have many gigabytes of extra storages space!

Your sync options will probably have been reset (what music, photos, etc) you want and you can change them back to whatever you like. I prefer to turn them all off again until I'm finished. For you, this might be as far as you want to go, although you MUST go to the Disable Updates section of the guide before you finish here completely.

Read on if you want to do a few more nice things, like playing avi movies, organising TV Shows, etc.

Getting the patched Apple TV to do more

What we're going to do now is install some more menu options on the Apple TV. Each menu option is known as a frappliance (Front Row Appliance) and we'll see a little more about these later. Each frappliance will do a couple of things for us, before we remove them again (optional) later and are just left with the functions we want. So, onwards.

Go to the Awkward TV menu option and use the Applications installer in this menu to download and install Sapphire and Nito TV. This should all be self-explanatory and there are clear on-screen instructions.

Now you have and Apple TV with a 3 new menu options:-

1. Awkward TV

2. Nito TV

3. Sapphire

Back upstairs to your Intel Mac and we're going to use the Terminal again to sort out a couple of things. Enter the following:-

    ssh -1 frontrow@AppleTV.local

If you named your Apple TV something other than "AppleTV" then you need to replace the text above. The first time your do this, it might take a few moments to establish a connection. When prompted, enter "frontrow" as the password.

Now, we are logged into the Apple TV, so rather than commands being run on your Intel Mac, they are run on the Apple TV. The Apple TV has a version of Mac OS X on it, so a lot of things work much the same way.

Next, type:-

    sudo /System/Library/CoreServices/Finder.app/Contents/PlugIns/nitoTV.frappliance/Contents/Resources/fixPerm

and press enter. I suggest you don't worry about what this does, just enter "frontrow" as the password if prompted.

Now you can go back the the Apple TV and go the NitoTV option. Go to the settings menu and then run the Perian Installer. When done, run the MPlayer Codecs installer. Do not use any other menu option.

Right, back to your Intel Mac. Open the Finder and under Network, you should see your Apple TV. Press "Connect" and connect as a registered user with username "frontrow" and the password as "frontrow".

Now, you should be able to see the partitions and drives of the Apple TV. Earlier, we installed a plugin called Sapphire. This will play virtually any media file you care to copy to the Apple TV Drive called "frontrow" in the directory called "Movies". Unfortunately, this directory is on the internal hard drive, so there's limited space. To get around this, we're going to do a bit of fakery and delete this directory and replace it with a link to a directory on the bigger external USB drive we installed.

Download this useful little utility, which is designed to make just such links, which are known as symlinks (Symbolic Links). Once downloaded, install this little utility.

On your external drive (the one *not* called "Media", "frontrow" or "OSBoot") on your Apple TV, create a folder called "movies". On the frontrow drive, delete the folder called "movies". Now, go back to the external drive, right click on the movies folder and there should be a new menu option, thanks to the little utility we installed called "Make symlink in". Front the submenu, just select "frontrow". When you now go to the "frontrow" drive, there will be an item called "Movies symlink". Rename it to "movies". Now Sapphire will be fooled into looking in this directory for media to play.

You can now rip DVDs into .avi format or many others not supported by iTunes on your Mac and then simply drag and drop them into the movies folder on your external drive. When you go to the Sapphire plugin, you will be see them and be able to click on them to play them. Sapphire will read complete folder structures, so you can have folders for TV or Film and subdirectories in each for different series, genres and seasons. More on Sapphire TV in its own page.


You'll probably read later on that there are other frappliance options for browsing and playing files. However, Sapphire is my personal choice for a few good reasons:-

1. You can turn off lots of the menu options that you don't want, making it nice and tidy

2. It's pretty quick and handles directory structures as is off the drive

3. It handles symlinks seamlessly (links to other drives / folders)

4. It can label all your ripped DVD TV Shows with episode names and give them their synopses and custom images automatically.

5. It marks items viewed / unviewed - most handy when you want to know what episode you last watched.

6. It does appear to be in active development. See here and here.

7. Bar its custom icons (which you can replace, if you want), everything it does looks like it belongs on the Apple TV.

Disable Update - Completely and Utterly Essential!

If you don't disable the auto-update feature, within a few days your Apple TV will update itself and undo all your hard work! So, we will fool the Apple TV into thinking that the update from Apple's update site on the Internet is somewhere other than where it actually is. We're going to tell the Apple TV it's at a dead end, so it never finds one. Cue evil laughter. Muahahahaha! There it is.

On your Mac, go to the Terminal and, if not already, connect to your Apple TV:-

    ssh -1 frontrow@AppleTV.local

Enter your password as "frontrow" if prompted. Then type:

    sudo bash -c 'echo "       mesu.apple.com" >> ../../etc/hosts'

And press return. This will stop future updates.

Tidying Up

Let's remove some of the menu options that we no longer need. We don't need Awkward TV or NitoTV anymore, so we'll make them disappear from the menu. You can actually do this with other things you don't use. Being in the UK, I never bother buying Apple's own TV shows from iTunes as we have lots on DVD or recorded to our Sky+ box (that's a Tivo type box to you, my friends from across the pond). So, you might want to remove other options, too. Up to you. However, do make sure you keep at least 7. For some reason Apple TV doesn't like having fewer than 7. More information and original info on removing menu options is here.

If you are not already, go into the Terminal and type:-

    ssh -1 frontrow@AppleTV.local

to log into your Apple TV and enter "frontrow" as the password when asked.

Type the following command to go to the directory where the frappliance menu options are stored:-

    cd ../../System/Library/CoreServices/Finder.app/Contents/PlugIns/

Now we're going to rename the items we don't want. If you want to see all the items and rename others, type

   ls -l

For this exampe, we'll just remove NitoTV and and Awkward TV

   mv NitoTV.frappliance/ NitoTV.frappliance.old


   mv AwkwardTV.frappliance/ AwkwardTV.frappliance.old

Next time you restart your Apple TV, these two menu items will be gone.