Original URL: https://www.theregister.com/2009/02/06/apple_tv_hacking_part_1/

Hacking the Apple TV

Getting in

By Nick Hawkesmoor

Posted in Personal Tech, 6th February 2009 13:02 GMT

Part 1 Apple continues to describe its Apple TV set-top box as a “hobby” project: it’ll continue to develop the platform, but it’s not making any money out of it yet. The gadget’s a hobby project for a lot of other folk too. They want to gain access to this closed but surprisingly powerful system to make it more useful.

We’ve had an Apple TV unit for a while now, and we decided it was time to dig a little deeper into its foundations. Under the hood, it’s essentially a tweaked Mac OS X 10.4 box. There’s no shortage of information on a variety of internet sites, Awkward TV, in particular. But, like so many online guides, bits were written some time ago and not updated, while others skip steps.

Apple TV

Apple’s Apple TV: Mac OS X computer in set-top box form

What follows is our attempt to collate and make consistent a number of online guides, and to ensure they work on the latest version of the Apple TV’s OS.

Apple released Apple TV 2.0 system software almost a year ago, and many — but not all — of the hacks posted online have been modified to work with the second-gen OS, recently upgraded to 2.3. Our Apple TV was still running 1.1, so we allowed the device to update itself to the latest version of the OS.

The Apple TV hacker’s first stop should be the ATV USB Creator site, home of the premier tool for installing the basic access code into an Apple TV without having to rip the hardware apart to get your hands on the hard drive.

ATV USB Creator

ATV USB Creator in action

There are versions of the utility for Mac and Windows machines. Both take a USB stick — it’s dubbed a ‘patchstick’ in Apple TV hacking circles — and prep it for connection to the Apple TV’s otherwise-unused USB port. ATV USB Creator will grab the latest Apple TV system software from Apple, pull out the important components and add the code that’ll be installed at runtime. The result is a Flash drive that the Apple TV will boot from.

By default, ATV USB Creator will prep the drive with SSH; some general tools; a software acquisition tool for the Apple TV; XMBC, an open source media manager; and Boxee, an open source media sharing system. We didn’t — for now — want anything other than SSH, which is key to access the Apple TV remotely, so we made sure only that was selected in ATV USB Creator’s Installation Options.

Standard Definition Colour

Want an Apple TV, but you’ve only got an SD TV and you’re frustrated by Apple’s insistence its box only works with flat panels? The device will output a colour signal to an SD TV’s composite-video input. You need to access the unit’s OS, as outlined on the next page, but when you’re done, you can install a composite colour hack.

Using the Patchstick

We plugged ATV USB Creator into the Apple TV, restarted the hardware and watched Linux boot up and SSH copied across. It takes a just couple of minutes all told, but it doesn’t automatically restart, so you’ll need to watch out for the on-screen warning to remove the patchstick and restart the Apple TV.

Login

Logging in to the Apple TV using SSH

Restarting the device, this time without the Flash drive disconnected, and we got the usual Apple TV front end. And so far there’s nothing about the UI to tell you it’s been opened up.

Starting up a terminal application on a nearby networked computer, however, and you’ll be able to log in to the Apple TV using SSH. Just enter ssh frontrow@appletv.local then key in the password — frontrow — when you’re asked for it. If appletv.local isn’t recognised, use the Apple TV’s IP address, which you can get from the machine’s Settings/General/Network menu.

SSH lets you explore the file system through a terminal application, but you’ll also need an SFTP client to copy files across easily.

Apple TV Network Settings

Apple TV’s network settings

Users comfortable with the Unix terminal may prefer the scp command. You’ll need to use the -r option to ensure Mac OS X entities that appear as single files but are actually directories get copied across in their entirety.

Now back to the modifications. ATV USB Creator allows you to load your USB boot drive with SoftwareMenu, a handy tool for running scripts and managing Apple TV functionality plug-ins — of which SoftwareMenu is itself one. We didn’t use this option, so had to install SoftwareMenu manually, which we’ll detail here. You can use ATV USB Creator, but it’s worth reading the next few paragraphs because it shows you how to install any Apple TV plug-in beyond those the ATV USB Creator and SoftwareMenu will install for you.

File transfer

Copy across files using SFTP

You can download the latest version of Thomas Cool’s SoftwareMenu from Awkward TV here. Unpack the file and you’ll get a folder containing a second folder, called SoftwareMenu.frappliance — it’s the .frappliance suffix that identifies it as an Apple TV plug-in.

Set up SoftwareMenu

Copy the file across to your Apple TV, and then type this into your terminal:

sudo cp SoftwareMenu.frappliance /System/Library/CoreServices/Finder.app/Contents/Plugins/SoftwareMenu.frappliance
cd /System/Library/CoreServices/Finder.app/Contents/PlugIns
sudo chown -R root:wheel SoftwareMenu.frappliance

That’ll put SoftwareMenu in the right place and give it the correct ownership settings. Restart your Apple TV, and when it’s come back up, you’ll see Software Menu listed in the main UI. If not, try again and check your typing.

