The iPhone Gutenberg Science Fiction eBook Repository!

Yes, I managed to finish it. I've managed to convince Project Gutenberg books to install onto the iPhone.

To make use of the repository:

1. Obtain an iPhone.
2. Jailbreak the iPhone, I recommend ziphone for this task.
3. Install Books, the iPhone ebook reader using the Installer application (1.4+ only!)
4. Add the repository to Installer:
1. Start Installer
2. Click "Sources"
3. Click "Edit"
4. Click "Add"
5. Enter "http://library.pollock.ca/gutenberg_scifi"
6. Click "OK"
7. Click "Done"
8. Click "Refresh"
5. Select "Install" at the bottom of the screen. You will see "Gutenberg SciFi" is now available as an application category!
6. Before you can install a book, you will need to install GutenMark, it is under Utilities. I am using it to format the files on your phone to save me bandwidth.

There are currently 163 books in the library, in English and French. The list of books I used is from Gutenberg's SciFi CD collection. Since I can convert any Gutenberg book at this point, if there is a favourite you are looking for, please let me know.

The installation software has a preference for the HTML version of the book if it exists, however it will use the TXT version and pass it through GutenMark if it doesn't. Both versions will be split into chapters using the very handy GutenSplit.

VoIP and 911

I see that another infant has died because a VoIP call wasn't properly routed to a 911 operator. Situations like this caused some very extreme results for US VoIP carriers - Vonage wasn't allowed to accept new customers for a couple of months until they sorted it out!

Every time I see one of these stories, I try to come up with a solution. Here's what I would do for this problem.

There are a couple of problems in the current solution that need to be solved. First, the call was routed based on the customer's billing data. That isn't accurate in the VoIP world. It's not even accurate in the fixed line world! Many people have phones that are billed to PO boxes or businesses that are not the physical location of the line. Second, E911 has the ability to locate an individual caller. Without that, if the call is disconnected, or the caller cannot speak, the 911 operator has no way of determining where the person needing help is.

First, the easy one. Routing based on billing data. This is pretty easy, DON'T DO IT!

We need to find some reasonably accurate geolocation data in a VoIP call. Thankfully, it's right there. The source IP address. Home VoIP will be at the end of either a cable or DSL modem. Either is a physical port. With a static IP address, it's well defined where they are. Even with a dynamic address, the address range is still geographically limited. Definitely accurate enough to select a 911 call center.

We can make use of commercial IP address geolocation databases to route to the nearest 911 operator. There are existing commercial databases that provide just this information. However, the data may be inaccurate. So, you add the data to the call. You now have a call with location data of the call and the billing data. If they disagree, you route based on the IP address and inform the call center to verify the region information.

Perhaps it's too simple a solution. VoIP telephony people (and most Internet people) view the Internet as a cloud, they don't trust IP addresses to identify locations (Telephony people have the opposite problem, they put too much trust in the phone number.)

However, society has started using IP addresses as not only identification of location, but of a specific user too. For an example, have a look at the RIAA lawsuits in the US. The IP address is sufficient to sue an individual for copyright infringement. It is used to identify not only the location the connection is made from, but to make a reasonable assertion to the identity of the individual!

So, current commercial IP address geolocation products have the information we need to properly route 911 calls to the local call center.

How do we get E911 levels of location accuracy? To do that, we need the help of the ISPs.

Remember, everyone is connecting through DSL or cable, or some other fixed-line connection. We will deal with mobile later. That means that the ISP has a mapping between the IP address and the physical port (at least for DSL, cable too probably). However, gaining access to this data will require government regulation and probably some money changing hands (carriers bill for 911 services).

If this database is also made available to the 911 operator, then we have a complete system, a database that maps an IP address to a call center, and then on from the IP address to the physical location. There is probably even a standard that we can use, since E911 services for mobile phones have the same problems.

So, what about mobile? Well, in the mobile world, we still have the IP address to location mapping, and the carrier still has the IP address to physical location mapping. However, it is a little more indirect. There is a mapping from IP address to phone number, and then the carrier can use their existing E911 services to locate the actual device.

Is any of this even expensive code? No, it isn't. That's the interesting bit. It's all information that is added on to the existing 911 call. Even without a correct geolocation of the IP address, the call center operator can still correct the problem by asking "Where are you?". This system will be there to provide additional information to the 911 operator, not replace them. Since the 911 operator themselves are a key component of this solution, additional training will undoubtedly be needed, including a change in some of the scripts they read from. Adding the city to the address for confirmation would solve many problems.

Where does this break down?

1. VPN - If the phone is in a branch office, that routes IP traffic through a VPN to a different POP, it won't work. However, they've already got this exact same problem with corporate PBXs anyways, this isn't new.
2. Calls from outside of the jurisdiction. If someone takes the device overseas to use it for cheap (free) long distance.
3. Carriers making frequent changes to their routing rules. If a subnet moves from one region to another, 911 calls may have the wrong location until the database is updated.

Baen Free Library iPhone eBook Repository Updated!

