If you are writing an iPhone GameKit app without using GKPeerPickerController (as I did in PhotoBeamer), you need to detect when Bluetooth is disabled and ask the user to turn it on in the settings app. Apple doesn’t provide a way for a developer to enable Bluetooth other than through GKPeerPickerController.

This is pretty easy to do. First, create your GKSession and set it to be available:

    session = [[GKSession alloc] initWithSessionID:kMyAppSessionID
                                       displayName:nil
                                       sessionMode:GKSessionModeClient];
    session.delegate = self;
    [session setDataReceiveHandler:self withContext:nil];
    session.available = YES;

Next, set up your - (void)session:(GKSession *)session didFailWithError:(NSError *)error delegate method to detect when Bluetooth is not available and alert the user:

// GKSessionErrorDomain causes link error (rdar://problem/7014349)
#if 0
#define kGKSessionErrorDomain GKSessionErrorDomain
#else
#define kGKSessionErrorDomain @"com.apple.gamekit.GKSessionErrorDomain"
#endif
 
- (void)session:(GKSession *)session didFailWithError:(NSError *)error {
    if ([[error domain] isEqual:kGKSessionErrorDomain] &&
        ([error code] == GKSessionCannotEnableError))
    {
        // Bluetooth disabled, prompt the user to turn it on
    } else {
        // Some other error, get the description from the NSError object
    }
 
    // destroy the GKSession and clean up
}

The GKSessionErrorDomain symbol causes a link error for me, so I’m temporarily using the constant string instead. When Apple fixes the SDK, I’ll change that #if 0 to use the official symbolic name.

Note that this error will sometimes occur on a reconnection attempt even when Bluetooth is enabled, presumably because the old session is still partially active.

