mercurious

How to install Native Applications onto an iPhone

• Introduction↓
• Getting Started↓
• How to install NES Game ROMs↓
• How to get sound working in NES↓
• How to get PICO working in iPhone Remote Terminal↓
• How to change the SSH root password↓
• How to Remove (Uninstall) applications↓
• How to Find your iPhone’s IP Address↓

Introduction

This guide is written for Mac users who are not familiar with using UNIX, but are very interested in getting third-party applications installed into the Springboard home screen of their iPhone (not Safari web apps). There are several guides and wiki sites out there at the moment that detail this process. This guide has not yet been updated for firmware 1.1.1 and only applies to 1.0.2 and under until it is updated. In the meantime, iPhoneAlley offers one of the first step-by-step guides for the recently announced 1.1.1  third-party application installation technique. It is not meant for novices, but could  be what you’re looking for.

Since the original posting, installing native iPhone applications has become easier than ever, thanks to the amazing Nullriver software Installer. → It gives you a beautiful iPhone style multi-touch interface to install emerging 3rd party applications handling all the tricky stuff for you. Furthermore, it automatically checks for updates and makes sure you can keep up with the rapid pace of development. It is already clear that the Nullriver Installer is going to fuel the growth of this exploding scene.Nullriver has created AppTapp, a Mac and Windows graphical wizard← to get you started automated script that allows you to bypass all the instructions on this guide! You will need to issue a single command in Terminal, and so the gentle primer to using that below may no longer be required since this installer installer (I know, unfortunately, redundant, but true) handles everything and gets you started. An open source alternative to Nullriver Installer has emerged called Breezy that I’ll be testing a reviewing. Clearly, Nullriver is bound to be one of the first commercial (shareware) programs available for the native iPhone application market, eventually. Apparently, Nullriver and the PXL package development group are joining forces to bring aspects of open source to AppTapp.

This guide also addresses some of the most frequently asked questions that I’ve been seeing in the comments and threads. Most of them, I’ve also had myself at some point during this process. This guide is the result of working through these challenges, doing the research, trial-and-error. It may try your patience, but be reassured that it’s all very possible, and the hardest part is just getting set up. This guide relies on some of the excellent guides that have emerged at ModMyiPhone.com, but attempts to update, augment and clean up things.

Contributions

It is my hope that this helps out the iPhoneDevTeam by fulfilling the overwhelming need to teach so many new users basic UNIX and other tricks to get these mods working. Instead of wasting time teaching newbies the basics, these amazing folks can stay focused on delivering us amazing new tools to make the most of our beloved devices. Consider this my donation to the cause.

Disclaimer and Warning

If you run into problems during modding, such as losing sync capabilities with iTunes, you will need to go through the Restore process through iTunes, which should make your phone factory fresh, but you will lose your customizations. Hopefully, this guide will help you quickly rebuild your mods, in case that happens.Set aside several hours to go through everything in this guide. However, when you’re done, you will have a nice setup for enjoying third-party iPhone applications.

Of course, this guide is provided AS IS, and use it at your own risk. I do not condone, endorse or warrant any of the actions suggested here. You are advised that altering the software on your iPhone is consideration a violation of the legal agreement you enact with Apple, and hence, they will no longer be obligated to support you. This means that you will likely void your warranty.

Modding from iPhone 1.0.1 to 1.0.2

If you have made modifications prior to the iPhone 1.0.2 software update, it is strongly recommended that you:

1. Sync to iTunes to backup your settings
2. Choose “Download” instead of “Download and Install” when prompted to update your iPhone to 1.0.2
3. Run a restore process, which will reset your phone to factory settings. Then only things you should lose are your voicemail password and WiFi access point passwords. Everything else, including SMS and Notes should be restored and you’ll have iPhone 1.0.2
4. Re-sync to iTunes. Quit iTunes and then run the Nullriver Installer script (the included README file gets you going)
5. Install Launcher, through Installer on the iPhone
6. Proceed to install items such as BSD Subsystem and OpenSSH, and then you’ll be in good shape to get NES, Lights Off and many of the other great tools and programs emerging.

