Creating an activity: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Developer's manual content factored into the developer's manual, rest is dup of act tutorial)
Line 1: Line 1:
#Redirect [[Activity tutorial]]
{{Translations}}
''see also: [[Creating a content bundle]]''

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/" below:
<inputbox>
type=create
default=Activities/
width=20
height=10
buttonlabel=Create activity summary
bgcolor=#fffcf9
preload=Template:New activity summary
break=yes
align=right
editintro=Template:New activity key
</inputbox>
<br clear="right"/>

<div style="float:right">
__TOC__
</div>
== 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 &mdash; 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''' &mdash; 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''' &mdash; 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''' &mdash; 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 [[HIG | OLPC human interface guidelines]] and the [[educational activity guidelines]] for more detailed information.

Also, look at other [[software ideas]] and [[Activities | 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 [[Art wanted | artists]], [[educators]], and [[Developers program | programmers]] &mdash; 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 [[HIG|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 [[Getting started programming]] 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 [http://lists.laptop.org/listinfo mailing lists]. These lists are where a lot of the action goes on, and where the latest is discussed. For activity developers, the [http://lists.laptop.org/listinfo/sugar Sugar] list, and the [http://lists.laptop.org/listinfo/games games] list are great ways to get up to speed. For those interested in the hardware platform and the nitty gritty details, the [http://lists.laptop.org/listinfo/devel 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]] &mdash; especially channels #sugar and #olpc-content on irc.freenode.net. You can get basic IRC instructions [[IRC#How_to_use_irc_channels | 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:
* [http://www.pygtk.org/ pyGTK] &mdash; This is what Sugar is written in and is useful for activities that require lots of buttons and widgets.
* [http://www.pygame.org/news.html pygame] &mdash; 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 [http://dev.laptop.org 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 [http://www.gnu.org/licenses/gpl-howto.html 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 [http://git.or.cz/course/svn.html 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 &mdash; 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 [[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 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.

<small>
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.
</small>

The setup.py script below <font color=red>in progress</font> zips up your activity directory into an .xo file -- it also autogenerates the MANIFEST.

===== <tt>setup.py</tt> =====
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("YourActivityName")
except ImportError:
import os
os.system("find ./ | sed 's,^./,YourActivityName.activity/,g' > MANIFEST")
os.chdir('..')
<font color="red">os.system('zip -r YourActivityName.xo YourActivityName.activity')</font>
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 '''<tt>./setup.py</tt>''' 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 [[Developer Console]], go to the <tt>/home/olpc</tt> directory.
# Make a directory called <tt>Activities</tt> inside <tt>/home/olpc</tt>, if it doesn't already exist.
# Unpack your .xo file inside the <tt>Activities</tt> directory (using the <tt>unzip</tt> command). This should create a <tt>/home/olpc/Activities/YourActivityName.activity</tt> directory.
# Restart the X-server (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 &mdash; just rename some of them to <tt>name.activity.bak</tt>, and restart X.
* If 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

== Activity refinements ==

=== l10n ===
l10n pages targeted at developers need consolidation. See:
*[[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.)

== Other notes ==

== List of Helpful Pages ==
* list all pages mentioned with brief explanation here

[[Category:Developers]]
[[Category:Software]]
[[Category:Activities]]
[[Category:Tutorials]]
[[Category:HowTo]]

Revision as of 02:50, 20 December 2007

Redirect to:

Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=Creating_an_activity&oldid=86805"