It would be nice to have a more user-friendly way to turn on Bluetooth without leaving the app and without using the full GKPeerPickerController UI. I’ve filed a bug report (rdar://problem/7061502) asking for this functionality. You should file one too.

Sure, there are apps that let you upload images to Facebook, Flickr, and all sorts of other places…. Sure, you can email a picture, and with iPhone OS 3.0 coming soon even MMS one (assuming you’re not in the US and don’t care about quality). There are even apps that let you share photos on the spot, phone-to-phone, but only if you are all on the same WiFi network.

We knew that 3.0 would be out soon, possibly as soon as WWDC. We also knew that 3.0 had peer-to-peer Bluetooth networking support through the new GameKit framework. We decided this was a perfect opportunity to take advantage of the new OS.

I went home and got some sleep (long day and Crown don’t make for productive programming), then dived right into GameKit first thing in the morning. By lunch time I was able to share small images reliably, but clearly needed a lot of UI and networking polish. We knew we wouldn’t be the only ones with this idea, and that the quality of the app would be more important than being the first ones to market.

I spent the rest of the week polishing the prototype, and by the time I left for San Francisco had the core user interface pretty solid: translucent autohiding toolbars, a zooming and scrolling image view very much like the native Photos app, support for viewers coming and going mid-session, and more.

During the keynote at WWDC Apple announced that the 3.0 gold master was available immediately to developers. I updated from the Beta I was running and immediately found bugs in my apps. Not so much in PhotoBeamer, but in SpinSlide, which was already in the store with paying customers. I had to put PhotoBeamer aside and work on fixing the bugs in SpinSlide as quickly as possible, while attending 8+ hours of sessions and nearly as many parties through the week.

Once I got back from WWDC I was able to finish up the bug fixes and internationalization work on SpinSlide (now available in Spanish and Japanese!) and get back to work on PhotoBeamer. I updated the networking code to send arbitrary size images reliably, added a camera button to allow taking pictures right in the app, and continued with the visual polish, adding activity spinners and a status view with separate progress bars for each client and a multi-line status area to ensure the user has a chance to read messages as they come up. I created a free version called BeamCatcher and fought through some issues with my build scripts, and added the ability for the clients to save images to their Photo Album, but only if the sender allows.

A few beta test sessions using multiple devices at once uncovered some more bugs that were addressed, and the arrival of the 3GS showed some more room for improvement in both the networking and image display code, thanks to the larger images. Most importantly, I discovered how to detect when Bluetooth is not enabled without using the built-in peer picker controller, which doesn’t fit well with the PhotoBeamer app flow.

After all that, and an unusually long review at Apple (likely due to the massive influx of new and updated apps around 3.0), both PhotoBeamer and BeamCatcher went live June 12th. Get PhotoBeamer to share your pictures. If your friends won’t spring for the full app, they can download BeamCatcher to view for free.

Last night I gave a talk at the Philly CocoaHeads meeting in an attempt to cover the 1000 or so new APIs in over a dozen functional areas in under an hour. I’m sharing the slides here for all, whether you were able to make it last night or not. We had some great discussions, which unfortunately are not in the slides, but hopefully these will help give you an idea of what is newly possible in iPhone OS, and where to look for more details.

What’s New in iPhone OS 3.0, Philly CocoaHeads June 2009 (pptx, 552kB)

What’s New in iPhone OS 3.0, Philly CocoaHeads June 2009 (pdf, 366kB)

I’d love to hear your thoughts on the new APIs and how you plan to make use of them in your apps.

There’s not much to add, so I’m just posting to add it to my Google-powered memory.

Watch a video demo, read my previous post about it, or just go buy it!

Additionally, in any build that leaves the developer’s desk it is especially important to include version information so that bug reports can be traced back to the correct version of the source, and to ensure that any distributed version can be located in the version control system. I use git for source control (installed with MacPorts), though the script should be easily adaptible to CVS or SVN.

The goals for this script were:

• Automatically tag the project with a unique build number before each build.
• Build all supported configurations with a single command. Sometimes compiler errors or warnings are only revealed with certain preprocessor flags or optimization settings.
• Ensure any build created for distribution is cleanly committed to version control and tagged.
• Name tags so that they can be easily correlated to user-visible version information.

Preliminaries

Before we get into the script, a bit of groundwork is needed in the XCode project.

Build Configurations

By default, XCode includes two configurations in a new project: Debug and Release. I add a third configuration, Distribution, created by copying the Release configuration, but signed with my distributions certificate instead of the development certificate. This allows me to test using the same build settings that will be used for the submitted app.

I also set a couple of preprocessor flags based on the build configuration. The Debug configuration sets DEVELOPMENT_BUILD=1 and DEBUG_BUILD=1, while the Release build just sets DEVELOPMENT_BUILD=1. These flags are used for several purposes, including conditional logging, but in the context of this article they are used just for version string generation.

The versioning tool discussed in the next session also requires a build variable. Search for the CURRENT_PROJECT_VERSION key and set its value to 1.

Apple’s Versioning Tool

First, we need to take a little side trip into Apple’s built-in versioning support. XCode includes agvtool, which with a bit of setup can be used to satisfy our versioning requirements. The first step is to separate the “marketing version” from the build version. Both components are stored in the Info.plist file, though a new XCode project only includes the build version key.

I set the marketing version to the version I plan to specify in iTunesConnect when the app is submitted. The build version is simply set to 1 initially and incremented with each build thereafter (this should match the CURRENT_PROJECT_VERSION build variable).

Displaying the Version

In the About view controller’s viewDidLoad method I include the following:

- (void)viewDidLoad {
   NSString *versionString = [NSString stringWithFormat:
                        NSLocalizedString(@"Version: %@%@ (%@)", @"Version string format"),
                        [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleShortVersionString"],
#if DEBUG_BUILD
                        @" Debug",
#elif DEVELOPMENT_BUILD
                        @" Beta",
#else
                        @"",
#endif
                        [[NSBundle mainBundle] objectForInfoDictionaryKey:(NSString*)kCFBundleVersionKey]];
   [versionLabel setText:versionString];
   // Additional initialization
}

This provides enough information to determine the build and configuration from any copy of the app. Actually, the marketing version isn’t even needed, but it allows the user to compare with the information in iTunes.

The remainder of this article breaks down the script, section by section. You can download the script (updated July 14, 2009) and use or adapt it to your own projects. The script is under a BSD license.

The description below details the 1.0 version of the script.

Helper Functions

The first section of the script defines a few helper functions.

The die function simply prints its arguments to stderr and exits.

die() {
	echo "$*" >&2
	exit 1
}

The usage function prints its args (if any) followed by a usage message and exits.

usage() {
	if [ -n "$1" ] ; then
		echo "$@" >&2
		printf "\n"
	fi
	echo "usage: build [-n] [config...]" >&2
	echo "    -n : do not update build number or commit to git">&2
	if [ -n "$xcodeconfigs" ] ; then
		printf "\n    Known configs:" >&2
		printf " %s" $xcodeconfigs >&2
		printf "\n\nDefault action is to build all configs\n" >&2
	else
		echo "This does not appear to be a valid project directory!" >&2
	fi
	exit 3
}

The usage message is:

usage: build [-n] [config...]
    -n : do not update build number or commit to git

    Known configs: Debug Release Distribute

Default action is to build all configs

Defaults and Known Configurations

By default, the script will run agvtool and the git operations, and build all configs in the project.

nocommit=0
configs=

The list of known configurations is determined by filtering the output of xcodebuild -list with sed:

# all known configurations
xcodeconfigs=$(xcodebuild -list | sed '
		/Build Configurations:/,/^[[:space:]]*$/	!d
		/Build Configurations/				d
		/^[[:space:]]*$/				d
		s/[[:space:]]*\([^[:space:]]*\).*/\1/
	')

The output of xcodebuild -list looks like:

$ xcodebuild -list
Information about project "SpinSlide":
    Targets:
        SpinSlide (Active)

    Build Configurations:
        Debug (Active)
        Release
        Distribute

    If no build configuration is specified "Release" is used.

The four-line sed script first deletes all lines except those between Build Configurations: and the first blank line. The second and third lines delete the Bould Configurations line and the blank line, respectively. Finally, each line is replaced by just the first word on that line.

Next the script checks for an empty list of configurations, which can occur if there is no project bundle in the current directory.

if [ -z "$xcodeconfigs" ] ; then
	# no project bundle?
	usage;
fi

Argument Processing

Command line arguments are processed in a loop. The only supported flag is ‘-n‘, which suppresses avgtool and git operations. All non-flag arguments are assumed to be build configuration names, and are checked against the list of known configurations generated in the last section before being added to the list of configurations to build.

while [ -n "$*" ]; do
	case "$1" in
		-n) nocommit=1 ; shift ;;
		-*) usage ;;
		*)	if echo $xcodeconfigs | grep -wq "$1" ; then
				configs="$configs $1"; shift
			else
				usage "Invalid config '$1'"
			fi
			;;
	esac