Getting Started

Refer to this handy Glossary by Erica Sadun to have some of the common terms of iPhone modding translated into plain language.

1. Get comfortable with Terminal

Open what’s called a UNIX shell by finding /Applications/Utilites/Terminal on your hard drive and practice using some basic commands. If you’ve used Terminal before, you can skip this step.You’ll need to issue lots of these commands during the process, so it’s worth understanding the relationship between the command-line actions and the equivalent familiar actions that is second nature when clicking around in the Finder.Try out these commands, hitting enter after each line. See if you can figure out what’s going on.

lscd /lscd /var/root/lscd ../../cd /usr/ls -lacd ~

cd means change directory. ls means list the files in the directory, with -la you get all the file information and show hidden files also. This is what’s happening behind the scenes when you click on icons and folders in the Finder. Note that ~ means your user’s home directory.Tip: If you’re ever lost in the Terminal file paths, you can always drag-and-drop a file from the Finder into the Terminal and it will convert the path for you.

2. Get started with iActivator

http://www.modmyiphone.com/wiki/index.php/Getting_Started_iPhone_ModdingFollow the detailed guide on this page, which includes download links. In this step, you’ll create a local “phonedmg” directory on your Mac’s user account, download the restore files from Apple, and go through the “jailbreak” process, which makes your iPhone writable. You’ll always need to go back to jail to make it work with iTunes. If you have any trouble with iActivator, or it suddenly becomes unavailable for download, you can perform a jailbreak in Terminal on the command-line.

3. Install iPHUC

http://www.modmyiphone.com/wiki/index.php/Installing_iPHUC_iPhoneThis process is complicated, requiring several programmer’s tools and libraries including XCode from Apple, the MacPorts open source kit and others. All of it is free and open source, and this tutorial does take you through each step very carefully. iPHUC is required to install SSH, which will allow you to copy and manage files on your iPhone much more elegantly. Luckily, you only have to go through this and the next step once. Seriously, this is the most elaborate step, but you’ll only have to go through it once.

4. Install SSH

http://www.modmyiphone.com/wiki/index.php/Installing_ssh_on_iPhone_using_iPHUC_in_OS_XFortunately, after completing this next step, you’ll be able to easily install a more robust version of SSH, with a better security setup, as you’ll create unique security keys for your device. In addition, it is strongly recommended that you change your root password after you’ve gotten things in order. This may help prevent an attack on your phone by a malicious program that looks for iPhones with SSH enabled on public WiFi networks. Be aware that by enabling SSH, you are making your device prone to malicious attacks by downloading software that may contain malware or worse. In other words, by enabling SSH, you open the possibility of allowing software to connect to servers behind the scenes. This could involve allowing your private data being sent to servers without your explicit knowledge, or worse. There were many reasons why Apple removed SSH from the iPhone’s UNIX system in the first place. But keep things in perspective — you probably have SSH enabled on your Mac right now and so you’ve been living with these risks all along. When you realize you can wirelessly connect to your iPhone from anywhere and transfer files and do other powerful things, you’ll appreciate the potential that you’ve unlocked.

5. Install Installer.app (aka AppTapp)

http://iphone.nullriver.com/beta/Note: Nullriver’s AppTapp no longer requires the manual command-line installation detailed below, instead offering a GUI wizard style installer for Mac and Windows. This installation occurs over the USB dock cable, so if would like to install over wireless.Once you install this, adding and updating software becomes very elegant and easy. However, the documentation for this is very poor, assuming you are already familiar installing programs manually. Unfortunately, this is probably the best app to install first if you’re a newbie! Here are detailed steps, assuming you have already completed the installation of iPHUC and SSH, above.

