Tutorial

Developing game activities for the OLPC on Windows

First of all: almost every information about development for the OLPC can be found in the OLPC wiki (http://wiki.laptop.org/). This guide's aim is just to give the information to you which you really need and to provides you with the experiences we made during our project.

As an overview our setup:
  • Windows Vista
  • OLPC XO


Platforms:
As our main development platform we used Windows Vista. Actually because we both had no other operating system installed. But finally we can say that it worked well.
Because activities for the OLPC are mostly written in Python they run on Windows too. So developing - testing, trying something - can also be done on a common Windows installation. And it can be done much more eassier! On the XO activities either start and work or simply do not start. No further feedback is given.So you do not know which error occurred. After a time that can become pretty anoying.
The real XO we needed just at the very end to be sure that activities that run in the emulator work on the real device as well.

Programming language:
As already mentioned most activities make use of Python. Activities which are games also use usually a game library called Pygame. Games using these two components work just normal on windows. To make them run on the OLPC you will later have to import another library called OLPCgames. It is a wrapper library which adapts the calls of Pygame library in a way which allows the Pygame code to be executed on the OLPC.
Before you tackle your project and start coding you should have become a bit familiar with Python and also Pygame. To get an impression of the feeling of Python and how things are done we  recommend to read a few tutorials and maybe some source code. Also it may be eassier to read seperate small tutorials and to compare them to each other than trying to understand every little detail of a tutorial which covers almost every aspect of Python.
Afterwards you can start using the wrapper library OLPCGames

Emulation:
When you managed to make your game or even your small hello-world-pygame-dummy working on windows you are ready to face the hardest part of activity development: bring the activity to the XO.
First you need to hava a running emulator. We used therefore a modified version of QEMU which we found in the OLPC wiki. After we installed it we recognized that the included image contains absolutely no activities yet. That can become a problem if you want to install other activities. Usually you do this by starting the "Browse" activity and downloading it from the internet. So we started to search for an image which contains at least this activity and found a directory which seems to contain rather many different images (the link adress can be found above). Best way to find a good one is to download some and test them. Therefore you also need to modify the batch file "run.bat" which is located in the installation folder of QEMU. In it you simply need to replace the filename of the old image with the filename of your new one (this filename is following the "-hda" parameter).
After modifying this you need to add another parameter which is necessary to make QEMU establish network connections. It is called "-redir" and is followed by (for example) "tcp:2222::22".
On the whole your batch file should look like this (our "run.bat"): "qemu -L . -cpu athlon -m 512 -net user -net nic,model=rtl8139 -soundhw es1370 %* -hda olpc-redhat-stream-joyride-devel_ext3.img -redir tcp:2222::22"
To enhance the performance which we recommend you can also install KQEMU on your computer. For some reasons it makes QEMU run much faster. After you installed KQEMU you need to start the service you have installed. You do this by opening the command line (as an administrator) and type in "net start kqemu". After a few seconds you should be informed that kqemu was successfully launched.
After all these steps you should have a quite nice running emulator (Note: start it via the batch file). You have a modified Linux Fedora OS running with the OLPC frontend Sugar. So you are able to start some activities and play with them.
But you are still not able to get new activities transferred on your emulation. To Change this you need to set up a root password on your OLPC image. To do this you need to run your emulator and then hit Control + Alt + F1. You should now enter the Linux Bash (Note: If you do not enter any command line and instead lose the focus of your emulation you need to find someone to perform the setup of the root password on your OLPC image. During our porject we experienced that problem and the one workaround was just to transfer the image from the other computer). After you see the command line type in "passwd". Just follow the instructions and set a new password, for example "123".
After this operation it should be possible a network connection via SFTP. We therefore used a tool called WinSCP which served us very well. After installing and starting it you will see a form which allows you to fill in "localhost" as name, "2222" as port, "root" as user name and the password which you just set. By hitting connect you should see after a few moments a window which shows on the one side the files of your computer, the emulating device, and on the other side the files of your emulated OLPC.

Portation:
Portation seemed to us to be a lot about trial and error. The most usefull strategy we found out was to take an already existing activity (manny can be found in the "git" list) examine its structure and make some little changes to see which effects occur.
A few words to describe the structure of an activity (further details are described very well here: http://wiki.laptop.org/go/Activity_bundles). One important thing is to notice that all activities come in bundles which are so called ".xo" files. Actually they are "zip" files . You just need to rename the file "*.xo" into "*.zip" to view its content. While making experiences with existing activities try to focus on an understanding of the whole complex. A "way to go" for structuring seems to be something like one meta folder "activity", one folder for own data and one folder for OLPCgames library. Further you got four kind of meta files such as "activity.py", "game.py", "setup.py" and "MANIFEST". These structure can be found in many activities, for example in "Maze" activity (http://dev.laptop.org/git/activities/maze/) which we used to try out how an activity works.
The one and big problem we experienced about trying out wether our activity works or not was that we had to have a new clean image to put our activity on. So our test procedure looked as following: delete old image (somehow destroyed by last testing), copy new one (Note: It is important to have already a root password set on it), start QEMU (Note: start it via "run.bat"), launch WinSCP, wait, connect, transfer files, download in emulation, wait, test. Hopefully your activity works at that moment otherwise you have problems. Actually their must be a more elegant way to put more developing versions on an emulation at the same time. But finally this workflow served us as well.

Some hints about programming your activity:
  • Check if all needed imports are made.
  • Check if MANIFEST file is complete.
  • The resoultion of the display is 1200*900. It does not change according to illumination or something. When you create an activity you will always have a toolbar on the upper side of the screen. Therefore the resolution changes to 1200*825.
  • Keep your activity small. Size of the whole bundle should clearly not expand something like 10 MBytes.
  • Keep in mind that your programs will be kind of slow on the OLPC.
  • The OLPC supports PNG - with transparency.

Something about icons:
If you want to design your own icons you can do it the following way. Download InkScape and install it. Create a new file: size: 55*55 pixels (important). Draw something (Note: For us just using one color, black, worked well.). Download the Sugar-iconify script, place it somewhere, perhaps on your Desktop, and run the command line. Navigate via "cd" to the destination folder of the downloaded script. Then type "Sugar-iconify.py -c " then follows the filename of your drawing. This may be "myIcon.svg". Hopefully you will get a modified version of your icon returned which works well as a proper icon for your own activity. For further details see: http://wiki.laptop.org/go/Sugar-iconify.
Subscribe to: Posts (Atom)