Project 2008 HOWTO
- Firstly, read
the original project description.
- While sitting in the lab,
please keep your iPod connected to a PC via its USB charging cable,
to charge its battery.
A full charge takes about 30 minutes and lasts
(depending on the amount of WiFi activity) about 3-4 hours.
This will help all.
- As bugs are uncovered,
and then hopefully resolved,
information will be posted via
help3230
so that all students may remain equally informed.
Please read it each day.
- If you find these instructions confusing,
please email Chris McDonald
with any suggestions on how they could be clearer.
|
Introduction
The Apple iPod Touch is a handheld mobile device
promoted by Apple as an iTunes music and video player,
also capable of executing a few supported applications.
However, it is possible to bypass the supported, constrained,
environment of the device and to develop general programs for it,
taking advantage of the IEEE802.11 (WiFi) networking interface, TCP/IP
protocol stack, and novel 320x480pixel @ 163ppi GUI.
CSSE has 20 Apple iPod Touch devices for experimentation in student projects.
Each device has a 670MHz ARM processor,
128MB of RAM in which the operating system and applications execute,
and 8GB of flash memory providing a solid-state disk.
The iPod runs a modified version of Apple's OS-X operating system
(as used on the workstations in CSSE Lab 2.1),
and provides a multi-touch GUI for all input
[Wikipedia].
The iPod has only two physical buttons to control its operation;
all other control is through its on-screen GUI.
The button at the top-left is the "Power" button,
which both boots the device from its off state,
and awakens the device if it was sleeping.
Clicking the power button while the iPod is running
will put the device to sleep (suspend it);
clicking it again will awaken the device and execution will continue from
where it was suspended.
The "Home" button,
located at the centre bottom of the front face,
may be used to interrupt the execution of a running program.
Clicking the "Home" button will kill the current process and return
execution to SpringBoard (see next).
Pressing both the Power and Home buttons together for 3 seconds
will power-off the device
(SpringBoard will first ask for confirmation).
Need a video?
[Apple's
guided tour].
The primary interface on the iPod is named SpringBoard,
which displays multiple "screens" of available applications.
You may navigate between screens by quickly stroking the screen from
right-to-left or left-to-right.
Each application is represented by an icon and its name, under the icon.
On the CSSE iPods, most of the standard applications have been moved to
the 2nd screen so that students may easily add their own applications
to the primary screen.
|
Additions to the iPod's applications
do not immediately appear on SpringBoard's display,
even though they may be on the solid-state disk.
This is because SpringBoard caches each application's icon,
once, and never reloads them until SpringBoard is restarted.
Restart SpringBoard by clicking the "Respring" application icon
(as seen at left),
and then any new applications should appear.
|
How to borrow an iPod
If enrolled in CITS3230 in 1st semester,
you may borrow one of the iPods from the CSSE front office,
during office hours (8.30am - 4.30pm).
Outside of these hours you may borrow one from Chris McDonald if he's in
his office, Rm 2.20.
You may borrow the iPod under these conditions:
- You may only borrow one iPod at a time.
- You must surrender your UWA Student Card in exchange for the iPod.
- You may borrow an iPod for a two hour period
(this may be increased, depending on how many are currently being borrowed),
- You must sign a form, providing your name and signature,
agreeing to all of these conditions.
- You must not take the device outside of the CSSE building.
- At the end your borrowing period, you must return the iPod,
its USB charging cable, and cardboard box.
You must return the same iPod that you borrowed,
and should not return an iPod borrowed by another student.
- In signing the form,
you understand and agree to the condition that your unit marks
in CITS3230 will be withheld until you return the borrowed iPod,
or replace it with another new, equivalent device.
|
How to compile your cnet protocol for the iPod
|
The execution of cnet protocols on the iPods
is rather different to their execution on workstations or laptops.
When executing within the cnet simulator on desktop computers,
cnet compiles your protocols for the native machine,
and dynamically loads an instance of the compiled executable.
The simulation supports the execution of multiple nodes, each with
multiple links.
In contrast, each iPod device (obviously) acts as a single mobile node
and your cnet protocols are used to communicate between multiple
iPods using its WiFi interface as its single physical link.
cnet protocols on the iPod execute natively,
and so your protocols must be specifically cross-compiled for its ARM processor,
and not the Intel processors of our laboratory machines.
To considerably simplify this error-prone activity,
the copy of cnet running in CSSE (now v3.1.2)
has been modified to contact a purpose-written cnet4ipod
cross-compilation server running on another CSSE machine.
To cross-compile your protocols for the iPod,
execute cnet with its new -P command-line switch,
providing all C files (both .c and .h files) that you wish to be compiled.
For example:
linux> cnet -P project.c dll.c nl.c al.c
iPod application is named project.app
Note that all named files will be copied to the cross-compiler,
so ensure that you provide all necessary C (*.c) and header (*.h) files.
If the compilation is successful,
cnet will inform you where it has placed your compiled protocol.
You should endeavour to maintain the same body of code for execution
within the full cnet simulator, and on the iPod.
If there is a need to identify different pieces of code, you may use the
following C preprocessor construct in your files:
#if defined(CNET4IPOD)
......
#else
......
#endif
Each successfully compiled protocol will appear as an OS-X "bundle",
a directory containing all files necessary to execute
your protocol on the iPod.
In addition to your actual executable,
the new directory will include an XML properties file
and a number of icons in PNG format.
linux> ls -l project.app
total 296
-rw-r--r-- 1 chris chris 2149 May 29 22:48 Default.png
-rw-r--r-- 1 chris chris 752 May 29 22:48 Info.plist
-rw-r--r-- 1 chris chris 1542 May 29 22:48 button_green.png
-rw-r--r-- 1 chris chris 1474 May 29 22:48 button_green_pressed.png
-rw-r--r-- 1 chris chris 1775 May 29 22:48 button_red.png
-rw-r--r-- 1 chris chris 1658 May 29 22:48 button_red_pressed.png
-rw-r--r-- 1 chris chris 1471 May 29 22:48 button_silver.png
-rw-r--r-- 1 chris chris 1427 May 29 22:48 button_silver_pressed.png
-rw-r--r-- 1 chris chris 7153 May 29 22:48 icon.png
-rwxr-xr-x 1 chris chris 106500 May 29 22:48 project
If the compilation of your protocol was unsuccessful,
the stderr and stdout streams from the cross-compiler
will be displayed on your screen.
|
How to load your cnet protocol onto the iPod
|
A great irony in developing our cnet protocols for the iPod is that
we must use TCP/IP and the device's WiFi interface to load our protocols.
While the device has a USB interface on its bottom,
this is only used for charging the device's battery and downloading iTunes
music, and is not used for installing general programs and data.
From the iPod's main SpringBoard screen,
click the Settings icon (displayed at left).
The resulting screen will enable you to turn on the WiFi interface
(wait 10 seconds for the "fan" icon to appear in the iPod's top title bar),
and then start a VPN connection to UWA's SNAP infrastructure.
Both the SNAP and VPN passwords have already been recorded on all devices.
When connected to SNAP via VPN,
each iPod has its own, unique, IP address.
Each iPod's cardboard box has two numbers on it, e.g.
2380 / 023.
The first matches the sticker on the back of the iPod,
the second is the device's SNAP account name, e.g. csse-023.
You may find a list of these
account names and IP addresses here.
Being a single-user device,
it is generally considered adequate for
processes on the iPod run as the root user
(we'll discuss the ramifications of this in
CITS3231!).
To load your protocol on to the iPod,
you'll need to copy your whole OS-X bundle directory to the iPod,
first providing the root password.
All iPods have the same root password of alpine
(there seems little need to change this to something different
in our shared group environment).
So, to copy your protocol bundle:
linux> scp -rp project.app root@130.95.49.XXX:/Applications
root@130.95.49.XXX's password: alpine (not echoed)
Your protocol's icon will not immediately appear on the iPod's screen,
even though it will be on its solid-state disk.
Restart SpringBoard by running clicking the "Respring" application icon,
and then your protocol's icon should appear.
In summary:
- click the Settings icon.
- turn on the WiFi interface.
- wait 10 seconds for the WiFi icon to appear in the title bar.
- start a VPN connection.
- determine your iPod's
VPN IP address.
- copy your protocol from Linux to the iPod using scp .....
- stop the VPN connection.
- exit the Settings application by pressing the Home key.
- click the Respring icon - your protocol's icon should appear.
- click your protocol's icon ....
|
When testing your protocol across multiple iPods you will, of course,
require the same copy/version of your protocol installed on each iPod.
To ensure that you understand the necessary steps,
first try to compile, load, and run this simple "protocol":
ipoddemo.c
|
How to remove your cnet protocol from the iPod
|
|
cnet names your protocol after the name of the first file
appearing after cnet's -P argument.
You may thus have multiple, different, protocols installed on an iPod, each
with its own application, name, and icon.
At the end of your borrowing period,
you should remove each of your protocol applications with:
linux> ssh root@130.95.49.XXX rm -rf /Application/project.app
root@130.95.49.XXX's password: alpine (not echoed)
Click the Respring icon and your protocol's icon should have
disappeared.
|
Finishing up
|
|
At the end your borrowing period, you must return the iPod,
its USB charging cable, and cardboard box to the CSSE office.
Invoke the Settings application and:
- turn off the VPN connection (using Settings),
- turn off the WiFi interface (using Settings), and
- turn off the device itself (using the Power button).
|
This will conserve the device's battery while it sits in its cardboard
box, waiting for another student.
|
Good luck,
Chris McDonald.
|