done

If no configurations were specified on the command line, all known configurations are built.

# default to building all configs
if [ -z "$configs" ] ; then
	configs=$xcodeconfigs
fi

Check for Modified Files

The next step is to check for modified files. If modified files exist and -n was not specified, the script will exit with an error. If -n was specified the script continues after setting the isdirty flag.

if ! git status | grep -q 'nothing to commit (working directory clean)' ; then
	if [ "$nocommit" -eq "0" ] ; then
		# if committing the directory must be clean at first
		git status
		die "directory is dirty"
	else
		# development build, just remember that it was dirty
		isdirty=1
	fi
else
	isdirty=0
fi

This step is git-specific, and must be adapted if you are using a different VCS.

Versioning

The next step handles all of the versioning and source control operations.

The steps required depend on the command line options used.

Tagged Builds

First, we handle the case where the -n flag was not specified. The first step is to use agvtool to determine the marketing version. This will not be changed when the build number is incremented. Checking the marketing version first lets us verify that the project is set up properly before making changes.

if [ "$nocommit" -eq "0" ] ; then
	# read out the marketing version
	# do this separate from the cut so we can check the exit code
	mvers=$(agvtool mvers -terse)
	if [ $? -ne 0 -o -z "$mvers" ] ; then
		die "No marketing version found"
	fi
 
	if echo "$mvers" | grep -q = ; then
		mvers=$(echo "$mvers" | cut -f 2 -d =)
	fi

The output of agvtool looks like:

"SpinSlide.xcodeproj/../Info.plist"=1.0

The cut command is used to extract the field after the = sign.

After this point, the environment has been fully verified, so we can go ahead and increment the build version.

	# going to commit, bump the version number
	agvtool bump -all

Now we extract the (newly incremented) build version…

	bvers=$(agvtool vers -terse)
	if [ $? -ne 0 -o -z "$bvers" ] ; then
		die "No build version found"
	fi

… and combine the marketing version and build numbers into a human-readable string and a tag identifier, which has the spaces replace by underscores.

	# read out the build version, must exist if the marketing version does
	fullvers="$mvers build $bvers"
	tag=$(echo "$fullvers" | tr ' ' _)