Since STE has released v 1.4 of the iPhone EBook reader, I have finally had to update the repository to support 1.4. The major change? It now places books in ~/Media/EBooks instead of /var/root/Media/EBooks. This is because Books.app only looks in ~/ now!

I took the opportunity and added some additional features:

1. Cover Art! The books now display their cover art in the main title list.
2. Chapter Sorting! The Books.app team removed a hack they had specifically put in for Baen, it was causing performance problems. I have renamed the html files to avoid the problem.

Well, I thought it was more features than that when I started.

If you already have the book installed, it should upgrade through Installer.app. I have tested a couple of books, so I'm reasonably confident it will work.

Also, since webscriptions has a habit of updating the .zip files every week or so, I now scan their site every hour to ensure that the source plist is up to date.

Again, if you run into any problems, file a bug report over at the google code project

Truth in Advertising

If you say "Usually ships in 48 hours", it means that I should expect to see it ship in two business days. It also means that if I leave five business days, I should have the item in my little hands by the time I need it.

I'll understand if you are going to miss that deadline. Let me know, and give me the option of canceling my order. Leaving me guessing about the status of my order is frustrating and ultimately (as we'll see in a second) bad for business.

I won't be shopping at Gameplanet Store NZ again. I have placed two orders with them, the first one took an extraordinary amount of time to arrive, missing the party that I wanted it for.

I ordered a second game (mostly due to a $10 discount from the first order), and again it didn't ship inside of the 48 hour window. So, you have to ask, "What does 'Usually' mean to them?" To me, it means at least 95% of the time. How ever, two failures in two orders means it sure isn't 95% to them.

GPStore - Avoid, they're the "flying pig" of NZ software retailers.

Announcing the iPhone eBook Repository

Installing eBooks onto the iPhone for reading was nearly impossible. You needed to download third party tools, use scp, rename files, the works. To help, I decided to package existing eBooks for viewing on the iPhone.

Since this is an AppTapp repository, the books can be installed onto the iPhone from any location that the device has a valid network connection, GPRS, EDGE or WiFi.

The current repository provides installation instructions for 117 SciFi novels from the Baen Free Library, with plans to add additional sources. I am currently working on Project Gutenberg.

To make use of the repository:

1. Obtain an iPhone.
2. Jailbreak the iPhone, I recommend ziphone for this task.
3. Install Books, the iPhone ebook reader using the Installer application (http://code.google.com/p/iphoneebooks/ (1.37 only!))
4. Add the repository to Installer:
   1. Start Installer
   2. Click "Sources"
   3. Click "Edit"
   4. Click "Add"
   5. Enter "http://library.pollock.ca/baen_books"
   6. Click "OK"
   7. Click "Done"
   8. Click "Refresh"
5. Select "Install" at the bottom of the screen. You will see "Baen Free Library" is now available as an application category!

Just to clarify a couple of things. I am not providing copies of the .zip archives, they are provided to the iPhone by Webscription and Baen. The content of the files themselves are unchanged, although I have had to rename the html files to better fit in with the reader (I changed the SKU in the filename to Chapter).

To make it easy to spread these repositories around, I have uploaded the scripts I used to generate the repository to google code (iphoneebookrepo). If you would like to help, either with code, by reporting faults (thanks Ross!), or just general comments, I would appreciate it!

Take that Kindle!

AppTapp Exec bug

I released my project to a couple of friendly users. After giving it a try, one of the testers came back and told me the installer was leaving crufty directories lying around in the root directory.

I eventually tracked it down to this:

<array>
   <string>Exec</string>
   <string>/bin/mkdir -p "/var/root/Media/EBooks/Beyond World's End"</string>
</array>

Now, if this was in a shell, or passed to the OS using "system" or a similar call, it would work. However, it seems that they are using direct calls to exec. I can't really tell, because AppTapp is oddly closed source.

The directories it was creating were:

• "/var/root/Media/EBooks/Beyond
• /World's
• /End"

Fun!

Next up, I tried escaping the spaces, again with no luck. It looks like the code is splitting the parameters out through the use of spaces and ignores any attempt at grouping the packager might make.

Luckily CopyPath does the right thing, properly handling the spaces. It even creates parent directories, which is why I was using mkdir in the first place.

Now to figure out how to host it on Amazon S3. I really don't want a 2.5meg file being slurped across my cable modem every day!

Debugging an iPhone repository

The AppTapp Installer doesn't provide any feedback during a failed install or source update. This makes it very difficult to create packages. At first, it really feels like you are stumbling around in the dark.

Here is what I learned from my project.

Installer.app ignores bad XML documents. If you have one good version of your repository, and then make a change that results in a "bad" one, you will still see the good copy that has been cached on the phone. This confused me for a long time.

Always test the document for correctness first. Firefox is a quick, easy test tool. Point it at the URL, and if it displays the XML in tree format, you at least know that your XML is balanced, and that your web server is configured correctly.

Next, run Installer.app manually on the iPhone. This should let you know what is going wrong with the package. (original source)

1. make sure you are not running Installer.app
2. ssh into your iPhone (root password is "alpine")
3. for 1.1.3 firmware and higher: su - mobile
4. maximize your ssh window
5. cd /Applications/Installer.app
6. ./Installer
7. you will see Installer.app pop up on the iPhone's screen
8. reproduce the error
9. observe the debugging output from Installer.app in the ssh window

Finally, never, ever change the root password on your iPhone. You may think that because you are running an SSH server that is open to the world that it would be a good idea to change it. After all, there is a "passwd" command sitting right there in the terminal window. RESIST!

There is a problem with the 1.1.3 and later firmwares, and the version of passwd shipped with the BSD subsystem results in Springboard (the desktop shell) crashing continuously. I made this mistake and had to completely wipe the phone and restore it.

For security, install the services application, and disable the SSH server between uses. This will also help with the battery life of the phone!

Creating an iPhone AppTapp Repository.

I had a project where I needed to create a repository for AppTapp (Installer.app), the application used for over the air software installation on jailbroken iphones.

It's near impossible to find instructions on how to do this. If you google for them, all you get are "how to jailbreak your phone" and "how do I install applications" questions. Nothing about how to actually create a repository!

Thankfully, I eventually found the a wiki on ipodtouchfans with a detailed description.

The repository file is an XML document using Apple's plist format. Since it's XML it is both easy to pick up and nasty to use at the same time. The header portion of the plist file is self-explanatory, check out the wiki link. Here's the header from my test repository.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
 <key>info</key>
 <dict>
  <key>name</key>
  <string>Testing</string>
  <key>maintainer</key>
  <string>Jason Pollock</string>
  <key>contact</key>
  <string>jason@pollock.ca</string>
  <key>url</key>
  <string>http://www.pollock.ca/repos/baen</string>
  <key>category</key>
  <string>TestRepositories</string>
 </dict>
 <key>packages</key>
 <array>
        </array>
</dict>
</plist>

The individual package instructions go in the final array. However, this is a fully specified (if empty) repository. If you place it on a publicly accessible URL, people will be able to add it to Installer.app and track updates!

Next are the individual packages and installation scripts. The package themselves are separated into scripts and .zip archives. There is no provision to deliver software in any other format.

The install/uninstall scripts are part of the repository XML, not the .zip archive. This means that you can host the .zip files on a cheap, low cost volume server, while the xml document (since it is generally smaller) can be hosted closer to you. Web servers are more able to cache the repository document. Hopefully, with a single http request, the application is able to tell from the header response if the repository has changed, keeping transfers to a minimum. To keep from having someone change the .zip file on you, both a size and an md5 hash are provided in the plist file. Finally, the separation between script and installed files allows other people to provide fixed installers for your application!

The install/uninstall scripts are also XML, complete with if/then/else syntax. This is near impossible to either understand or get right due to all of the tag nesting, and chaining of siblings without explicit keyword enclosures. For example, let's look at an extremely simple "if" block to check the firmware version.

First, the logic in C, just to let you see what it should be doing:

   if (! FirmwareVersionIs("1.1.2")) {
       AbortOperation("Firmware 1.1.2 is required to update to 1.1.3.");
   }

Now for the insanely verbose XML code.

           <array>
             <string>IfNot</string>
             <array>
               <array>
                 <string>FirmwareVersionIs</string>
                 <array>
                   <string>1.1.2</string>
                 </array>
               </array>
             </array>
             <array>
               <array>
                 <string>AbortOperation</string>
                 <string>Firmware 1.1.2 is required to update to 1.1.3.</string>
               </array>
             </array>
           </array>

Completely impenetrable.

Installer.app works best when the .zip is already in the destination layout. Then the installation process is relatively simple. However, if not, each file must be individually copied into its target location, using the <CopyPath> command.

<array>
    <string>CopyPath</string>
    <string>iZoo.app/</string>
    <string>/Applications/iZoo.app</string>
</array>

There are several gotchas.

First, if you create directories, Installer.app creates them with no permissions what so ever, you will need to perform a chmod!

Second, the location of the Media tree was moved between 1.1.2 and 1.1.3. In current releases of the iPhone firmware, applications run as the user mobile. This means that the Media tree (where the music/etc is stored), is now in /var/mobile/Media instead of /var/root/Media. Since applications are installed on both 1.1.2 and later versions of the firmware, they need to work on both. To help with this, Installer.app has added support for "~", to refer to the home directory for the user. Again, however, this depends on a specific version of Installer.app being present. Personally, I chose to ignore all of this, since the application I was using didn't know about /var/mobile/Media anyways. Still, it is something that developers will need to figure out.

Third the syntax in the scripts is nasty. If you find yourself writing a fair bit of it, write a tool to do it for you. I'm sure it is possible to come up with a more human readable syntax that will generate the XML for you.

Finally, debugging your packages is painful and slow. However, that's for the next post.

Other than that, there's nothing too difficult about the whole thing. If the zip file you are trying to install is already in the target layout, it's dead simple.

Enjoy!