Creating an activity

english | 日本語 | 한국어 HowTo [ID# 187491] +/-

see also: Creating a collection and Activity tutorial

<inputbox> type=create default=Activities/ width=20 height=10 buttonlabel=Create activity summary bgcolor=#fffcf9 preload=Template:New activity summary break=yes align=left editintro=Template:New activity summary key </inputbox>

<inputbox> type=create default=New Activity Name width=20 height=10 buttonlabel=Create activity bgcolor=#fffcf9 preload=Template:New activity preload break=yes align=right editintro=Template:New activity intro </inputbox>

Creating an Activity is simple, but shepherding it through release, testing, and support can be harder. The main aspects of activity development are noted here. If you are already developing an activity, please create a page for it on this wiki, starting with a summary. Just add the name of your activity after "Activities/" to make a summary, and create a new article with that name for the activity itself:

Ideas

The first step in creating an activity is coming up with a good idea. OLPC is not just a 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 to keep in mind as you think about your activity. In particular, activities should include:

Discoverability — Is the activity intuitive to learn? Long instruction manuals are boring to read and hard to translate. The more intuitive you can make your activity's interface, the better. That means using an interaction model that encourages experimentation, using evocative 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 both a single-user mode and a multi-user mode, if that makes sense with the activity. Is your game multiplayer? Does your word processor let two people write the same document?
More ...

These are core principles in the XO's Sugar user interface; it is worth looking at the OLPC human interface guidelines and the educational activity guidelines for more detailed information.

Also, look at other software ideas and existing activities 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, educators, and programmers — 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 design your activity.

Overview of 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 experience programming, you should take a look at the Developers manual and begin some tutorials. While completing tutorials (or coding 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 up to speed. For those interested in the hardware platform and 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 account, 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 contact information), and what specific kind of feedback you want. Don't worry about 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, e-mail 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 — especially channels #sugar and #olpc-content on irc.freenode.net. You can get basic IRC instructions here. 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 writing games that do not require lots of buttons and widgets but instead move lots of images around 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 in which category your activity fits and to learn about these modules. Both of the websites have excellent starting tutorials. A good starting point for your activity is to download a working example and change it to fit the design of your activity. At this point you are ready to start hosting your code at OLPC.

When you have at least ten lines of code

At this point you are ready to host your code in a repository so that other developers can look at it. You should also create 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 (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 ten 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 in an emulation environment sooner rather than later, because there are a few surprises. For one thing, the XO's screen is small in physical dimensions but high in resolution. Speed is another issue — 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 perform several steps:

Create a Sugar wrapper for your activity.
Package the activity.
Put the activity on an XO or emulator.
Tweak, tweak, tweak.

Sugarize your activity

Depending on whether you use pyGTK or pygame, this process is a little different. For both of them, you need to start by following the steps at the 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 complete the tutorial up to the point where setup.py is invoked.

For activities written in pygame, you need to follow the instructions at Game development HOWTO, specifically the steps "Development Environment" and "Wrapping and Testing".

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 others to use it.

The setup.py script below in progress zips up your activity directory into an .xo file -- it also autogenerates the MANIFEST.

`setup.py`

Create a setup.py script such as the following (replace YourActivityName with the proper name):

#!/usr/bin/env python
try:
    from sugar.activity import bundlebuilder
    bundlebuilder.start()
except ImportError:
    import os
    os.system("find ./ | sed 's,^./,YourActivityName.activity/,g' > MANIFEST")
    os.chdir('..')
    os.system('zip -r YourActivityName.xo YourActivityName.activity')
    os.system('mv YourActivityName.xo ./YourActivityName.activity')
    os.chdir('YourActivityName.activity')

Note that you will need to rename you xo with the version number of the latest build (say, YourActivityName-#.xo). This can be worked into the above script to pull automatically from the activity/activity.info file.

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).

In the Terminal Activity, go to the /home/olpc directory.
Make a directory called Activities inside /home/olpc, if it doesn't already exist.
Unpack your .xo file inside the Activities directory (using the unzip command). This should create a /home/olpc/Activities/YourActivityName.activity directory.
Restart the X Window System server by pressing Ctrl+Alt+Backspace.
When Sugar loads, you should see your new activity's icon in the Sugar dock. Click on it to test your activity.

Alternately, you can put it in /usr/share/activities, rather than /home/olpc/Activities.

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.
If there was a crash, run the Log viewer activity to 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

Activity refinements

l10n and i18n

l10n means localization (date, number, and currency formats), while i18n means internationalization (translation). See Localization and Translating for general information on these topics.

Developer specific links follow:

Python i18n and Localization
Activity Translations, other resource links in Translating
Kuku/Localization (worked example) with resource links at the bottom of Kuku.

Packaging using Sugar Bundle Builder

see #Package the activity, above; if you are in a Sugar context then the first part of the setup.py script will run the bundlebuilder function to create the bundle.

Testing and review

The Activity review and testing process is still being developed; ask on #olpc-content, and see Content release cycle, Category:Test Plans, Test meeting Minutes.

Include your Activity in the core?

From http://lists.laptop.org/pipermail/community-news/2007-October/000079.html

15. Core activities: There has been a discussion on the devel list about the criteria for inclusion of core activities on the laptop. We'd like to broaden the discussion. Some proposed "Criteria for Inclusion":

Epistemological impact—to what degree does this activity positively impact learning? (This is of course the most important criteria.)
Fun—is it fun? engaging?
Quality—is the activity sufficiently robust in its implementation that it will not compromise the integrity or supportability of the system? Is the overall quality of the implementation adequate to meet our standards? Can the community be engaged in the process of testing and "certifying" and maintaining the activity?
Sugarized—to what extent has the activity been integrated into Sugar, including UI, Journal, security, internationalization, etc.? Does the activity require the folding in of additional libraries and resources? (This has impact on robustness—positive and negative—support, bloat, and the overall usability, aesthetics, and perception of quality of the machine.)
FOSS—is the activity and all of its dependencies free and open?
Extensible—is the activity something the community can extend? Does it span multiple needs? (And does it have—or the potential of having—an upstream community of support?)
Uniqueness—does the activity add a unique feature to the core?
Expectations—does the activity meet the expectations of (children, teachers, parents, G1G1 audience, etc.)?
Discoverable—is the core activity discoverable? (This is not to say that it shouldn't be hard work to fully exploit the power of an activity, but it should have a low barrier to entry.)

Activity hosting

It is recommended that you host a project for your activity on the laptop.org servers (this server). See Project hosting for details.

If you want to make your activity directly downloadable to the laptop from elsewhere, you must set the correct mime types. (See Apache docs or your web server's documentation.) The mime types for XO activities are:

 application/vnd.olpc-sugar      xo
 application/vnd.olpc-content    xol

In either case, be sure to add your activity to the Activities page.

List of Helpful Pages

list all pages mentioned with brief explanation here

Creating an activity

Contents

Ideas

Design

Overview of unique hardware environment

Development

Start to write your activity

When you have at least ten lines of code

Making your activity work on an XO

Sugarize your activity

Package the activity

`setup.py`

Put the activity on an XO or emulator

Troubleshooting

Tweak, tweak, tweak

Activity refinements

l10n and i18n

Packaging using Sugar Bundle Builder

Testing and review

Include your Activity in the core?

Activity hosting

List of Helpful Pages

Navigation menu

Creating an activity

Ideas

Design

Overview of unique hardware environment

Development

Start to write your activity

When you have at least ten lines of code

Making your activity work on an XO

Sugarize your activity

Package the activity

setup.py

Put the activity on an XO or emulator

Troubleshooting

Tweak, tweak, tweak

Activity refinements

l10n and i18n

Packaging using Sugar Bundle Builder

Testing and review

Include your Activity in the core?

Activity hosting

List of Helpful Pages

Navigation menu

Search

`setup.py`