Finally, we commit the changed .plist and tag the new version.

	# commit the changed version and tag it
	echo "Committing "$fullvers" with tag $tag"
	git ci -a -m "Set build version '$fullvers'" -n || die 'commit failed'
	git tag "$tag" -m "$fullvers"

Untagged Builds

Untagged builds are much simpler. The SHA1 of the current version is used as the tag. If the source directory is dirty, the current date and time is added to make a unique identifier.

else
	# not committing, use the SHA1 as the version
	fullvers=$(git rev-parse HEAD 2>/dev/null)
 
	# if it's dirty, append the date, time, and timezone
	if [ "$isdirty" -ne 0 ] ; then
		fullvers="$fullvers+ $(date +%F\ %T\ %Z)"
	fi
fi

Build Prep

To ensure the build matches the source, we delete the build directory and the Payload directory (the former is used by XCode, the latter by this script).

# clean up old builds so that everything is built from scratch
rm -rf build
rm -rf Payload
all=

Build and Package

Next we loop over the requested configurations, building and packaging each one.

# build and package each requested config
for config in $configs ; do

The build is performed with the xcodebuild utility, supplied with XCode. A failed build stops the script.

	xcodebuild -alltargets -parallelizeTargets -configuration $config build || die "Build failed"

Build output is stored in a tree named for the build type (tagged or untagged), version, and XCode build configuration:

	# packaged output goes in Releases if tagged, Development otherwise
	if [ "$nocommit" -eq "0" ] ; then
		basedir=Releases
	else
		basedir=Development
	fi
	releasedir=$basedir/$config/"$fullvers"
	mkdir -p "$releasedir"