1. Download Installer.app ZIP file from Nullriver, unzip, and move into your local “phonedmg” folder with your usual drag-and-drop Finder interactions. Make this folder, if necessary: ~/phonedmg/Applications/
2. Shut down iTunes, and use Activity Monitor to quit iTunesHelper. (see iActivator guide for details, it should be familiar from step #2 above)
3. Open iActivator, and do a Jailbreak
4. Open Terminal on your Mac
5. Find your iPhone’s IP address↓: iPhone > Settings > WiFi > blue-arrow on current network > 10.0.1.4 (sample address)We’ll use the IP address 10.0.1.4 in this guide. Your IP will probably vary, so remember to replace it with yours each time you see in the code examples.
6. Type (replacing with your iPhone’s IP address)

ssh -l root 10.0.1.4

7. When prompted, enter default password (unless you’ve already changed it)

dottie

8. Type (hitting return after each line):

       cd /Applications    mkdir Installer.app    cd Installer.app    exit

9. Type:

       cd ~/phonedmg/Applications/Installer.app

10. Type: (replacing your IP address)

    scp * root@10.0.1.4:/Applications/Installer.app[password "dottie"]

11. Type: (replacing with your IP address)

        ssh -l root 10.0.1.4    [password "dottie"]    cd /Applications/Installer.app    chmod +x Installer    chmod +x ditto    exit

12. Hold down Sleep button and slide power off. Restart iPhone
13. The Installer widget icon should appear in the Springboard. Use it to install the available packages, especially, Launcher, BSD Subsystem and Open SSH. You’ll probably find dozens of interesting native applications to try, all of them constantly being updated and easily maintained with Installer.
14. You’ll always need to be jailbroken to allow Installer to write to the iPhone file system. Keep this in mind if you get any installation errors when using Installer.

How to install NES Game ROMs

Game ROMs are .nes files. Note: No one is going to tell you how to obtain these files. Learn about what ROMs are on NerveGas’s NES project page.

1. Make sure iPhone is jailbroken
2. Copy ROMs to ~/phonedmg/var/root/Media/ROMs/NES on your local drive. (Create directories if necessary)
3. Open Terminal and type (as always, replacing with your IP address):

        ssh -l root 10.0.1.4        [password "dottie"]        cd /var/root/Media        mkdir ROMs        cd ROMS        mkdir NES        exit        cd ~/phonedmg/var/root/Media/ROMs/NES        scp * root@10.0.1.4:/var/root/Media/ROMs/NES        [password "dottie"]

1. Restart iPhone, games should appear in NES

How to get sound working on NES

UPDATE September 1, 2007

Nervegas’ NES app no longer requires further hacking to get the sound to work as of its version 1.0 release, so you can disregard the tutorial below, as it is now obsolete.

Erica Utility Method — UPDATE August 26, 2007

If you install the Erica Utilities package with apptapp Installer from Nullriver, you already should have the command to disable and en-enabled the system sound, which allows the NES sound to work. You can also manually install the Erica command-line utilities if you don’t use apptapp. Use Mobile Terminal and type:

sound no

When you’re done playing NES, return to Mobile Terminal and re-enable the system sounds, so important things like calls will work:

sound yes

The program gives you textual confirmation of sound status. This new method is much easier than the old method

Manual Method

At the time of this writing, sound support was very glitchy, but may be improving with the rapid updates of NES.app thanks to the hard work of NerveGas. Although having sound is very appealing, if you have difficulties with this step, realize that it may not be worth the trouble.

1. Make sure iPhone is jailbroken
2. Create a text file in your local drive here: ~/phonedmg/var/root/.profileDon’t use TextEdit. Download TextWrangler or TextMate if you don’t have a true plain text editor.
3. Contents of .profile text file should be:

    # Aliases    alias pico='pico -w'    alias rm='rm -i'    alias ssh='ssh2'    alias nosound="launchctl unload /System/Library/LaunchDaemons/coreaudiod.plist"    alias sound="launchctl load /System/Library/LaunchDaemons/coreaudiod.plist"    # User specific environment    PATH=$PATH:/sbin:/usr/sbin

4. In Terminal:

       cd ~/phonedmg/var/root    scp .profile root@10.0.1.4:/var/root/.profile

5. Make sure ‘login’ is present in ‘/bin’

   cd /bincurl http://iphone.natetrue.com/login

6. Make sure you installed MobileTerminal with Installer by Nullriver
7. Restart iPhone, as needed. Unplug earbuds.
8. Open Terminal on iPhone and type:

   nosound

9. Go Home, and Launch NES. Sound should work.
10. When you’re done playing, dont’ forget to return to Terminal on iPhone and type:

sound

11. Regular sound functions should be restored

How to get pico (text editor) working on iPhone Remote Terminal:

pico is a very basic text editor that works in the Unix command line. Although it would be cool to be able to edit files in Mobile Terminal, this is actually more useful for the occasions when you have connected into your iPhone via SSH on your Mac Terminal and want to make an edit to a configuration file directly.I haven’t been able to get pico working on the Mobile Terminal, on the iPhone itself, but through an SSH session on your Mac it works well. It appears that it’s a problem with the Mobile Terminal application, rather than with the UNIX configurations. Recent updates to the Mobile Terminal native application suggest that we are very close to being able to enable pico on the iPhone directly. However, there will be tricky interface issues to contend with because the iPhone keyboard lacks essential things like arrow keys. Running on your Mac Terminal, however, is useful to cut out the step of editing the text file on your computer and then needing to copy it to the phone.

1. Make sure you’ve installed the BSD Subsystem, either with Installer.app, or manually. Using Nullriver’s Installer is by far the easiest way to get the BSD Subsystem, which in turn, help makes your iPhone work like a full-on computer.
2. Open Terminal, and type (replace with your iPhone’s IP address):

       ssh -l root 10.0.1.4    [password "dottie"]    mkdir /usr/share/terminfo    mkdir /usr/share/terminfo/76    exit    cd /usr/share/terminfo/76    scp vt100 root@10.0.1.4:/usr/share/terminfo/76/vt100    [password "dottie"]    ssh -l root 10.0.1.4    [password "dottie"]    csh    set term=vt100

How to change the SSH root password:

Since the root password “dottie” is now very public knowledge, it’s a security hazard to be walking around with SSH enabled on your iPhone, roaming around on public WiFi networks. You should change your root password once you’ve got the basics installed.

1. Visit this site to get your new root password encryptedhttp://iphone.simbunch.com/crypt.php
2. Make a backup of your original master password. In Mac Terminal, type:

   ssh -l root 10.0.1.4[password "dottie"]cp /etc/master.passwd /etc/master.passwd.bakexit

3. Optional: While you’re in there, consider changing your default shell to ‘bash’ from ’sh’ which will do a better job of honoring the changes to your .profile and other nice things. See this tutorial on the iPhoneDevWiki to change your default shell.
4. Copy the contents of the result of the password form on the above page into a new blank text file. Save it to your local drive at ~/phonedmg/etc/master.passwd
5. Upload it your iPhone. In Mac Terminal type:

       cd ~/phonedmg/etc    scp master.passwd root@10.0.1.4:/etc/master.passwd    [password "dottie"]

6. Restart your iPhone
7. In Mac Terminal, test the new password:

   ssh -l root 10.0.1.4

8. Enter your new password at prompt

How to Remove, (Uninstall) applications:

If you’ve installed a 3rd party application with Nullriver’s Installer, just use its Uninstall feature.If you need to uninstall by the command-line, follow this example where we’ll delete an installed application called Tetris.appThe trick is to go into the .app directory, and delete the files first, then go up, and delete the enclosing .app directory.

1. In Mac Terminal, SSH into your iPhone

       ssh -l root 10.0.1.4    [password]    cd /Applications/Tetris.app    rm *.*    cd ../    rmdir Tetris.app    exit

2. Restart iPhone. Application widget should be gone, no longer appearing on the Springboard.

How to Find your iPhone’s IP Address:

You need to be connected to a WiFi network.

1. At the Home screen…
2. Click Settings
3. Click WiFi
4. Click the blue arrow of the network you’re connected to
5. IP address is displayed