Apple TV SoftwareMenu

SoftwareMenu in the Apple TV’s UI

SoftwareMenu’s sub-menus provide some handy plug-in download tools, and the ability to keep the add-ins updated. It also runs scripts, and comes with a pre-loaded one to restart the Apple TV, saving you the need to yank out the power cable every time you want to reboot the box. For the hacker, SoftwareMenu’s worth installing for that alone.

SoftwareMenu allows you to install a number of plug-ins directly, including the useful ATVFiles, which can be used with the regular Apple TV remote to find and play files that the main UI will not allow you to view.

We’ll cover ATVFiles in detail next time, when we’ll also step through the process of adding other codecs, such as DivX, to the Apple TV.

Apple TV SoftwareMenu

SoftwareMenu has a very useful script runner

Meantime, other third-party plug-ins available include CouchSurfer, a web browser with Flash support. It’s still in development — Register Hardware was not a site it was happy rendering, alas — but it provides a way of getting the web on your telly. Entering URLs with the remote is a little bit of a chore, but with both History and Bookmark menu options, you shouldn’t need to type addresses in too often.

The remaining SoftwareMenu-supported plug-ins all focus on media playback. NitoTV is a bionic front end for the mPlayer media player app that chucks in network sharing, RSS feeds, weather news and even old games console emulators.

Sapphire is an alternative to ATVFiles, presenting internet-sourced album art, video covers and so on when you use it to select files you’ve copied over to the AppleTV that use unofficial codecs.

Apple TV SoftwareMenu

Install other plug-ins directly

Finally, XMBCLauncher is an open source skinnable-media centre application that provides an alternative UI to the Apple TV’s own. It also runs on Macs, Windows PCs and Linux boxes. Just make sure you disable the Apple TV’s screensaver, which can prevent XMBC firing up correctly.

How to get a colour picture on an SD TV

If, like us, your Apple TV is connected to a standard definition TV, you’ll have a picture, but it’ll be in black and white. The Apple TV’s green component-video connector will feed an SD TV’s yellow composite-video port, but you won’t get a colour picture.

There is a physical hack that gets around this, and we tried it successfully in the past. But it’s tricky and, since upgrading to Apple TV 2.3, it proved hard to get to work. It has to be applied every time the Apple TV’s rebooted.

Apple TV

HDMI and component ports — not good for many SD TVs

Here’s a better option. Download the file TVComposite.tar — you can find it here — and unpack the compressed file. You’ll find the source code along with a Mac OS X kernel extension called TVComposite.kext.

You’ll also need to download hacker Turbo’s utility, turbo_atv_enabler.bin from Oxfeedbeef.com. It provides tools that’ll allow you to dynamically load kernel extensions on the Apple TV.

Copy both TVComposite.kext and turbo_atv_enabler.bin over to the SFTP default directory /Users/frontrow then log in to the Apple TV using your terminal app and enter the following lines:

sudo mount -uw /
sudo chmod -R 755 TVComposite.kext
sudo chown -R root:wheel TVComposite.kext
sudo mv TVComposite.kext /System/Library/Extensions/TVComposite.kext

This code applies the appropriate file and group ownerships to the extension then moves it to its correct location on Mac OS X’s System folder. Now restart the Apple TV. When it’s back up, fire up your terminal again, log in to the box and enter:

sudo chmod 755 turbo_atv_enabler.bin
sudo turbo_atv_enabler.bin
sudo kextload /System/Library/Extensions/TVComposite.kext

Instantly, your black-and-white composite-video image will go full colour.

The downside is that, like the physical hack, it’s not resistant to reboots. Restart your Apple TV and you’ll get a monochrome picture again. Fortunately, there’s a way around it.

Open up a text editor and enter the following lines:

#!/bin/sh
. /etc/rc.common
/Users/frontrow/turbo_atv_enabler.bin
kextload /System/Library/Extensions/TVComposite.kext

Save the file as ATV_Colour, close it and open a new file. Enter the following lines:

{
  Description = "Load Composite Kext";
  Provides = ("Composite");
  OrderPreference = "First";
}

Save the file as StartupParamaters.plist. Use your SFTP app to copy both to the Apple TV’s /Users/frontrow directory. Log in to the Apple TV using a terminal and enter the following:

sudo mkdir /System/Library/StartupItems/ATV_Colour
sudo cp ATV_Colour /System/Library/StartupItems/ATV_Colour/ATV_Colour
sudo cp StartupParameters.plist /System/Library/StartupItems/ATV_Colour/StartupParameters.plist

That’s created the Startup Item, Mac OS X’s system for loading code when it boots. Now we need to make the script executable:

sudo chmod +x /System/Library/StartupItems/ATV_Colour/ATV_Colour

and, last of all, ensure the new Startup Item’s container directory is owned by the system:

sudo chown -R root:wheel /System/Library/StartupItems/ATV_Colour/

Restart the Apple TV, and after an initial monochrome splash screen, colour should kick in. ®