Each build target is then packaged, one at a time.

	# Package each app
	for app in build/$config-iphoneos/*.app ; do
		basename="$(basename "$app" .app)"

The application bundle is copied into a directory called Payload/Payload. The first directory name isn’t significant, but the second is important to make a working .ipa file.

		mkdir -p Payload/Payload
		cp -Rp "$app" Payload/Payload

To have an icon in iTunes, the package must include a 512×512 PNG or JPEG named iTunesArtwork at the root. The following code supports per-project default artwork as well as app-specific artwork (if there are multiple apps in a single project).

		# Get app-specific iTunes artwork or project-specific artwork
		# if available
		if [ -f "$basename".iTunesArtwork ] ; then
			cp -f "$basename".iTunesArtwork Payload/iTunesArtwork
		elif [ -f iTunesArtwork ] ; then
			cp -f iTunesArtwork Payload/iTunesArtwork
		fi

A .ipa file is just a .zip file with a particular content format. When building for distribution through the AppStore, the .zip extension is required. Otherwise the .ipa extension is used.

		# Distribution builds have a .zip extension, development
		# builds have a .ipa extension
		if [ "$config" -eq "Distribute" ] ; then
			ext=zip
		else
			ext=ipa
		fi

Next we use ditto to zip the contents, then delete the temp directory.

		# zip the Payload directory then delete it
		output="$releasedir/$basename.$ext"
		ditto -c -k Payload "$output" || die "Failed to compress"
		rm -rf Payload

We remember the name of the generated file to display at the end of the script.

		# add to the list of output files
		all="${all:+$(printf "%s\n" "$all")}$(printf "\t%s" "$output")"

XCode supports splitting the debug symbols from the app. If this option is enabled (as it should be for Release and Distribution builds) we save the debug symbols with the app:

		# save debug symbols (if available) with the app
		if [ -d "$app.dSYM" ] ; then
			output="$releasedir/$basename.dSYM.zip"
			ditto -c -k "$app.dSYM" "$output" || die "Failed to compress debug info"
			all="$(printf "%s\n" "$all")$(printf "\t%s" "$output")"
		fi

Finally, we update a symlink to point to the latest version.

		# update a symlink to the latest version
		(cd $basedir/$config ; ln -sf "$fullvers/$basename.$ext")
	done
done

Report Results

Once all the builds have completed and been packaged, a build summary is displayed to the user.

# report the generated files
printf "Created: $all\n"

Registration

Registration is simple, although the menu item is hidden in the Help menu instead of being in the Application menu (which doesn’t actually exist). Once you’ve entered the registered name and serial number, the app is fully activated. Registration is per-user, not per-machine, so you can install it on your desktop, laptop, home desktop, etc. Registration includes free perpetual updates.

Reinventing the… uh… clock

When you launch Mockups, you are presented with a new mockup window, ready for your design. Across the top are a number of controls you can add to the Mockup. These controls are broken down into a number of categories. Since I write iPhone apps for a living, we’ll select the iPhone category to get started, then set about creating a workflow for the built-in clock app.

First, drag a iPhone object into the mockup to act as a container for our views. Bring up the properties window (it’s greyed out until you point at it) and select the middle background pattern, which shows a Nav Bar at the top and a Tab Bar at the bottom. Then click in the “Quick Add” box and start typing “Icon”. Select the “Icon and Text Label” and type in “World Clock”. Click on “Icon search” and type in “Circle”, then select the “Dot, Little Black Circle” icon. Change the font size to 9 and icon size to Small to make it fit better, and drag it over the tab bar area on the phone. In a similar way, we can quickly make the Alarm, Stopwatch, and Timer buttons and place them in their approximate locations. Select all 4 icons and Align Bottom, then Distribute Centers Horizontally and Group them. We’ll save this as “iPhone Clock App World Clock”.

Next we clone the mockup (??N) three times and save the clones as “iPhone Clock App Alarm”, “iPhone Clock App Stopwatch”, and “iPhone Clock App Timer”. Later we can link the icon buttons to the different views, but for now we’ll continue creating the World Clock view. In a few moments we can add an Edit button and a + button and use a Label to finish the Nav Bar.

Next we complete the content view. Simple add a Rectangle/Canvas to the content area, an icon for the clock, and a few Labels for the City, Time, AM/PM and Day, adjusting the fonts appropriately (remember, the goal is an approximate representation of the final app). Duplicate the row we just created a few times to fill out the content area.

In-App Navigation

The last step on this view is to fill out the links. Just select each control and choose the desired mockup from the Link dropdown. A small blue arrow will appear on the control. If you switch to View->Full Screen Presentation (?F) you can click on these linked buttons to navigate around the mockup.

We can use the included iPhone Picker control to quickly mockup the Timer screen as well. The buttons in the middle are made from Canvases and Labels to allow customizing the text layout and colors, much as we’d have to do in Interface Builder or programmatically if we were to build this app for real. It would be nice if Mockups let you change button colors. Maybe that feature will be added soon.

Full Screen Presentation

We can go on like this adding additional mockups until we’ve covered all the screens in the app. Along the way we can share the files with the rest of the team to get feedback much more quickly than if we were writing code for all of this. If you are in the same office as the rest of your team or use some sort of web collaboration software, you can use the Full Screen Presentation mode to click through the various screens in the app, using the ridiculously large pointer (and I mean that in a nice way) to point out parts of the interface as you discuss it.

Conclusions

Mockups is extremely easy to use. I wrote this review as I was learning the app for the first time. The hand-drawn images really do have the intended “lo-fi” effect, encouraging you to stay focused on the big picture instead of spending hours tweaking individual pixels. Mockups will definitely become part of the AppMobi design process. It will be a big help as we move ahead with development of our more sophisticated productivity apps.

There are a number of events going on around WWDC this year. Brandon Kwaselow has the most comprehensive list I’ve seen so far, it even includes Three Wolf Tuesday!

WWDC Parties/events – WWDC 2009 – Brandon “Quazie” Kwaselow’s Blog.

Google Calendar with the events:

We were looking for a fairly simple app to use as a learning experience. After toying with a few ideas, we ended up settling on a puzzle game that my son and I initially wrote during “take your kid to work day.” What started as a simple slide puzzle grew a number of features including tile spinning, image importing, picture taking, and more. Here’s the description from the app store:

And some screenshots:

Now it’s just a matter of waiting for Apple approval of both the SpinSlide application and AppMobi’s contracts. We’ll see which comes through first.

1. Connect your iPhone or iPod Touch to a computer with iTunes installed.
2. Launch iTunes and switch to the Applications section of the Library
   
3. If this is your first install of an app
   1. Save the provisioning file to your desktop…
      
   2. and drag it into iTunes
      
4. Save the application to your desktop…
   
5. and drag it into iTunes
   
6. Select your to your iPhone or iPod in the Device section in the left column of iTunes; then go to the Applications tab.
   

Make sure you’ve either selected “All Applications” or that the checkbox next to the new app is selected.

7. Click “Sync”
8. Enjoy!