Creating an activity
see also: Creating a content bundle
This page is intended to outline, and to provide links for, all the steps in creating an Activity. From initial concept to release and support.
Ideas
The first step in creating an activity is coming up with a good idea. OLPC is not just another fancy hardware platform for kids to use - it is also a rethinking about how to use a computer as an educational tool. To that end, there are several design principles that you should keep in mind as you think about your activity. In particular, activities should include:
- discoverability - Is the activity intuitive to learn to use? Generally speaking, large instruction manuals are boring to read, and hard to translate. The more intuitive you can make the interface to your activity the better. That means suggestive images on buttons rather than text, etc.
- extensibility - Can the activity be easily edited by teachers and kids to expand its use? For example, does your quiz activity give teachers the ability to change the questions so that they can use it for any type of quiz question, not just the ones you thought of?
- collaboration - Can your activity be used by more than one child at a time? Great activities should have a single-user mode, and a multi-user mode that makes sense with the activity. Is your game multiplayer, is your word processor able to let two people write the same document?
- More ...
Many of these ideas are core to the Sugar interface for the XO, and it is worth taking a look at the human intereface guidlines and the Educational activity guidelines for more detailed information.
Also have a look at other software ideas, and existing activities (link) to find out what is already going on. Maybe you can join an existing team and help out. There are many facets to a team including artists (link) and programmers (link) - you don't need to know everything about making an activity to be a part of the process.
Design
While, the Educational activity guidelines and OLPC Human Interface Guidelines are the foundation of your activity, there are some important things to keep in mind about the OLPC hardware platform when you think about designing the implementation of your activity.
overview of this unique hardware environment
- Display
- stub
Development
Once you start development of your activity, there are several things you should do. First of all, if you do not have any experince programming, you should take a look at Getting started programming and begin some tutorials. While those are going on (or coding of your activity if you already have programming experience), you should start to participate in the OLPC community:
- join some of the mailing lists - these lists are where a lot of the action goes on, and where the latest is discussed. For activity developers, the sugar list, and the games list are great ways to get caught up to speed. For those interested in the hardware platform and some of the nitty gritty details, the devel list is full of the latest information.
- introduce yourself to the community - start by making a wiki page for your project. If you haven't done so already, make a wiki accound, and post some information about yourself and a picture on your user page. You can then make a wiki page for your activity. Start by introducing the idea of the project and where you want to go with it, who is on the project with your contact information, and what specific kind of feedback you are looking for. Don't worry about all the technical details for now like code repositories, versions, etc. Eventually the project wiki page will become the center of the project where newcomers can go to find out more. The best way to get started is to copy one of the existing Activities.
- Once your wiki page is made, email one of the lists with a link to it to notify the community what you are up to. They can then start editing your wiki page with advice, suggestions, etc.
- Listen in and ask questions on irc.freenode.net #sugar and #olpc-content. (We should have a link to a mini-irc tutorial.) This is the fastest way to get answers to your questions.
Start to Write Your Activity
There are two primary ways you can write activities for an XO, and both involve python:
- pyGTK - This is what Sugar is written in and is useful for activities that require lots of buttons and widgets
- pygame - This is a lightweight framework for for writing games that do not require lots of buttons and widgets, but instead move lots of images around on the screen.
Both pyGTK and pygame are python modules that work on many platforms. This allows you to start writing your activity without having an XO in your hand, and without trying to emulate Sugar. The best way to get started is to decide which category your activity fits into, and start to learn about these modules. Both of the websites have excellent starting tutorials, and it is often a good idea to download a working example and begin to change it towards the design of your activity to start off. At this point you are ready to start hosting your code at OLPC.
When you have at least 10 lines of code
At this point you are ready to host your code in a repository so that other developers can start having a look at it. You should also be creating trac tickets to track bugs and feature requests. One of the main OLPC communication systems is through the dev.laptop.org trac page where people can see the status of activities as releases are prepared, testers can file bug reports, and translators can submit translations of your activity. You need to do three things to set this system up
- Request project hosting: You need to fill out an application and send it to the devel list (another good reason to join). If you have a nice wiki page outlining what you want to do, and a little bit of code, you should be all set for the application. Request a git tree, as well as a trac component for your activity (so you can file trac tickets under your application).
- Add a GPL license to your project files: The OLPC repository is public, so you want to be careful not to put any proprietary code in there. Also, you want to make sure that you are using an open source license on your code so that others can modify and extend it with ease. The GPL license howto provides some simple steps that you need to follow to get this straight (include a copy of the license, have a copyright declaration in each file, etc.) Now is a good time to do this if you only have 10 lines of code!
- Import your project into your git tree: See Importing your project for more instructions. Also, if you have not used git before, you may want to read Using_a_central_git_tree or the Git-SVN crash course.
Making Your Activity Work on an XO
It is a good idea to test out your activity on an XO, or an emulation environment sooner rather than later, because there are a few suprises. Most of them has to do with the screen being small in physical dimensions, but high in resolution. Other isssues are with speed - odds are that your development machine is much faster than an XO. Nonetheless, to even get your activity to run on an XO to see this for yourself, you need to do several steps
- Create a sugar wrapper for your activity
- Package the activity
- Put the activity on an XO or emulater
- Tweak, tweak, tweak
Sugarize your activity
Depending on whether you used pyGTK or pygame, this process is a little different. For both of them, you need to start by following the steps at the Sugar Activity Tutorial. This tutorial outlines the basic directory structure that you need for your activity, as well as instructions for how to make an icon for your activity (as well as giving a small pyGTK example activity). However, you cannot complete the tutorial if you do not have sugar installed on your machine. For now we will pretend you don't so stop just before the invocation of setup.py.
For activities written in pygame, you need to perform 2 additional steps:
- get the olpcgames code from xxx: This is wrapper code that lets your activity run inside sugar. You should keep it in a directory called olpcgames/ within your activity directory.
- Create a file called activity.py with contents
import olpcgames
class YourActivity(olpcgames.activity.PyGameActivity):
"""Your Descriytion as a Sugar activity."""
game_name = 'your_game_name'
game_title = 'Your Game Title'
game_size = (1200,825)
This ensures that the wrapper code is called properly within sugar.
Package the activity
Now for both methods (pyGTK or pygame), we can package the activity. For now we will not package it properly using the sugar bundle builder because we just want to see if the activity works. We will correct this below when we start to want testers to test the activity, and anyone to use it. Make sure all of your activity files are listed in your MANIFEST, and put the following code as your setup.py file (replace YourActivityName with the proper name)
#!/usr/bin/env python
try:
from sugar.activity import bundlebuilder
bundlebuilder.start()
except ImportError:
import os
os.chdir('..')
os.system('cat YourActivityName.activity/MANIFEST | zip YourActivityName.xo -@')
os.system('mv YourActivityName.xo ./YourActivityName.activity')
os.chdir('YourActivityName.activity')
This way you can run
./setup.py
without sugar installed, and at the end you should find a zipped up .xo file ready for you to put on an XO or emulator.
Put the activity on an XO or emulator
Now you need to get that .xo file onto an XO or an emulator to test it out. (More detailed instructions). There is a directory called ~olpc/. Make a directory called Activities with ~olpc/, and unpack your .xo file there. You should now see a ~olpc/Activities/YourActivityName.activity directory. Now you need to restart the X-server, and when sugar loads (and all goes well), you should see your icon in the sugar dock. Click on it to test your activity.
TroubleShooting
- If you can't see your icon, there could be too many activities installed - just rename some of them to name.activity.bak, and restart X.
- There was a crash: go into the developer console log viewer and view the logs associated with your activity.
Tweak, tweak, tweak
- notes about the development environment
try:
import sugar
dev = 0
except ImportError:
dev = 1
if dev:
SCREENRECT = Rect(0,0,400,300)
scale_x = 1./3.
scale_y = 1./3.
FONT_SIZE = 36
else:
SCREENRECT = Rect(0,0,1200,825)
scale_x = 1.
scale_y = 1.
FONT_SIZE = 36
Release process
what else?
l10n
There isn't currently a l10n page targetted at developers. See:
- Python i18n
- Activity Translations
- Localization
- Resource links in Translating.
- Kuku/Localization Resource links at the bottom of Kuku.
Packaging using Sugar Bundle Builder
- stub
testing and review
The Activity review and testing process is still being developed. Ask on #olpc-content.
The testing process is still being developed. See:
what else?
Other notes
List of Helpful Pages
- list all pages mentioned with brief explanation here