wrdk - a WikiReader Development Kit
===================================

Michael Hope <michael.hope@seabright.co.nz>  (c) 2010

http://wrdk.seabright.co.nz/

*wrdk* is a toolchain, set of examples, and simple serial loader that
makes developing applications for the Openmoko_ WikiReader_ a little
bit easier.

Most of the work was already done by Openmoko (thanks Openmoko_!).
wrdk builds on this and adds a pre-built toolchain and loader which
make it easier to get up and going and shortens the
compile/load/test cycle.

Download
--------
* Linux binary: http://wrdk.seabright.co.nz/files/wrdk-linux-0.1.tar.gz
* Windows installer: http://wrdk.seabright.co.nz/files/wrdk-installer-0.1.exe
* Source: http://wrdk.seabright.co.nz/files/wrdk-0.1.tar.gz

The Linux binary was built on Ubuntu 8.04 and should work on versions 8.04
through to 10.04.

Development occurs on github at http://github.com/nzmichaelh/wrdk.
Issues can be filed at http://github.com/nzmichaelh/wrdk/issues.
There's a mailing list at http://groups.google.com/group/wrdk-users.

Install
-------
*For Linux users:*

wrdk is designed to be installed under /opt or your home directory.

To install:

* Change to your home directory
* Extract the archive using ``tar xzf wrdk-linux-$VERSION.tar.gz``
* Add ``$HOME/wrdk/bin`` to your path
* Add ``$HOME/wrdk/python`` to your PYTHONPATH

*For Windows users:*

* Download and run the installer above.  wrdk is automatically added
  to your path

Making a SD card
----------------
The loader and examples are grifo based applications.  This section
covers making a new SD card that boots grifo and gives a menu to
select applications from.

* Get a micro SD card
* Format it with the FAT32 filesystem
* Copy all the files from ``wrdk/share/sdimage`` to the root of the card
* Sync and unmount

Insert the card into the WikiReader and turn the device on.  You
should see the WikiReader logo, then 'wrdk', then icons for all of the
installed applications.

Examples
--------
A few simple examples are included under ``$WRDK/examples``.  To build,
change to an example directory such as ``$WRDK/examples/pongex`` and
run ``make``.

.. figure:: baby.png

   A simple 'save the baby from the burning building' game.

   Catch the babies and bounce them over into the ambulance!

.. figure:: splash.png

   A splash screen.

   Shows when the device boots.

.. figure:: pongex.png

   Pong with not many twists.

   Get the ball past the other player.  First to five points wins.

.. figure:: wrinv.png

   A strangely familiar game.

   Destroy the invaders before they land.

Making your own applications
----------------------------
wrdk includes a set of Makefile rules designed to make writing your
own application fairly straightforward.  It does expect a fairly
rigid, self-contained layout though.

Say you want to make a new application called ``wrhello``:

* Make a directory called ``wrhello``.
* Make a directory under wrhello called ``resources``.  All images go in here.
* Copy the Makefile from ``examples/wrinv`` to the ``wrhello`` directory.
* Create ``wrhello.c`` and write your application.
* Save any images in PNG or XPM format under ``wrhello/resources``.
* Create a 64x64 icon and save it as ``wrhello.xpm``.

Make sure the wrdk bin directory is in your path.

Running ``make`` will give you the application in
``wrhello/build/samov1/wrhello.app`` and the binary icon in
``wrhello/build/wrhello.ico``.  Copy these both onto the SD card and add
them to the ``init.ini`` on the card.

Don't forget to ``umount && sync`` before removing the card!

Have a look in ``grifo.h`` for the available functions.

Serial loader
-------------
The serial loader is a small, grifo based program that can load and
execute other grifo programs over the WikiReader's built in serial
port.

Build a 3.3 V serial cable and connect it to the debug connector in
the battery bay of the WikiReader.

For teardown pictures see:
 http://wiki.seabright.co.nz/wiki/WikiReader.html

For the debug connector pinout see:
 http://wiki.github.com/wikireader/wikireader/hardware-specifications

To use the loader:

* Build your application (foo.app)
* Build a binary only version (``make foo.bin``)
* Start the WikiReader
* Press the loader icon (looks like a circle with an arrow)
* Use ``wrdk-load`` to load and run the binary version of the
  application

See also
--------
.. toctree::
   :maxdepth: 1

   building

.. _Openmoko: http://www.openmoko.com/
.. _WikiReader: http://www.thewikireader.com/